domma-cms 0.93.0 → 0.94.0

package/plugins/security/docs/guide.md

@@ -0,0 +1,170 @@
+---
+title: Guide
+order: 1
+---
+
+Security protects your site with no set-up. It checks what is weak and tells you how to fix it, locks out repeated wrong passwords, enforces sensible password rules, logs every sign-in and turns away scanners. It is free and comes with Domma CMS, switched on.
+
+## What it does
+
+- **Health check**: a list of checks, each with why it matters and how to fix it.
+- **Sign-in lockout**: after repeated wrong passwords, the account or the address is locked for a while, longer each time.
+- **Password rules**: new passwords must be long enough, not a common password, and not contain the person's name or email.
+- **Sign-in log**: every sign-in, failed or successful, and every "Forgot your password?" request.
+- **Scanner guard**: requests for things no Domma site has (WordPress, `.env` files, database dumps and the like) get an empty "not found". An address that keeps probing is blocked for a while.
+- **Blocks**: block an address or range by hand, and see and clear lockouts and blocks.
+- A badge on the Security sidebar entry: the number of health checks needing attention. It turns red only when a failing check is critical.
+
+## Getting started
+
+Security is on from the start. To review it:
+
+1. Open [Security](#/plugins/security) in the sidebar.
+2. Read the **Health** card on the Overview tab. Click a check to see why it matters and how to fix it.
+3. Fix what you can. Use **Go there** in a check's menu where it offers one.
+4. Click the cog in the banner to review **Security settings**.
+
+## Screens
+
+The screen has three tabs. The banner has **Run the checks again** and **Security settings** (the cog).
+
+### Overview
+
+- **Health**: a score and the list of checks, grouped under People, Sign-in, Server, Web and Plugins.
+- Tiles: **Need attention**, **Failed sign-ins, 24h**, **Blocked now**, **Probes refused today** and **Reset requests, 24h**.
+
+Right-click a check for **Why, and how to fix it**, **Go there**, **Run the checks again** and **Copy**.
+
+The checks include:
+
+| Group | Checks |
+|---|---|
+| People | Unused admin accounts, How many admins, Accounts never used |
+| Sign-in | Sign-in lockout, Password rules, Two-factor sign-in, Email for resets and alerts |
+| Server | Domma CMS up to date, Production mode, Visitor addresses, Listening address |
+| Web | HTTPS certificate, Security headers, HTTPS, Private files not served |
+| Plugins | Plugin licences |
+
+A check the plugin cannot confirm shows as information, never as a pass. Results are kept for 10 minutes; **Run the checks again** refreshes them.
+
+### Sign-ins
+
+- Filters: **All**, **Failed**, **Succeeded** and **Resets**.
+- Period: **Last 24 hours**, **Last 7 days**, **Last 30 days** or **All kept**.
+- A search box for email, address or browser.
+- **CSV** downloads what is shown.
+
+Right-click an entry for **Only this address**, **Unlock this account**, **Block this address...**, **Copy the address** and **Copy the browser**.
+
+The Resets filter lists "Forgot your password?" requests and what happened to each.
+
+### Blocked
+
+- **Locked after wrong passwords**: current lockouts. **Unlock all** clears every one. Right-click one to **Unlock** it.
+- **Blocked for probing**: addresses blocked by the scanner guard. Right-click for **Unblock** or **Block for good**.
+- **Blocked by hand**: your own blocks. Enter an **Address or range** and an optional reason, then click **Block**. Right-click a block for **Remove the block**.
+
+An address can be written as:
+
+```text
+81.2.69.142        one address
+192.168.1.*        a trailing wildcard
+10.0.0.0/8         an IPv4 range
+2a00:23c7:*        an IPv6 prefix
+```
+
+If a block would cover your own address, you are warned first. The server itself cannot be blocked. Blocked addresses get an empty "forbidden" for every request.
+
+## Settings
+
+Click the cog in the banner to open **Security settings**. Click **Save** (or press Ctrl+Enter).
+
+### Sign-in lockout
+
+| Setting | Default |
+|---|---|
+| Lock after repeated wrong passwords | On |
+| Wrong passwords on one account | 5 |
+| Wrong passwords from one address | 20 |
+| Counted over (minutes) | 15 |
+| First lock (minutes) | 1. Each lock after that is twice as long |
+| Longest lock (minutes) | 60 |
+
+While locked, even the right password does not get in. The message never says whether the account exists. A successful sign-in clears the account's count.
+
+### Password rules
+
+| Setting | Default |
+|---|---|
+| Check new passwords | On |
+| Shortest password | 10 (8 to 64) |
+| Refuse the 10,000 most common passwords | On |
+| Refuse passwords containing the person's name or email | On |
+
+Passwords are checked when they are set or changed. Existing passwords keep working until then. While the rules are on, a password that uses only one or two different characters (such as `aaaaaaaaaa` or `abababababab`) is always refused.
+
+### Scanners
+
+| Setting | Default |
+|---|---|
+| Refuse probes, and block addresses that keep probing | On |
+| Probes before a block | 5 |
+| Counted over (minutes) | 10 |
+| Block for (minutes) | 60 |
+| Also treat as probes | Your own extra paths, one per line, starting with `/` |
+| This site does serve | Paths that look like probes but are real on your site, for example `/legacy/` |
+
+An address someone has signed in from in the last 7 days is never blocked automatically. Requests from the server itself are never touched.
+
+### Keeping and telling
+
+| Setting | Default |
+|---|---|
+| Keep the sign-in log (days) | 30 (7 to 365) |
+| Admin unused after (days) | 90. The health check flags admins who have not signed in for this long |
+| Notify when an account or address is locked | On |
+| Notify when someone signs in after many wrong passwords | On |
+| Notify when a scanner is blocked | Off |
+| Notify when password resets look like someone trying addresses | On |
+
+The last one fires when one address asks about 3 different accounts within an hour, or when 10 requests in an hour name accounts that do not exist.
+
+## Locked out yourself
+
+If you cannot sign in because of a lockout or a block, someone with access to the server can clear it. In the site's folder, run:
+
+```text
+node plugins/security/bin/unlock.js --list
+node plugins/security/bin/unlock.js --all
+node plugins/security/bin/unlock.js --ip 81.2.69.142
+node plugins/security/bin/unlock.js --user sam@example.com
+```
+
+`--list` shows what is locked or blocked. `--all` clears everything. `--ip` clears one address and `--user` one account. The site notices within a few seconds, with no restart.
+
+## Permissions and roles
+
+In System > Roles, Security adds the permission **Security** with two actions:
+
+| Action | Label | Meaning | Granted by default to |
+|---|---|---|---|
+| read | View | See the health check, sign-ins and blocks | Admin |
+| manage | Manage | Change settings; block, unblock and unlock | Admin |
+
+Super Admins always have both. Someone with View only sees the screens, but the unlock and block actions are switched off.
+
+Security adds no roles.
+
+## Tips
+
+- Keep the health check clear. The sidebar badge tells you when something needs attention.
+- Give only a few people admin rights. The health check flags admin accounts that are not used.
+- Set up outgoing email under Settings > Email, so password resets and alerts can be sent.
+- On a site behind a proxy, check **Visitor addresses** in the health check. If the site cannot see real visitor addresses, lockouts and blocks apply to the proxy's address.
+- The CSV export is safe to open in a spreadsheet: cells that could run as formulas are neutralised.
+
+## Limitations
+
+- Lockout and password rules need Domma CMS 0.83 or later. On older versions the screen says so and only the scanner guard and health check work.
+- Reset requests are only logged on Domma CMS 0.88 or later.
+- No two-factor sign-in. **Security Pro** adds it, along with more protection. When Security Pro is installed it takes over from Security.

package/plugins/security/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "security",
   "displayName": "Security",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "tier": "free",
   "description": "Keeps a Domma CMS site safe: a health check of what is weak and how to fix it, sign-in lockout after repeated wrong passwords, password rules, a log of every sign-in, and blocking of the scanners that probe every site for WordPress, .env files and the like.",
   "author": "Domma CMS",

package/plugins/shopping-cart/docs/guide.md

@@ -0,0 +1,191 @@
+---
+title: Guide
+order: 1
+---
+
+Sell from your own site. Add products, choose how you get paid, and run orders from the Shop in the admin sidebar. Shopping Cart is free.
+
+## What it does
+
+- A storefront at `/shop` (you can move it) with category filters, and search and sort once there are more than four products, and a page for each product.
+- Products with pictures, a "was" price, stock counts and options (for example sizes or colours), each option with its own price, SKU and stock.
+- A basket that follows shoppers round the whole site, with a floating basket button.
+- A one-page checkout at `/shop/cart` that takes payment by Stripe, PayPal or offline (for example bank transfer).
+- A receipt page for each order that the shopper can come back to.
+- Orders in the admin: mark paid, fulfil with tracking, refund, cancel, print a packing slip.
+- A badge on the Shop sidebar item showing paid orders waiting to be sent.
+
+The free Shopping Cart sends no emails at all - not to the shopper and not to you. The receipt page is the shopper's record of the order. Order confirmation and dispatch emails come with Shopping Cart Pro.
+
+## Getting started
+
+1. Open [Shop](#/plugins/shopping-cart) in the sidebar. A new shop shows "Open your shop" with three steps.
+2. Click **Add a product**, or **or try samples** to load six sample products with pictures, options and stock. You can edit or delete the samples later.
+3. Click **Payment settings** and turn on at least one way to pay (see Settings below). Pay offline is on by default.
+4. Click **See the shop** to check it, then link to `/shop` from your menu or put `[shop-products /]` on any page.
+5. If your site sits behind a proxy or on an unusual port, set your site's address first: [Site Settings](#/settings) > General > **Site URL** (for example `https://example.com`). Stripe and PayPal send shoppers back to this address after they pay. Without it the Shop guesses the address from the request, which can be wrong behind a proxy.
+
+## Screens
+
+The Shop has three tabs under the banner: Overview, Orders and Products. Shopping Cart Pro adds tabs of its own to this row. The banner has three buttons: the cog (Shop settings), open the shop in a new tab, and + (Add a product, on the Products tab).
+
+### Overview
+
+- **Today**, **Last 30 days** (compared with the 30 days before), **Average order** and **To fulfil**. Click To fulfil to go to the orders.
+- **Takings, last 30 days** - a bar per day. Hover a bar to see the day, the takings and the number of orders. Only paid and fulfilled orders count; refunded and cancelled orders are left out.
+- **Needs you** - paid orders to send, orders awaiting payment, products low in stock or sold out, checkouts started this week and not paid, and a reminder if you only take offline payment.
+- **Latest orders** and **Best sellers** (by takings over the last 30 days).
+
+### Orders
+
+1. Pick a filter: **To do**, **To fulfil**, **Awaiting payment**, **Fulfilled**, **Started**, **Cancelled & refunded** or **All**. Each shows a count.
+2. Search by order number, name, email or item.
+3. Click an order to open it. Right-click a row (or use the ⋮ button, or Shift+F10) for its actions.
+
+An open order shows the items and totals, the shopper, the delivery address and tracking, the shopper's note, a **Staff note** only you can see (saved when you click away), the payment reference and the order's history.
+
+Order statuses:
+
+| Status | Meaning |
+|---|---|
+| Checkout started | The shopper went to pay and has not finished. No stock is held. |
+| Awaiting payment | An offline order. Nothing has been charged. |
+| Paid - to fulfil | Paid. Stock has been taken. Ready to send. |
+| Fulfilled | Sent, delivered or collected. |
+| Cancelled | Never paid, and closed. |
+| Refunded | Paid, then given back. |
+
+Actions:
+
+- **Mark paid** - for an offline order when the money arrives. Stock is taken at this point.
+- **Mark fulfilled** (or **Mark collected**) - add a carrier, tracking number and tracking link if you have them. The shopper sees the tracking on their receipt page.
+- **Back to "to fulfil"** - reopen a fulfilled order.
+- **Refund** - see below.
+- **Cancel order** - only for orders that were never paid.
+- **Packing slip** - opens a printable slip with the items, SKUs, address and the shopper's note. Allow pop-ups for your site if nothing opens.
+- **Copy receipt link** - the shopper's receipt page address.
+- **Email the shopper** - opens your own email program.
+- **Delete** - only for Checkout started, Awaiting payment and Cancelled orders. A paid or refunded order cannot be deleted.
+
+Refunds:
+
+- Refunds are full refunds only. You cannot refund part of an order.
+- A Stripe or PayPal order is refunded through Stripe or PayPal first. The order is only marked refunded once they accept it.
+- An offline order is only marked refunded. Give the money back yourself, the way it came.
+- Tick **Put the items back in stock** to return the stock.
+
+### Products
+
+1. Pick a filter: **All**, **On sale**, **Drafts**, **Low stock** or **Archived**.
+2. Click a product to edit it, or click **Product** (or + in the banner) to add one.
+3. Right-click a row (or ⋮) to **Edit**, **View in the shop**, **Duplicate**, **Put on sale**, **Back to draft**, **Feature**, set stock, **Archive** or **Delete**.
+
+Only products **On sale** appear in the shop. **Archive** hides a product but keeps it. Deleting a product does not change past orders; they keep their own copy.
+
+The product form:
+
+- **Name**, **Address** (the last part of the product's web address), **Pictures** (from Media; the first is shown on the card, the second on hover; drag to reorder).
+- **Price** and **Was** (an earlier, higher price, shown struck through with a Sale flag).
+- **Summary** (on the card and the top of the product page) and **Description** (Markdown and shortcodes work).
+- **Category**, **Tags** (comma-separated), **Status** (On sale, Draft - hidden, Archived) and **Featured** (shown first, with a Featured flag).
+- **Options & stock** - tick **Count stock** to track stock; it then sells out at 0. Add options with **Add an option**, each with a name, price (empty uses the product's price), SKU and stock. **Options are** names them (for example Size).
+- **Delivery & tax** - untick **Needs delivering** for downloads, services and tickets (no delivery charge, no address asked). **Weight (g)** and **Tax class** are used by Shopping Cart Pro.
+
+Ctrl+Enter saves the form.
+
+## Settings
+
+Click the cog in the Shop banner to open **Shop settings**. It has four sections. Click **Save** when done. Changing the currency or the shop address reloads the page.
+
+### Storefront
+
+- **Shop name**, **Address** (default `/shop`; takes effect at once, and old links stop working), **Introduction**.
+- **Currency** - changing it does not convert prices you have entered.
+- **Products per row** (2, 3 or 4).
+- **Category filters**, **Search box** (shown once there are more than four products), **Basket button on every page**, **Say "Only 3 left"**.
+- **Basket button side** (Right or Left), **Low stock at**.
+- **Terms of sale page** - if set, shoppers must tick "I agree to the terms of sale" before paying.
+
+### Delivery
+
+- **We deliver to** - the countries checkout offers. Products that need no delivery can be bought from anywhere.
+- **Delivery charge** - one charge per order, and what it is **Called**.
+- **Free over** - orders at or above this amount go free. 0 means never.
+- **Offer collection** - shoppers can collect in person, with no charge and no address.
+
+### Tax
+
+- **Tax rate %** - one rate for every product. Leave at 0 for no tax.
+- **Called** (for example VAT).
+- **My prices include tax** - on: the price is what the shopper pays, and the receipt shows the tax inside it. Off: tax is added at checkout.
+- **Tax the delivery charge too**.
+
+### Payment
+
+Turn on one or more:
+
+- **Stripe** - cards, Apple Pay and Google Pay on Stripe's own page.
+  1. In Stripe, go to Developers > API keys and copy the secret key (`sk_test_` for testing, `sk_live_` for real).
+  2. Paste it in **Secret key**.
+  3. Optional but recommended: in Stripe, go to Developers > Webhooks, add the **Webhook** address shown in the settings (use the copy button) for the event `checkout.session.completed`, then paste its signing secret in **Webhook signing secret**. This confirms a payment even if the shopper closes the tab before coming back.
+  4. Click **Test the key**.
+- **PayPal** - needs a PayPal Business account and a REST app.
+  1. Choose **Mode**: Sandbox (testing) or Live.
+  2. Paste the **Client ID** and **Secret** from developer.paypal.com > Apps & Credentials > your app.
+  3. Click **Test the keys**.
+- **Pay offline** - bank transfer or cash on collection. The order is placed as Awaiting payment and nothing is charged. Set what it is **Called** and **What to tell the shopper** (for example your bank details). This shows on the shopper's receipt with the order number and total.
+
+Keys are kept on the server. Once saved they show as dots and are never shown again. Leave the dots alone to keep the saved key.
+
+## Shortcodes
+
+Put products on any page.
+
+A grid of products (all options are optional; `limit` is 1 to 48, default 8):
+
+```text
+[shop-products /]
+[shop-products category="Mugs" limit="8" columns="4" /]
+[shop-products tag="gift" /]
+[shop-products featured="true" /]
+```
+
+One product card:
+
+```text
+[shop-product slug="blue-mug" /]
+```
+
+An add-to-basket button with the price. For a product with options it links to the product page instead, so the shopper can choose:
+
+```text
+[buy-button slug="blue-mug" label="Buy now" /]
+```
+
+Only products On sale are shown. A page built from these can show out-of-date stock until it is next rendered, but checkout always checks stock and prices again.
+
+## Permissions and roles
+
+Set in System > Roles, under Plugins:
+
+| Permission | Action | Lets someone |
+|---|---|---|
+| Shop | See | Open the Shop and read its orders and products |
+| Shop | Manage | Edit products, move and refund orders, change the Shop's settings |
+
+The admin role has both by default.
+
+## Tips
+
+- Test with Stripe's `sk_test_` key or PayPal Sandbox before going live.
+- Notifications: a notice arrives for each new paid order and for each offline order awaiting payment. A Super Admin can switch the "Shop orders" source off in the Notifications settings.
+- Stock is taken when an order is paid, not when checkout starts. Started checkouts hold no stock and can be deleted.
+- Order numbers start at 1001.
+- If a shopper's basket changes while they check out (something sold out, fewer left), checkout stops and shows the new total before taking payment.
+
+## Limitations
+
+- No emails. Shopping Cart Pro adds order and dispatch emails.
+- Refunds are full refunds only.
+- One flat delivery charge and one tax rate. Shopping Cart Pro adds shipping zones, rates by weight or order value, tax by country and tax class, and discount codes.
+- Behind a proxy, set Site URL in Site Settings or Stripe and PayPal may send shoppers back to the wrong address.

package/plugins/shopping-cart/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shopping-cart",
   "displayName": "Shopping Cart",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "tier": "free",
   "description": "Sell from your site: products with options, stock and pictures, a storefront and a cart that follows shoppers from page to page, and checkout with Stripe, PayPal or payment offline. Orders to fulfil in the sidebar, refunds from the order.",
   "author": "Domma CMS",

package/server/routes/api/documentation.js

@@ -0,0 +1,42 @@
+/**
+ * Documentation API - plugin guides for the admin's Documentation folder.
+ *
+ * GET /api/documentation/plugins              - the guides this user may read
+ * GET /api/documentation/plugins/:name        - one guide, its first page rendered
+ * GET /api/documentation/plugins/:name/:page  - one guide, the named page rendered
+ *
+ * Signed-in users only. A guide is readable by whoever can use the plugin
+ * (services/pluginGuides.js decides), so a role that cannot open Invoices is
+ * not shown the Invoices guide either.
+ */
+import {authenticate as defaultAuthenticate} from '../../middleware/auth.js';
+import {getPermissionsForRoles} from '../../services/roles.js';
+import {getEffectiveRegistry} from '../../services/permissionRegistry.js';
+import {getEffectiveRoles} from '../../services/userRoles.js';
+import {getGuide, listGuides} from '../../services/pluginGuides.js';
+
+/** The caller's permissions - the same union /api/auth/permissions answers. */
+function permissionsOf(user, resolve) {
+    if (resolve) return resolve(user);
+    const roles = getEffectiveRoles(user || {});
+    return getPermissionsForRoles(roles, getEffectiveRegistry().map(r => r.key));
+}
+
+export async function documentationRoutes(fastify, opts = {}) {
+    const authenticate = opts.authenticate || defaultAuthenticate;
+    const signedIn = {preHandler: [authenticate]};
+
+    fastify.get('/documentation/plugins', signedIn, async (request) => {
+        return {guides: listGuides(permissionsOf(request.user, opts.permissionsOf))};
+    });
+
+    const one = async (request, reply) => {
+        const {name, page} = request.params;
+        const out = await getGuide(name, page, permissionsOf(request.user, opts.permissionsOf));
+        if (out.status === 403) return reply.code(403).send({statusCode: 403, error: 'Forbidden', message: 'You cannot use this plugin.'});
+        if (out.status !== 200) return reply.code(404).send({statusCode: 404, error: 'Not Found', message: 'No such guide.'});
+        return out.guide;
+    };
+    fastify.get('/documentation/plugins/:name', signedIn, one);
+    fastify.get('/documentation/plugins/:name/:page', signedIn, one);
+}

package/server/server.js

@@ -487,6 +487,7 @@ const {apiTokensRoutes}     = await import('./routes/api/api-tokens.js');
 const {apiEndpointsRoutes}  = await import('./routes/api/api-endpoints.js');
 const {endpointsPublicRoutes} = await import('./routes/api/endpoints-public.js');
 const {sidebarRoutes}       = await import('./routes/api/sidebar.js');
+const {documentationRoutes} = await import('./routes/api/documentation.js');
 const { mediaRoutes }      = await import('./routes/api/media.js');
 const { usersRoutes }      = await import('./routes/api/users.js');
 const { pluginsRoutes }            = await import('./routes/api/plugins.js');
@@ -525,6 +526,7 @@ await app.register(apiTokensRoutes,     {prefix: '/api'});
 await app.register(apiEndpointsRoutes,  {prefix: '/api'});
 await app.register(endpointsPublicRoutes, {prefix: '/api'});
 await app.register(sidebarRoutes,       {prefix: '/api'});
+await app.register(documentationRoutes, {prefix: '/api'});
 await app.register(mediaRoutes,       { prefix: '/api' });
 await app.register(usersRoutes,       { prefix: '/api' });
 await app.register(pluginsRoutes,            { prefix: '/api' });
@@ -633,6 +635,16 @@ registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'Layouts
 registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'Plugins', url: '#/plugins', icon: 'package', permission: 'plugins', countUrl: '/api/plugins/_count', inventory: true}});
 registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'API Tokens', url: '#/api-tokens', icon: 'key', permission: 'api-tokens', countUrl: '/api/api-tokens/_count'}});
 registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'Search', url: '#/search', icon: 'search', permission: 'settings', countUrl: '/api/search/_count', inventory: true}});
+// Documentation pages added after the sidebar menu was seeded (0.93.1). The menu is
+// seeded once, so new pages reach existing sites only by registering here. The two
+// sub-folders have no key in older menus; findFolder() falls back to their name.
+registerSidebarItem({folder: 'Usage', item: {source: 'Built in', text: 'Collections & Forms', url: '#/docs/usage/collections', icon: 'database'}});
+registerSidebarItem({folder: 'Usage', item: {source: 'Built in', text: 'Built-in Tools', url: '#/docs/usage/tools', icon: 'tool'}});
+registerSidebarItem({folder: 'Usage', item: {source: 'Built in', text: 'Editions & Licences', url: '#/docs/usage/editions', icon: 'key'}});
+registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'Forms', url: '#/docs/api/forms', icon: 'layout'}});
+registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'Scaffold', url: '#/docs/api/scaffold', icon: 'package'}});
+registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'External API & Tokens', url: '#/docs/api/external', icon: 'key'}});
+registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'API Builder', url: '#/docs/api/builder', icon: 'code'}});
 
 // Core's notification sources, before plugins add theirs (0.80).
 const {registerCoreSources} = await import('./services/notification-sources.js');

package/server/services/docs.js

@@ -55,6 +55,9 @@ const MAP = [
     ['usage-views',          'usage/views',          'Views'],
     ['usage-actions',        'usage/actions',        'Actions'],
     ['usage-cta-shortcode',  'usage/cta-shortcode',  'CTA Shortcode'],
+    ['usage-editions',       'usage/editions',       'Editions & Licences'],
+    ['usage-collections',    'usage/collections',    'Collections & Forms'],
+    ['usage-tools',          'usage/tools',          'Built-in Tools'],
     ['tutorial-crud',        'tutorials/crud',       'Building a CRUD App'],
     ['tutorial-plugin',      'tutorials/plugin',     'Writing a Plugin'],
     ['tutorial-forms',       'tutorials/forms',      'Form Follow-Up'],
@@ -72,7 +75,11 @@ const MAP = [
     ['api-plugins',          'api/plugins',          'Plugins API'],
     ['api-collections',      'api/collections',      'Collections API'],
     ['api-views',            'api/views',            'Views API'],
-    ['api-actions',          'api/actions',          'Actions API']
+    ['api-actions',          'api/actions',          'Actions API'],
+    ['api-forms',            'api/forms',            'Forms API'],
+    ['api-scaffold',         'api/scaffold',         'Scaffold API'],
+    ['api-external',         'api/external',         'External API & Tokens'],
+    ['api-builder',          'api/builder',          'API Builder']
 ];
 
 // Admin-SPA hash routes and stale /resources/… paths don't resolve on the
@@ -134,6 +141,10 @@ function rewriteLinks(html) {
     for (const [from, to] of Object.entries(LINK_MAP)) {
         out = out.split(`href="${from}"`).join(`href="${to}"`);
     }
+    // Usage and API pages share their tail with the public handbook; plugin guides
+    // are admin-only (they depend on what is installed), so they open the admin.
+    out = out.replace(/href="#\/docs\/(usage|api)\/([a-z0-9-]+)"/g, 'href="/domma-docs/$1/$2"');
+    out = out.replace(/href="#\/docs\/plugins([^"]*)"/g, 'href="/admin#/docs/plugins$1"');
     // Any remaining /resources/… link has no doc equivalent - unwrap to text.
     out = out.replace(/<a\b[^>]*\shref="\/resources\/[^"]*"[^>]*>([\s\S]*?)<\/a>/gi, '$1');
     return out;
@@ -347,7 +358,7 @@ export async function renderDocPage(docPath, opts = {}) {
 }
 
 /**
- * Every valid doc path (home + 29 leaves + 3 section landings). The Components
+ * Every valid doc path (home + every leaf + 3 section landings). The Components
  * landing is the 'components' leaf, already in MAP. `renderDocPage` returning
  * null is the authoritative miss; this is an enumeration aid (e.g. sitemap).
  *