domma-cms 1.6.59 → 1.7.0

package/docs/superpowers/specs/2026-09-22-dcms-marketplace-design.md

@@ -0,0 +1,1150 @@
+# dcms-marketplace - one source of truth, three delivery paths - design
+
+**Date:** 2026-09-22
+**Status:** Proposed design - not yet approved
+**Repos:** `dcms-marketplace` (new, private), `domma-cms`, `domma-cms-manager`
+**Builds on:** [Plugin Monetisation Split](./plans/2026-04-08-plugin-monetisation-split.md) (decisions still stand),
+[Phase 2 Plugin Distribution](../../../../domma-cms-manager/docs/superpowers/specs/2026-03-30-phase2-plugin-distribution-design.md) (manager, shipped)
+
+Gives every plugin - free and paid - a single home in git, generates the catalogue from that home
+rather than by hand, and adds a second delivery path alongside the existing fleet push: a signed
+standalone bundle a paying customer downloads once and installs offline on their own CMS.
+
+That bundle is also the **interchange unit in both directions**: any plugin can be exported from a
+running CMS as a single file and imported into another, which is the same operation a purchase
+performs and therefore the same code path.
+
+## Goal
+
+Today a plugin's code can live in four places and its identity in seven. The runtime is fine -
+`discoverPlugins()` scans `plugins/` and the manifest is authoritative for one site - but there is
+no truth for the *estate*: a plugin's canonical copy is in `domma-cms`, or in the manager, or inside
+the Site Manager plugin, depending on which plugin you mean, and five exist only on a live site.
+
+Five outcomes:
+
+1. **One repo holds every plugin.** Free and paid, one slug each, with history.
+2. **The catalogue is derived**, never hand-maintained, and signed.
+3. **Three delivery paths from one artifact set**: fleet push-copy (as now, unchanged), a signed
+   standalone bundle for offline install by a customer who has paid, and plain export/import
+   between any two installations.
+4. **A plugin is one portable file.** Export it from any CMS, import it into any other, with no
+   manual copying of directories and no second format to maintain.
+5. **Commercial terms are editable, not compiled.** Renting to a managed site and selling outright
+   to an unmanaged one are different products; both are priced from a screen in Site Manager, not
+   from a field in git.
+
+Non-goal: making Site Manager the public marketplace host. See [Why Site Manager does not host the
+public catalogue](#why-site-manager-does-not-host-the-public-catalogue).
+
+## Prior art found during the audit
+
+Ten discoveries, all verified. Several change the shape of the work, and #8 is a live leak.
+
+1. **The client half is complete and already shipped to npm.** `server/services/managerClient.js`
+   has `registerInstance` (:52), `fetchCatalogue` (:86), `fetchPluginBundle` (:119) and
+   `heartbeat` (:162). `server/services/pluginInstaller.js` does real RSA-SHA256 verification
+   against `TRUSTED_KEYS['manager-2026']`, parses tar without a dependency, guards path traversal,
+   writes an audit log to `content/instances_log.json`, and uninstalls. `pluginMarketplaceRoutes`
+   is registered at `server/server.js:448`, and the **Marketplace tab is live** in the Plugins
+   screen (`admin/js/views/plugins.js:6`).
+
+2. **The manager serves none of the four endpoints the client calls.** No route anywhere answers
+   `/api/plugins/catalogue`, `/api/plugins/install/:slug/:version`, `/api/instances/register` or
+   `/api/instances/heartbeat`. The client has been calling into the void since it landed.
+
+3. **`registerInstance()` and `heartbeat()` have no callers at all.** Not dormant - never wired.
+
+4. **The private signing key is missing.** `pluginInstaller.js` names its counterpart as
+   `domma-cms-manager/config/keys/plugin-signing-2026.pem`; `config/keys/` does not exist on the
+   manager. The public key is genuine (RSA-2048, verified with `crypto.verify('sha256', …)`), not
+   the placeholder the code explicitly guards against, so the verification path works and **nothing
+   can currently produce a bundle that passes it**. Confirmed lost on 2026-09-22 and resolved by
+   rotation - see [Signing keys](#signing-keys).
+
+5. **`MANAGER_URL` is unset on every fleet site**, so the Marketplace tab reports unavailable
+   fleet-wide. Harmless, but it is shipped UI pointing at nothing.
+
+6. **Licences never leave the manager.** No paid plugin contains a licence check, no licence file
+   reaches a child site, and the CMS's `pluginLicence()` (`server/services/plugins.js:796`) is a
+   *display string* derived from `closedSource`. Enforcement today is entirely "the manager owns
+   the filesystem": revoke means the manager deactivates the files. Sound for directories on our
+   own host; it cannot survive a download onto a disk we do not own, where the first copy is
+   permanent.
+
+7. **There is no upgrade path.** `installPlugin()` refuses if `plugins/<slug>/` exists - install and
+   uninstall only. `pluginDistributor.update()` has version-swap logic, but only on the manager side.
+
+8. **Surveys Pro is published to npm source-open.** It was designed as a Pro plugin
+   ([spec](./2026-06-26-surveys-pro-plugin-design.md)) but developed at `domma-cms/plugins/surveys`
+   with no `closedSource` flag, it is present in `_publish/plugins/surveys`, and a `closedSource`
+   duplicate sits at `plugins/site-manager/paid-plugins/surveys` at the same version 1.0.0. This is
+   precisely the leak the 2026-04-08 split existed to prevent, and it must be settled before a
+   catalogue is generated, because one slug cannot carry two tiers.
+
+9. **Restart after install is already solved.** `hasSupervisor()`
+   (`server/routes/api/plugins.js:37`) detects pm2 and the fleet manager's IPC channel, restarts
+   are debounced so four toggles cost one exit, and `restartOnPluginToggle` in `config/server.json`
+   lets an admin opt out. An install can reuse all of it.
+
+10. **The scaffolder copies paid plugins to every new site.** `siteScaffolder.js:277` holds a
+    hand-written `SKIP_PLUGINS` set, and it has drifted: it excludes `job-board`, `theme-roller`,
+    `data-transfer` and `garage`, but not `calendar`, `docs`, `email-pro`, `invoice`, `messages` or
+    `surveys`. So **six paid plugins land on every new site's disk**, unlicensed and disabled.
+    `pj-plastering` holds five of them and has no licence record at all. Once entitlement
+    verification lands, each of those copies becomes a plugin reporting `"unlicensed"` in the admin,
+    which is correct behaviour and a terrible first impression. This is the same hand-maintained-list
+    failure the rest of this design exists to remove.
+
+11. **The paid plugins are in git, but in an awkward place; five other plugins are in no git at
+    all.** `paid-plugins/` is tracked in the manager repo (96 files) and mirrored to the private
+    plugin repo by `sync-plugin-repo.sh`, which excludes only runtime data - so `analytics-pro`,
+    `data-transfer`, `mongodb-adapter`, `job-board`, `theme-roller` and `email-pro` all have
+    history, in two places. What is awkward is *where*: they sit inside another plugin
+    (`plugins/site-manager/paid-plugins/`), so a paid product's history is entangled with the fleet
+    supervisor's. The site copies are minified derivatives, since
+    `pluginDistributor.minifyAdminCode()` runs on the destination at `activate()`.
+
+    The five **site-only** plugins are versioned too, in their sites' own repos:
+    `reactive-showcase` (21/21 files tracked in the `reactive` repo), `retro64-games` (6) and
+    `retro64-cors` (3) in `retro-64`, `cache-autoflush` (3) in `pinpointzero`. **The single
+    genuinely unversioned plugin is `shopping-cart`**, because the `domma-cms-site` site directory
+    is not a git repo at all - which is a bigger problem than the plugin, since the same is true of
+    everything else on that site.
+
+    `reactive-showcase`'s 9,587 LOC also needs qualifying: 7,999 of them are
+    `public/domma-reactive.esm.js`, a vendored build of a library that has its own repo and npm
+    package. Its own code is about 1,588 LOC.
+
+## Decisions
+
+| Decision | Resolution |
+|---|---|
+| Code truth | One **private monorepo `dcms-marketplace`**, `plugins/<slug>/`, every plugin free and paid. |
+| Free tier and npm | The free subset is **synced into `domma-cms/plugins/` at release**, so `npm install` keeps shipping the free tier and free plugins keep working with no network. |
+| Catalogue truth | **Generated** from the manifests by `make catalogue`. Never hand-written. |
+| Public serving | **Static signed artifacts** on object storage plus CDN. No application server on the public path. |
+| Site Manager's role | Fleet distributor (unchanged) **plus** standalone bundle dispenser. **Not** the public catalogue host. |
+| Fleet delivery | **Push-copy stays.** For sites we own it beats pull: no network dependency, no licence race, and the manager already restarts children correctly. |
+| Standalone delivery | Signed envelope downloaded from the Plugin Store, installed offline by admin upload. |
+| Entitlement verification | Lives in **core (`server/`)**, not in the plugin. A plugin checking its own licence is the one file the customer can edit. |
+| Licence binding, v1 | **Purchaser identity embedded, no hardware binding.** Copyable but traceable. Fingerprint activation stays available as v2. |
+| Slug uniqueness | **Absolute.** One slug is one plugin at one tier, across both repos and the catalogue. |
+| Free to paid upgrades | Use the existing `supersedes` mechanism, which already handles it correctly (`email-pro` supersedes `mail-reader`, and a lapsed licence restores the free plugin on next boot rather than losing both). |
+| Signing key | **`manager-2026` is gone and is removed, not retained.** A new key `marketplace-1` replaces it, held offline. Rotation stays pinned by CMS version per the 2026-04-08 decision. |
+| Signature algorithm | **Ed25519.** 64-byte signatures, no caller-chosen digest, and a mismatched digest argument throws rather than degrading. `TRUSTED_KEYS` holds Ed25519 keys only. |
+| Interchange unit | **One envelope format** (`.dcmsplugin`) for all three paths: catalogue bundle, paid download, and local export. No second format. |
+| Exporting a paid plugin | **Refused.** `closedSource: true` never exports, on the same principle that already blocks the source editor. |
+| Unsigned imports | Allowed only behind an **explicit admin confirmation**, and refusable outright by config. An export from a running CMS cannot be marketplace-signed. |
+| Runtime data on export | **Excluded by default.** `data/` is the site's, not the plugin's. Opt in per export. |
+| Commercial terms | Live in **Site Manager**, editable in the admin (`plugin-terms.json`). Never in the manifest, never in git, never in the catalogue build. |
+| Managed sites | Paid plugins are **rented monthly**. Lapse stops the plugin, which is what the manager already does today. |
+| Unmanaged sites | **Bought outright** - a hefty one-off including **12 months** support and updates, then an ongoing renewal for further updates. The plugin runs forever regardless. |
+| Plugin builder | **Free permanently**, never entitlement-gated, never metered. Submissions to the marketplace arrive as a path C envelope. |
+| Which plugins are paid | Recorded in the [Tier register](#tier-register). `blog` free; `invoice` paid under either model; `mongodb-adapter` paid, **managed only**. |
+
+## Repository layout
+
+```
+dcms-marketplace/                 (private)
+├── plugins/
+│   ├── analytics-pro/            imported from a live site
+│   ├── blog/                     free
+│   ├── data-transfer/            imported from a live site
+│   ├── email-pro/                from manager plugins/
+│   ├── mongodb-adapter/          imported from a live site
+│   ├── seo-pro/                  imported from a live site
+│   └── …                         one directory per slug, no exceptions
+├── scripts/
+│   ├── build-catalogue.js        manifests -> catalogue.json + bundles + signatures
+│   └── sync-free-tier.js         free subset -> domma-cms/plugins/
+├── keys/                         public keys only; private keys never live here
+└── Makefile                      catalogue, sync-free-tier, verify
+```
+
+### Manifest additions
+
+Two optional fields on the existing manifest. Everything else is unchanged, so a plugin dropped
+into a CMS still loads exactly as today.
+
+```json
+{
+  "name": "seo-pro",
+  "displayName": "SEO Pro",
+  "version": "1.0.0",
+  "closedSource": true,
+  "tier": "paid",
+  "supersedes": ["site-search"]
+}
+```
+
+- `tier`: `"free" | "paid"`. Drives the free-tier sync, the catalogue split, and whether an
+  entitlement is required at load. Absent means free.
+- **No price.** Commercial terms are deliberately not in the manifest - see
+  [Commercial terms](#commercial-terms). A manifest is a git artifact, so a price living there
+  would make "change the price of SEO Pro" a code change, a release and a fleet roll.
+- `closedSource` keeps its current meaning and its current job - it already gates the source editor
+  (`pluginFiles.js`, `isClosedSource`) and already names the licence line. It is not the tier flag,
+  because a paid plugin could in principle be source-visible.
+
+## The catalogue
+
+`make catalogue` walks `plugins/*/plugin.json` and emits, into a publishable directory:
+
+```
+catalogue.json                    signed index
+catalogue.json.sig
+bundles/seo-pro-1.0.0.tar.gz      one per plugin per version
+bundles/seo-pro-1.0.0.tar.gz.sig  detached signature over the tarball bytes
+```
+
+`catalogue.json` entries carry the **artifact** facts only: `slug`, `version`, `displayName`,
+`description`, `tier`, `icon`, `supersedes`, `requires` (npm deps, so the dependency warning
+`pluginDistributor.checkDependencies()` already produces can be shown *before* purchase) and
+`minCmsVersion`. Prices and terms are a separate file on a separate lifecycle
+([Commercial terms](#commercial-terms)), because the catalogue is rebuilt on release and terms
+change whenever we decide they do.
+
+The existing client expects a `price` field from `fetchCatalogue()`. Site Manager merges
+`terms.json` into the catalogue it serves, so that contract holds without pricing entering git.
+
+Signatures are produced **offline**, with a key that never sits on the manager host. The signature
+covers the tarball bytes, which is what `pluginInstaller.js` already verifies - no format change.
+
+This generation step is what retires the hand-maintained lists: the stale **Bundled Plugins** table
+in `README.md`, and `KNOWN_HUES` in `admin/js/lib/plugin-accent.js` (which still names retired
+`site-search` and `form-builder`). Both become derived, or in the accent map's case simply deleted
+in favour of the catalogue's `icon` plus the existing hash fallback.
+
+## Delivery path A - the fleet (unchanged)
+
+Site Manager keeps doing what it does now, because for sites we own it is the better design:
+
+```
+dcms-marketplace  ──(git pull)──▶  manager paid-plugins/  ──(push-copy)──▶  sites/<slug>/plugins/
+                                          │
+                                   entitlements.js: licence + distribute + Mongo + restart
+```
+
+`entitlements.js`, `pluginDistributor.js` and `licenceManager.js` are unchanged in behaviour. The
+only change is provenance: `paid-plugins/` stops being the source of truth and becomes a checkout
+of the monorepo, so `git status` in the manager is no longer where a paid plugin's history lives.
+
+## Delivery path B - standalone offline install (new)
+
+The customer pays, downloads one file, and installs it on a CMS that may never reach the internet.
+
+### The envelope
+
+A single file, `<slug>-<version>.dcmsplugin`, which is a gzipped tar containing three members:
+
+```
+plugin.tar.gz        the plugin directory, exactly as the fleet path copies it
+plugin.sig           detached signature over plugin.tar.gz (base64)
+entitlement.json     signed entitlement, see below
+```
+
+This maps one-to-one onto the triple `installPlugin()` already accepts
+(`{ tarball, signature, publicKeyId }`), so the installer needs an `entitlement` option and
+nothing else. The envelope exists so the customer handles one file rather than three, and so a
+tampered or mismatched trio cannot be assembled by accident.
+
+### Install route
+
+New: `POST /api/plugins/install-upload`, admin-only, multipart. It unpacks the envelope, hands the
+triple to `installPlugin()`, and writes the entitlement to `plugins/<slug>/.entitlement.json`.
+Signature failure, slug mismatch between envelope and manifest, and `minCmsVersion` failure each
+refuse loudly - the existing installer already cleans up a partial extraction before rethrowing.
+
+After a successful install the route reuses the restart machinery from finding #9, so the plugin's
+routes and admin views register on the next boot without the operator being told to restart a
+server by hand.
+
+### Entitlement
+
+An entitlement states which of the two commercial models it was issued under
+([Commercial terms](#commercial-terms)), because the two expire in completely different ways.
+
+```json
+{
+  "slug": "seo-pro",
+  "model": "perpetual",
+  "versions": "<=1.4.0",
+  "licenceKey": "DOMMA-XXXX-XXXX-XXXX",
+  "purchaser": { "name": "…", "email": "…", "customerId": "…" },
+  "issuedAt": "2026-09-22T00:00:00.000Z",
+  "expiresAt": null,
+  "supportExpiresAt": "2027-09-22T00:00:00.000Z",
+  "gracePeriodDays": 7,
+  "keyId": "marketplace-1",
+  "signature": "…"
+}
+```
+
+- `model`: `"rental"` (managed sites, monthly) or `"perpetual"` (unmanaged sites, bought outright).
+- `expiresAt`: the rental term. **`null` for perpetual** - a bought licence does not expire.
+- `supportExpiresAt`: perpetual only. When support and updates end. **Not** when the plugin stops.
+- `versions`: the range this entitlement covers. For a perpetual licence it is resolved **at issue
+  time** to everything released up to `supportExpiresAt`, and a renewal reissues it with a later
+  ceiling. This is what a lapsed maintenance term actually costs the customer: not the software,
+  the newer versions of it.
+
+Verified by a new **core** service, `server/services/pluginEntitlement.js`, called from
+`registerPlugins()` for any manifest with `closedSource: true`. Named for the thing it checks
+rather than as `entitlements.js`, which already exists on the manager side and does a different
+job.
+
+| Model | State | Outcome |
+|---|---|---|
+| rental | Within term | Loads normally. |
+| rental | Within `gracePeriodDays` of `expiresAt` | Loads; `GET /api/plugins` reports `"grace"`. |
+| rental | Past grace | **Does not load**, reported `"expired"`. Files stay on disk, so a renewal is a file drop and a restart. |
+| perpetual | Support current | Loads; updates offered. |
+| perpetual | Support lapsed | **Loads indefinitely**, reported `"support-ended"`. Updates are refused at install, not at load. The screen offers renewal; it does not nag. |
+| either | Version outside `versions` | Install refused with the reason. An already-installed version is never retrospectively unloaded. |
+| either | Missing or signature invalid | Does not load, reported `"unlicensed"`. |
+
+The perpetual row is the one worth getting right. Somebody who paid a hefty one-off sum and then
+declined the ongoing renewal **keeps what they bought**, forever, offline. Stopping their site
+because a maintenance term lapsed would be indefensible, and would also punish exactly the customer
+who paid the most up front.
+
+Never silently disabled in `config/plugins.json`. Same reasoning as the supersedes case: writing a
+lapse into stored state means a renewal cannot simply restore it.
+
+No phone-home under either model. A rental's term is its offline window, so a 12-month rental works
+for 12 months with no network; a perpetual licence needs no window at all. Renewal means downloading
+a fresh `entitlement.json` and dropping it in - a route takes the file on its own without
+reinstalling the plugin.
+
+### What this does and does not achieve
+
+Stated plainly because the alternative is pretending. Domma CMS is source-open: an operator who
+wants to remove `pluginEntitlement.js` can, and minified admin code is
+*unrewarding to read*, not protected - which is the honest framing
+`pluginDistributor.minifyAdminCode()` already uses for itself.
+
+The goal is therefore not prevention. It is that the honest path is frictionless, the dishonest
+path is deliberate rather than accidental, and every issued copy carries its purchaser's identity.
+Nothing in this design should be described internally or to customers as copy protection.
+
+### Owner instances
+
+Two installations are ours and run paid plugins with no licence records:
+
+| Instance | Paid plugins enabled | What it is |
+|---|---|---|
+| `dcm.dommajs.org` (port 8192) | `docs`, `email-pro`, `garage`, `invoice` | the manager - **the testbed where plugins are developed**, and the management plane for every other site |
+| `cms.dommajs.org` | `docs`, `invoice`, `messages` | the Domma CMS site |
+
+Without a decision, entitlement verification would refuse to load those on boot. On the manager that
+means the fleet's management plane loses half its admin, including the screens used to issue the very
+licences that would fix it.
+
+**Decision: a wildcard entitlement, not an exemption flag.** An owner instance holds an
+`entitlement.json` whose `slug` is `"*"`, `model: "perpetual"`, `expiresAt: null` and no support
+window, signed with `marketplace-1` like any other. The verifier gains one rule - a wildcard
+entitlement satisfies any slug - and no second code path.
+
+Why not the alternatives:
+
+- **Not an environment flag or an "is this the manager" check.** That would be a branch that only
+  ever executes on our own machines, which makes it the least exercised and most rot-prone path in
+  the verifier, and the one place where a forgeable trigger would matter most. A wildcard entitlement
+  needs the private key, exactly like every other entitlement.
+- **Not per-plugin self-issued licences.** The manager is where plugins are *written*. A plugin being
+  built today has no slug in any ledger, so per-plugin licensing would mean issuing a licence before
+  you can run your own new code, on the machine where that happens most.
+
+It also removes an expiry to forget: the management plane cannot lose its admin because a renewal
+lapsed, because there is nothing to renew.
+
+**Scope.** Issued to those two instances only, by hand, and never distributed - `pluginDistributor`
+copies plugins, not entitlements, so a customer site cannot receive one by accident.
+
+This dovetails with the rule established when the scaffolder was fixed: `closedSource` lives on
+**distribution** copies, not on an instance's own installs, so the manager's `plugins/` stay
+editable in the code editor. Between the two, the testbed can both edit its plugins and run them,
+and neither mechanism needs a special case for it.
+
+## Delivery path C - export and import as one file
+
+The same envelope, produced by a running CMS rather than by the build. This is what makes a plugin a
+portable entity rather than a directory someone has to know how to copy: authored on a dev site,
+exported, imported on production; handed to another operator; kept as a versioned artifact outside
+the fleet.
+
+### Export
+
+`GET /api/plugins/:name/export` returns `<slug>-<version>.dcmsplugin`, admin-only, requiring
+`plugins.develop`.
+
+**What travels.** The whole plugin directory as `discoverPlugins()` sees it, which already includes
+the parts a plugin needs to reconstitute itself on the far side: `plugin.json`, `plugin.js`,
+`config.js`, `admin/`, `public/`, `templates/`, and the three scaffolding directories
+`setupPlugin()` reads at first load - `collections/*/schema.json` (`plugins.js:485`), `forms/`
+(:511) and `roles/` (:560). Import runs `setupPlugin()`, so collections, forms and roles are created
+on the target exactly as they are on a fresh install.
+
+**What does not travel:**
+
+| Excluded | Why |
+|---|---|
+| `data/` | Site runtime state, and already treated as not-ours by the `files` exclusions in `package.json`. Opt in with `?includeData=1`. |
+| Collection **entries** | A plugin's entries live in `content/collections/<slug>/`, outside the plugin. The *schema* travels, the rows do not. Moving rows is what Data Manager and collection export are for. |
+| `config/plugins.json` state | Enabled and settings are the target site's decision. Import lands disabled, matching `installPlugin()` today. |
+| `plugins/_lib/` | Shipped with the CMS, so a plugin that imports `../_lib/dataStore.js` resolves on any target. This is why `minCmsVersion` matters more than bundling shared code. |
+
+**Refusals.** Export is refused for `closedSource: true`. A paid plugin is distributed to run, not
+to be re-emitted as a redistributable file, and one-click export would otherwise turn every
+licensed customer into a distribution channel. The precedent and the mechanism both exist:
+`pluginFiles.js` already refuses source access on the same flag, reading the manifest and treating
+an unreadable one as closed so the gate cannot fail open.
+
+### Import
+
+Import is `POST /api/plugins/install-upload` - the same route the paid path uses, because the
+envelope is the same. The difference is trust, and it has to be faced directly: a bundle exported
+from a running CMS **cannot carry a marketplace signature**, because the signing key is offline and
+is never on a customer's host.
+
+So `plugin.sig` becomes optional, and the installer classifies what it is given:
+
+| Envelope | Outcome |
+|---|---|
+| Valid signature from `TRUSTED_KEYS` | Installs. Current behaviour, unchanged. |
+| Signature present but invalid | **Refused**, loudly. A broken signature is a tampered bundle, never an unsigned one. |
+| No signature, `requireSignedPlugins: false` (default) | Installs **after an explicit confirmation** naming the plugin and stating that its code will run on this server. Recorded in the audit log as `install:unsigned`. |
+| No signature, `requireSignedPlugins: true` | Refused. |
+
+`requireSignedPlugins` is a new key in `config/server.json`. Default `false`, because a CMS whose
+own plugin scaffolder (`scripts/create-plugin.js`, `POST /plugins/scaffold`) produces unsigned
+plugins cannot refuse unsigned plugins without refusing its own. Fleet sites should set it `true`,
+since everything they receive arrives by push-copy and nothing legitimate is ever uploaded there.
+
+The confirmation is not security theatre and should not be dressed up as security: uploading a
+plugin is uploading server-side code, exactly like `plugins.develop` already permits through the
+file editor. The prompt exists so that *running someone else's code* is a decision rather than a
+side effect of dragging a file onto a page.
+
+### Why not just a zip of the directory
+
+Because the three paths would then diverge. One envelope with an optional signature means the paid
+download, the catalogue bundle and a hand-made export all enter through `installPlugin()`, get the
+same traversal guard, the same manifest validation, the same cleanup on failure and the same audit
+record. A second "just unzip it" path would be the one that skips a check.
+
+## Commercial terms
+
+Two things are being sold, and they are not the same thing sold twice.
+
+| | **Managed site** (fleet) | **Unmanaged site** (self-hosted) |
+|---|---|---|
+| Model | **Rental**, per month | **Bought outright**, one hefty payment |
+| Entitlement | `model: "rental"`, `expiresAt` = end of paid month | `model: "perpetual"`, `expiresAt: null` |
+| Included | Support and updates while renting | **12 months** support and updates |
+| Then | Stops on non-payment, after grace | **Keeps running forever**; ongoing renewal buys further support and updates |
+| Delivery | Push-copy, path A | Download envelope, path B |
+| Enforcement | Manager owns the filesystem; `rescindPlugin()` already does this | Entitlement file, verified offline |
+
+The asymmetry is deliberate and should be said out loud to customers: on a managed site we carry the
+hosting, the updates, the restarts and the backups, so the plugin is rented alongside them. On an
+unmanaged site the customer carries all of that, gets no operational help, and pays once - heavily,
+because a paid plugin is months of work and a one-off sale has to stand on its own.
+
+### Where terms live
+
+**`plugins/site-manager/data/plugin-terms.json`**, edited in the admin. Not in the manifest, not in
+git, not in the catalogue build. Changing a price must be a form field and a save, never a release.
+
+```json
+{
+  "seo-pro": {
+    "managed":   { "available": true, "monthly": 1200, "minimumTermMonths": 1 },
+    "unmanaged": { "available": true, "licence": 89900, "supportMonths": 12,
+                   "renewal": 17900, "renewalPeriodMonths": 12 },
+    "currency": "GBP",
+    "notes": "Shown on the purchase screen",
+    "updatedAt": "2026-09-22T00:00:00.000Z",
+    "updatedBy": "darryl"
+  }
+}
+```
+
+All amounts are **integer minor units** (pence), never floats. `available: false` withdraws one
+model without withdrawing the plugin - a plugin can be fleet-only, or sale-only, by flipping a
+boolean rather than by being removed from the catalogue.
+
+This file is also what Site Manager merges into the catalogue it serves, and what gets published
+alongside the static catalogue as `terms.json`. Two files, two lifecycles: `catalogue.json` is
+rebuilt when a plugin is released, `terms.json` is rewritten whenever a price changes. A price
+change is therefore instant and touches no code.
+
+### Editing terms
+
+New Site Manager view, **Plugin Terms**, sitting beside Plugin Store and Licences. Per plugin: both
+models, both prices, support and renewal periods, availability toggles, free-text notes. It is a
+table of editable rows, not a wizard - this is a screen for changing a number.
+
+Two rules the editor enforces:
+
+1. **A terms change never alters an issued entitlement.** What someone paid, and what they were
+   promised, is captured in the entitlement and the ledger at issue time. Raising the price of SEO
+   Pro tomorrow does not shorten anybody's support window or re-rate a live rental. The new figure
+   applies to new purchases and to renewals quoted after the change.
+2. **Renewal quotes the terms current at renewal**, which is the honest version of the same rule and
+   should be stated on the purchase screen so nobody is surprised a year later.
+
+### Tier register
+
+The assignment, as decided on 2026-09-22. `tier` in the manifest is the machine-readable half of
+this table; the table is the record of *why*.
+
+**Free - the Tools tier, given away without conditions**
+
+| Plugin | LOC | Note |
+|---|---|---|
+| `blog` | 1,878 | **Decided free.** The largest thing in the giveaway pile, and a CMS without a blog looks broken. |
+| `contacts` | 1,427 | Enabled on 8/8 sites. Standard PIM. |
+| `analytics` | 678 | Core plugin already, cannot be switched off. Sold separately as `analytics-pro`. |
+| `todo` | 452 | Lightweight essential. |
+| `notes` | 412 | Lightweight essential. |
+| `theme-switcher` | 101 | Cosmetic, Domma-branded. |
+| `mail-reader` | 74 | Read-only IMAP. The substance is `_lib/mail`, which stays free - `email-pro` is the paid half. |
+| `demo-viewer` | 40 | Marketing shortcode for Domma itself. |
+
+Roughly 5.3k LOC given away. Only `analytics`, `contacts` and `demo-viewer` are widely enabled
+today; the rest are there for credibility rather than uptake, which is the correct job for a free
+tier and the reason none of them need a terms entry.
+
+**Paid**
+
+| Plugin | LOC | Managed | Unmanaged | Note |
+|---|---|---|---|---|
+| `invoice` | 4,999 | rental | perpetual | **Decided paid, licence or rent.** Largest product plugin. Currently free on npm - see [Extracting a plugin that shipped free](#extracting-a-plugin-that-shipped-free). |
+| `email-pro` | 4,275 | rental | perpetual | Supersedes `mail-reader`. Read surface stays free in `_lib/mail`. |
+| `docs` | 2,253 | rental | perpetual | Finished, enabled on zero sites. |
+| `calendar` | 1,791 | rental | perpetual | Finished, enabled on zero sites. |
+| `surveys` | 1,657 | rental | perpetual | **Decided paid; the free copy is extracted**, same as `invoice`. Slug stays `surveys`. |
+| `job-board` | 1,221 | rental | perpetual | Finished, never sold. |
+| `messages` | 1,118 | rental | perpetual | Enabled on 2 sites. |
+| `garage` | 1,038 | rental | perpetual | UK-vertical, wraps DVLA. Finished, enabled on zero sites. |
+| `data-transfer` | 1,003 | rental | perpetual | 5 active licences. |
+| `theme-roller` | 637 | rental | perpetual | Finished, never sold. |
+| `analytics-pro` | 476 | rental | perpetual | 4 active licences. |
+| `mongodb-adapter` | 40 | **rental only** | **not available** | **Decided: paid upgrade for managed sites, monthly.** See below. |
+| `seo-pro` | 15 | - | - | **Withdrawn. Licences revoked, slug reserved.** See [Withdrawing seo-pro](#withdrawing-seo-pro-and-reserving-a-slug). |
+
+**Never in the marketplace, at any tier**
+
+`site-manager` (29,923) and `customer-registration` (1,768) run the business rather than a customer's
+site. `site-tweaks` (10) is a marketing injection carrier for our own site. None get a `tier`, a
+terms entry or a catalogue entry.
+
+**Site-local - stays with its site, decided 2026-09-22**
+
+| Plugin | Site | Disposition |
+|---|---|---|
+| `reactive-showcase` | `reactive` | Stays in the site's repo. Loads `domma-reactive` and provides `[srcview]`, which renders the source behind each live demo. Site-specific by nature. Worth doing separately: stop vendoring `domma-reactive.esm.js` and take it from npm, which removes 8k lines from the site. |
+| `retro64-games` | `retro-64` | Stays in the site's repo. Note it *is* structurally a plugin - four routes, an admin view and a per-game JSON store - so it stays one; it is simply never a marketplace plugin. |
+
+**Becoming core rather than a plugin**
+
+| Plugin | Disposition |
+|---|---|
+| `cache-autoflush` | **Promote into core.** See [Promoting a plugin into core](#promoting-a-plugin-into-core). |
+| `retro64-cors` | **Promote into core as config**, then delete. Core registers `@fastify/cors` once with `serverConfig.cors`, which is global, so it cannot express "`Access-Control-Allow-Origin: *` on GET and HEAD under one path prefix" - which is all this plugin does, for `/public/retro64/`. A `cors.publicPrefixes: []` key in `config/server.json` would cover it in about fifteen lines and serve any site that wants its own assets hot-linkable. |
+
+**Free tier, but nothing built yet**
+
+`shopping-cart` (50 LOC, `domma-cms-site`) is **untouched scaffolder output** - every route commented
+out, `onEnable` empty, only the description written. Free is the right intention, but there is no
+asset to import: the slug goes in `reserved.json` until something exists behind it, exactly as
+`seo-pro` does. Separately, `domma-cms-site` needs to become a git repo.
+
+**To be deleted rather than tiered**
+
+`form-builder` - 0 LOC, empty `data/` directories on all eight sites, code long gone since forms
+moved into core. `plugins/site-search/` - empty residue the migration could not remove for want of a
+manifest. Both still appear in `KNOWN_HUES`, which this design deletes anyway.
+
+### Managed-only plugins
+
+`mongodb-adapter` is the first plugin available under one model only, and the reason is technical
+rather than commercial. The plugin is a 40-line shim that reads a `config/connections.json`
+**written by the manager during provisioning** (`mongoProvisioner.js`) and decorates Fastify with
+it. On an unmanaged site nothing writes that file, so the plugin has nothing to read and would sell
+a customer a no-op.
+
+What a self-hosted customer can do instead, for free: write `connections.json` themselves and
+declare `"storage": {"adapter": "mongodb"}` in a schema. Core already resolves that
+(`adapterRegistry.resolveMongoAdapter()`), and `mongodb` is in `optionalDependencies`, so Mongo
+support is **not** withheld from the free tier at all.
+
+Which makes the managed subscription honest to describe: it does not sell the adapter, it sells
+provisioning, credentials, connection management and the backups that go with them. Anyone prepared
+to run their own Mongo already has the capability. The terms editor expresses this as
+`unmanaged.available: false`, and the purchase screen should say why rather than leaving a customer
+to wonder what they are being denied.
+
+This is a pattern, not a one-off: any plugin whose value is a service we operate belongs in the
+managed column only.
+
+### Extracting a plugin that shipped free
+
+`invoice` is paid from now on, and it is currently in `domma-cms/plugins/`, in the npm tarball, and
+enabled on four sites. `garage` went through this in 2026-04 and the steps are the same:
+
+1. **Move it to the monorepo** with `tier: "paid"` and `closedSource: true`. Two guards switch
+   themselves on as a consequence: the source editor refuses it (`pluginFiles.isClosedSource`) and
+   path C refuses to export it.
+2. **Remove it from `domma-cms/plugins/`**, so it leaves the next npm release and the next
+   `_publish/` build. Whether git history is rewritten is a separate call - the 2026-04-08 plan did
+   rewrite for `garage`; for `invoice` the code is already public in published tarballs, so a
+   rewrite buys less.
+3. **Grandfather the four live sites.** All four are managed fleet sites, so
+   `entitlements.grantPlugin()` covers it exactly as it stands: files are already in place, a rental
+   licence is issued, nothing restarts, nobody notices. Do this **before** step 2, so there is no
+   window where a site holds a paid plugin with no licence record.
+4. **Accept that published tarballs stay published.** Anyone who already ran `npm install` has the
+   version they have, forever. Only new versions are withheld. Saying this plainly is better than
+   implying an extraction is a recall.
+
+Nothing here is specific to `invoice`. **`surveys` takes the same four steps**, with one difference
+in its favour and one against:
+
+- **In its favour:** it is enabled on zero sites, so step 3 grandfathers two licence records rather
+  than four running installations. Nothing to disturb.
+- **Against:** it is *present* on all eight sites, copied there by the scaffolder (finding #10), and
+  it is the plugin whose duplicate-slug collision blocks catalogue generation. Extraction resolves
+  both at once, which is why it is the cleaner of the two options that were on the table - the
+  alternative, renaming the paid copy `surveys-pro`, would have left a permanently lesser `surveys`
+  on npm and two plugins to maintain.
+
+### Stop distributing paid plugins by default
+
+`SKIP_PLUGINS` in `siteScaffolder.js:277` is replaced by a tier check:
+
+```js
+// Free-tier plugins are seeded into a new site; paid ones arrive by grant.
+if (manifest.tier === 'paid') continue;
+```
+
+Read from the manifest that is being copied anyway, so a new paid plugin is excluded the day it is
+written rather than the day somebody remembers the list. The manager-specific exclusions
+(`site-manager`, `customer-registration`) stay, because they are not a tier, they are not a
+customer's software at all.
+
+Two consequences worth stating:
+
+1. **A new site starts clean:** free plugins seeded, nothing else on disk. A paid plugin appears when
+   it is granted, which is when `pluginDistributor.activate()` copies it.
+2. **Existing sites carry strays** - six slugs' worth, unlicensed and disabled. They should be
+   **removed**, not left to report `"unlicensed"` forever. Removal is safe because a grant copies the
+   files back; a site that later buys `docs` gets `docs` then.
+
+## The plugin builder is free, permanently
+
+The builder is the thing that makes a marketplace worth having, so it is never gated, never metered
+and never moved to the paid tier. It already exists and already ships free:
+
+| Surface | Where |
+|---|---|
+| Scaffolder (admin) | `POST /api/plugins/scaffold` → `pluginScaffold.js`, instantiating `plugins/_template/` |
+| Scaffolder (CLI) | `scripts/create-plugin.js` |
+| Code editor | `#/plugins/code/:name` (`admin/js/views/plugin-code.js`), files API under `plugins.develop` |
+| Shared helpers | `plugins/_lib/` - dataStore, mail, admin UI, schemaSync |
+| Documentation | `docs/plugin-development.md`, `plugins/CLAUDE.md` |
+
+Commitments this design makes about them:
+
+- **No entitlement check ever runs against a plugin the user wrote.** The gate keys on
+  `closedSource: true`, which is a flag *we* set on *our* paid plugins. A user's own plugin has no
+  entitlement, needs none, and must never be asked for one.
+- **`_template` and `_lib` stay in the free npm package**, so `npm install domma-cms` is a complete
+  plugin development environment with no account, no key and no network.
+- **`requireSignedPlugins` defaults to `false`** partly for this reason: a CMS whose own scaffolder
+  emits unsigned plugins cannot refuse unsigned plugins without refusing the user's own work.
+
+### Withdrawing seo-pro, and reserving a slug
+
+`seo-pro` is fourteen lines whose own header calls it a sample. It answers
+`GET /api/plugins/seo-pro/meta` with `{title: null, description: null, ogImage: null}` and has three
+active licences against it. It is withdrawn: the licences are revoked and the slug is held back until
+there is something behind it.
+
+Two facts make this safe rather than a customer-facing change:
+
+1. **Nothing calls it.** No site's content or public JS references `seo-pro` anywhere across the
+   eight sites. A plugin returning hardcoded nulls could not have acquired a dependent.
+2. **The licences were never sold.** All three are `type: "generated"`, issued automatically by
+   `proManager.enable()` when the Pro bundle was switched on for each site - the activation dates
+   match each site's provisioning. Nobody bought `seo-pro`; it arrived inside a bundle.
+
+**The step that makes or breaks this:** `seo-pro` is in the **default Pro bundle**
+(`config.js:55` - `proBundle: ['mongodb-adapter', 'analytics-pro', 'seo-pro', 'data-transfer']`).
+Revoking the three licences without removing it from that array means the next Pro enable on any site
+re-issues one. The order is therefore:
+
+1. Remove `seo-pro` from `proBundle`.
+2. `entitlements.rescindPlugin()` for each of the three sites - which deactivates, revokes and
+   restarts through `processManager`. **Not** by hand: a site stopped outside `processManager` does
+   not come back.
+3. Delete the files from those three sites and from `paid-plugins/`.
+4. Do not import it into the monorepo. The slug becomes reserved.
+
+### Reserved slugs
+
+A reserved slug is one that is neither free nor paid: it has no tier, no terms entry, no catalogue
+entry, and **cannot be granted**. It exists only so that nothing else takes the name and so the
+eventual real plugin inherits it.
+
+`dcms-marketplace/reserved.json` holds the list with a reason each, and `build-catalogue.js` refuses
+to emit a bundle for any slug in it. That refusal is the point: a stub cannot reach a catalogue by
+somebody adding a directory and forgetting why the name was being kept.
+
+```json
+{
+  "seo-pro": "Withdrawn 2026-09-22 - was a sample stub with three bundle-issued licences. Slug held for a real SEO plugin.",
+  "form-builder": "Retired when forms moved into core. Slug held to avoid resurrecting a dead name.",
+  "site-search": "Retired into server/services/search.js. Slug held for the same reason."
+}
+```
+
+### Packaging belongs with the terms, not in code
+
+`proBundle` is a hand-maintained array in `config.js`, and it is the fourth such list this design
+retires - after `SKIP_PLUGINS`, `KNOWN_HUES` and the README table. It is also, unlike those, purely
+**commercial** configuration: which plugins a customer gets for the Pro price is the same kind of
+decision as what the Pro price is.
+
+So it moves into `plugin-terms.json` as a `bundles` block and becomes editable in the Plugin Terms
+view:
+
+```json
+"bundles": {
+  "pro": { "label": "Pro", "plugins": ["mongodb-adapter", "analytics-pro", "data-transfer"],
+           "monthly": 2900 }
+}
+```
+
+`resolveBundle()` reads it from there instead of from `DEFAULT_PRO_BUNDLE`, which means withdrawing a
+plugin from the bundle - exactly what `seo-pro` needs - stops being a code change and a fleet roll.
+The `mongodb-adapter` special case at `proManager.js:120`, which skips it when no master Mongo URI is
+configured, stays as it is: it is a capability check, not packaging, and it agrees with the
+managed-only decision.
+
+### Promoting a plugin into core
+
+`cache-autoflush` should not be a plugin, and the CMS has already done this once: `site-search`
+became `server/services/search.js`, with `search-migration.js` lifting existing sites off the plugin
+at startup. That is the pattern to copy.
+
+**Why it belongs in core**, in its own words: the CMS invalidates the response cache on API and admin
+saves (`content.js` → `cache.invalidateTags`), but changes made *outside* the API - direct file
+edits, git or rsync deploys, scripted updates - never fire that hook, and the production
+`MemoryDriver` has no TTL. So an edited page is served stale indefinitely. It has to run in-process
+to reach the live in-memory cache, which is exactly why an external tool cannot fix it.
+
+This is a fleet-wide papercut, not one site's quirk: every fleet site runs `NODE_ENV=production`, so
+every one of them serves stale HTML after a hand-edit until it is restarted. One site happens to have
+the fix installed.
+
+**Shape in core:**
+
+- Lives with the cache it serves, in `server/services/cache/`, started from `server.js` alongside the
+  cache itself.
+- Configured in `config/cache.json`, which already exists and is already the owner's file:
+  `"autoflush": { "enabled": true, "debounceMs": 300, "watch": [...] }`.
+- Default **on in production, off in development**, matching how the cache itself already defaults -
+  in development nothing is cached, so there is nothing to flush.
+- Keeps the whole-cache clear rather than per-page invalidation. A block, CSS or menu change can
+  affect many pages and entries repopulate lazily, so the precision is not worth the bookkeeping.
+- A retirement migration modelled on `search-migration.js`: settings out of `plugins.json`, the
+  `plugins.json` entry removed, and `plugins/cache-autoflush/` deleted **only if it is the bundled
+  one** (manifest name and author both match). A directory of that name carrying somebody else's work
+  is left alone, and the migration must run before the plugin loader, or the site briefly runs two
+  watchers.
+
+The same question should be asked of any plugin nobody may reasonably switch off. `CORE_PLUGINS` in
+`plugins.js` documents itself as a waiting room rather than a destination for exactly this reason.
+
+### Submitting a plugin to the marketplace
+
+Path C is the submission pipeline, and no new machinery is needed for it. A user builds a plugin
+with the free builder, exports it as one `.dcmsplugin` file, and sends that file. We review it,
+sign it with the marketplace key, and add it to the monorepo as any other plugin.
+
+That the export format and the distribution format are the same file is the point: a submission is
+testable by installing it exactly the way a customer would, before any decision is made about it.
+
+Author terms - revenue share, attribution, support obligations, whether a third-party plugin can be
+paid at all - are **out of scope here** and listed in Open questions. Accepting third-party *paid*
+plugins in particular would change the signing model, because we would be signing code we did not
+write.
+
+## Signing keys
+
+`manager-2026` is gone. It is replaced by **`marketplace-1`**, and the old entry is **deleted from
+`TRUSTED_KEYS` rather than kept for continuity**.
+
+Deleting it is the security decision, and it is worth being explicit about why. A private key we
+cannot find is not a key we know to be destroyed - it is a key whose whereabouts are unknown.
+Leaving its public half in `TRUSTED_KEYS` would mean that anyone who does have it can sign a bundle
+that every Domma CMS accepts as ours, forever. Nothing has ever been signed with it, so there is not
+a single artifact to keep compatible. Removing it costs nothing and closes that door.
+
+### Naming
+
+`marketplace-<n>`, a monotonic counter, not a year. The first key is `marketplace-1`. A year in the
+id reads as an expiry date it does not have, and the key being replaced today would have to be
+called a 2026 key too, which is exactly the confusion worth avoiding.
+
+### Algorithm - Ed25519
+
+**Decided 2026-09-22.** Rotation was the one free moment to change algorithm, since no existing
+signature had to stay valid.
+
+```js
+// Ed25519 passes null as the digest; the algorithm is implied by the key.
+const valid = crypto.verify(null, tarball, pubKeyPem, signatureBuffer);
+```
+
+That is the entire change to `pluginInstaller.js` - one argument. Generation and signing:
+
+```sh
+openssl genpkey -algorithm ed25519 -out marketplace-1.pem          # offline, then encrypt it
+openssl pkey -in marketplace-1.pem -pubout -out marketplace-1.pub  # commit this half
+```
+
+Measured on Node 22.22.2 rather than assumed:
+
+| | Ed25519 | RSA-2048 (retired key) |
+|---|---|---|
+| Signature | **64 bytes** | 256 bytes |
+| Public key PEM | **3 lines** | 9 lines |
+| Digest argument | none - implied by the key | `'sha256'`, chosen by the caller |
+
+**The mismatch fails closed**, which is the part worth knowing: calling
+`crypto.verify('sha256', …)` against an Ed25519 key throws `ERR_OSSL_INVALID_DIGEST`. So if the
+digest argument is ever left behind during the edit, installs break loudly instead of silently
+accepting something. A verifier that quietly degraded would be the worst outcome available here, and
+the runtime refuses to provide it.
+
+`TRUSTED_KEYS` therefore holds Ed25519 keys only, and the verifier handles exactly one algorithm.
+Accepting either would invite a downgrade, and with `manager-2026` deleted there is no legacy to
+accommodate.
+
+Recorded alternative: RSA-4096 would have needed no code change at all, but carried a larger key, a
+caller-chosen digest, and no upside. RSA-2048 was not an option for a key meant to last.
+
+### Custody
+
+**What actually happened, 2026-09-22:** `marketplace-1` was generated **on the manager host**, as a
+deliberate call, against the rule below. Recorded rather than quietly contradicted - a custody
+document that does not match reality protects nothing.
+
+The consequence is bounded but real: the private half has existed in the filesystem of an
+internet-facing box, and in any snapshot or backup taken since. It lives at `~/.domma-keys/` (0700,
+key 0600), outside every repository, and `*.pem` is gitignored in the marketplace repo so it cannot
+be committed by reflex. If that box is ever suspected, this key is suspect with it, and the rotation
+procedure below is the answer.
+
+The rule, for the next key:
+
+- Generated on a machine that is not the manager host, and **never copied onto it**. The manager
+  serves bundles; it does not sign them.
+- Private half encrypted with a passphrase and stored in **at least two places** that are not the
+  same disk and not a git repository. This is the failure being recovered from today.
+- Signing happens where the key lives, as part of `make catalogue`. The output that travels is the
+  signature, never the key.
+- The public half is committed: it ships inside `domma-cms` in `TRUSTED_KEYS`, and a copy lives in
+  `dcms-marketplace/keys/` so the build can verify its own output.
+
+### Manager keys: entitlements only (2026-10-01)
+
+A manager mints licences as it grants them, so its signing key has to live **online, on the manager
+host** - the opposite of the rule above, and unavoidable for that job. svr-2 (aurelius, a shared
+box) got its own key, `svr-2-1`, generated there on 2026-10-01 and never copied off it, instead of a
+copy of `marketplace-1`.
+
+What makes that acceptable is that `TRUSTED_KEYS` now says what each key may sign: `bundle` (plugin
+code, which every CMS installs) and/or `entitlement` (a licence for a plugin a site already has).
+`svr-2-1` is trusted for **entitlements only**: `installPlugin` refuses it by name, exactly like an
+unknown key. If it leaks, the damage is forged licences, never code every CMS would run, and it is
+withdrawn by a release without touching `marketplace-1` or anything it signed. A manager signs as
+its key file's name (site-manager's `keyIdForKeyFile`), so the id and the key cannot disagree.
+
+### Rotating again
+
+Losing a key is survivable, which this rotation demonstrates. Because a CMS pins the keyIds it
+trusts, and the catalogue records `minCmsVersion`, the procedure is:
+
+1. Generate `marketplace-<n+1>` offline.
+2. Add it to `TRUSTED_KEYS` **alongside** the current key and ship that CMS release.
+3. Re-sign the catalogue with the new key once enough of the fleet is updated.
+4. Remove the old key in a later release.
+
+The overlap in steps 2 and 3 is what makes a planned rotation invisible to customers. It is also
+precisely what a *lost* key does not get: today's rotation has no overlap period, and it does not
+need one only because no signed artifact exists.
+
+### Consequence for existing installs
+
+`marketplace-1` is trusted only by CMS versions that ship it. Anything older trusts `manager-2026`,
+which will never sign anything. That is not a regression - no CMS anywhere has ever successfully
+installed a signed bundle - but it does mean the marketplace's real floor is the release that
+carries the new key, which is what `minCmsVersion` on every catalogue entry exists to express.
+
+## Why Site Manager does not host the public catalogue
+
+Site Manager is the right dispenser and the wrong host.
+
+**Right dispenser:** it already holds the paid catalogue, the licence ledger, the grant/rescind
+logic, the Plugin Store UI, and the process control to restart a child. Serving the fleet endpoints
+and producing a download envelope is a small addition to something already built.
+
+**Wrong host:** it is the fleet's reverse proxy, routing every customer domain by `Host` header,
+and in the same process it holds the licence ledger, certificate manager, Mongo provisioner, site
+users and data manager. Exposing it to the public internet for anonymous catalogue browsing widens
+the blast radius of the most privileged process we run, for no gain - the catalogue is static
+files. It also lives in a repo the updater half-overwrites, which is a poor foundation for a
+public service.
+
+So: static artifacts serve the public, Site Manager serves the fleet and mints downloads.
+
+## Changes by file
+
+### `domma-cms` (core)
+
+| File | Change |
+|---|---|
+| `server/services/pluginEntitlement.js` | New. Verify, classify, report. |
+| `server/services/plugins.js` | Gate `closedSource` plugins on entitlement in `registerPlugins()`; surface state through `getLoadedPlugins()`. |
+| `server/services/pluginInstaller.js` | Accept `entitlement`; add the upgrade path (below); make `plugin.sig` optional; **`crypto.verify(null, …)` for Ed25519**; `TRUSTED_KEYS` gains `marketplace-1` and loses `manager-2026`. |
+| `server/routes/api/plugins.js` | `POST /plugins/install-upload`, `GET /plugins/:name/export`, `POST /plugins/entitlement`; add `entitlement` to the `GET /plugins` payload beside the existing `licence` and `supersededBy`. |
+| `admin/js/views/plugins.js` | Install-from-file control and the unsigned-import confirmation; an Export action per card (absent on `closedSource`); entitlement state on the card; make the Marketplace tab real. |
+| `config/server.json` | New `requireSignedPlugins` (default `false`), merged on update. |
+| `admin/js/lib/plugin-accent.js` | Delete `KNOWN_HUES`; keep the hash fallback. |
+| `README.md` | Bundled Plugins table generated, or removed in favour of a link. |
+
+### `domma-cms-manager` (Site Manager plugin)
+
+| Route | Purpose |
+|---|---|
+| `GET /api/plugins/catalogue` | **Built.** Serve the catalogue to a fleet child, joined with terms and this site's licences. |
+| `GET /api/plugins/install/:slug/:version` | **Built.** Serve the triple plus a rental entitlement minted for the calling site. |
+| ~~`POST /api/instances/register`~~ | **Dropped** - see below. |
+| ~~`POST /api/instances/heartbeat`~~ | **Deferred.** Opt-in and off by default, per 2026-04-08; still nothing calls it. |
+
+### How a fleet child authenticates (revised)
+
+The register handshake was designed for an instance the manager did **not** start: HMAC a fingerprint
+with a shared `INSTANCE_SECRET`, receive a licence token back. That is the right shape for a customer's
+own server phoning home. It is the wrong shape for this fleet, where the manager forks every child
+itself and therefore already knows, with certainty, which site is on the other end - a handshake could
+only re-establish something we never lost.
+
+So `processManager` mints a token when it forks a child and hands it over in the environment, alongside
+`MANAGER_URL` and `SITE_SLUG`. Three properties a shared secret would not have:
+
+- **Nothing on disk.** No secret to distribute to nine sites, drift, or leak through a backup.
+- **It rotates on every restart**, so a token read from a process listing or an old log stops working
+  the moment the site is restarted. `stop()` revokes, because nothing should still speak for a site
+  that is not running.
+- **A token names exactly one site.** There is no credential anywhere that speaks for the fleet, so a
+  compromised child cannot read another site's licences.
+
+The fleet env is applied *after* the site's own `.env`, so a site cannot claim a different slug or
+point itself at another manager.
+
+`isManaged()` requires the token as well as the URL: a site with one and not the other used to send
+`Bearer undefined` and report the resulting 401 as though the manager had rejected it.
+
+**What the catalogue joins.** Artifact facts from `catalogue.json` (rebuilt on release), prices from the
+terms store (changed whenever somebody changes a number), and `entitled` computed per request from the
+live ledger and never stored - so revoking a licence takes effect on the next refresh rather than the
+next catalogue build. A plugin the site cannot have is still listed, disabled: a customer who cannot see
+a plugin cannot buy one.
+
+**The entitlement minted on this path is a RENTAL** ending when the licence does. Perpetual belongs to
+the standalone download and is unreachable from here; confusing the two would hand a monthly renter
+something that never stops, or expire something bought outright.
+| `GET …/plugins/:slug/download?licence=…` | **New.** Mint and return a `.dcmsplugin` envelope for a paid licence. |
+| `GET/PUT …/plugin-terms` | **New.** Read and amend commercial terms per plugin. |
+
+Plus:
+
+- `paid-plugins/` becomes a monorepo checkout rather than the source of truth.
+- The Plugin Store view gains a **Download standalone** action beside the existing per-site grant.
+- A new **Plugin Terms** view (`admin/views/plugin-terms.js` + template, sidebar entry beside
+  Plugin Store and Licences) edits `data/plugin-terms.json`.
+- `licenceManager` gains the model distinction: a rental carries `expiresAt`, a perpetual licence
+  carries `supportExpiresAt` and a version ceiling, and `runExpiryCheck()` must **not** deactivate
+  a perpetual licence when its support window ends.
+
+### Upgrade path
+
+**Built** (`upgradePlugin()` in `pluginInstaller.js`; `tests/services/plugin-upgrade.test.js`).
+`installPlugin()` used to refuse an existing directory outright, which made this a marketplace you
+could buy from once and never update from.
+
+1. Compare manifest versions - **numerically**, so 1.10.0 is newer than 1.2.0 - and refuse a
+   downgrade unless forced.
+2. Extract to `.<slug>.incoming` and validate the manifest **there**, via the same
+   `validatePluginDir()` that `discoverPlugins()` uses. Validating after the swap would mean
+   finding out the new version is broken with the old one already gone.
+3. Carry `plugins/<slug>/data/` and `.entitlement.json` across: both belong to the site rather than
+   the version, and a renewal dropped in yesterday must survive today's update.
+4. Rename the old directory to `.<slug>.backup`, swap, and only then delete the backup. On any
+   failure the previous directory goes back. The one state this must never produce is "neither
+   version installed".
+
+The upload route asks for consent rather than reporting a refusal: a second upload of an installed
+slug answers **409** carrying both version numbers, which the Marketplace turns into "Update 1.0.0
+to 1.1.0?". An unsigned file and a downgrade each take their own confirmation. Consent flags are
+read after the file is drained, so where the browser puts them in the multipart body cannot decide
+whether they are seen.
+
+## Sequencing
+
+Ordered so that the riskiest thing gets fixed first and the easiest last.
+
+**1. Settle the duplicate slugs.** Decide Surveys' tier (finding #8) and whether `theme-roller`
+overlaps `theme-switcher` enough to merge. Blocks everything: the catalogue cannot be generated
+while one slug has two tiers. *Exit test:* every slug across both repos resolves to exactly one
+tier.
+
+**2. Consolidate into one repo, and extract `invoice`.** Create `dcms-marketplace`; import the paid
+set from the manager's `paid-plugins/` (**the source**, not the minified site copies), the
+manager-only plugins from `domma-cms-manager/plugins/`, and the free set from `domma-cms/plugins/`. Then run [the extraction](#extracting-a-plugin-that-shipped-free) for `invoice`:
+grandfather the four live sites **first**, then remove it from `domma-cms/plugins/`. Do the same for
+`surveys` (two licence records, no running installs). Replace `SKIP_PLUGINS` with the tier check, and
+delete the stray paid copies from the eight existing sites along with the `form-builder` and
+`site-search` residue. Withdraw `seo-pro` in the order given in
+[Withdrawing seo-pro](#withdrawing-seo-pro-and-reserving-a-slug) - `proBundle` first, then
+`rescindPlugin()` per site - and write `reserved.json`. *Exit test:* a fresh clone plus
+`make catalogue` reproduces every currently deployed paid plugin byte-for-byte; the four invoice
+sites each hold an active rental licence with no restart having occurred; a newly scaffolded site contains
+free-tier plugins only; and enabling Pro on a site issues no `seo-pro` licence.
+The value here is consolidation, not rescue: the paid plugins already have history (finding #11),
+they are just filed inside the fleet supervisor. **The actual unbacked code is the five site-only
+plugins**, and `reactive-showcase` at 9,587 LOC should be put somewhere versioned regardless of
+whether the marketplace is ever built. It is not a marketplace plugin and does not belong in the
+monorepo - a repo of its own, or the `reactive` site's own repo, is the right home.
+
+**3. Catalogue generation and key rotation.** `build-catalogue.js`, and the key work in
+[Signing keys](#signing-keys): generate the Ed25519 key `marketplace-1` offline, add it to
+`TRUSTED_KEYS`, **delete `manager-2026`**, and switch the verifier to `crypto.verify(null, …)`. *Exit test:* a generated bundle
+installs on a scratch CMS; flipping one byte in the tarball makes it fail loudly; and a bundle signed
+with the old key is refused as an unknown keyId.
+
+**4. Export and import as one file.** The envelope reader and writer, `GET /plugins/:name/export`,
+`POST /plugins/install-upload`, the `closedSource` export refusal, and the unsigned-import policy.
+Independent of entitlements and useful on its own: it is also the tool that makes step 2 repeatable
+rather than a one-off copy, since an orphaned paid plugin can be exported off a live site instead of
+lifted out of a directory by hand. *Exit test:* tests 10 to 13 below.
+
+**5. Child-side entitlement verification, and the terms store.** `pluginEntitlement.js`, the load
+gate, the entitlement route, the admin surface; on the manager side, `plugin-terms.json`, the Plugin
+Terms view, and the issuing half of `licenceManager` for both models. **Gates selling to anyone
+outside the fleet** - until it exists, a standalone download is unenforceable. The builder needs no
+work at any point here: it is already free and must stay untouched. *Exit test:* the table in
+[Entitlement](#entitlement), each row observed, plus tests 15 to 18 below.
+
+**6. Wire the existing client to the new endpoints.** **Done.** Two routes rather than four (the
+register handshake was dropped, heartbeat deferred), and `MANAGER_URL` is injected at fork rather than
+set per site. *Exit test passed on pj-plastering:* it lists all fourteen catalogue entries over HTTP,
+shows `invoice` and `docs` as Licensed from the real ledger, refuses `docs` before its licence exists
+and installs it after, and updates 1.0.0 to 1.1.0 from the Browse tab keeping its data and entitlement.
+
+One thing the exit test found: **the Browse tab had never mounted at all.** It loaded its template with
+`H.get`, which ends every call with `response.json()`, so an HTML template threw on the first `<`. The
+lazy mount caught that and left the panel empty - indistinguishable from the empty catalogue the
+manager was returning anyway, which is why it survived this long.
+
+## Testing
+
+The 2026-04-08 verification list still stands and is not repeated. In addition:
+
+1. **Free tier offline.** Fresh `npm install domma-cms`, no network: every free plugin loads. No
+   entitlement code path runs for a plugin without `closedSource`.
+2. **Envelope tampering.** Flip one byte in `plugin.tar.gz` inside the envelope - install fails,
+   nothing is left in `plugins/`.
+3. **Entitlement tampering.** Extend `expiresAt` by hand - signature fails, plugin does not load,
+   admin reports `unlicensed`.
+4. **Slug mismatch.** Envelope named for one slug, manifest declaring another - refused.
+5. **Expiry and grace.** Backdate `expiresAt` into grace: loads with a warning. Past grace: does
+   not load, `config/plugins.json` untouched, files present.
+6. **Renewal without reinstall.** Drop a fresh entitlement, restart, plugin loads.
+7. **Supersede interaction.** `email-pro` installed and entitled displaces `mail-reader`; let the
+   entitlement expire and confirm `mail-reader` returns on the next boot rather than both going dark.
+8. **Upgrade preserves data.** Install v1, write plugin data, upgrade to v2, data intact.
+9. **Upgrade rollback.** Upgrade with a deliberately broken manifest in the new version - previous
+   version and its data restored.
+10. **Export and reimport round-trip.** Export `notes` from one CMS, import on a second, restart:
+    same version, collections and forms created by `setupPlugin()`, plugin runs. Exported twice from
+    the same state, the envelope is byte-identical.
+11. **Export excludes state.** Write plugin data and collection entries, export, import elsewhere:
+    no `data/`, no entries, schema present, plugin lands disabled.
+12. **Paid export refused.** `GET /plugins/email-pro/export` answers 403, and the Export action is
+    absent from its card rather than present and failing.
+13. **Unsigned import policy.** With `requireSignedPlugins: false`, an unsigned envelope installs
+    only after confirmation and logs `install:unsigned`. With it `true`, refused. A *tampered*
+    signature is refused under both settings.
+14. **Rental expiry stops the plugin.** A `model: "rental"` entitlement past `expiresAt` plus grace:
+    plugin does not load, reported `"expired"`, files and `config/plugins.json` untouched.
+15. **Perpetual support lapse does not.** A `model: "perpetual"` entitlement with
+    `supportExpiresAt` in the past: plugin **loads**, reported `"support-ended"`, indefinitely and
+    with no network. Installing a version above the `versions` ceiling is refused with the reason;
+    installing one within it still works.
+16. **Renewal by file drop.** Post a fresh entitlement with a later ceiling, restart: the newer
+    version installs. No reinstall of the plugin itself.
+17. **Terms edits do not reach issued entitlements.** Change `monthly` and `licence` in Plugin
+    Terms; every existing entitlement and ledger record is byte-identical afterwards, and a live
+    rental is not re-rated.
+18. **The builder is untouched by all of it.** On a CMS with no entitlement file anywhere, scaffold
+    a plugin from the admin and from the CLI, edit it in the code editor, enable it, export it:
+    all succeed, and no entitlement check runs at any point.
+19. **A new site is seeded with free plugins only.** Scaffold a site: no `calendar`, `docs`,
+    `email-pro`, `invoice`, `messages` or `surveys` on disk. Grant one, and it appears.
+20. **A reserved slug cannot ship or be granted.** `make catalogue` with a `seo-pro` directory
+    present emits no bundle for it and says why; the Plugin Store offers no grant for it.
+21. **The retired key is untrusted.** A bundle bearing `publicKeyId: "manager-2026"` is refused as
+    an unknown key, not merely as a bad signature.
+22. **Ed25519 round-trip.** A bundle signed offline verifies on a scratch CMS; one flipped byte
+    fails; and a verifier still passing `'sha256'` throws `ERR_OSSL_INVALID_DIGEST` rather than
+    accepting anything.
+23. **Fleet path unregressed.** Grant and rescind a paid plugin from the Plugin Store exactly as
+    today; `getEntitlements()` still reports ground truth.
+24. **No supervisor.** On a bare `node server/server.js`, install reports that a manual restart is
+    needed rather than exiting into a dead site.
+
+## Deliberately deferred
+
+- **Payments.** Stripe, invoicing, dunning. The ledger records entitlement; it does not take money.
+- **Auto-update of paid plugins.** Manual click for v1, per 2026-04-08.
+- **Hardware or domain binding.** Purchaser identity only for v1. Fingerprint activation is a v2
+  option and `registerInstance()` already exists for it.
+- **Public anonymous browsing UI.** The static catalogue is machine-readable first; a marketing
+  storefront is separate work.
+- **Heartbeat and telemetry.** Stays opt-in and off by default.
+- **Search, ratings, third-party authors.** A marketplace with one vendor needs none of it, and
+  third-party plugins would change the signing model completely.
+
+## Open questions
+
+1. **Currency and tax.** `terms.json` carries one currency per plugin. Does a non-UK customer see
+   GBP, or do terms need per-currency amounts? VAT and reverse charge are unaddressed and belong
+   with payments, but the *displayed* figure needs a decision sooner than payments do.
+2. **Proration on managed rentals.** Granting a paid plugin mid-month: charge the full month, prorate,
+   or start the term at the grant? `minimumTermMonths` exists in the shape but nothing reads it yet.
+3. **Third-party authors.** Revenue share, attribution, support obligations, and whether a
+   third-party plugin can be *paid* at all. Signing code we did not write is the part that needs the
+   most thought; accepting free submissions needs almost none of it.
+4. **Should `requireSignedPlugins` default `true` on a fleet child?** The updater merges
+   `config/server.json`, so the default could differ by how a site was provisioned rather than by a
+   global choice. Leaning yes for fleet children, `false` for a self-hosted install.
+5. **Does the free tier stay vendored in `domma-cms/plugins/`, or move to the monorepo entirely?**
+   Vendoring keeps `npm install` self-contained, which is the current behaviour and worth keeping,
+   but it does mean the free subset exists in two working trees with a sync step between them.