domma-cms 0.43.1 → 0.45.0

package/server/services/apiTokens.js

@@ -3,7 +3,7 @@
  * Project-scoped machine credentials for the external collections API.
  *
  * Tokens are entries in the file-based `api-tokens` preset collection.
- * Only a SHA-256 hash is stored — the plaintext (`dcms_<64 hex>`) is returned
+ * Only a SHA-256 hash is stored - the plaintext (`dcms_<64 hex>`) is returned
  * exactly once, from createToken(). A token is accepted only on collection
  * verbs configured with `api.<verb>.access === 'token'`, and only for
  * collections whose resolved project matches the token's `project` binding.
@@ -26,7 +26,7 @@ let tokenCache = null;
  * Serialises this service's fire-and-forget writes (the throttled lastUsedAt
  * update) against its mutations. FileAdapter does unlocked read-modify-write,
  * so an in-flight lastUsedAt update that read the data file BEFORE a revoke
- * wrote it would write the revoked token straight back — resurrection.
+ * wrote it would write the revoked token straight back - resurrection.
  * Mutations await the chain; lastUsedAt updates append to it.
  */
 let writeChain = Promise.resolve();
@@ -35,7 +35,7 @@ function invalidateCache() {
     tokenCache = null;
 }
 
-// Generic admin collection endpoints emit these for ALL collections — the
+// Generic admin collection endpoints emit these for ALL collections - the
 // service's own mutations invalidate directly, this catches edits made
 // through the admin entries grid.
 for (const ev of ['collection:entryCreated', 'collection:entryUpdated', 'collection:entryDeleted']) {
@@ -162,7 +162,7 @@ export async function findTokenByName(name, project) {
 /**
  * Validate a presented plaintext token.
  * Returns the sanitised entry when the token exists, is enabled, and has not
- * expired — otherwise null. Updates lastUsedAt at most once per minute
+ * expired - otherwise null. Updates lastUsedAt at most once per minute
  * (fire-and-forget; the cached copy is patched in place to avoid thrash).
  *
  * @param {string} plaintext
@@ -184,7 +184,7 @@ export async function validateToken(plaintext) {
 
     const lastUsed = entry.data.lastUsedAt ? Date.parse(entry.data.lastUsedAt) : 0;
     if (Date.now() - lastUsed > LAST_USED_THROTTLE_MS) {
-        // updateEntry replaces data wholesale — pass the full object.
+        // updateEntry replaces data wholesale - pass the full object.
         const data = {...entry.data, lastUsedAt: new Date().toISOString()};
         entry.data = data; // keep the cached copy current without invalidating
         // Fire-and-forget, but chained so revoke/update can await it.
@@ -222,7 +222,7 @@ export async function getTokenSanitised(id) {
 
 /**
  * Update mutable token fields. The project binding, hash, and hint are fixed
- * for the token's lifetime — revoke and re-issue to rebind.
+ * for the token's lifetime - revoke and re-issue to rebind.
  *
  * @param {string} id
  * @param {{name?: string, enabled?: boolean, scopes?: object[], expiresAt?: string|null}} patch
@@ -264,7 +264,7 @@ export async function updateToken(id, patch = {}) {
  * @returns {Promise<boolean>}
  */
 export async function revokeToken(id) {
-    await writeChain; // drain any in-flight lastUsedAt write — revoke must be final
+    await writeChain; // drain any in-flight lastUsedAt write - revoke must be final
     const entry = await getEntry(API_TOKENS_COLLECTION_SLUG, id);
     if (!entry) return false;
     await deleteEntry(API_TOKENS_COLLECTION_SLUG, id);

package/server/services/blocks.js

@@ -1,7 +1,7 @@
 /**
  * Blocks Service
  * CRUD operations and seeding for reusable HTML block templates in content/blocks/.
- * Never overwrites existing files during seeding — user customisations are preserved.
+ * Never overwrites existing files during seeding - user customisations are preserved.
  */
 import fs from 'fs/promises';
 import path from 'path';
@@ -21,7 +21,7 @@ async function seedBlock(name, content) {
     const filePath = path.join(BLOCKS_DIR, `${name}.html`);
     try {
         await fs.access(filePath);
-        // File exists — leave it alone
+        // File exists - leave it alone
     } catch {
         await fs.writeFile(filePath, content.trim() + '\n', 'utf8');
     }
@@ -34,7 +34,7 @@ async function seedBlock(name, content) {
 const BLOCKS = {
 
     /**
-     * contact-info — standalone contact details panel for landing pages.
+     * contact-info - standalone contact details panel for landing pages.
      * Fields: heading, intro, phone, phoneHref, email, address, hours,
      *         facebook, facebookLabel, instagram, instagramLabel,
      *         website, websiteLabel, footnote
@@ -99,7 +99,7 @@ const BLOCKS = {
 `,
 
     /**
-     * contact-card — for the Contacts form
+     * contact-card - for the Contacts form
      * Fields: full_name, phone_number, email_address
      */
     'contact-card': `
@@ -120,7 +120,7 @@ const BLOCKS = {
 `,
 
     /**
-     * enquiry-card — for the Enquiries form
+     * enquiry-card - for the Enquiries form
      * Fields: full_name, email, phone, subject, message
      */
     'enquiry-card': `
@@ -143,7 +143,7 @@ const BLOCKS = {
 `,
 
     /**
-     * feedback-card — for the Feedback form
+     * feedback-card - for the Feedback form
      * Fields: name, email, rating, category, subject, message, recommend
      */
     'feedback-card': `
@@ -159,7 +159,7 @@ const BLOCKS = {
   <div class="card-body">
     <p style="margin:0 0 1rem;line-height:1.65;">{{message}}</p>
     <div style="display:flex;justify-content:space-between;align-items:center;flex-wrap:wrap;gap:.5rem;font-size:.8rem;color:var(--dm-text-muted,#888);">
-      <span>{{name}} &mdash; {{email}}</span>
+      <span>{{name}} - {{email}}</span>
       <span>Would recommend: <strong>{{recommend}}</strong></span>
     </div>
   </div>
@@ -167,7 +167,7 @@ const BLOCKS = {
 `,
 
     /**
-     * note-card — for the Notes form
+     * note-card - for the Notes form
      * Fields: title, content, category, tags
      */
     'note-card': `
@@ -187,7 +187,7 @@ const BLOCKS = {
 `,
 
     /**
-     * todo-item — for the To-Do form
+     * todo-item - for the To-Do form
      * Fields: title, description, status, priority, due_date, assigned_to
      */
     'todo-item': `
@@ -238,7 +238,7 @@ function blockMetaPath(name) {
     return path.join(BLOCKS_DIR, `${name}.meta.json`);
 }
 
-/** Per-block CSS size cap — matches the 100 KB site-wide cap, scaled down. */
+/** Per-block CSS size cap - matches the 100 KB site-wide cap, scaled down. */
 const MAX_CSS_SIZE = 50 * 1024;
 
 // ---------------------------------------------------------------------------
@@ -300,7 +300,7 @@ export async function getBlock(name) {
         let css = '';
         try {
             css = await fs.readFile(blockCssPath(name), 'utf8');
-        } catch { /* no CSS file — treat as empty */
+        } catch { /* no CSS file - treat as empty */
         }
         return {name, content, css, bundled, ...(meta && {meta})};
     } catch (err) {
@@ -334,7 +334,7 @@ export async function saveBlock(name, content, {bundled, css, meta} = {}) {
     await fs.mkdir(BLOCKS_DIR, {recursive: true});
     await fs.writeFile(blockFilePath(name), content, 'utf8');
     const metaPath = blockMetaPath(name);
-    // Merge sidecar meta — bundled flag plus any caller-supplied fields (eg meta.project).
+    // Merge sidecar meta - bundled flag plus any caller-supplied fields (eg meta.project).
     const sidecar = {
         ...(meta && typeof meta === 'object' ? meta : {}),
         ...(bundled ? {bundled: true} : {})
@@ -345,7 +345,7 @@ export async function saveBlock(name, content, {bundled, css, meta} = {}) {
         await fs.unlink(metaPath).catch(() => {
         });
     }
-    // CSS is optional — only touch the file when the caller passed the field explicitly.
+    // CSS is optional - only touch the file when the caller passed the field explicitly.
     if (typeof css === 'string') {
         if (css.trim().length > 0) {
             await fs.writeFile(blockCssPath(name), css, 'utf8');

package/server/services/cache/drivers/MemoryDriver.js

@@ -3,7 +3,7 @@ import {LRU} from '../lru.js';
 /**
  * In-memory cache driver with TTL and tag invalidation.
  *
- * Each entry is stored as {value, expiresAt, tags}. TTL is lazy — entries
+ * Each entry is stored as {value, expiresAt, tags}. TTL is lazy - entries
  * past their expiresAt are returned as undefined on the next get and dropped.
  *
  * Tag index: a Map<tag, Set<key>>. set() with {tags} adds the key to each
@@ -79,14 +79,14 @@ export class MemoryDriver {
         this._tagIndex.clear();
     }
 
-    /** Current entry count (sync — for the dashboard widget). */
+    /** Current entry count (sync - for the dashboard widget). */
     size() {
         return this._lru.size;
     }
 
     /**
      * Snapshot the currently cached entries as `{key, tags, expiresAt}`.
-     * No values — they can be megabytes of HTML. Uses `entries()` (non-mutating)
+     * No values - they can be megabytes of HTML. Uses `entries()` (non-mutating)
      * so the LRU order is preserved through the iteration.
      */
     listEntries() {

package/server/services/cache/drivers/NoneDriver.js

@@ -1,5 +1,5 @@
 /**
- * Null driver — used when the cache is disabled.
+ * Null driver - used when the cache is disabled.
  * Every read misses; every write is dropped on the floor.
  */
 export class NoneDriver {

package/server/services/cache/index.js

@@ -61,7 +61,7 @@ export async function initCache(config = {}) {
  *
  * When turning on, re-initialise with the last config (or sensible defaults)
  * so a previously disabled cache gets a real driver. When turning off, keep
- * the driver in place but short-circuit reads/writes — preserves cached data
+ * the driver in place but short-circuit reads/writes - preserves cached data
  * if the user toggles back on. The persistence of this choice across restarts
  * is the caller's responsibility (the route handler writes to config/cache.json).
  */
@@ -69,12 +69,12 @@ export async function setEnabled(enabled) {
     if (Boolean(enabled) === _enabled) return;
     if (enabled) {
         if (_driver instanceof NoneDriver) {
-            // No usable driver yet — bootstrap one from last-known config.
+            // No usable driver yet - bootstrap one from last-known config.
             const cfg = {...(_lastConfig || {}), enabled: true};
             if (!cfg.driver || cfg.driver === 'none') cfg.driver = 'memory';
             await initCache(cfg);
         } else {
-            // Memory/Redis driver still live — flip the flag and preserve data.
+            // Memory/Redis driver still live - flip the flag and preserve data.
             _enabled = true;
         }
     } else {
@@ -110,7 +110,7 @@ export async function clear() {
 
 /**
  * List the cache's keys with their tags and expiry. Values are deliberately
- * excluded — cached entries can be megabytes of HTML.
+ * excluded - cached entries can be megabytes of HTML.
  * @returns {{key: string, tags: string[], expiresAt: number|null}[]}
  */
 export function listEntries() {
@@ -148,7 +148,7 @@ export function getStats() {
  * Get-or-set with in-flight coalescing.
  *
  * Producer may return either a raw value, or an object with a `_cacheTags`
- * array — those tags are merged into opts.tags before storing, and the
+ * array - those tags are merged into opts.tags before storing, and the
  * `_cacheTags` field is stripped from both the cached and returned value.
  * This lets producers report tags discovered during rendering (e.g. the
  * markdown pipeline noting embedded collection slugs) without the caller

package/server/services/collections.js

@@ -1,6 +1,6 @@
 /**
  * Collections Service
- * Schema-first data store — one directory per collection under content/collections/{slug}/.
+ * Schema-first data store - one directory per collection under content/collections/{slug}/.
  * Each collection has a schema.json (field definitions + API access config).
  *
  * Entry storage is delegated to the active adapter (FileAdapter or MongoAdapter).
@@ -65,11 +65,11 @@ function defaultApiAccess() {
 }
 
 // ---------------------------------------------------------------------------
-// Schema (collection) operations — always file-based
+// Schema (collection) operations - always file-based
 // ---------------------------------------------------------------------------
 
 /**
- * List all collections — reads all schema.json files and appends entryCount.
+ * List all collections - reads all schema.json files and appends entryCount.
  *
  * @returns {Promise<object[]>}
  */
@@ -93,7 +93,7 @@ export async function listCollections() {
     return results
         .filter(r => r.status === 'fulfilled')
         .map(r => r.value)
-        // Hand-rolled schemas can lack `title` — fall back to slug rather
+        // Hand-rolled schemas can lack `title` - fall back to slug rather
         // than crashing the whole listing (seen in the wild: a schema with
         // `name` instead of `title` 500'd /api/collections permanently).
         .sort((a, b) => String(a.title || a.slug || '').localeCompare(String(b.title || b.slug || '')));
@@ -215,7 +215,7 @@ export async function deleteCollection(slug) {
     if (!schema) throw new Error(`Collection "${slug}" not found`);
 
     // Remove adapter-side data first (handles MongoDB collections on
-    // non-file adapters). Prefer drop() — clear() only deletes documents
+    // non-file adapters). Prefer drop() - clear() only deletes documents
     // and leaves the backing Mongo collection + its unique index behind
     // forever.
     try {
@@ -228,7 +228,7 @@ export async function deleteCollection(slug) {
             }
         }
     } catch {
-        // Ignore errors — directory removal handles file-backed data.
+        // Ignore errors - directory removal handles file-backed data.
     }
 
     invalidate(slug);
@@ -244,7 +244,7 @@ export async function deleteCollection(slug) {
  * Validate entry data against a collection schema.
  *
  * Reference-field validation (target id existence) requires async I/O and is
- * therefore done in `validateReferences()` — called from create/update paths
+ * therefore done in `validateReferences()` - called from create/update paths
  * after this synchronous shape check passes.
  *
  * @param {object} schema
@@ -268,7 +268,7 @@ export function validateEntryData(schema, data) {
  * entry that actually exists in the target collection. Single-valued and
  * array-valued references are both supported.
  *
- * Empty/null references are skipped here — the required check in
+ * Empty/null references are skipped here - the required check in
  * `validateEntryData()` handles those.
  *
  * @param {object} schema
@@ -280,7 +280,7 @@ export async function validateReferences(schema, data) {
     for (const field of (schema.fields || [])) {
         if (field.type !== 'reference') continue;
         const targetSlug = field.reference?.collection;
-        if (!targetSlug) continue;             // misconfigured schema — skip silently
+        if (!targetSlug) continue;             // misconfigured schema - skip silently
 
         const raw = data[field.name];
         if (raw === undefined || raw === null || raw === '') continue;
@@ -301,7 +301,7 @@ export async function validateReferences(schema, data) {
 }
 
 // ---------------------------------------------------------------------------
-// Entry operations — delegated to storage adapter
+// Entry operations - delegated to storage adapter
 // ---------------------------------------------------------------------------
 
 /**
@@ -309,22 +309,22 @@ export async function validateReferences(schema, data) {
  * structured filtering, and reference resolution.
  *
  * Delegates to the configured adapter (File or Mongo). Both adapters honour
- * identical option semantics — see `filterEngine.js` for the filter DSL.
+ * identical option semantics - see `filterEngine.js` for the filter DSL.
  *
  * @example
  *   // Paginated, sorted, simple search
  *   await listEntries('jobs', { page: 1, limit: 20, sort: 'postedAt', search: 'engineer' });
  *
  * @example
- *   // Structured filter — full-time London roles paying £50k+
+ *   // Structured filter - full-time London roles paying £50k+
  *   await listEntries('jobs', { filter: { location: 'London', type: 'full-time', salary_gte: 50000 } });
  *
  * @example
- *   // Row-level scoping — applications belonging to one user
+ *   // Row-level scoping - applications belonging to one user
  *   await listEntries('applications', { filter: { createdBy: userId } });
  *
  * @example
- *   // Resolve reference fields — each entry gets `_refs.<field>` with display labels
+ *   // Resolve reference fields - each entry gets `_refs.<field>` with display labels
  *   await listEntries('applications', { resolveRefs: true });
  *   // → entries[0]._refs.jobId === { id, display: 'Senior Engineer', missing: false, link: null }
  *

package/server/services/components.js

@@ -159,7 +159,7 @@ export function compileComponent(source, name) {
     catch (e) { return {js: null, errors: [{type: e.code, message: e.message}]}; }
 
     const js = [
-        `// Compiled from ${name}.dmc — do not edit by hand.`,
+        `// Compiled from ${name}.dmc - do not edit by hand.`,
         `const template = ${toBacktickLiteral(parts.template)};`,
         `const style = ${toBacktickLiteral(parts.style)};`,
         `const props = ${JSON.stringify(propsObj)};`,
@@ -219,7 +219,7 @@ export async function getCompiledJs(name) {
 // ─── CRUD operations ──────────────────────────────────────────────────────
 
 /**
- * List all components. Lightweight metadata — does NOT compile.
+ * List all components. Lightweight metadata - does NOT compile.
  * The `props` field is parsed from each file's <props> block so the admin
  * list view can show props without a follow-up fetch.
  *
@@ -245,7 +245,7 @@ export async function listComponents() {
             const src = await fs.readFile(path.join(COMPONENTS_DIR, file), 'utf8');
             const {props: propsBlock} = parseDmcSource(src);
             props = validatePropsJson(propsBlock);
-        } catch { /* malformed — list still usable */ }
+        } catch { /* malformed - list still usable */ }
         entries.push({
             name,
             size: stat?.size ?? 0,
@@ -263,7 +263,7 @@ export async function listComponents() {
         try {
             const parts = parseDmcSource(pc.source);
             props = validatePropsJson(parts.props);
-        } catch { /* malformed plugin source — list still usable */ }
+        } catch { /* malformed plugin source - list still usable */ }
         entries.push({
             name: pc.name,
             size: pc.source.length,
@@ -313,7 +313,7 @@ export async function getComponent(name) {
 }
 
 /**
- * Create or update a component. Compiles BEFORE writing — a malformed source
+ * Create or update a component. Compiles BEFORE writing - a malformed source
  * never reaches disk. Returns the compile errors (if any) rather than throwing.
  *
  * @param {string} name
@@ -352,12 +352,12 @@ export async function saveComponent(name, source, {bundled = false, meta} = {})
     return {success: true, name, errors: []};
 }
 
-/** Lazy, circular-safe import — refreshes the markdown sanitiser's dm-* tag allowlist. */
+/** Lazy, circular-safe import - refreshes the markdown sanitiser's dm-* tag allowlist. */
 async function _refreshSanitiserAllowlist() {
     try {
         const {refreshComponentTagAllowlist} = await import('./markdown.js');
         await refreshComponentTagAllowlist();
-    } catch { /* no-op — markdown module not ready at first save */ }
+    } catch { /* no-op - markdown module not ready at first save */ }
 }
 
 /**
@@ -465,7 +465,7 @@ const SEED_COMPONENTS = {
 }
 </props>
 <script>
-// NB: Domma's factory calls data() with no \`this\` binding — props must be
+// NB: Domma's factory calls data() with no \`this\` binding - props must be
 // read from within onMount() / methods, which ARE bound to the component context.
 export default {
   data() { return { count: 0 }; },
@@ -633,7 +633,7 @@ export default {
 
 /**
  * Seed starter components into content/components/.
- * Never overwrites existing files — user customisations are preserved.
+ * Never overwrites existing files - user customisations are preserved.
  * All seeded components are marked `bundled: true` via their .meta.json.
  */
 export async function seedDefaultComponents() {

package/server/services/connectionManager.js

@@ -2,7 +2,7 @@
  * Connection Manager (Pro feature)
  *
  * Manages MongoDB client lifecycle for named database connections.
- * Loaded dynamically via import() — never required in the free version.
+ * Loaded dynamically via import() - never required in the free version.
  *
  * Usage:
  *   await initialise(connectionsConfig)   // on server startup
@@ -15,13 +15,13 @@ const clients = new Map();
 
 /**
  * Initialise all named MongoDB connections from config.
- * Connects lazily — each client is created but connect() is deferred to first use.
+ * Connects lazily - each client is created but connect() is deferred to first use.
  *
  * @param {Record<string, { type: string, uri: string, database: string, options?: object }>} connectionsConfig
  * @returns {Promise<void>}
  */
 export async function initialise(connectionsConfig) {
-    // Dynamic import — mongodb package is optional and not loaded in the free version.
+    // Dynamic import - mongodb package is optional and not loaded in the free version.
     const { MongoClient } = await import('mongodb');
 
     for (const [name, cfg] of Object.entries(connectionsConfig)) {
@@ -43,7 +43,7 @@ export async function initialise(connectionsConfig) {
             console.log(`[connectionManager] Connected: ${name} → ${cfg.database}`);
         } catch (err) {
             console.error(`[connectionManager] Failed to connect "${name}": ${err.message}`);
-            // Don't throw — allow server to start with degraded MongoDB support.
+            // Don't throw - allow server to start with degraded MongoDB support.
         }
     }
 }

package/server/services/content.js

@@ -79,6 +79,17 @@ export async function getPage(urlPath, opts = {}) {
 /**
  * Create a new page. Auto-creates parent directories.
  *
+ * Every frontmatter key the caller sends is written through - the same
+ * contract as updatePage. An earlier version built `meta` from a fixed
+ * whitelist, which silently discarded `project`, `visibility`, `tags`,
+ * `category` and `theme` on the FIRST save of a page: a page created inside
+ * a project landed in core, vanished from that project's list, and yet the
+ * URL was taken, so re-creating it answered "already exists".
+ *
+ * `project: ''` means "inherit by rootUrl" - the key is omitted rather than
+ * written as null (null is the deprecated core opt-out, and it pins the page
+ * to core forever).
+ *
  * @param {string} urlPath
  * @param {object} frontmatter
  * @param {string} body
@@ -91,6 +102,7 @@ export async function createPage(urlPath, frontmatter, body) {
     const defaults = config.content.pageDefaults;
     const now = new Date().toISOString();
     const meta = {
+        ...frontmatter,
         title: frontmatter.title || 'Untitled',
         slug: slugFromPath(urlPath),
         description: frontmatter.description || '',
@@ -104,6 +116,7 @@ export async function createPage(urlPath, frontmatter, body) {
         createdAt: now,
         updatedAt: now
     };
+    if (meta.project === '' || meta.project === undefined) delete meta.project;
 
     await fs.writeFile(filePath, serialiseMarkdown(meta, body || ''), 'utf8');
     const page = await readPageFile(filePath);
@@ -134,6 +147,11 @@ export async function updatePage(urlPath, frontmatter, body, {author} = {}) {
 
     if (existingMeta.createdAt) meta.createdAt = existingMeta.createdAt;
 
+    // '' is the editor's "inherit by rootUrl" choice - drop the key so the
+    // resolver re-derives it. (null stays meaningful: the deprecated explicit
+    // core opt-out.)
+    if (meta.project === '') delete meta.project;
+
     try {
         await createVersion(urlPath, {author, type: 'auto', label: null});
     } catch {
@@ -321,7 +339,7 @@ async function collectMdFiles(dir) {
  * @param {object} [opts]
  * @param {object|null} [opts.user] - Forwarded to parseMarkdown so the
  *   `[menu]` shortcode can filter items by per-user visibility. Defaults to
- *   anonymous (null) — most callers (listings, admin previews) leave this unset.
+ *   anonymous (null) - most callers (listings, admin previews) leave this unset.
  * @returns {Promise<object>}
  */
 async function readPageFile(filePath, opts = {}) {
@@ -331,7 +349,12 @@ async function readPageFile(filePath, opts = {}) {
     // against menus bound to this page or its project, exactly as the navbar does.
     const { data, content, html, usedComponents, tags } =
         await parseMarkdown(raw, {user: opts.user || null, urlPath});
-    return { ...data, urlPath, content, html, usedComponents, tags };
+    // parseMarkdown's `tags` are CACHE tags (`block:x`, `collection:y`), not
+    // the page's editorial tags. Spreading them last used to shadow the
+    // frontmatter's `tags`, so the editor loaded `block:feedback-card` into
+    // the tag pillbox and wrote it back on save, and the pages list showed
+    // cache internals in its Tags column. Keep them apart.
+    return { ...data, urlPath, content, html, usedComponents, cacheTags: tags };
 }
 
 /**

package/server/services/docs.js

@@ -1,10 +1,10 @@
 /**
- * Domma Docs — request-time renderer
+ * Domma Docs - request-time renderer
  *
  * Serves the Domma CMS handbook at /domma-docs/* directly from the admin doc
  * HTML templates (admin/js/templates/docs/*.html) at request time. There is no
  * baked content: a domma-cms version bump ships new templates and the docs
- * update everywhere automatically — no porter, no per-site provisioning, no
+ * update everywhere automatically - no porter, no per-site provisioning, no
  * staleness. (Replaces the one-shot scripts/migrate-docs.js bake.)
  *
  * The publish switch is the `domma-docs` project's enabled flag, enforced by
@@ -33,7 +33,7 @@ const TPL_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../..', 'admin
 // Functional nav chrome only (breadcrumb + prev/next + section nav). Everything
 // else (hero, cards, tabs, accordion, buttons) is a native Domma component, so
 // it follows the theme. Injected as an inline <style> per docs page at render
-// time — no dependency on content/custom.css.
+// time - no dependency on content/custom.css.
 const DOCS_BODY_CSS = `.doc-breadcrumb { display: flex; flex-wrap: wrap; gap: .5rem; align-items: center; max-width: 80ch; margin: 0 auto 1.25rem; font-size: .85rem; color: var(--dm-text-muted); }
 .doc-breadcrumb a { color: var(--dm-primary); text-decoration: none; }
 .doc-breadcrumb a:hover { text-decoration: underline; }
@@ -76,7 +76,7 @@ const MAP = [
 ];
 
 // Admin-SPA hash routes and stale /resources/… paths don't resolve on the
-// public site — rewrite doc-to-doc links to /domma-docs/…, admin-feature links
+// public site - rewrite doc-to-doc links to /domma-docs/…, admin-feature links
 // to the admin SPA, and unwrap the rest.
 const LINK_MAP = {
     '#/docs/components-walkthrough': '/domma-docs/components/walkthrough',
@@ -97,7 +97,7 @@ const LINK_MAP = {
     '/resources/components':         '/domma-docs/components'
 };
 
-// The four top-level doc sections — rendered as a persistent nav on every page.
+// The four top-level doc sections - rendered as a persistent nav on every page.
 const SECTIONS = [
     {label: 'Usage',         href: '/domma-docs/usage'},
     {label: 'Tutorials',     href: '/domma-docs/tutorials'},
@@ -134,13 +134,13 @@ function rewriteLinks(html) {
     for (const [from, to] of Object.entries(LINK_MAP)) {
         out = out.split(`href="${from}"`).join(`href="${to}"`);
     }
-    // Any remaining /resources/… link has no doc equivalent — unwrap to text.
+    // Any remaining /resources/… link has no doc equivalent - unwrap to text.
     out = out.replace(/<a\b[^>]*\shref="\/resources\/[^"]*"[^>]*>([\s\S]*?)<\/a>/gi, '$1');
     return out;
 }
 
 // Pull every inline <style> block out of the body, returning the cleaned HTML
-// plus the extracted (deduped) CSS — collected PER CALL (no shared module state,
+// plus the extracted (deduped) CSS - collected PER CALL (no shared module state,
 // which would leak across requests in a long-lived server).
 function stripStyleBlocks(html) {
     const styles = new Set();
@@ -182,7 +182,7 @@ function unwrapDocsBody(html) {
 // Plain-text heading title, safe as a shortcode attribute value.
 function headingText(inner) {
     return inner.replace(/<[^>]+>/g, '')
-        .replace(/&amp;/g, '&').replace(/&mdash;/g, '—').replace(/&ndash;/g, '–')
+        .replace(/&amp;/g, '&').replace(/-/g, '-').replace(/-/g, '-')
         .replace(/&quot;/g, "'").replace(/&#39;/g, "'").replace(/&lt;/g, '<').replace(/&gt;/g, '>')
         .replace(/\s+/g, ' ').trim().replace(/"/g, "'");
 }
@@ -200,7 +200,7 @@ function splitSections(inner, level) {
     return {preamble, sections};
 }
 
-// ≥7 sections → accordion; 2–6 → tabs; <2 → a single card.
+// ≥7 sections → accordion; 2-6 → tabs; <2 → a single card.
 function structureBody(body) {
     const inner = unwrapDocsBody(body);
     const level = /<h2\b/i.test(inner) ? 2 : 3;
@@ -265,9 +265,9 @@ function buildSectionLanding(label) {
 function buildHomeLanding() {
     const hero = `[hero title="Domma Docs" tagline="The Domma CMS handbook" variant="gradient" align="center" fullwidth="true"][/hero]`;
     const cards = [
-        {label: 'Usage',         href: '/domma-docs/usage',      icon: 'book-open',     blurb: 'Day-to-day guides for running the CMS — pages, media, navigation, shortcodes and more.'},
+        {label: 'Usage',         href: '/domma-docs/usage',      icon: 'book-open',     blurb: 'Day-to-day guides for running the CMS - pages, media, navigation, shortcodes and more.'},
         {label: 'Tutorials',     href: '/domma-docs/tutorials',  icon: 'academic-cap',  blurb: 'Step-by-step walkthroughs that build something real from start to finish.'},
-        {label: 'Components',    href: '/domma-docs/components', icon: 'puzzle',        blurb: 'The full component reference — shortcodes, how-tos, walkthroughs and rules.'},
+        {label: 'Components',    href: '/domma-docs/components', icon: 'puzzle',        blurb: 'The full component reference - shortcodes, how-tos, walkthroughs and rules.'},
         {label: 'API Reference', href: '/domma-docs/api',        icon: 'code',          blurb: 'Every REST endpoint for headless and external integrations.'}
     ].map(s =>
         `[card icon="${s.icon}" title="${heroAttr(s.label)}"]\n${escText(s.blurb)}\n\n[button label="Browse ${heroAttr(s.label)} →" href="${s.href}" variant="primary" /]\n[/card]`
@@ -278,7 +278,7 @@ function buildHomeLanding() {
 // ── render ───────────────────────────────────────────────────────────────────
 
 // Build the shortcode body for a doc path, or null if the path is unknown.
-// Returns {title, body, styles[]} — `styles` is the inline CSS extracted from a
+// Returns {title, body, styles[]} - `styles` is the inline CSS extracted from a
 // leaf template (empty for synthesized landings).
 async function buildDocBody(docPath) {
     if (docPath in LANDINGS) {
@@ -292,7 +292,7 @@ async function buildDocBody(docPath) {
     try {
         src = await readFile(join(TPL_DIR, `${tpl}.html`), 'utf8');
     } catch {
-        return null; // template missing — treat as a 404
+        return null; // template missing - treat as a 404
     }
     const {html: stripped, styles} = stripStyleBlocks(stripHeader(src));
     const body = escapeCodeBrackets(dedentOutsidePre(rewriteLinks(stripped))).trim();
@@ -308,7 +308,7 @@ async function buildDocBody(docPath) {
 /**
  * Render a Domma Docs page to full HTML, or return null for an unknown path
  * (the route turns that into a 404). Cached per path+origin under the static
- * 'docs' tag — invalidated on boot so a version bump never serves stale HTML.
+ * 'docs' tag - invalidated on boot so a version bump never serves stale HTML.
  *
  * @param {string} docPath  url tail after /domma-docs (e.g. 'usage/pages', '' for home)
  * @param {{user?: object|null, baseUrl?: string}} [opts]