domma-cms 0.92.1 → 0.94.0

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

@@ -101,7 +101,6 @@
                   <pre><code>[box]
 Any content - text, a button, a [grid] or a [card].
 [/box]
-
 [box shadow="md" rounded="lg" padding="spacious"]
 Lifted off the page, with rounder corners.
 [/box]</code></pre>
@@ -675,24 +674,79 @@ Body content in **Markdown** is supported.
                       <tr>
                           <td><code>[hero variant="dark" size="sm"]...[/hero]</code></td>
                           <td>Full-width hero section; supports <code>twinkle</code>, <code>blobs</code>,
-                              <code>image</code>, <code>overlay</code></td>
+                              <code>image</code>, <code>overlay</code>, <code>color</code>, <code>min-height</code></td>
+                      </tr>
+                      <tr>
+                          <td><code>[banner type="warning" title="..." icon="..." dismissible]...[/banner]</code></td>
+                          <td>An alert strip: <code>info</code>, <code>success</code>, <code>warning</code>,
+                              <code>danger</code> or <code>neutral</code></td>
+                      </tr>
+                      <tr>
+                          <td><code>[listgroup variant="flush"][item]...[/item][/listgroup]</code></td>
+                          <td>A list group; <code>variant</code> flush, numbered or horizontal</td>
                       </tr>
                       <tr>
                           <td><code>[table striped="true"]...[/table]</code></td>
                           <td>Wraps a GFM Markdown table with Domma table CSS classes</td>
                       </tr>
+                      <tr>
+                          <td><code>[text size="xl" bold color="primary"]...[/text]</code></td>
+                          <td>Styled inline text</td>
+                      </tr>
+                      <tr>
+                          <td><code>[button href="/contact" variant="primary"]...[/button]</code></td>
+                          <td>A link styled as a button</td>
+                      </tr>
+                      <tr>
+                          <td><code>[link href="/about" icon="arrow-right"]...[/link]</code></td>
+                          <td>A link with an icon or target</td>
+                      </tr>
+                      <tr>
+                          <td><code>[center]...[/center]</code></td>
+                          <td>Centres its content</td>
+                      </tr>
+                      <tr>
+                          <td><code>[embed url="https://youtu.be/..." /]</code></td>
+                          <td>YouTube, Vimeo, an uploaded video, or a page from a host allowed in
+                              <code>config/embeds.json</code></td>
+                      </tr>
                       <tr>
                           <td><code>[form name="slug" /]</code></td>
-                          <td>Embeds a Form Builder form by slug</td>
+                          <td>Embeds a form from <strong>Data &gt; Forms</strong></td>
+                      </tr>
+                      <tr>
+                          <td><code>[menu slug="legal" /]</code></td>
+                          <td>Places a menu, or <code>location="..."</code> whatever a slot holds</td>
+                      </tr>
+                      <tr>
+                          <td><code>[block template="post-card" title="..." /]</code></td>
+                          <td>Renders one block template from <strong>Data &gt; Blocks</strong> with the values given.
+                              A block can also be written as its own tag, <code>[post-card title="..." /]</code></td>
+                      </tr>
+                      <tr>
+                          <td><code>[component name="counter" /]</code></td>
+                          <td>Mounts a component from <strong>Data &gt; Components</strong> (same as
+                              <code>&lt;dm-counter&gt;</code>)</td>
+                      </tr>
+                      <tr>
+                          <td><code>[demo src="elements/accordion" /]</code></td>
+                          <td>Embeds a demo page from this site in a frame</td>
+                      </tr>
+                      <tr>
+                          <td><code>[collection slug="..." /]</code></td>
+                          <td>Shows a collection's entries - see below</td>
                       </tr>
                       <tr>
-                          <td><code>[collection slug="..." display="table" /]</code></td>
-                          <td>Renders collection entries inline (table, cards, list, accordion, or block)</td>
+                          <td><code>[view slug="..." /]</code></td>
+                          <td>Shows a saved View's results - see <a href="#/docs/usage/views">Views</a></td>
                       </tr>
                       </tbody>
                   </table>
 
-                  <h4>Collection attributes</h4>
+                  <h3>Collections on a page</h3>
+                  <pre class="code-block"><code>[collection slug="team" display="cards" columns="3" title-field="name" /]
+[collection slug="jobs" display="cards" searchable filterable="location,type" sortable page-size="9" where_status="open" /]
+[collection slug="applications" scope="mine" display="cards" title-field="jobTitle" paginate transitions /]</code></pre>
                   <table class="table table-sm">
                       <thead>
                       <tr>
@@ -705,75 +759,78 @@ Body content in **Markdown** is supported.
                       <tr>
                           <td><code>slug</code></td>
                           <td>collection slug</td>
-                          <td>Required. Which collection to render.</td>
+                          <td>Required. Which collection to show.</td>
                       </tr>
                       <tr>
                           <td><code>display</code></td>
                           <td><code>table</code> &middot; <code>cards</code> &middot; <code>list</code> &middot;
-                              <code>accordion</code> &middot; <code>block</code></td>
-                          <td>How to render each entry. Default <code>table</code>.</td>
+                              <code>accordion</code> &middot; <code>timeline</code> &middot; <code>carousel</code>
+                              &middot; <code>listgroup</code> &middot; <code>block</code></td>
+                          <td>How each entry is shown. Default <code>table</code>.</td>
                       </tr>
                       <tr>
                           <td><code>block</code></td>
                           <td>block template name</td>
-                          <td>Required when <code>display="block"</code>. Names a template in
-                              <code>content/blocks/&lt;name&gt;.html</code> whose
-                              <code>{{field}}</code> placeholders get substituted per entry.
-                          </td>
+                          <td>Required with <code>display="block"</code>; also works with carousel and listgroup.
+                              The template's <code>&#123;&#123;field&#125;&#125;</code> placeholders are filled per entry.</td>
                       </tr>
                       <tr>
-                          <td><code>cols</code></td>
-                          <td><code>2</code> &middot; <code>3</code> &middot; <code>4</code> &middot; <code>5</code>
-                              &middot; <code>6</code></td>
-                          <td>Grid column count when <code>display="block"</code>.</td>
+                          <td><code>fields</code>, <code>title-field</code>, <code>columns</code></td>
+                          <td>field names, 2-4</td>
+                          <td>Which fields show, which one is the title, and card columns.</td>
                       </tr>
                       <tr>
-                          <td><code>where</code></td>
-                          <td><code>field=value</code> or<br><code>f1=v1,f2=v2</code></td>
-                          <td>Row filter (simple equality only, AND'd across comma-separated predicates). Example:
-                              <code>where="tab=developers"</code> or
-                              <code>where="tier=free,featured=true"</code>. No OR, no comparison operators -
-                              use a saved View for anything more complex.
-                          </td>
+                          <td><code>sort</code>, <code>order</code>, <code>limit</code></td>
+                          <td>field, <code>asc</code>/<code>desc</code>, number</td>
+                          <td>Default newest first (<code>createdAt</code>, <code>desc</code>), no limit.</td>
                       </tr>
                       <tr>
-                          <td><code>sort</code></td>
-                          <td>field name or <code>createdAt</code></td>
-                          <td>Sort field. Default <code>createdAt</code>.</td>
+                          <td><code>where_&lt;field&gt;</code></td>
+                          <td>value</td>
+                          <td>Filter: <code>where_location="London"</code>, or add an operator -
+                              <code>_ne</code>, <code>_gt</code>, <code>_gte</code>, <code>_lt</code>, <code>_lte</code>,
+                              <code>_in</code>, <code>_nin</code>, <code>_contains</code>, <code>_starts</code>,
+                              <code>_ends</code>, <code>_exists</code>. Filters combine with AND. The older
+                              <code>where="field=value"</code> still works.</td>
                       </tr>
                       <tr>
-                          <td><code>order</code></td>
-                          <td><code>asc</code> &middot; <code>desc</code></td>
-                          <td>Sort direction. Default <code>desc</code>.</td>
+                          <td><code>scope</code></td>
+                          <td><code>mine</code></td>
+                          <td>Only the signed-in visitor's own entries; anonymous visitors are asked to sign in.</td>
                       </tr>
                       <tr>
-                          <td><code>limit</code></td>
-                          <td>integer</td>
-                          <td>Maximum number of entries to render. 0 or omitted = all.</td>
+                          <td><code>searchable</code>, <code>sortable</code>, <code>filterable</code>,
+                              <code>paginate</code></td>
+                          <td>flags; <code>filterable="a,b"</code></td>
+                          <td>Any of these turns the block into the interactive <strong>Collection Browser</strong>:
+                              search box, sort, a filter rail built from the fields, and pages
+                              (<code>page-size</code>, default 12). <code>exportable</code> adds a CSV button.</td>
                       </tr>
                       <tr>
-                          <td><code>fields</code></td>
-                          <td>comma-separated field names</td>
-                          <td>Column filter - only these fields are shown (table/cards/list displays only).
-                          </td>
+                          <td><code>transitions</code></td>
+                          <td>flag</td>
+                          <td>On an interactive block, each row gets buttons for the workflow actions that apply to
+                              it now. Works with <code>scope="mine"</code>. See
+                              <a href="#/docs/usage/actions">Actions</a>.</td>
                       </tr>
                       <tr>
-                          <td><code>title-field</code></td>
-                          <td>field name</td>
-                          <td>Which field to use as the entry title (cards/accordion displays).</td>
+                          <td><code>cta</code></td>
+                          <td>action slug</td>
+                          <td>A button per entry that runs a CMS Action. See
+                              <a href="#/docs/usage/cta-shortcode">CTA Shortcode</a>.</td>
                       </tr>
                       <tr>
                           <td><code>empty</code></td>
-                          <td>string</td>
-                          <td>Message shown when the filter matches no entries.</td>
-                      </tr>
-                      <tr>
-                          <td><code>cta</code></td>
-                          <td>action slug</td>
-                          <td>Attach a CMS Action button to each rendered entry. See CTA attributes below.</td>
+                          <td>text</td>
+                          <td>Shown when nothing matches.</td>
                       </tr>
                       </tbody>
                   </table>
+                  <p>Timelines take <code>date-field</code>, <code>status-field</code>, <code>body-field</code>;
+                      carousels take <code>image-field</code> and <code>body-field</code>. Visitors can right-click
+                      any collection display to filter, sort, group, copy, print or export it (export follows the
+                      collection's export setting), and the state is kept in the address so it can be shared.
+                      Dates in collection displays read dd/mm/yyyy.</p>
 
                   <h3>Form follow-up</h3>
                   <p>Two optional settings control what happens after a submission is stored:</p>
@@ -803,7 +860,7 @@ Body content in **Markdown** is supported.
                       <tr>
                           <td><code>actionSlug</code></td>
                           <td>Actions tab → CMS Action</td>
-                          <td>Slug of a CMS Action to execute after the entry is stored. Requires Pro (MongoDB).
+                          <td>Slug of a CMS Action to execute after the entry is stored. Actions need MongoDB (Pro).
                               Non-fatal on failure.
                           </td>
                       </tr>
@@ -832,29 +889,25 @@ Body content in **Markdown** is supported.
                       </tbody>
                   </table>
 
-                  <h3>Pro shortcodes</h3>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Shortcode</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>[view slug="..." display="table" /]</code></td>
-                          <td>Executes a saved View and renders results. Requires MongoDB.</td>
-                      </tr>
-                      <tr>
-                          <td><code>[cta action="..." entry="..."]Label[/cta]</code></td>
-                          <td>Action-trigger button. Requires the visitor to be logged in.</td>
-                      </tr>
-                      </tbody>
-                  </table>
+                  <h3>Effects</h3>
+                  <p>Effects wrap content or run on the whole page: <code>[reveal]</code>, <code>[breathe]</code>,
+                      <code>[pulse]</code>, <code>[shake]</code>, <code>[scribe]</code>, <code>[scramble]</code>,
+                      <code>[counter]</code>, <code>[ripple]</code>, <code>[twinkle]</code>,
+                      <code>[ticker-tape]</code>, <code>[butterflies]</code>, <code>[strobe]</code>,
+                      <code>[animate]</code>, <code>[ambient]</code>, <code>[firework]</code>,
+                      <code>[fireworks]</code> and <code>[celebrate]</code> (with shorthands such as
+                      <code>[christmas /]</code>). Many can also be added to a card, box, hero, banner, column or
+                      button as attributes: <code>[card reveal reveal-animation="zoom"]</code>. Settings are at
+                      <strong>System &gt; Effects</strong>.</p>
+
+                  <h3>Actions on pages</h3>
+                  <p><code>[cta action="..." entry="..."]Label[/cta]</code> places a button that runs a CMS Action
+                      for a signed-in visitor. Actions need a MongoDB connection (Pro); collections, views and
+                      everything else on this page work without one.</p>
 
-                  <p>Full attribute reference and live demos: <a href="/resources/shortcodes" target="_blank">Shortcode
-                      Reference</a> · <a href="/resources/components" target="_blank">Components</a> · <a
-                          href="/resources/effects" target="_blank">Effects</a></p>
+                  <p>The page editor's Editor Reference lists every shortcode with its attributes, and its Insert
+                      menu adds them for you. Plugins can add shortcodes of their own - see
+                      <a href="#/docs/plugins">Plugin guides</a>.</p>
 
     </div>
   </div>

package/admin/js/templates/docs/usage-site-settings.html

@@ -7,45 +7,77 @@
   <div class="col-12">
     <div class="docs-body">
 
-<p>Site Settings are stored in <code>config/site.json</code> and editable from the Settings page in
-                      the admin
-                      panel.</p>
+<p>Site Settings are at <strong>System &gt; Site Settings</strong> and are stored in
+                      <code>config/site.json</code>. Themes and fonts have their own screen, <strong>Content &gt;
+                      Theme</strong>.</p>
 
                   <table class="table table-sm">
                       <thead>
                       <tr>
-                          <th>Field</th>
-                          <th>Description</th>
+                          <th>Tab</th>
+                          <th>What it holds</th>
                       </tr>
                       </thead>
                       <tbody>
                       <tr>
-                          <td><code>siteName</code></td>
-                          <td>Site title used in the public navbar and browser tab.</td>
+                          <td>General</td>
+                          <td>Site title and tagline; <strong>Site URL</strong> (the site's real address, used for
+                              password reset links, canonical links and the sitemap - set it); <strong>Admin
+                              home</strong> (the screen the admin opens on); the default spacer size.</td>
                       </tr>
                       <tr>
-                          <td><code>tagline</code></td>
-                          <td>Subtitle shown in the public site footer.</td>
+                          <td>SEO</td>
+                          <td>Default page title, title separator and default description. The full SEO Tool is
+                              <strong>SEO</strong> in the sidebar.</td>
                       </tr>
                       <tr>
-                          <td><code>adminTheme</code></td>
-                          <td>Admin panel colour theme (e.g. <code>charcoal-dark</code>, <code>ocean-light</code>).</td>
+                          <td>Footer</td>
+                          <td>Copyright text, social links, and whether visitors get a "Reduce motion" switch.
+                              Footer links are menus - see <a href="#/docs/usage/navigation">Navigation</a>.</td>
                       </tr>
                       <tr>
-                          <td><code>publicTheme</code></td>
-                          <td>Public site theme applied to <code>&lt;html data-theme&gt;</code>.</td>
+                          <td>Email</td>
+                          <td>The SMTP server the site sends mail through (form notifications, password resets,
+                              action emails). Without it, "Forgot your password?" cannot send a link.</td>
                       </tr>
                       <tr>
-                          <td><code>defaultLayout</code></td>
-                          <td>Fallback layout for pages that don't specify one.</td>
+                          <td>Back to top, Cookie consent, Breadcrumbs</td>
+                          <td>Switch each on or off and set its wording and position.</td>
+                      </tr>
+                      <tr>
+                          <td>Custom CSS</td>
+                          <td><code>content/custom.css</code>, applied to every public page after the theme.</td>
+                      </tr>
+                      <tr>
+                          <td>Cache</td>
+                          <td>The public page cache: switch it on or off, clear it, and see what it holds. Saving a page clears what it affects automatically.</td>
                       </tr>
                       </tbody>
                   </table>
 
+                  <h3>Theme</h3>
+                  <p><strong>Content &gt; Theme</strong> (stored in <code>config/theme.json</code>) sets the public
+                      theme, the admin theme, fonts, the visitor theme switcher, automatic day and night themes (at
+                      the clock times you choose) and per-element overrides. A page can override the theme in its
+                      Page Details.</p>
+
+                  <h3>Dates and times</h3>
+                  <p>The admin shows dates as dd/mm/yyyy and times on a 24-hour clock (dd/mm/yyyy HH:mm), whatever
+                      the browser's language. Recent items may read "3 days ago" or "tomorrow at 09:00". Stored
+                      values, API responses, date pickers, feeds and CSV exports keep their own formats. In a block
+                      template, <code>&#123;&#123;field:FORMAT&#125;&#125;</code> formats a date field on the public site.</p>
+
                   <h3>Server configuration</h3>
-                  <p>Low-level settings (port, CORS, upload size) live in <code>config/server.json</code> and require a
-                      server
-                      restart to take effect. These are not editable from the admin panel.</p>
+                  <p>Low-level settings live in <code>config/server.json</code> and need a server restart to take
+                      effect. They are not editable from the admin:</p>
+                  <ul>
+                      <li><code>port</code>, <code>host</code>, <code>cors</code></li>
+                      <li><code>uploads.maxFileSize</code> - the largest upload, in bytes (10 MB by default)</li>
+                      <li><code>restartOnPluginToggle</code> - restart automatically when a plugin is switched on
+                          or off (on by default)</li>
+                      <li><code>requireSignedPlugins</code> - refuse unsigned plugin files</li>
+                  </ul>
+                  <p>Sign-in token lifetimes and password reset link expiry are in <code>config/auth.json</code>.</p>
 
     </div>
   </div>

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

@@ -0,0 +1,73 @@
+<div class="view-header">
+  <h1><span data-icon="book"></span> Built-in Tools</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>Contacts, Notes, Todo, Analytics and SEO are part of the CMS. They sit in the sidebar's Tools folder
+                      and are on unless you switch them off at the top of the Marketplace (<strong>System &gt;
+                      Plugins</strong>). Switching a Tool off hides it and stops its screens and API; nothing is
+                      deleted. Who may use each is a permission under <strong>System &gt; Roles</strong> (Tools
+                      group): only the level-0 role has them all to begin with, and Admin has SEO.</p>
+
+                  <h3>Contacts</h3>
+                  <p>An address book for each user. <strong>Your contacts are private</strong>: nobody else sees
+                      them, admins included. Star favourites, search as you type, and right-click a contact to edit,
+                      email, call, copy, file it in a group, duplicate or delete it.</p>
+                  <p><strong>Groups are shared.</strong> Everyone who uses Contacts has the same list of groups, and
+                      anyone can file their own contacts in any group. Because renaming or deleting a group changes
+                      it for everyone, only the person who created it, or someone holding <strong>Contacts &gt;
+                      Manage groups</strong> (<code>contacts.manageGroups</code>), may do it. The level-0 role holds
+                      it and Admin is given it once. Groups made before 0.93.0 have no recorded creator, so only
+                      holders of the permission can change them. In Manage groups, Rename and Delete are greyed out
+                      where you may not, with a note saying why.</p>
+
+                  <h3>Notes</h3>
+                  <p>Private notes for each user, with categories and search.</p>
+
+                  <h3>Todo</h3>
+                  <p>To-do lists with priorities and due dates. Each morning, anyone with overdue tasks gets one
+                      notification listing them, and one for what is due today. Switch that off under
+                      Notifications &gt; Sources ("To-dos overdue or due today").</p>
+
+                  <h3>Where Notes, Todo and Contacts are stored</h3>
+                  <p>On files, unless the site has a working MongoDB connection (Pro): Notes and Todo then use
+                      MongoDB, as their collections declare; Contacts stay on files. A site is never switched to
+                      an empty store - while the files still hold notes or to-dos they stay on files, and the
+                      server log says so. To settle it, use the collection's <strong>Storage</strong> move, which
+                      keeps every id (see <a href="#/docs/usage/collections">Collections &amp; Forms</a>).</p>
+
+                  <h3>Analytics</h3>
+                  <p>Page views and visitors, counted on your own server - no third-party script. Admin pages, the
+                      API and browsers that ask not to be tracked are never counted. Analytics Pro, in the
+                      Marketplace, adds deeper reports.</p>
+
+                  <h3>SEO</h3>
+                  <p>How the site looks to search engines: an audit of every page with a score, each page's search
+                      result and share card as they will look, titles and descriptions used twice, redirects (added
+                      for you when a page is renamed), the sitemap and robots.txt, and who runs the site. SEO Pro
+                      adds a not-found log, a link monitor and SEO history.</p>
+
+                  <h3>Notifications</h3>
+                  <p>The bell in the admin, and <strong>System &gt; Notifications</strong>. Opening the screen marks
+                      everything read. Its settings choose which <strong>sources</strong> notify which roles, and
+                      whether your browser shows desktop notifications. A notice with no audience goes to admins
+                      and above.</p>
+
+                  <h3>Site search</h3>
+                  <p><strong>System &gt; Search</strong> sets up the search box visitors open from the navbar (or
+                      with Ctrl+K). It searches pages only. Results follow the visitor's roles: a page they may not
+                      open never appears, nor do drafts, <code>noindex</code> pages or pages in a disabled
+                      project.</p>
+
+                  <h3>Plugins</h3>
+                  <p>Tools from the Marketplace (Calendar, Blog, Feedback, Mail Reader and others) join the same
+                      folder when switched on. See <a href="#/docs/plugins">Plugin guides</a> for each one you have
+                      installed, and <a href="#/docs/usage/plugins">Plugins</a> for installing and switching.</p>
+
+    </div>
+  </div>
+</div>

package/admin/js/templates/docs/usage-users-roles.html

@@ -8,12 +8,12 @@
     <div class="docs-body">
 
 <p>Users are stored as individual JSON files in <code>content/users/</code>. Passwords are hashed with
-                      bcrypt and never returned by the API. Manage them at <strong>System &gt; Users</strong>.</p>
+                      bcrypt and never returned by the API. Manage accounts at <strong>System &gt; Users</strong> and
+                      roles at <strong>System &gt; Roles</strong>.</p>
 
                   <h3>Roles</h3>
-                  <p>Roles are data, stored in the <code>roles</code> preset collection and managed at
-                      <strong>System &gt; Roles</strong>. Every site starts with three base roles, which cannot be
-                      deleted:</p>
+                  <p>Roles are data, stored in the <code>roles</code> preset collection. Every site starts with three
+                      base roles, which cannot be deleted:</p>
                   <table class="table table-sm">
                       <thead>
                       <tr>
@@ -26,13 +26,15 @@
                       <tr>
                           <td><strong>Super Admin</strong> (<code>super-admin</code>)</td>
                           <td>0</td>
-                          <td>Everything, including permissions added by plugins.</td>
+                          <td>Everything. The level-0 role holds every permission, including the ones plugins and
+                              built-in Tools add, whatever its permission list says.</td>
                       </tr>
                       <tr>
                           <td><strong>Admin</strong> (<code>admin</code>)</td>
                           <td>1</td>
                           <td>Content, structure, collections, views, actions, users, settings, theme, plugins,
-                              API tokens and endpoints, notifications.</td>
+                              API tokens and endpoints, notifications, SEO, and renaming or deleting any contact
+                              group. Plugins usually grant their own permissions to Admin when first switched on.</td>
                       </tr>
                       <tr>
                           <td><strong>User</strong> (<code>user</code>)</td>
@@ -41,23 +43,100 @@
                       </tr>
                       </tbody>
                   </table>
-                  <p>You can add your own roles (New role on the Roles screen) and plugins can add theirs. Each role has
-                      a level (lower = more senior) and a set of permissions, ticked in a matrix of resources and
-                      actions (view, create, edit, delete). A user has one primary role plus optional additional
-                      roles; a permission check passes if any of their roles grants it. You can only manage users
-                      whose role is less senior than your own.</p>
+                  <p>The built-in Tools (Contacts, Notes, Todo, Analytics) are not given to Admin or User by
+                      default - tick them for the roles that should have them.</p>
 
-                  <h3>Authentication</h3>
-                  <p>The admin panel uses JWT Bearer tokens, stored in the browser and refreshed automatically. By
-                      default an access token lasts 15 minutes and a refresh token 7 days (<code>config/auth.json</code>).
-                      Each sign-in is a session kept on disk, so signing out holds even across a restart; changing a
-                      password signs out that account's other sessions.</p>
+                  <h3>Your own roles</h3>
+                  <p>Add roles with <strong>New role</strong> on the Roles screen. Each role has a
+                      <strong>level</strong> (lower is more senior) and a set of permissions, ticked in a matrix of
+                      resources and actions (View, Create, Edit, Delete, and extras such as Contacts &gt; Manage
+                      groups). Permissions are grouped: Content, Structure, Data, Configuration, Tools, then Plugins.</p>
+                  <ul>
+                      <li><strong>Additional roles.</strong> A user has one primary role and can hold more. A
+                          permission check passes if any role they hold grants it.</li>
+                      <li><strong>Grants only add.</strong> A plugin that grants its permission to a role does it
+                          once. If you untick it afterwards it stays unticked.</li>
+                      <li><strong>Plugin roles.</strong> Some plugins bring roles of their own (the Blog's Blog Author
+                          and Blog Editor, for example). They appear on the Roles screen
+                          like any other and you can edit them; the plugin never overwrites your changes.
+                          Switching the plugin off keeps its roles; uninstalling it removes them and moves their users to <code>user</code>.</li>
+                  </ul>
+
+                  <h3>Confining a role to some screens</h3>
+                  <p>A role can be confined to a list of admin screens, with one of them as its home - useful for
+                      people who sign themselves up on the public site. A confined user sees only those screens
+                      in the sidebar, and the server refuses their calls to any plugin API whose screens they
+                      cannot open. A user is confined only when every role they hold is confined: one unconfined
+                      role lifts it. The level-0 role is never confined.</p>
+
+                  <h3>Who can see what: the role ladder</h3>
+                  <p>Pages, menu items, views and actions name the roles they are for. Two forms exist, and the
+                      page and menu editors offer both for every role:</p>
+                  <table class="table table-sm">
+                      <thead>
+                      <tr>
+                          <th>You choose</th>
+                          <th>Stored as</th>
+                          <th>Who gets in</th>
+                      </tr>
+                      </thead>
+                      <tbody>
+                      <tr>
+                          <td>Candidate and above</td>
+                          <td><code>candidate</code></td>
+                          <td>Holders of that role and everyone on the same or a more senior level.</td>
+                      </tr>
+                      <tr>
+                          <td>Candidate only</td>
+                          <td><code>=candidate</code></td>
+                          <td>Holders of that role only (primary or additional), plus the level-0 role. An ordinary
+                              admin does not pass - give them the role as an additional role if they need it.</td>
+                      </tr>
+                      <tr>
+                          <td>Several roles</td>
+                          <td><code>[candidate, employer]</code></td>
+                          <td>Anyone who passes any one of them. Exact and ladder forms mix.</td>
+                      </tr>
+                      <tr>
+                          <td>Private</td>
+                          <td><code>private</code></td>
+                          <td>The level-0 role only.</td>
+                      </tr>
+                      </tbody>
+                  </table>
+                  <p>A role name the site does not have (a role since deleted, or a typo) admits only the level-0
+                      role - never everyone. The collection and action editors flag such a role so you can fix it. A
+                      page a visitor may not see answers 403; a draft answers 404.</p>
+
+                  <h3>Managing users</h3>
+                  <p>You can only create, edit, delete or reset the password of a user whose role is less senior
+                      than yours (a higher level number) - an admin cannot manage another admin. You cannot give
+                      anyone a role more senior than your own.</p>
+                  <p>Right-click a user (or use the row menu) to <strong>Send password reset email</strong>,
+                      <strong>Copy a reset link</strong> (for a site without email) or <strong>Withdraw the reset
+                      link</strong>. The account holder is emailed whenever their password changes.</p>
+
+                  <h3>Passwords and sign-in</h3>
+                  <p>The core rule is at least 8 characters. The free Security plugin, when switched on, adds stricter
+                      password rules, sign-in lockout and a log of every sign-in; Security Pro adds two-factor
+                      sign-in and a list of every signed-in session.
+                      "Forgot your password?" works only when the site can send email (Site Settings &gt; Email);
+                      without it the sign-in screen tells the person to ask an administrator.</p>
+                  <p>The admin panel uses JWT Bearer tokens, refreshed automatically. By default an access token
+                      lasts 15 minutes and a refresh token 7 days (<code>config/auth.json</code>). Each sign-in is a
+                      session kept on disk, so signing out holds even across a restart; changing a password signs
+                      out that account's other sessions.</p>
 
                   <h3>Views &amp; Actions</h3>
-                  <p>Access to Views and Actions is controlled by the <code>views</code> and <code>actions</code>
-                      permissions. Super Admin and Admin hold both by default; the User role holds neither. Grant
-                      them to a custom role in the role editor. Views work on every storage adapter; Actions need a
-                      MongoDB connection.</p>
+                  <p>Building Views and Actions is controlled by the <code>views</code> and <code>actions</code>
+                      permissions. Super Admin and Admin hold both by default; the User role holds neither. Who may
+                      read a view or run an action is set on the view or action itself (its Access tab), using the
+                      role ladder above - any listed role is enough. Views work on every storage adapter; Actions
+                      need a MongoDB connection.</p>
+
+                  <p>See also: <a href="#/docs/usage/editions">Editions &amp; Licences</a> for what the free and
+                      Pro editions include, and <a href="#/docs/plugins">Plugin guides</a> for the roles and
+                      permissions each installed plugin adds.</p>
 
     </div>
   </div>