domma-cms 0.93.0 → 0.94.0

package/plugins/blog/docs/guide.md

@@ -0,0 +1,205 @@
+Blog adds a public blog to your site: posts with categories and tags, scheduled publishing, optional comments, an RSS feed and a choice of looks. Writers can draft posts; editors publish them.
+
+## What it does
+
+- Posts written in Markdown, with an excerpt, featured image, categories, tags and search-engine fields.
+- Drafts, publishing now, and scheduling for a later date and time.
+- Categories, each with its own page on the site.
+- Optional reader comments, held for approval if you want.
+- Six post layouts and four listing displays, all editable as blocks.
+- An RSS feed, and pages for each category, tag and author.
+- Shortcodes to show recent posts, a grid, a featured post or the category list on any page.
+- A **Blog** link added to your navbar when the plugin is turned on.
+
+## Getting started
+
+1. Open [Blog](#/plugins/blog) from the admin sidebar.
+2. Optional: click the three-dot button beside **New post** and choose **Add sample posts** to see how the blog looks before you write anything (admins only). Remove them later from the same menu.
+3. Click **New post**.
+4. Enter a **Title** and write the **Content**.
+5. Add an **Excerpt**, **Categories**, **Tags** and a **Featured Image** if you like.
+6. Click **Publish** to put it live now, or **Schedule** to pick a date and time. **Save** keeps it as a draft.
+7. Visit `/blog` on your site to see it.
+
+## Screens
+
+The sidebar **Blog** item opens **Posts**, **Categories** and **Comments**. Every Blog screen has a **Blog settings** cog in the banner.
+
+### Posts
+
+- Figure chips at the top show **All**, **Published**, **Drafts** and **Scheduled**. Click one to show only those.
+- Search matches titles, excerpts and slugs. Filter by category, and sort by **Newest first**, **Oldest first** or **Title, A to Z**. **Clear filters** resets them.
+- Right-click a post (or use its three-dot button) for **Edit**, **View on site**, **Copy link**, **Publish now**, **Unpublish**, **Duplicate as draft** and **Delete**.
+- The three-dot button beside **New post** has **View the blog**, **Edit layouts in Blocks**, and **Add sample posts** or **Remove sample posts** (admins only). Removing samples removes only the sample posts, and sample categories nothing else uses.
+
+Writers without the Publish permission see only their own posts.
+
+### Post editor
+
+| Field | What it does |
+|---|---|
+| Title | Required. |
+| Slug | The last part of the post's address, for example `my-first-post`. With **Auto** ticked it follows the title. Changing it on a published post breaks links to the old address. |
+| Excerpt | A sentence or two shown in listings. Also used as the search-engine description when **SEO Description** is empty. |
+| Content | Markdown. Every shortcode the site supports works here too. |
+| SEO Title / SEO Description | What search engines and link previews show. Leave empty to use the title and excerpt. |
+| Post layout | **Site default** (follows Blog settings) or a layout of its own. |
+| Categories | Type to find one, or click the box to see them all. A post can be in several. |
+| Tags | Type a tag and press Enter or a comma. Tags already used on other posts are suggested. Each tag gets its own page. |
+| Featured Image | Shown at the top of the post and in listings. **Pick Image** opens the Media library; **Clear** removes it. |
+
+The buttons:
+
+- **Save** (or Ctrl+S) stores your changes and keeps the post as it is. A draft stays a draft; a live post stays live and updates.
+- **Publish** puts it on the site now.
+- **Schedule** picks a date and time. The post goes live by itself when that time passes.
+- **Move to drafts** takes a live or scheduled post off the site.
+- **Preview** shows the post as readers will see it, in any layout, before you save.
+
+The **Status** card shows the status, the scheduled or published date, when it was last saved and when it was created.
+
+### Categories
+
+Lists every category with its post count. Click **New category** and enter a **Name**, **Slug** and optional **Description**. Each category has a page at `/blog/category/<slug>`.
+
+Right-click a category (or use its three-dot button) for **Edit**, **Show its posts**, **View on site** and **Delete**.
+
+### Comments
+
+- Filter by **Pending**, **Approved**, **Rejected**, **Spam** or **All**, and search.
+- **Approve all pending** approves every waiting comment at once.
+- Click a comment to read all of it. Right-click it (or use its three-dot button) for **Approve**, **Back to pending**, **Reject**, **Mark as spam**, **Open the post**, **Reply by email** and **Delete**.
+
+Only approved comments appear on the site. If comments are switched off, the screen says so and links to **Blog settings**.
+
+## The public blog
+
+These pages are served under the blog's base path (default `/blog`):
+
+| Address | What it shows |
+|---|---|
+| `/blog` | The newest posts, with paging (`/blog/page/2` and so on). |
+| `/blog/<slug>` | One post. |
+| `/blog/category/<slug>` | Posts in a category. |
+| `/blog/tag/<tag>` | Posts with a tag. |
+| `/blog/author/<id>` | Posts by one author. |
+| `/blog/feed.xml` | The RSS feed. |
+
+Depending on the layout, post pages show reading time, a contents list, share links, newer and older post links, related posts and, when switched on, comments with a comment form (name, email and comment; the email is never shown).
+
+Listings can offer readers a search box, category filters, sorting, a display switch and a right-click menu on each post (more in this category, more with this tag, more by this author), all without reloading. Blogs with more than 300 posts page normally instead.
+
+## Settings
+
+Click the **Blog settings** cog in the banner. Only admins can save changes.
+
+| Setting | What it does |
+|---|---|
+| Base path | The address every blog page lives under. `/blog` gives `/blog/my-post`. Applies as soon as you save. The navbar link Blog added moves with it; links typed into pages do not. |
+| Posts per page | How many posts a listing page shows. Default 10. |
+| RSS feed length | How many of the newest posts the feed carries. Default 20. |
+| Comments | Readers can leave a comment under each post. Off by default. Turning it off hides the form; existing comments stay. |
+| Hold comments for approval | New comments wait under Comments > Pending until approved. On by default. |
+| Post layout | How a post looks unless it picks its own. |
+| Listing display | How the blog index and the category, tag and author pages show posts. |
+| Readers can switch display | Shows a Cards / List / Magazine / Compact switch above listings. A reader's choice is remembered in their browser. |
+| Search and filter in the page | Adds the search box, category pills, sorting and right-click menu to listings. |
+| Related posts | How many posts sharing a category or tag are suggested under each post. 0 turns them off. Default 3. |
+
+### Post layouts
+
+| Layout | Look |
+|---|---|
+| Classic | Title, image, then the story in one centred column. The default. |
+| Feature | A full-width hero image with the title over it. |
+| Minimal | Just the words: a narrow reading column, no image. |
+| Sidebar | The story beside a contents list, details and share links. |
+| Split | The picture on one half, the headline on the other. |
+| Essay | A long read set like print: serif type, a drop cap and pull quotes. |
+
+### Listing displays
+
+| Display | Look |
+|---|---|
+| Cards | A grid of picture cards. The default. |
+| List | One post per row, picture beside the text. |
+| Magazine | The newest post large across the top, the rest as cards. |
+| Compact | Titles and dates only. |
+
+Every layout and display is a block you can edit in **Blocks**: `blog-post-...` for post layouts and `blog-card`, `blog-card-row` and `blog-card-compact` for listings. Copy one under a new name starting `blog-post-` or `blog-card-` (for example `blog-post-long-read`) and it appears as a new choice in the settings and the post editor.
+
+## Shortcodes
+
+Use these on any page.
+
+A list of recent post titles and dates:
+
+```text
+[blog-list count="5" category="news" /]
+```
+
+A grid of post cards with pictures:
+
+```text
+[blog-grid count="6" cols="3" category="news" /]
+```
+
+One post as a large card (leave out `slug` for the newest post):
+
+```text
+[blog-featured slug="my-first-post" /]
+```
+
+A linked list of categories, optionally with post counts:
+
+```text
+[blog-categories show-counts="true" /]
+```
+
+| Attribute | Used by | What it does |
+|---|---|---|
+| `count` (or `limit`) | blog-list, blog-grid | How many posts. Defaults: 5 for the list, 6 for the grid. |
+| `category` | blog-list, blog-grid | Only posts in this category (its slug). |
+| `cols` | blog-grid | Columns, 1 to 4. Default 3. |
+| `slug` | blog-featured | The post to show. |
+| `show-counts` | blog-categories | `true` shows each category's post count. |
+
+## Permissions and roles
+
+Permissions appear in **System > Roles** under the **Blog** group:
+
+| Permission | Actions |
+|---|---|
+| Blog posts (`blog-posts`) | View, Write, Edit, Delete, Publish |
+| Blog categories (`blog-categories`) | View, Create, Edit, Delete |
+| Blog comments (`blog-comments`) | View (includes the commenter's email), Moderate, Delete |
+
+All three are granted to the Admin role. **Publish** also lets a user see and edit everyone's posts; without it, a writer sees and edits only their own.
+
+Blog adds two roles:
+
+- **Blog Author** - writes posts and edits their own, and can pick categories. Cannot publish, schedule, delete or moderate comments.
+- **Blog Editor** - everything: publish, schedule, delete, categories and comments.
+
+Users need the Blog posts View permission to see Blog in the sidebar. Adding and removing sample posts, and saving settings, are for admins only.
+
+## Sidebar badge and notifications
+
+- The **Blog** sidebar item shows how many comments are waiting for approval. Hover it for waiting, published, drafts, scheduled (with the next date) and the latest waiting comments.
+- A comment held for approval raises a notification, which goes to Super Admins unless you change who receives it. It clears when the comment is moderated or deleted.
+
+## Search engines
+
+Blog adds the blog index and every public post to your site's sitemap, and gives each post page its proper address for search engines. Use the SEO fields in the editor to set what search results and link previews show.
+
+## Tips
+
+- Use **Duplicate as draft** to start a new post from an old one.
+- Keep categories few and broad; use tags for the detail.
+- Changing the default **Post layout** changes every post that has not chosen its own.
+
+## Limitations
+
+- Content is written in Markdown. There is no visual editor.
+- There is one blog per site. Several blogs, more layouts, themes, author pages and media embeds are part of Blog Pro.
+- Comment spam protection is a hidden form field. Keep **Hold comments for approval** on if spam is a problem.

package/plugins/blog/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "blog",
   "displayName": "Blog",
-  "version": "1.9.2",
+  "version": "1.9.3",
   "tier": "free",
   "description": "Public-facing blog with posts, categories and comments - layouts and listings built from editable blocks.",
   "author": "Domma CMS",

package/plugins/feedback/docs/guide.md

@@ -0,0 +1,95 @@
+---
+title: Guide
+order: 1
+---
+
+Feedback lets you tell Domma what is broken, missing or good, straight from your admin, and follow what happens to it. It is free.
+
+## What it does
+
+- Sends a report to the Domma team with your name, your site and its CMS version attached, so Domma can reply.
+- Lists every report this site has sent, whoever sent it, with its status.
+- Shows Domma's reply inside the report, and tells you when one arrives.
+- Keeps a report safe if Domma cannot be reached, and sends it as soon as it can.
+
+## Getting started
+
+1. Open [Feedback](#/plugins/feedback) from the admin sidebar.
+2. Click **Send feedback**.
+3. Under **What is it?** pick one: Something is broken, An idea or request, A question, Something we got right, or Something else.
+4. Type a **Title** (one line) and a **Description**.
+5. For something broken, choose **How bad is it?**: Minor - a nuisance, Major - gets in the way, or Blocker - cannot carry on.
+6. Optional: fill in **Where** - the screen or page it is about, for example "Pages" or `/contact`.
+7. Click **Send**.
+
+A good bug report says what you did, what you expected and what happened instead. For a request, say what you are trying to get done.
+
+## Screens
+
+### Your reports
+
+Each row shows the type, title, when it was sent and by whom, and a status:
+
+| Status | Meaning |
+|---|---|
+| New | Domma has it and has not looked yet |
+| Seen | Domma has read it |
+| Planned | It is on the list |
+| In progress | Being worked on |
+| Done | Finished |
+| Not planned | Domma does not intend to do it |
+| Waiting to send | Domma could not be reached yet; it goes automatically |
+| Not accepted | Domma's server turned the report down |
+
+A dot on a row means a new reply. Click a row to open it: you see the details, **What was sent**, and **Domma replied** with the reply, or "No reply yet".
+
+If "Tracked as" appears, Domma has filed the report in its own issue tracker, and the status follows that issue.
+
+When reports are waiting to send, a note says so, with **Try now**.
+
+### Not connected
+
+If the screen says "This site is not connected to Domma", your site was not started by a Domma server, so there is nowhere to send to. Ask whoever set the site up.
+
+## Settings
+
+There is no settings screen. Whoever runs the site can change one option in the plugin's configuration file:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `syncMinutes` | 60 | How often the site sends waiting reports and checks for replies |
+
+Opening the Feedback screen also sends anything waiting and checks for replies straight away.
+
+## Notifications
+
+When Domma replies, you get an admin notification "Domma replied:" followed by the report's title. The sidebar badge counts replies you have not opened; opening the report clears it.
+
+## Permissions and roles
+
+In System > Roles, Feedback appears in the **Plugins** group:
+
+| Action | Label | Allows |
+|---|---|---|
+| `feedback.send` | Send | Send feedback to Domma and see what this site has sent |
+| `feedback.manage` | Manage | Only used on the Domma server (see below) |
+
+Only the **admin** role has them by default. Everyone with **Send** sees every report the site has sent, not just their own.
+
+## On the Domma server
+
+On the Domma server itself (the Manager), the same screen is the **Inbox** of every site's reports, for holders of **Feedback > Manage**:
+
+- Filter by **Open**, each status, or **All**; by site and type; and search title, text, person and site.
+- Open a report to set its **Status**, write a **Reply to the site** (the site sees it and is notified) and keep **Internal notes** (never sent to the site). Click **Save**.
+- With Waypoint Pro installed, **Make a Waypoint issue** files the report in a project with a type and priority. The report then follows the issue: planned, in progress, done. "Not planned" set by hand stays until you change it.
+- Right-click a row to open it, change its status quickly, or **Delete** it. Deleting removes it for the site too.
+- Holders of the most senior role also get **My feedback**, to file their own reports. These appear in the Inbox as "Manager (this server)".
+
+## Limitations
+
+- Only sites started by a Domma server can send. A standalone install cannot.
+- No attachments or screenshots. Describe the problem in words, and use **Where** for the page.
+- Titles are limited to 140 characters and descriptions to 8,000.
+- The Domma server accepts up to 10 reports from one site in 10 minutes. Any more show as **Waiting to send** and go later.
+- You cannot edit or withdraw a report once sent. Send a follow-up instead.

package/plugins/feedback/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "feedback",
   "displayName": "Feedback",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "tier": "free",
   "description": "Tell Domma what is broken, missing or good - straight from your admin - and see what became of it: seen, planned, in progress, done, with Domma's reply.",
   "author": "Domma CMS",

package/plugins/free-tier.lock.json

@@ -1,9 +1,9 @@
 {
   "note": "Written by `make sync-free-tier` in dcms-marketplace. Do not edit these plugins here - edit them there and sync.",
-  "source": "dcms-marketplace@ef02b46",
+  "source": "dcms-marketplace@5dcb9db",
   "plugins": {
     "blog": {
-      "version": "1.9.2",
+      "version": "1.9.3",
       "files": {
         "CLAUDE.md": "926730d510cc38f6764ffcb9afbed1c3ae3a547117c6c0243b14f899271350fb",
         "admin/css/index.css": "6142a6b756e1218157842528830b1e84f592f0b84b7d5ce6449db421b6f4b039",
@@ -41,6 +41,7 @@
         "collections/comments/schema.json": "29cbd289cbfcfc4158c9357a218db4ce06eddc3370bfbf9afb7d7f52065a849e",
         "collections/posts/schema.json": "19a5a770d3eefea73f4117454bd1312a7a7e3d727cfcdfde141139fbc81cabd7",
         "config.js": "ee67396262762f5c31269d258affd75f7392a3e364f72f7792c2f1cdafd94bba",
+        "docs/guide.md": "6a7466881851797789a18e0d32c4fcb515f2259b110948c55be03923c38e0de5",
         "lib/access.js": "af47440c7233a56000641a3231d7e9ff81b12f40dfb9528aa6dd4e2dd9bca8df",
         "lib/layouts.js": "0a921fb427c5ffe0a31eb687a6f8f10cb5573a1ad638a88ce386b687b49a2692",
         "lib/nav-link.js": "6a8f9368bb8aee1c21e90fb335a691859cb9a9bc250c2b9167a33ca9189fa2ff",
@@ -49,7 +50,7 @@
         "lib/render.js": "0e97c6a950bc962c8d8ea4b2f21d06cb73fbcdc738d8942d6935d01309a29b1d",
         "lib/samples.js": "e8cdb77ce22e43937707f6854d3a5cb722437dc584e22ac7b24480bef686cf85",
         "plugin.js": "0aa46a01b5298065497f39729b88e34a9f56ac684b0a14f8d94ab6007f0221d0",
-        "plugin.json": "abeac6a753aa8d16b5a9d457527850ed62b37f52065a264df62e0eb359b8780b",
+        "plugin.json": "f74ba12c5dfef7d0b9accd267cc0c4e333ea61a936cc8afa565db82da5b02389",
         "plugin.public.js": "ab23fadd5655fab8eea0e636a3e1f8ced78432d6da929059a4a147f0805ff3a4",
         "public/blog.css": "fd733e6b624190da1e70dc1b6613e2376efd7f7570a28fab311d81006d03d960",
         "public/blog.js": "d01c72a9834dcc7c5241923371f2b164ac30d20ac9f1a5c5dc5b71fa3cb09f08",
@@ -72,7 +73,7 @@
       }
     },
     "feedback": {
-      "version": "1.1.1",
+      "version": "1.1.2",
       "files": {
         "CLAUDE.md": "38122c71cacfda28fa87afd3321ae77b8a8b02facfa2f0d1bc637e6cfa59e448",
         "admin/css/index.css": "f2e934c8b94f883340148aba17945dfa725eeb2b0ddb6cabb8a8c17e2487c1de",
@@ -83,27 +84,29 @@
         "admin/views/send.js": "5868038a4020158746c5705d2a0ab5f552ac5021328a1dcf64a2def890495427",
         "collections/feedback-reports.json": "a072291b52463f7785a77f5f77d36b8238ba8f89cfc2672c6642eccdb3144486",
         "config.js": "29d9999d1028c2c11931f67fb9abdf35132430b7cf58c161681e734c0b45143a",
+        "docs/guide.md": "e006cc3f3c114583285964bc1b5d22b2a01285c2d2015d132434bfed363917d4",
         "lib/receiver.js": "c6ab2858dc7bfff6de19b41c84295c0c918ba50ddc57f6d3d83f1352662ebd91",
         "lib/sender.js": "037f9b4469a34ffe1d302a633e664860d625f7fb3be4dfadd01b8a3d094849b7",
         "lib/shape.js": "67acf62f812c2c9a01b52776641ed7ae1601c59ebab8ea278a07d1087a9f299b",
         "plugin.js": "96c95eb4c4c0b84c23822eb6e69aa8ae050d1ba14b283be848bcaa5b236a1ceb",
-        "plugin.json": "dc505c99213e1892fe13dd0ceca980022d9dc38f9bc97d95c1e3f6092aac3958",
+        "plugin.json": "1cc8f582be6b73e39fa1600ea738a5173d6c7378b01b092d35999d8f5de80741",
         "tests/api.test.js": "e822b0b9cd2dc5d32eb1f77ae76e34adfe13fb7d0fbe77fe3a7c3cca2a9c6b11",
         "tests/shape.test.js": "5133578142a79cc1a100b3215436372129f01fb0de8c757fd743ff99e1d7e37f"
       }
     },
     "mail-reader": {
-      "version": "1.2.2",
+      "version": "1.2.3",
       "files": {
         "CLAUDE.md": "e7722bf8464087e6568bac2f3cf2cf1eb4a84702e3f5d591737976db4fe5313e",
         "admin/views/mail.js": "c5c6483f9618c75cac8f4be32d3aea99511db76d4b9d38b8ef43bdc1d35db3c5",
         "config.js": "6e65803ad822a9acda40c203631b8eb32a87cf9d9e5f1c7cb59d01aa406075c6",
+        "docs/guide.md": "518441f4dcbd95c1318e1db9ad002b024dbe7b2aa3dee479ebb6976f00355d18",
         "plugin.js": "7f602a60c4eca7d3637659d03d5de9e242584666846b16c9e5a1b758e4856c9f",
-        "plugin.json": "1faa627f7f5c90033d805f564209008f80c54bd438b09a948396e5c8d2d55868"
+        "plugin.json": "2cae5b11f9975bcf76aa6369001e42ba4e5cf5bc3cee169f125720383acd7fdb"
       }
     },
     "security": {
-      "version": "1.1.2",
+      "version": "1.1.3",
       "files": {
         "CLAUDE.md": "29507f4460053b1a16a1902d47c007213d83ad3b497e86398ccaab92d07d3d51",
         "admin/lib/blocks.js": "5ef346b7de751518f8beb9212e3b89b270ae236560ae3d8a1f40d129c50918ff",
@@ -118,8 +121,9 @@
         "admin/views/security.js": "89c8dcaea89a0b8999798ecb84e9b41e5a08ceefa404aff529b02a6f28874361",
         "bin/unlock.js": "5fcc3c0ef3ba3c424a366aa62896f51abad578183dfde283aa838a86549ca785",
         "config.js": "e6a00f7816637687d6a68ebbac65a71489246a926c28523c2a78d859e75b7ae0",
+        "docs/guide.md": "a27d5303f9146057fd79c2093d7476ada1a5ee4fd14d34df7f94ad8555d88ca0",
         "plugin.js": "9d3a2e8b56dd637407c8abd93252dda9f67042231bc79d35771f766a62022c14",
-        "plugin.json": "6379097f0cbabb2ef1aa8034cb3727dba44b6c755e3e75ae49261a731b917d83",
+        "plugin.json": "c3457c117c66a8434318e51e13f0569d5b0f3f5e8500c9864a95c9c91049ce15",
         "server/common-passwords.NOTICE": "3b148a49a569bfa24feaa7879db602da8f0607fa61ab6c52b7a62391fc7c009a",
         "server/common-passwords.txt": "68782d6a4a19a4768d5f15dd66bd534e7a33055cc755411e33f16d18c50fdcce",
         "server/facts.js": "25538a8d1cfe012688fceb8ec0d0dd7b43ac9e168430723d6fb731183701fb46",
@@ -128,7 +132,7 @@
       }
     },
     "shopping-cart": {
-      "version": "1.0.2",
+      "version": "1.0.3",
       "files": {
         "CLAUDE.md": "fb9167502ceac9b1cc264f6c287c2e778e628137c87b6f87f84959618df4f1cb",
         "admin/css/index.css": "a6bab1d0072e364ee1d94c2d7d7b99c3660ba91c5eba537e269a579f5b17f924",
@@ -142,6 +146,7 @@
         "collections/shop-orders.json": "0bca8eef2d5f9108651f73d273480265c167dc983aa115ce59613d13015ca255",
         "collections/shop-products.json": "4d4613ecec7b8a5a0744c4f0a57b17a4429b461e060206a4bbdea5ad7c8c75dc",
         "config.js": "dcb91db2839c1ab9e40bb1811397024fad9e37e3753d17e2baa2b9b31d4a7d7c",
+        "docs/guide.md": "cc9935594a14ea8cda1eb0d9c507bbc580ba30c8d6beb9265f55f9b03a4c1ba1",
         "inject/body.html": "de20f92c83229545d20e5186fd37ef0046a8820881bff34e7df5391cd7a2c75d",
         "lib/extensions.js": "2cba90efef5b437ace557c7265fe7363ac7923d155681087a63e31e1168f6601",
         "lib/payments.js": "84ad14813688de1f38448b4935180a786cda8af2f7f4b8890a8f1d426982d1aa",
@@ -151,7 +156,7 @@
         "lib/shop.js": "36e1cea342e23f1a53b9fac63b993f860afc1bcb74b25bef9f7bf8eaf07d2d85",
         "lib/summary.js": "a510386e28eb19d9617f488551d1057819ae9f76fc85c744f2e5dbce492607fe",
         "plugin.js": "594c2174e36566f90ac1e9ff11cb76656ad111dc392dc8e9556d731b7dd0a41a",
-        "plugin.json": "b5deb15221610f9380a78c934bbc0cd3f6fd2bb219b7e8431e772b2d4958e22f",
+        "plugin.json": "1d76fea187dea958b82e752e5d6e7a729217b08b061490c8590e2c6e6537496e",
         "plugin.public.js": "176383dfa7af913c433e0397584c46a67a21ab3307b80a08f0aaf50da2634f9e",
         "public/cart.js": "fcc706773a36e4bfd02ea235bcdad629137e996218e0a0e23892e33c689f2a6e",
         "public/lib/money.js": "d22b2b6f80dde6f7887b69e24188c05ea93c02217aba639b5331aa3bd616f4fc",

package/plugins/mail-reader/docs/guide.md

@@ -0,0 +1,147 @@
+---
+title: Guide
+order: 1
+---
+
+Mail Reader lets you read your own email inside the admin. It connects to any standard IMAP mail server and never changes anything there: nothing is marked as read, moved, deleted or sent.
+
+## What it does
+
+- Three panes: **Folders**, the message list and the message itself. Drag the dividers to resize them.
+- Several mailboxes per person. Each person sees only their own mailboxes; nobody else in the admin can see them.
+- Read-only by design. Opening a message does not mark it as read on the server, so your phone or desktop mail app still shows exactly what you have and have not read.
+- Remote images are blocked until you ask for them.
+- Attachments can be downloaded.
+- An unread count on the **Mail Reader** sidebar item, taken from each mailbox's Inbox.
+
+Mail Reader is free. For sending, replying, flags, moving, deleting and search, see "Mail Reader or Email Pro" below.
+
+## Getting started
+
+You need your mailbox's IMAP details from your email provider: the server name, port, username and password.
+
+1. Open [Mail Reader](#/plugins/mail-reader) from the admin sidebar.
+2. If no mailbox is set up yet, click **Add a mailbox**. Otherwise click the cog at the top of the **Folders** pane (**Mail account settings**).
+3. On the **Mailboxes** tab, click **Add mailbox**.
+4. Fill in:
+   - **Name** - what to call this mailbox, for example "Office".
+   - **IMAP server** - for example `mail.example.com`.
+   - **Port** - 993 for TLS, 143 without.
+   - **Username** and **Password**.
+   - **Use TLS (port 993)** - leave ticked unless your provider says otherwise. Ticking or unticking it switches the port between 993 and 143 until you type a port yourself.
+5. Click **Test connection**. Fix anything it reports.
+6. Click **Save**. Your folders appear on the left.
+
+## Screens
+
+### Folders
+
+- Click a folder to list its messages. Folders that cannot hold mail are hidden.
+- The cog opens **Mail Settings**.
+
+### Message list
+
+- Newest first, 50 messages a page. Use **Newer** and **Older** to page.
+- Icons on a row show high priority, messages you have replied to, and attachments.
+- **Refresh** (the circular arrow) fetches the list again.
+- Right-click a message for **Open**, **Copy sender's address**, **Copy subject** and **Add sender to contacts**. The last one is shown only when the Contacts Tool is switched on, and is greyed out when the sender is already in your contacts.
+
+### Message
+
+- The header shows who sent it and when. Click **Show headers** for Reply-To, all recipients and the message id; **Hide headers** folds them again. Your choice is remembered.
+- Messages are shown in a locked-down frame: scripts in email never run.
+- If a message has remote images, a notice says how many were blocked. Click **Load images** to load them for this message only. Loading them tells the sender you opened it.
+- **Always from** (followed by the sender's address) trusts that sender, so their images load straight away in future. It appears only when **Offer to remember senders** is on (see Settings).
+- Click an attachment to download it.
+
+### Keyboard
+
+Press `?` to see the list.
+
+| Key | Does |
+|---|---|
+| Up and Down, or j and k | Move through the list |
+| Left and Right | Move between folders and messages |
+| Enter | Open |
+| Esc | Clear the selection |
+| ? | Show the shortcut list |
+
+The list also names shortcuts for replying, starring and deleting. In Mail Reader they do nothing; they work only in Email Pro.
+
+## Settings
+
+Click the cog in the **Folders** pane to open **Mail Settings**. It has three tabs.
+
+### Mailboxes
+
+Lists your mailboxes with **Edit** and **Remove**, plus **Add mailbox**.
+
+- When you edit a mailbox, leave **Password** blank to keep the saved one.
+- **Remove** forgets the mailbox and deletes its stored password. Nothing on the mail server changes.
+- Passwords are stored encrypted on the server and are never sent back to the browser.
+
+### Images
+
+- Lists the senders you trust. Their remote images load without asking. Click **Stop trusting** to remove one.
+- **Offer to remember senders** switches trusted senders on or off for the current mailbox. Switching it off ignores the list but keeps it.
+
+### Diagnostics
+
+Shows what the screen knows about itself: the build it is running, the mailbox and folder, and recent errors. Click **Copy diagnostics** to copy it for a support request. It never shows passwords.
+
+### Site-wide options
+
+Whoever runs the site can change these in the plugin's configuration file (`config/plugins.json`). There is no screen for them.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `listLimit` | 50 | Messages per page |
+| `allowRemoteImages` | false | Load remote images without asking |
+| `allowInsecureTLS` | false | Accept mail server certificates that do not verify (see Tips) |
+| `connectionTimeoutMs` | 20000 | How long to wait for a mail server, in milliseconds |
+| `maxConnections` | 20 | Most mail server connections kept open at once |
+| `maxMessageBytes` | 25000000 | Largest message that will be opened, in bytes |
+
+## Permissions and roles
+
+In System > Roles, Mail Reader uses the **Email** permission in the **Plugins** group. It has one action:
+
+| Action | Label | Allows |
+|---|---|---|
+| `email.read` | Use | Add your own mailboxes and read them |
+
+Only the **admin** role has it by default. To let other staff read their own mail here, give their role **Email > Use**. Even with this permission, people only ever see their own mailboxes.
+
+Email Pro uses the same **Email** permission.
+
+## Tips
+
+- **Use the mail server's real name.** If **Test connection** says "The mail server's TLS certificate could not be verified", the server name you typed probably does not match the name on the server's certificate. This often happens with a name like `mail.yourdomain.com` when the provider's certificate is issued for their own host name. Ask your provider for the exact IMAP host name (the one their certificate covers) and use that. Your mailbox is the same either way.
+- Only set `allowInsecureTLS` to true for a mail server you control that has a self-signed certificate. It turns off the check that the server is who it says it is, for every mailbox on the site.
+- Other error messages mean:
+  - "That mail server hostname could not be resolved" - check the spelling of **IMAP server**.
+  - "The mail server refused the connection on that port" - check **Port** and **Use TLS**.
+  - "The mail server rejected that username and password" - check the login details. Some providers need an app password.
+- Your pane widths and folded folders are remembered in your browser, and carry over if you move to Email Pro.
+
+## Mail Reader or Email Pro
+
+| | Mail Reader (free) | Email Pro (paid) |
+|---|---|---|
+| Read mail, folders, attachments | Yes | Yes |
+| Marks mail as read on the server | Never | Yes, like any mail app |
+| Send, reply, forward, drafts | No | Yes |
+| Flag, move, delete, spam | No | Yes |
+| Search and conversations | No | Yes |
+| Rules, away message, send later, snooze | No | Yes |
+| Needs MongoDB | No | For search, conversations, rules, send later, snooze and the away message. Without it, reading, filing and sending still work. |
+
+When Email Pro is installed it takes over from Mail Reader. Your saved mailboxes, passwords and trusted senders carry across.
+
+## Limitations
+
+- Read only. It cannot send, reply, mark as read, flag, move or delete.
+- No search, and no conversation (thread) view.
+- IMAP only. There is no sign-in with Google or Microsoft accounts; use the provider's IMAP settings and, where needed, an app password.
+- The unread badge counts each mailbox's Inbox only. It is refreshed at most once a minute.
+- Mail connections are kept by the running site. The site must run as a single server process; several worker processes for one site are not supported.

package/plugins/mail-reader/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mail-reader",
   "displayName": "Mail Reader",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "tier": "free",
   "description": "Read-only IMAP mailbox reader. Connects to a standard IMAP server and reads mail without ever writing to it.",
   "author": "Darryl Waterhouse",