domma-cms 0.92.1 → 0.94.0

package/admin/js/templates/docs/usage-editions.html

@@ -0,0 +1,213 @@
+<div class="view-header">
+  <h1><span data-icon="book"></span> Editions &amp; Licences</h1>
+  <a href="#/documentation" class="btn btn-ghost btn-sm"><span data-icon="arrow-left"></span> All usage topics</a>
+</div>
+
+<div class="row">
+  <div class="col-12">
+    <div class="docs-body">
+
+<p>What you get free with Domma CMS, what is paid, what "Pro" means, and how plugin licences work.
+    Prices: TBC.</p>
+
+<h3>In short</h3>
+<ul>
+    <li>The CMS itself is free. Every core feature works without a licence.</li>
+    <li>Some plugins are free and ship with the CMS. Others are paid and need a licence.</li>
+    <li>A "Pro" plugin adds to, or replaces, a free Tool or plugin. If its licence lapses, the free one comes back.</li>
+    <li>A licence is either a <strong>rental</strong> (a site the Domma Manager runs for you) or
+        <strong>perpetual</strong> (bought outright).</li>
+    <li>A rental stops when its term and grace period end. A perpetual licence never stops; only support and
+        updates end.</li>
+    <li>A few features need MongoDB. One plugin, MongoDB Adapter, is only for sites run by the Domma Manager.</li>
+</ul>
+
+<h3>What the free CMS includes</h3>
+<p>Everything in the core CMS is free:</p>
+<ul>
+    <li><strong>Content</strong> - pages with a visual editor, version history, drafts and share links,
+        shortcodes, blocks, components and a media library.</li>
+    <li><strong>Design</strong> - built-in themes, menus, right-click menus and a visitor theme switcher.</li>
+    <li><strong>Data</strong> - collections on file storage, saved views, a form builder, and public collection
+        displays.</li>
+    <li><strong>API</strong> - the <code>/api/v1</code> collection API, API tokens and API Builder endpoints.</li>
+    <li><strong>Admin</strong> - dashboard, notifications, in-admin docs, projects, roles and permissions.</li>
+    <li><strong>Built-in Tools</strong> - Notes, Todo, Analytics, Contacts and SEO. Each can be switched off in
+        the <a href="#/plugins">Marketplace</a> under "Built-in Tools".</li>
+    <li><strong>Marketplace</strong> - installing, updating and switching plugins.</li>
+</ul>
+
+<h3>Core features that need MongoDB</h3>
+<p>These are marked "Pro" in the CMS. They are not licensed. They switch on when the site has a MongoDB
+    connection in <code>config/connections.json</code>:</p>
+<ul>
+    <li><strong>MongoDB storage</strong> - keep any collection in MongoDB instead of files. Set it per collection
+        on the collection's Storage tab.</li>
+    <li><strong>Actions</strong> - workflows that run steps against a collection entry. Without MongoDB the
+        Actions screen says they need MongoDB.</li>
+</ul>
+<p>Add a connection under <strong>Data &gt; Collections &gt; Database connections</strong> (admins only), or
+    with <code>npm run pro enable</code>. On a site run by the Domma Manager, the MongoDB Adapter plugin sets the
+    connection up for you (see below).</p>
+<p>The optional Redis cache driver is also described as a Pro feature. It needs Redis, not a licence.</p>
+
+<h3>Free plugins</h3>
+<p>These are marked <code>free</code> in their manifests and ship in the CMS <code>plugins/</code> folder.
+    Switch them on in the Marketplace.</p>
+<ul>
+    <li><strong>Blog</strong> - posts, categories and comments.</li>
+    <li><strong>Feedback</strong> - tell Domma what is broken, missing or good, from your admin.</li>
+    <li><strong>Mail Reader</strong> - a read-only IMAP mailbox reader.</li>
+    <li><strong>Security</strong> - a health check, sign-in lockout, password rules and a sign-in log.</li>
+    <li><strong>Shopping Cart</strong> - products, a storefront, a cart and checkout.</li>
+</ul>
+
+<h3>Paid plugins</h3>
+<p>Every other plugin in the Marketplace is paid. A paid plugin is marked closed source. It needs a valid
+    licence on the site, or it does not start. Paid plugins cannot be viewed or exported from the Marketplace.</p>
+<p>A plugin you write yourself is never asked for a licence.</p>
+
+<h3>What "Pro" means</h3>
+<p>A Pro plugin builds on a free Tool or plugin. It does this in one of two ways:</p>
+<ul>
+    <li><strong>It replaces it</strong> (<code>supersedes</code> in its manifest). The free one stops loading
+        while the Pro one runs, so you see one screen, not two. For a built-in Tool, the Pro plugin hides the
+        Tool's sidebar entry and takes over its screen. The Tool's data and API stay in place.</li>
+    <li><strong>It adds to it</strong> (<code>requires</code> in its manifest). Both run. If the free one is
+        switched off, the Pro one does not start.</li>
+</ul>
+<table class="table table-sm">
+    <thead>
+    <tr>
+        <th>Pro plugin</th>
+        <th>Relationship</th>
+    </tr>
+    </thead>
+    <tbody>
+    <tr><td>Blog Pro</td><td>Replaces Blog</td></tr>
+    <tr><td>Contacts Pro</td><td>Requires and replaces the built-in Contacts Tool</td></tr>
+    <tr><td>Email (email-pro)</td><td>Replaces Mail Reader</td></tr>
+    <tr><td>Security Pro</td><td>Replaces Security</td></tr>
+    <tr><td>SEO Pro</td><td>Requires the built-in SEO Tool</td></tr>
+    <tr><td>Shopping Cart Pro</td><td>Requires Shopping Cart</td></tr>
+    <tr><td>Analytics Pro</td><td>Separate from the built-in Analytics Tool; neither replaces the other</td></tr>
+    <tr><td>Social Media Pro</td><td>No free edition</td></tr>
+    <tr><td>Waypoint Pro</td><td>No free edition</td></tr>
+    </tbody>
+</table>
+
+<h3>When a Pro licence lapses</h3>
+<p>The replacement is worked out each time the site starts. Nothing is written to your settings. So when a
+    Pro plugin stops running because its licence has lapsed:</p>
+<ul>
+    <li>the free plugin it replaced loads again on the next start, and</li>
+    <li>a built-in Tool it took over comes back.</li>
+</ul>
+<p>You are never left with less than a site that never bought the Pro plugin.</p>
+
+<h3>Where the licence lives</h3>
+<p>A licence is a signed file called an entitlement. The CMS looks for it in two places, in this order:</p>
+<ol>
+    <li><code>plugins/&lt;plugin&gt;/.entitlement.json</code> - one plugin, one licence. A
+        <code>.dcmsplugin</code> file carries it in.</li>
+    <li><code>config/entitlements/*.json</code> - site-wide licences.</li>
+</ol>
+<p>The file must be signed by the Domma Marketplace key. A missing, edited or wrongly signed file counts as
+    unlicensed, and the plugin does not start.</p>
+<p>The licence is checked each time the site starts. A plugin that is refused is not switched off in your
+    settings, so renewing brings it straight back on the next start.</p>
+
+<h3>Rental licences</h3>
+<p>For a site run for you by the Domma Manager. The plugin is rented monthly alongside the hosting.</p>
+<ul>
+    <li>The plugin banner shows <strong>Expires</strong> and the date.</li>
+    <li>After the end date there is a grace period. The plugin keeps running and the banner shows
+        <strong>Expired (date) (grace)</strong>. The Marketplace marks it <strong>Renew</strong>. The grace period
+        is set on the licence; the Manager issues 7 days unless told otherwise.</li>
+    <li>After the grace period the plugin does not start. The Marketplace marks it <strong>Expired</strong>. Its
+        data is kept.</li>
+    <li>A notice appears 14 days before the end date, during the grace period, and once it has stopped.</li>
+</ul>
+
+<h3>Perpetual licences</h3>
+<p>For a site the Domma Manager does not run. You buy the plugin once, with a period of support.</p>
+<ul>
+    <li>The plugin banner shows <strong>Support to</strong> and the date.</li>
+    <li>When support ends, the banner shows <strong>Support ended</strong>. The plugin keeps running for good.</li>
+    <li>What ends is support and updates. Renewing support extends it.</li>
+    <li>A notice tells you when support and updates have ended.</li>
+</ul>
+
+<h3>Managed-only plugins</h3>
+<p><strong>MongoDB Adapter</strong> is only offered for sites run by the Domma Manager. The Manager creates a
+    database and a user for the site, and writes the site's connection file. On a site the Manager does not run,
+    the plugin would have nothing to do.</p>
+<p>When the Manager removes it, the site's connection file and database user are removed. The database itself
+    is kept.</p>
+
+<h3>Plugins that need MongoDB</h3>
+<ul>
+    <li><strong>MongoDB Adapter</strong> - provides MongoDB to a managed site.</li>
+    <li><strong>Email (email-pro)</strong> - search, threads, rules, scheduled sends, snooze and vacation replies
+        need MongoDB. Without it, reading, filing and sending still work.</li>
+    <li><strong>Data Transfer</strong> - needs MongoDB only to move collections to or from MongoDB. Backups,
+        restores and clones work on file storage.</li>
+    <li><strong>Surveys</strong> - uses MongoDB when there is a connection, and falls back to file storage when
+        there is not.</li>
+</ul>
+<p>Garage and Messages work on either storage. The rest do not use MongoDB.</p>
+
+<h3>All Marketplace plugins</h3>
+<table class="table table-sm">
+    <thead>
+    <tr>
+        <th>Plugin</th>
+        <th>Tier</th>
+        <th>Needs MongoDB</th>
+        <th>Managed-only</th>
+        <th>Notes</th>
+    </tr>
+    </thead>
+    <tbody>
+    <tr><td>Analytics Pro</td><td>paid</td><td>No</td><td>No</td><td>Separate from the built-in Analytics Tool</td></tr>
+    <tr><td>Blog</td><td>free</td><td>No</td><td>No</td><td>Ships with the CMS</td></tr>
+    <tr><td>Blog Pro</td><td>paid</td><td>No</td><td>No</td><td>Replaces Blog</td></tr>
+    <tr><td>Calendar</td><td>paid</td><td>No</td><td>No</td><td>Uses Contacts, Notes and Todo when they are on</td></tr>
+    <tr><td>Contacts Pro</td><td>paid</td><td>No</td><td>No</td><td>Requires and replaces the built-in Contacts Tool</td></tr>
+    <tr><td>Data Transfer</td><td>paid</td><td>Only to move to or from MongoDB</td><td>No</td><td>Backups and restores work on file storage</td></tr>
+    <tr><td>Docs</td><td>paid</td><td>No</td><td>No</td><td></td></tr>
+    <tr><td>Email (email-pro)</td><td>paid</td><td>Partly</td><td>No</td><td>Replaces Mail Reader; some features need MongoDB</td></tr>
+    <tr><td>Feedback</td><td>free</td><td>No</td><td>No</td><td>Ships with the CMS</td></tr>
+    <tr><td>Garage</td><td>paid</td><td>No</td><td>No</td><td>Works on file or MongoDB storage</td></tr>
+    <tr><td>Invoices</td><td>paid</td><td>No</td><td>No</td><td>Uses Contacts</td></tr>
+    <tr><td>Job Board</td><td>paid</td><td>No</td><td>No</td><td></td></tr>
+    <tr><td>Mail Reader</td><td>free</td><td>No</td><td>No</td><td>Ships with the CMS</td></tr>
+    <tr><td>Messages</td><td>paid</td><td>No</td><td>No</td><td>File storage unless moved to MongoDB</td></tr>
+    <tr><td>MongoDB Adapter</td><td>paid</td><td>Provides it</td><td>Yes</td><td>Set up by the Domma Manager</td></tr>
+    <tr><td>Security</td><td>free</td><td>No</td><td>No</td><td>Ships with the CMS</td></tr>
+    <tr><td>Security Pro</td><td>paid</td><td>No</td><td>No</td><td>Replaces Security</td></tr>
+    <tr><td>SEO Pro</td><td>paid</td><td>No</td><td>No</td><td>Requires the built-in SEO Tool</td></tr>
+    <tr><td>Shopping Cart</td><td>free</td><td>No</td><td>No</td><td>Ships with the CMS</td></tr>
+    <tr><td>Shopping Cart Pro</td><td>paid</td><td>No</td><td>No</td><td>Requires Shopping Cart</td></tr>
+    <tr><td>Social Media Pro</td><td>paid</td><td>No</td><td>No</td><td>Uses SEO, Calendar and Blog when they are on</td></tr>
+    <tr><td>Surveys</td><td>paid</td><td>Optional</td><td>No</td><td>Falls back to file storage</td></tr>
+    <tr><td>Theme Roller</td><td>paid</td><td>No</td><td>No</td><td></td></tr>
+    <tr><td>Waypoint Pro</td><td>paid</td><td>No</td><td>No</td><td></td></tr>
+    </tbody>
+</table>
+
+<h3>Getting a licence</h3>
+<p>Prices: TBC.</p>
+<ul>
+    <li><strong>A site run by the Domma Manager</strong> - open <a href="#/plugins">Marketplace</a> &gt;
+        Browse. It lists what your Manager offers. Install brings a plugin in already licensed. A plugin not
+        licensed yet is still listed; ask for it to be added.</li>
+    <li><strong>Any other site</strong> - buy the plugin and you receive a single <code>.dcmsplugin</code> file.
+        Use <strong>Install from file</strong> in the Marketplace banner. The same button installs later
+        updates.</li>
+</ul>
+<p>To buy a plugin or renew a licence, contact Domma CMS.</p>
+
+    </div>
+  </div>
+</div>

package/admin/js/templates/docs/usage-media.html

@@ -7,18 +7,34 @@
   <div class="col-12">
     <div class="docs-body">
 
-<p>Media files are stored in <code>content/media/</code> and served publicly at <code>/media/{filename}</code>.
-                  </p>
+<p>Media files are managed at <strong>Content &gt; Media</strong>, stored in <code>content/media/</code>
+                      and served publicly at <code>/media/{filename}</code>. Anything uploaded there can be opened by
+                      anyone who has its address - do not upload private documents.</p>
+
+                  <h3>Uploading</h3>
+                  <p>Use the upload button in the banner, or drop files onto the screen. Uploading a file with the
+                      same name as one already there replaces it; you are asked first. Accepted types are images
+                      (JPEG, PNG, GIF, WebP, SVG, ICO, BMP, TIFF), PDF, text and CSV, Word and Excel documents, MP4,
+                      WebM and Ogg video, and MP3, Ogg, WAV and WebM audio.</p>
+
+                  <h3>Working with a file</h3>
+                  <p>Click a file for its details: its address, a snippet to paste into a page, a rename box, and -
+                      for pictures - the image editor (crop, resize, rotate, flip, colour presets, adjustments,
+                      watermark, border, and saving as JPEG, PNG or WebP, as a copy or over the original).
+                      Right-click a file (or use its row menu) for the same actions without opening it.</p>
+                  <p>Wherever the admin asks for a picture (SEO share images, a logo, some plugin settings) the
+                      <strong>Choose...</strong> button opens the Media Picker, where you can also upload.</p>
 
                   <h3>Using media in pages</h3>
-                  <p>Reference uploaded files by their public URL in Markdown:</p>
+                  <p>Reference uploaded files by their public URL in Markdown or HTML:</p>
                   <pre class="code-block"><code>![Alt text](/media/my-image.jpg)
-
 &lt;img src="/media/my-image.jpg" alt="Alt text"&gt;</code></pre>
+                  <p>Always give pictures alt text - SEO's audit checks for it.</p>
 
                   <h3>Upload limits</h3>
-                  <p>The maximum file size is configured in <code>config/server.json</code> under <code>uploads.maxFileSize</code>
-                      (bytes). Default is 10 MB.</p>
+                  <p>The largest file is set in <code>config/server.json</code> under
+                      <code>uploads.maxFileSize</code> (bytes). The default is 10 MB. File names are limited to 200
+                      characters and cleaned of unsafe characters.</p>
 
     </div>
   </div>

package/admin/js/templates/docs/usage-navigation.html

@@ -7,24 +7,80 @@
   <div class="col-12">
     <div class="docs-body">
 
-<p>The navigation tree is stored in <code>config/navigation.json</code> and injected into every public
-                      page as
-                      <code>window.__CMS_NAV__</code>.</p>
-
-                  <h3>Dropdowns</h3>
-                  <p>Nest items under a parent using the drag-and-drop tree in the Navigation editor. Child items are
-                      stored under
-                      the <code>items</code> key - the public navbar renders them as a dropdown.</p>
-
-                  <h3>External links</h3>
-                  <p>Set the URL to a full <code>https://</code> address to link outside the site. Leave blank for
-                      section
-                      headings.</p>
-
-                  <h3>Icons</h3>
-                  <p>Set the <code>icon</code> field to any registered icon name. Icons appear in the navbar link
-                      alongside the
-                      label.</p>
+<p>The site's navigation is made of <strong>menus</strong>, edited at <strong>Content &gt;
+                      Menus</strong>. A menu is a list of links; a <strong>location</strong> (a slot) is where one is
+                      shown. Each menu is a file in <code>config/menus/</code>, and the slot map is
+                      <code>config/menu-locations.json</code>. Pages have no "show in navigation" switch - a page
+                      appears in the navbar when a menu links to it.</p>
+
+                  <h3>Locations</h3>
+                  <table class="table table-sm">
+                      <thead>
+                      <tr>
+                          <th>Slot</th>
+                          <th>Where it shows</th>
+                      </tr>
+                      </thead>
+                      <tbody>
+                      <tr>
+                          <td><code>navbar</code></td>
+                          <td>The public site's top bar (or side rail, when the menu is vertical).</td>
+                      </tr>
+                      <tr>
+                          <td><code>footer-primary</code>, <code>footer-legal</code></td>
+                          <td>The two footer link rows.</td>
+                      </tr>
+                      <tr>
+                          <td><code>overlay</code></td>
+                          <td>Floating panels pinned to a corner or edge of the page. Several menus can share it.</td>
+                      </tr>
+                      <tr>
+                          <td><code>admin-sidebar</code></td>
+                          <td>This admin's own sidebar.</td>
+                      </tr>
+                      </tbody>
+                  </table>
+                  <p>Plugins can add slots of their own. Pick the menu for each slot under <strong>Menu
+                      locations</strong>. A menu that a location uses cannot be deleted until it is taken out.</p>
+
+                  <h3>Editing a menu</h3>
+                  <ul>
+                      <li><strong>Items</strong> - click an item to edit its label, link, icon, badge, look and who
+                          sees it. Drag the grip to move an item, or drop it onto another to nest it (the navbar
+                          shows nested items as a dropdown). Right-click an item for add, move, indent, duplicate,
+                          hide and remove. Separators and spacers are items too.</li>
+                      <li><strong>Behaviour</strong> - colour scheme, sticky, fixed, static or floating, horizontal
+                          or vertical, alignment, and the hover and current-page highlight. A single item can
+                          override the highlight in its own editor.</li>
+                      <li><strong>Binding</strong> - let this menu take a slot over on some pages only (a project's
+                          pages, or pages matching a pattern such as <code>/shop/*</code>) while the menu mapped
+                          under Menu locations shows everywhere else. The most specific match wins.</li>
+                      <li><strong>Meta</strong> - the menu's id, which is its file name and what
+                          <code>[menu slug="..."]</code> names.</li>
+                  </ul>
+
+                  <h3>Links</h3>
+                  <p>Use a site path (<code>/about</code>) for your own pages or a full <code>https://</code> address
+                      for another site. An item with no link and sub-items is a heading. When you rename a page in
+                      the page editor, every menu link to it follows it to the new address.</p>
+
+                  <h3>Who sees an item</h3>
+                  <p>Each item can be limited to roles, using the same ladder as page visibility: "Member and above",
+                      or "Member only" (<code>=member</code>). Items a visitor may not see are left out of the page
+                      on the server. See <a href="#/docs/usage/users-roles">Users &amp; Roles</a>.</p>
+
+                  <h3>Menus inside pages</h3>
+                  <p>Place any menu in a page with <code>[menu slug="legal" /]</code>, or show whatever a slot holds
+                      with <code>[menu location="footer-primary" /]</code>. See
+                      <a href="#/docs/usage/shortcodes">Shortcodes</a>.</p>
+
+                  <h3>The admin sidebar</h3>
+                  <p>The <code>admin-sidebar</code> menu is this sidebar. In the Menus editor you can move Tools
+                      between folders, rename them, hide them or add links of your own. Dashboard, Menus, Users and
+                      My Profile can be moved but never hidden, so you can always get back from a bad edit.</p>
+
+                  <p>Right-click menus on public pages are a separate feature: <strong>Content &gt; Context
+                      Menus</strong>.</p>
 
     </div>
   </div>

package/admin/js/templates/docs/usage-pages.html

@@ -8,8 +8,8 @@
     <div class="docs-body">
 
 <p>Pages are stored as Markdown files in <code>content/pages/</code>. Each file has a YAML frontmatter
-                      block at
-                      the top followed by the page body in Markdown.</p>
+                      block at the top followed by the page body in Markdown, with shortcodes anywhere in the body.
+                      Edit them at <strong>Content &gt; Pages</strong>.</p>
 
                   <h3>URL mapping</h3>
                   <table class="table table-sm">
@@ -29,39 +29,79 @@
                           <td><code>/about</code></td>
                       </tr>
                       <tr>
-                          <td><code>content/pages/blog/index.md</code></td>
-                          <td><code>/blog</code></td>
+                          <td><code>content/pages/services/index.md</code></td>
+                          <td><code>/services</code></td>
                       </tr>
                       <tr>
-                          <td><code>content/pages/blog/hello-world.md</code></td>
-                          <td><code>/blog/hello-world</code></td>
+                          <td><code>content/pages/services/design.md</code></td>
+                          <td><code>/services/design</code></td>
+                      </tr>
+                      <tr>
+                          <td><code>content/pages/404.md</code></td>
+                          <td>Shown for any missing page, once published</td>
                       </tr>
                       </tbody>
                   </table>
+                  <p>Changing a page's URL Path in the editor moves the file. Menu links to the page follow it,
+                      and SEO (when switched on) adds a redirect from the old address.</p>
 
                   <h3>Frontmatter reference</h3>
                   <pre class="code-block"><code>---
 title: My Page
-description: A short description for SEO meta tags.
-status: published        # published | draft  (draft pages return 404)
-layout: default          # layout name from config/presets.json
-tags: [one, two]         # optional taxonomy
-updatedAt: 2026-03-01    # auto-set on save
+description: A short description for search results.
+status: published        # published | draft
+layout: default          # a layout from config/presets.json
+visibility: public       # public | private | a role | =a role | a list
+project: core            # blank = inherit from the URL
+tags: [one, two]         # editorial tags - weighted in site search
+sortOrder: 99
+category: Guides
+theme: ocean-light       # optional per-page theme
 ---
-
 # Page heading
-
 Your Markdown content goes here.</code></pre>
+                  <p>The editor's <strong>Page Details</strong> tab sets all of these, and the
+                      <strong>SEO</strong> tab sets the page's search title and description.</p>
 
-                  <h3>Drafts</h3>
-                  <p>Pages with <code>status: draft</code> are never served on the public site - they return a 404.
-                      Toggle status
-                      in the Page Editor to publish.</p>
+                  <h3>Drafts and previews</h3>
+                  <p>A page with <code>status: draft</code> answers 404 to visitors. Signed in with permission to
+                      view pages, you see the real page at its real address with a draft banner and a Publish
+                      button. New pages start as drafts.</p>
+                  <ul>
+                      <li><strong>Live Preview</strong> in the editor shows the unsaved page as it will look, at
+                          desktop, tablet or phone width.</li>
+                      <li><strong>Share link</strong> (in Live Preview) makes an expiring link that shows one
+                          unpublished page to someone with no account. You can withdraw it at any time.</li>
+                  </ul>
+
+                  <h3>Who can see a page</h3>
+                  <p><code>visibility</code> takes <code>public</code> (the default), <code>private</code> (the
+                      level-0 role only), a role name ("that role and above"), <code>=role</code> ("that role
+                      only"), or a list of these. A visitor who may not see a page gets a 403. A page in a disabled
+                      project answers 404 to everyone. See <a href="#/docs/usage/users-roles">Users &amp;
+                      Roles</a> for how the role ladder works.</p>
+
+                  <h3>Navigation</h3>
+                  <p>A page is added to the navbar or footer in <strong>Content &gt; Menus</strong>, not in the page
+                      editor. See <a href="#/docs/usage/navigation">Navigation</a>.</p>
 
                   <h3>Layouts</h3>
-                  <p>Layouts are defined in <code>config/presets.json</code> and apply CSS class wrappers around page
-                      content.
-                      Select a layout per-page in the editor, or change the default in Site Settings.</p>
+                  <p>Layouts are defined in <code>config/presets.json</code>: <code>default</code>,
+                      <code>with-sidebar</code>, <code>minimal</code>, <code>blank</code>, <code>landing</code>,
+                      <code>article</code>, <code>product</code>, <code>dashboard</code> and <code>wide</code>. Pick
+                      one per page in the editor; new pages use <code>default</code>
+                      (<code>pageDefaults</code> in <code>config/content.json</code>). Manage them at
+                      <strong>System &gt; Layouts</strong>.</p>
+
+                  <h3>History</h3>
+                  <p>Every save keeps a version. The editor's <strong>History</strong> tab lists them with their
+                      date and time (dd/mm/yyyy HH:mm) and lets you compare it with the editor, restore or delete it, or save a named version. Restoring saves a snapshot of the current page first. Unsaved
+                      work is kept as a draft in your browser and offered back if you return.</p>
+
+                  <h3>Custom CSS</h3>
+                  <p>The editor's CSS pane edits <code>content/custom.css</code>, which applies to the whole site,
+                      not just the page you are on. It is also under <strong>System &gt; Site Settings &gt; Custom
+                      CSS</strong>.</p>
 
     </div>
   </div>

package/admin/js/templates/docs/usage-plugins.html

@@ -7,29 +7,101 @@
   <div class="col-12">
     <div class="docs-body">
 
-<p>Plugins extend the CMS with new server routes, admin views, and public-site injection snippets.
-                      Each plugin
-                      is a directory under <code>plugins/</code>.</p>
+<p>Plugins add features to the CMS: new admin screens, server routes, shortcodes and public-site
+                      scripts. You get them from the <strong>Marketplace</strong> - <strong>System &gt;
+                      Plugins</strong> in the sidebar (<code>#/plugins</code>). Once switched on, a plugin is a Tool
+                      and has its own place in the sidebar. Each plugin lives in a folder under
+                      <code>plugins/</code>.</p>
 
-                  <h3>Enabling and disabling</h3>
-                  <p>Use the Plugins page in the admin to toggle plugins on or off. State is saved to
-                      <code>config/plugins.json</code>. <strong>A server restart is required for changes to take
-                          effect.</strong>
-                  </p>
+                  <h3>The Marketplace screen</h3>
+                  <ul>
+                      <li><strong>Installed</strong> lists what is on this site. The built-in Tools come first, then
+                          your plugins, with filters for All, On, Off and Needs attention (a plugin that is on but
+                          not licensed, or waiting for something it needs).</li>
+                      <li>Click a plugin for its details and settings. Right-click it (or use the row menu, or
+                          Shift+F10) to switch it on or off, configure, update, view its source, export it as a
+                          <code>.dcmsplugin</code> file or uninstall it. Licensed plugins cannot be viewed or
+                          exported.</li>
+                      <li><strong>Browse</strong> lists what this site can get from its manager, with an Update
+                          button where a newer version is available. A site that is not managed installs from a
+                          file instead: <strong>Install from file</strong> in the banner.</li>
+                  </ul>
+
+                  <h3>Installing and updating</h3>
+                  <ul>
+                      <li>A new plugin arrives <strong>switched off</strong>. Switch it on when you are ready.</li>
+                      <li>A paid plugin installed from Browse arrives licensed to this site. A plugin that is on
+                          but has no valid licence does not run, and the Marketplace says so.</li>
+                      <li>An update keeps the plugin's data. If it fails, the version you had is put back.</li>
+                      <li>A plugin that needs a newer Domma CMS (its <code>minCmsVersion</code>) is refused, naming
+                          both versions - update the CMS first. An update refused this way leaves the installed
+                          version in place.</li>
+                      <li>Installing an unsigned file, replacing a newer version with an older one, or updating
+                          one already installed each asks you first. A site with
+                          <code>requireSignedPlugins</code> set in <code>config/server.json</code> refuses unsigned
+                          files outright.</li>
+                      <li>Uninstalling removes the plugin's files and its <code>data/</code> folder, and any roles
+                          it added (their users move to <code>user</code>). Switch a plugin off instead if you may
+                          want it back.</li>
+                      <li>Some plugins rely on extra npm packages (listed as <code>npmDependencies</code> in the
+                          catalogue). The CMS does not install these for you - if a plugin says a package is
+                          missing, ask whoever runs your server.</li>
+                  </ul>
+
+                  <h3>When a restart is needed</h3>
+                  <p>A plugin's routes and screens are read when the server starts, so:</p>
+                  <ul>
+                      <li><strong>Switching a plugin on or off</strong> restarts the server for you when something
+                          will bring it back (pm2 or the Domma manager). The screen waits and tells you when the
+                          site is live again. Several switches in a row cost one restart. Set
+                          <code>restartOnPluginToggle: false</code> in <code>config/server.json</code> to restart by
+                          hand instead.</li>
+                      <li><strong>Installing, updating or uninstalling</strong> takes effect after the next
+                          restart - the screen tells you when one is due.</li>
+                      <li><strong>Saving a plugin's settings</strong> never restarts anything.</li>
+                  </ul>
+
+                  <h3>Built-in Tools and switches</h3>
+                  <p>Contacts, Notes, Todo, Analytics and SEO are part of the CMS and on unless you switch them off
+                      at the top of the Installed tab. A Tool that is off disappears from the sidebar and its
+                      screens and API stop answering, but nothing is deleted: switch it back on and everything is
+                      where it was. A switch marked <strong>Locked</strong> is held by your site's manager and can
+                      only be changed there.</p>
+
+                  <h3>What plugins depend on</h3>
+                  <ul>
+                      <li><strong>Requires</strong> - a plugin that cannot work without a Tool or another plugin
+                          goes off with it. Switching it on switches on what it needs.</li>
+                      <li><strong>Uses</strong> - a plugin that only uses something (Calendar invites contact
+                          groups) stays on, and you are told which feature it loses.</li>
+                      <li>You are shown what a switch will change, and asked, before anything moves. A plugin whose
+                          requirement is off is not started.</li>
+                      <li><strong>Supersedes</strong> - a Pro edition replaces the free one it supersedes (Blog Pro
+                          and Blog): while the Pro plugin runs, the free one registers nothing. A Pro plugin can
+                          also take over a built-in Tool's screen (Contacts Pro and Contacts). Nothing is written
+                          down, so if a licence lapses the free plugin or built-in Tool is simply back after the
+                          next restart, with its data.</li>
+                  </ul>
 
                   <h3>Plugin settings</h3>
-                  <p>Plugins that expose a settings page will appear as a link in the sidebar under the Plugins section.
-                      Settings
-                      are merged with the plugin's defaults from <code>config.js</code> and saved to
-                      <code>config/plugins.json</code>.</p>
+                  <p>Open a plugin and choose Configure. Settings are merged with the plugin's defaults and saved to
+                      <code>config/plugins.json</code>. Many plugins also have a settings cog in their own screen's
+                      banner.</p>
 
                   <h3>Security</h3>
-                  <p>Only files inside a plugin's <code>admin/</code> and <code>public/</code> subdirectories are served
-                      statically. Server files (<code>plugin.js</code>, <code>config.js</code>, <code>data/</code>) are
-                      blocked and
-                      return 404.</p>
+                  <p>Only files inside a plugin's <code>admin/</code> and <code>public/</code> folders are served to
+                      browsers. Server files (<code>plugin.js</code>, <code>config.js</code>, <code>data/</code>)
+                      are never served. A plugin's code runs on your server with full access, which is why unsigned
+                      files ask before installing.</p>
 
-                  <p>See the <a href="#/tutorials">Tutorials</a> section for a guide to writing your own plugin.</p>
+                  <h3>See also</h3>
+                  <ul>
+                      <li><a href="#/docs/plugins">Plugin guides</a> - one page per installed Marketplace plugin:
+                          what it does, its screens, settings and permissions.</li>
+                      <li><a href="#/docs/usage/editions">Editions &amp; Licences</a> - free and Pro, rental and
+                          perpetual licences, and what happens when one ends.</li>
+                      <li><a href="#/tutorials/plugin">Writing a Plugin</a> - build your own.</li>
+                  </ul>
 
     </div>
   </div>