domma-cms 1.6.60 → 1.7.0

package/docs/superpowers/specs/plans/2026-09-22-marketplace-step2-consolidation.md

@@ -0,0 +1,505 @@
+# Marketplace Step 2 - Consolidation, Extraction and Withdrawal
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Put every plugin in one repo, extract `invoice` and `surveys` from the free tier without
+disturbing a live site, stop the scaffolder seeding paid plugins, withdraw `seo-pro`, and get the
+five unversioned site plugins into git.
+
+**Architecture:** A new private monorepo `dcms-marketplace` becomes the canonical home for every
+marketplace plugin, free and paid. `domma-cms/plugins/` keeps a vendored copy of the free tier only
+(so `npm install domma-cms` stays self-contained), synced from the monorepo. The manager's
+`paid-plugins/` becomes a checkout rather than a source. Every manifest gains `tier`, and the
+scaffolder's hand-written `SKIP_PLUGINS` set is replaced by a read of that field.
+
+**Spec:** `docs/superpowers/specs/2026-09-22-dcms-marketplace-design.md` (sequencing step 2)
+
+**Tech Stack:** Fastify 5 (ESM), Domma SPA admin, `node:test` runner, JSON file storage, git.
+
+**Critical project rules** (from `CLAUDE.md` + memory):
+
+- Server on port **4096** is **always running** - never start or stop it. Test via `curl`.
+- **Never stop a fleet site by hand.** Use `processManager` through the Site Manager API or
+  `entitlements.rescindPlugin()`. A site stopped outside `processManager` after a pm2 manager restart
+  becomes an orphan and does not respawn.
+- Fleet sites run `NODE_ENV=production`, so cached HTML ignores hand-edited data until the site
+  restarts. Plugin file changes need a restart too.
+- `domma-cms` is worked on concurrently by another agent. **Commit early, add named paths only,
+  never stash.**
+- `npm test` is serial on purpose (`--test-concurrency=1`). Restore any config file a test pollutes.
+- Do **not** publish to npm as part of this plan. Roll locally: build to `_publish/` and use
+  `SOURCE=` that directory.
+
+**Ordering constraints that must not be reordered:**
+
+1. **Grandfather before extract.** Licences for `invoice` and `surveys` are issued *before* either is
+   removed from `domma-cms/plugins/`, so no site ever holds a paid plugin with no licence record.
+2. **`proBundle` before revoke.** `seo-pro` leaves the Pro bundle *before* its licences are revoked,
+   or the next Pro enable re-issues one.
+3. **Verify provenance before importing.** Several plugins exist in three places and only one copy is
+   the source; importing a minified derivative is silent and permanent.
+
+---
+
+## Phase 0 - Provenance verification (no writes)
+
+The monorepo must be seeded from source, never from a build artifact. Two derivations are already
+known: the manager's copies of plugins that also live in `domma-cms` are built (their
+`admin/css/index.css` is a single line against 87 to 487 lines in `domma-cms`), and every site copy
+has been through `pluginDistributor.minifyAdminCode()` at `activate()`.
+
+- [x] For each slug, record the canonical copy in a provenance table committed to the monorepo as
+  `PROVENANCE.md`. **Done 2026-09-22** - findings below; the file is drafted and lands with Phase 1:
+  - **Free set + `invoice` + `surveys`** → `domma-cms/plugins/<slug>/` (unminified, carries CLAUDE.md)
+  - **Paid set** (`analytics-pro`, `data-transfer`, `mongodb-adapter`, `job-board`, `theme-roller`) →
+    `domma-cms-manager/plugins/site-manager/paid-plugins/<slug>/`
+  - **Manager-only** (`calendar`, `docs`, `messages`, `garage`) → `domma-cms-manager/plugins/<slug>/`
+- [x] **`email-pro` resolved.** Its two copies (`domma-cms-manager/plugins/email-pro` and
+  `paid-plugins/email-pro`) are byte-identical, so there is nothing to choose. Take `paid-plugins/`
+  as canonical, since that is the distribution source. Paid, sold under licence.
+- [x] Confirm no site copy is newer than its claimed source. **Done** - every file in every
+  candidate copy hashed, excluding `data/`, `backups/` and `node_modules/`.
+
+**Exit: met.** `PROVENANCE.md` names one source per slug and every difference is accounted for.
+
+### Phase 0 findings
+
+**1. `paid-plugins/surveys` is a stale fork and must not be imported.** This is what the phase was
+for. Three copies existed and the one that looked authoritative was three months behind:
+
+| Copy | `plugin.js` | mtime |
+|---|---|---|
+| `domma-cms/plugins/surveys` | 9,368 bytes | 2026-08-21 |
+| `domma-cms-manager/plugins/surveys` | 9,368 bytes | 2026-09-22 (build copy of the above) |
+| `paid-plugins/surveys` | **8,985 bytes** | **2026-06-29** |
+
+`domma-cms` against `paid-plugins`: **16 files differ**, including `plugin.js`, `lib/ledger.js`,
+`lib/sending.js`, `lib/submit.js` and two admin templates. Importing the wrong one would have rolled
+`surveys` back silently, with no error anywhere. Canonical source is **`domma-cms/plugins/surveys`**.
+No site runs the stale copy: every site receives `surveys` from the scaffolder, which copies the
+manager's build of the `domma-cms` source, and it is enabled on zero sites.
+
+**2. Nothing has ever been hand-edited on a live site.** All 18 scaffolder-distributed plugins are
+byte-identical across all 8 sites and match their manager source exactly. `email-pro` is the only
+exception and only in 8 minified `admin/**/*.js` files, which is `minifyAdminCode()` behaving as
+designed. **There are no live fixes to rescue**, which removes the risk that made Phase 5's deletions
+dangerous.
+
+**3. `minifyAdminCode()` has only ever run for `email-pro`.** `analytics-pro`, `data-transfer`,
+`mongodb-adapter` and `seo-pro` are all `closedSource: true`, yet their `admin/**/*.js` is byte
+identical to source on every site they are installed on - so their admin code ships readable. Either
+they were granted before that step existed, or esbuild was unavailable at grant time. Not a security
+matter, since it never was one, but re-granting them would apply it. Worth deciding whether to
+re-grant during Phase 5, when those sites are being touched anyway.
+
+**4. `email-pro`'s two copies are byte-identical**, so there was nothing to choose. `paid-plugins/` is
+canonical as the distribution source.
+
+**5. The monorepo needs `.gitignore` entries for `data/` and `backups/`.** `data-transfer` writes
+timestamped backup trees into `backups/` at runtime; `oneill-leisure` holds 28 such files.
+
+---
+
+## Phase 1 - Create the monorepo
+
+**Done 2026-09-22** at `/home/dommajs/domains/dcms-marketplace`, 22 commits, no remote yet.
+
+- [x] Repo created with the spec's layout, plus `README.md` and `scripts/verify.js`.
+- [x] All **20** plugins imported from their Phase 0 sources, one verbatim commit each naming the
+  absolute source path. Re-verified afterwards: every one is byte-identical to its source, manifest
+  excepted.
+- [x] `_lib` and `_template` not imported - they stay in `domma-cms/plugins/` so the builder works
+  from `npm install` alone.
+- [x] `site-manager`, `customer-registration`, `site-tweaks` and the four site-local plugins not
+  imported.
+- [x] `tier` on every manifest: **8 free, 12 paid**.
+- [x] `closedSource: true` added - **to six plugins, not two**. See the deviation below.
+
+**Exit: met.** `make verify` passes: 20 plugins, 8 free, 12 paid, 4 reserved slugs, required manifest
+fields present, no committed runtime state.
+
+### Deviation: closedSource on six plugins, not two
+
+This phase called for `closedSource: true` on `invoice` and `surveys` only. It was also applied to
+`calendar`, `docs`, `messages` and `garage`, which are open in their manager source but are becoming
+paid. `closedSource` is what refuses the source editor (`pluginFiles.isClosedSource`) and what makes
+path C refuse to export a plugin, so a paid plugin without it is readable and re-exportable by the
+customer who bought it - which would contradict the design's own export refusal. Deployed copies are
+unaffected until they are re-distributed.
+
+`scripts/verify.js` now enforces this as an invariant: a `tier: "paid"` plugin without
+`closedSource: true` fails the check.
+
+### What the import commits are for
+
+Each import is a pristine snapshot; `tier` and `closedSource` were applied afterwards in one separate
+commit. So `git show <import-commit>` remains exactly what the source looked like on 2026-09-22,
+which is what makes the Phase 0 provenance claims checkable later rather than merely asserted.
+
+### Remote
+
+Not configured - the user is setting it up. After `git remote add origin …`, push `main`. Nothing in
+the repo assumes a remote.
+
+---
+
+## Phase 2 - Grandfather the live installs
+
+**This phase runs before Phase 3. It issues licences for plugins that are about to become paid, while
+the files are already in place, so nothing changes on any site.**
+
+**Done 2026-09-22.** Exactly one file changed across the whole estate: the licence ledger.
+
+- [x] `invoice` licensed on `atlas-learning`, `oneill-leisure`, `jamie-alcock` and `pinpointzero` -
+  the four sites where it is **enabled**. 365-day term, 7-day grace, matching the existing
+  `proLicenceDays` / `gracePeriodDays` defaults. **Not** `grantPlugin()` - see the trap below.
+- [x] `surveys`' two existing licences (`pinpointzero`, `domma-cms-site`) both point at sites that
+  still exist. Left active.
+- [x] Verified: `invoice` still `enabled: true` on all four; no site file written (the only site
+  writes in the window were three `analytics-pro/data/hits.jsonl`, which is the visitor tracker
+  logging live traffic).
+
+**Exit: met.** Ledger now holds 24 records, 4 of them `invoice`, all active.
+
+**Rollback:** revoke the four licence ids, or restore
+`data/licences.json.bak-pre-invoice-grandfather-20260922T094837`. Nothing else was touched.
+
+### Trap: `grantPlugin()` would have disabled invoice on four live sites
+
+The plan said to use `entitlements.grantPlugin()`. **Do not**, for a plugin that is not resident in
+`paid-plugins/`. `grantPlugin()` issues the licence and then calls
+`pluginDistributor.activate()`, which throws `Plugin "invoice" not found in paid-plugins directory`
+- and its error path calls `pluginDistributor.deactivate()`, writing `enabled: false` into the
+child's `config/plugins.json` before rethrowing. The site keeps serving until its next restart and
+then comes back **without invoicing**, with the cause recorded nowhere near the symptom.
+
+Grandfathering was done with `licenceManager.activate()` instead: it writes the ledger record and
+nothing else. No files, no config, no restart. That is the correct tool whenever the files are
+already in place and only the licence is missing.
+
+`grantPlugin()` becomes the right call for `invoice` once `paid-plugins/` is a checkout of the
+monorepo - but note that at that point `activate()` will also overwrite each site's copy and minify
+its admin JS, now that `invoice` is `closedSource`. That is a deliberate re-distribution, not part of
+grandfathering.
+
+### Correction to this phase's original exit test
+
+It read "every site holding `invoice` **files** also holds an active licence". That is too strict:
+`invoice` files sit on all eight sites because the scaffolder put them there, but only four have it
+enabled. The other four are strays and **Phase 5 deletes them**; licensing a site that does not use
+the plugin would have been wrong. The test is: every site with `invoice` *enabled* holds an active
+licence.
+
+---
+
+## Phase 3 - Extract from the free tier
+
+- [x] **`invoice` removed** from `domma-cms/plugins/` (35 files, named-path `git rm`).
+- [x] **`surveys` removed**, with its 11 test files, once option 1 was chosen for the test question.
+- [x] `package.json` had no `files` entry for either. A fresh `npm run build` confirms
+  `_publish/plugins/` no longer contains `invoice`.
+- [x] `tier: "paid"` + `closedSource: true` on **both** manager copies. Committed for `invoice`;
+  applied on disk for `surveys` but **not committed, because `plugins/surveys/` is gitignored in the
+  manager** - see the finding below. The tag still takes effect, since `siteScaffolder` walks the
+  filesystem rather than git.
+- [x] History not rewritten; the reasoning is in the commit message.
+- [x] `CHANGELOG.md` entry added under Unreleased.
+
+**Exit: met.** `_publish/plugins/` contains neither plugin. The four invoice sites are unaffected and
+still licensed, `surveys` was enabled on no site and its two licences are untouched, and the suite
+passes: **1,584 before, 1,550 after, with the missing 34 now passing in the marketplace repo.**
+
+### Resolved: the tests moved with the plugin (option 1)
+
+`tests/surveys/` is **11 files, 527 lines**, and they import from three places at once:
+
+```
+../../plugins/surveys/lib/{ledger,tokens,campaigns,submit}.js   the plugin
+../../server/services/{collections,forms}.js                    the CMS core
+fastify, @fastify/jwt                                           domma-cms node_modules
+```
+
+Delete the plugin and `npm test` breaks. Move the tests to the monorepo and they need a CMS checkout
+*and* its `node_modules` to run at all. This is not a `surveys` problem - it is the general question
+of **how a paid plugin's tests run once the plugin no longer lives inside the CMS**, and it will
+recur for every paid plugin that has tests.
+
+Three options, none of them free:
+
+1. **Tests move with the plugin, monorepo gains a host-CMS dependency.** Honest about where the code
+   lives; costs a `package.json`, an `npm install`, and a documented path to a sibling `domma-cms`
+   checkout. Test imports of `../../server/services/…` become the awkward part.
+2. **Tests stay in `domma-cms`, importing the plugin from the sibling monorepo checkout.** Cheapest
+   to do, but `domma-cms`'s suite then fails for anyone without the private repo - including CI.
+3. **Ship `surveys` to the monorepo without its tests.** Fastest, and the worst: 527 lines of
+   coverage for a plugin about to be sold, discarded to avoid a packaging decision.
+
+**Chosen: (1).** Tests live at `plugins/<slug>/tests/` in the monorepo and run with `make test`.
+
+Implementing it turned up something the options above had not anticipated: **the plugin's own source
+addresses the CMS by relative path too**, not just its tests. `plugins/surveys/plugin.js` imports
+`../../server/services/collections.js`, and `lib/submit.js` requires
+`../../../public/js/form-logic-engine.js` - correct in production, where the plugin is installed at
+`plugins/<slug>/` inside a CMS tree, and broken in a repo whose root has no `server/`.
+
+Rewriting those imports would have been the obvious move and the wrong one: it would break every
+plugin where it actually runs. Instead `make link-cms` gives the repo just enough of the CMS's shape,
+as local symlinks into a sibling checkout, none committed:
+
+| Link | Points at | Why |
+|---|---|---|
+| `cms` | `../domma-cms` | the host checkout |
+| `node_modules` | `cms/node_modules` | the CMS's own fastify, not a separately pinned one |
+| `server` | `cms/server` | plugin source imports `../../server/services/…` |
+| `public` | `cms/public` | shared browser code, e.g. `public/js/form-logic-engine.js` |
+| `plugins/_lib` | `cms/plugins/_lib` | the shared helper library, imported as `../_lib/…` |
+
+Tests also run with cwd set to the CMS root, because the core reads `config/server.json` relative to
+cwd when imported. This harness is generic - it is what every paid plugin's tests will use.
+
+The manager's untracked `plugins/surveys/` was deleted at the same time, per the finding below. The
+manager had it disabled, so nothing there changed.
+
+### Finding: `plugins/surveys/` is gitignored in the manager, deliberately
+
+```
+# ── Pro plugins are distributed via paid-plugins/, not tracked in the engine tree ──
+# The 0.32.x domma-cms engine bundles plugins/surveys/; keep it Pro-isolated.
+plugins/surveys/
+```
+
+A past decision had already treated `surveys` as Pro and kept the engine's bundled copy out of the
+manager repo. That is why `paid-plugins/surveys` exists as a separate fork, and why it went stale:
+the engine copy kept being updated in `domma-cms` while the Pro copy sat untouched from 2026-06-29.
+Every other plugin in `domma-cms-manager/plugins/` is tracked normally.
+
+Consequence for later phases: once `surveys` does leave `domma-cms`, the manager's untracked
+`plugins/surveys/` should be **deleted**, not kept - it is the engine's bundled copy of a plugin the
+engine no longer ships. `surveys` then lives in `paid-plugins/` only, refreshed from the monorepo.
+
+---
+
+### Finding for step 5: the manager runs paid plugins itself - RESOLVED
+
+`domma-cms-manager` is a CMS, and its own `config/plugins.json` has `docs`, `email-pro`, `garage` and
+`invoice` **enabled** - four `closedSource` plugins, with no licence records, because it is ours.
+`cms.dommajs.org` is in the same position with `docs`, `invoice` and `messages`.
+
+Once entitlement verification lands (spec step 5), both would refuse to load them at boot - and on the
+manager that means the fleet's management plane losing half its admin, including the screens used to
+issue the licences that would fix it.
+
+**Resolved 2026-09-22: a wildcard entitlement.** The manager is not merely "ours", it is the testbed
+where plugins are written, so per-plugin self-issued licences would mean licensing a plugin before
+you can run your own new code. Full reasoning in the spec's
+[Owner instances](../2026-09-22-dcms-marketplace-design.md#owner-instances).
+
+## Phase 4 - Stop seeding paid plugins
+
+**Done 2026-09-22.**
+
+- [x] `SKIP_PLUGINS` replaced with `if (manifest.tier === 'paid') continue;`, keeping the
+  manager-only exclusions and the `_`-prefix skip.
+- [x] Manifest now read from the **source** before the copy, so a paid plugin is never written to the
+  site at all.
+- [x] **No readable manifest now means skip** - an addition, not in the original task.
+  `discoverPlugins` would not load such a directory either, and this is what keeps `form-builder`
+  residue off new sites.
+- [x] `tier: "paid"` added to the manager's `calendar`, `docs`, `email-pro`, `garage`, `messages`.
+- [x] Throwaway site scaffolded: **9 free plugins seeded, 0 paid**, and no `form-builder`.
+- [x] `data-transfer` granted to it and appeared correctly, enabled in its `config/plugins.json`.
+- [x] Throwaway deleted. `scaffoldSite()` writes only into `sites/<slug>` - it never touches
+  `sites.json`, `ports.json`, Apache or `processManager` - so nothing was registered or started and
+  deleting the directory orphaned nothing. Ledger still 24 records, sites still 9.
+- [x] 67 site-manager service tests pass.
+
+**Exit: met.**
+
+### Why only the paid manifests were tagged
+
+Absent `tier` means free, matching the CMS loader, so only paid plugins strictly need tagging. Tagging
+the free ones in the manager would also be pointless: the engine updater refreshes those copies from
+`domma-cms`, whose manifests carry no `tier` until `sync-free-tier` lands in step 3, so the tag would
+be overwritten. The paid ones are manager-owned and the updater leaves them alone.
+
+### Rule established: closedSource lives on distribution copies, not local installs
+
+`closedSource` was **removed** from the manager's `invoice` copy, reversing part of Phase 3.
+`domma-cms-manager/plugins/` holds the manager's *own installed* plugins; `paid-plugins/` is the
+distribution source. On a local install `closedSource` achieves nothing except stopping us editing
+our own code in the admin editor. The copies that reach customers - monorepo and `paid-plugins/` -
+carry it, which is where it does its job.
+
+### Aside: the manager's `npm test` runs nothing
+
+`package.json` globs `tests/**/*.test.js`, but the manager's tests live at
+`plugins/site-manager/services/*.test.js`. `npm test` reports "tests 0" and exits 0, which is worse
+than failing. Run directly, all 67 pass. Not fixed here - it is unrelated to this plan - but it means
+any verification step that says "run the manager's tests" has been passing vacuously.
+
+---
+
+## Phase 5 - Remove the strays
+
+Six paid slugs currently sit unlicensed on existing sites, seeded by the drifted skip-list. Left
+alone they will report `"unlicensed"` in the customer's admin once entitlement verification lands.
+
+**Done 2026-09-22.** Note it is **nine** sites, not eight: `domma-cms-site` lives under the manager
+rather than in `dcms/`, and earlier audits in this plan had missed it.
+
+- [x] Audited all nine sites against the licence ledger.
+- [x] **43 directories removed**, every one disabled and unlicensed, with their `config/plugins.json`
+  entries dropped. A last-second guard in the removal script re-checked `enabled` per directory and
+  would have refused any that were.
+- [x] `form-builder` gone from all nine; `plugins/site-search/` gone from `domma-cms` (it was
+  untracked - git does not track empty directories - so there is nothing to commit for it).
+- [x] `reserved.json` already carried `form-builder` and `site-search` from Phase 1.
+- [x] **No restarts needed.** Everything removed was disabled, so no running process had it loaded.
+  All nine domains verified returning 200 afterwards.
+
+**Exit: met, with five exceptions held back deliberately** - see below.
+
+### Everything was archived first
+
+`domma-cms-manager/var/phase5-removed-plugins-20260922T103005.tar.gz` - 43 directories, 1,280 files,
+947K, symlinks dereferenced so the real content is inside. Removal is fully reversible from it.
+
+This was not in the original task and should have been: `docs` and `form-builder` carry `data/` on
+every site. Most of it turned out to be seeded defaults - the same document UUIDs and identical file
+sizes repeated across sites - but `oneill-leisure/form-builder` held five form definitions that exist
+nowhere else, neither in `content/forms/` nor anywhere code can reach, since the plugin has no code
+left. Dead data, but a customer's dead data, and not something to delete on a judgement call.
+
+### STOP: five plugins are enabled and unlicensed
+
+Not removed, per this phase's own rule. These are plugins someone is using:
+
+| Site | Plugin | Status |
+|---|---|---|
+| `ginga-ninja` | `messages` | **Licensed 2026-09-22** - was a customer running a paid plugin nobody had billed for |
+| `oneill-leisure` | `messages` | **Licensed 2026-09-22** - as above |
+| `domma-cms-site` | `docs`, `invoice`, `messages` | **Still open** - our own site, the self-licensing question |
+
+The two customer cases got the `invoice` treatment: `licenceManager.activate()`, 365-day term, 7-day
+grace, files untouched and no restart, so nothing changed for either customer except that what they
+are using is now on the books. `messages` is not in `paid-plugins/` either, so `grantPlugin()` would
+have hit the same trap it would have hit for `invoice`.
+
+Ledger is now **26 records**. The only unlicensed paid plugins left anywhere are the three on
+`domma-cms-site`, which is the same question as the manager running its own paid plugins (see the
+step 5 finding above) - exempt, or self-issue. It is ours, so nothing is at risk while it waits.
+
+### Left uncommitted deliberately
+
+The removals show as `D` deletions in each site's own git repo, and for `domma-cms-site` inside the
+manager repo. They are **not committed**: those working trees already carry 70 to 220 files of
+unrelated drift that is not mine to commit, and `config/plugins.json` in particular may hold someone
+else's pending change. Worth committing per site, but as a deliberate act rather than swept up here.
+
+---
+
+## Phase 6 - Dispose of the site-local plugins
+
+Four of the five are already tracked in their own sites' git repos, so this phase is disposition
+rather than rescue. None go in the monorepo.
+
+**Done 2026-09-22.** A third correction to the version-control claim first: **`shopping-cart` is
+tracked too.** `domma-cms-site` has no `.git` of its own, but the manager repo tracks all 619 of its
+files, those 5 included. **Every plugin on the estate is versioned somewhere.** Each time this was
+got wrong the mistake was the same - looking for a `.git` or a specific home, and not checking
+whether an enclosing repo tracked it.
+
+- [x] `reactive-showcase` - **no action required.** 21/21 files tracked in the `reactive` repo. Log a
+  separate, optional task to stop vendoring `public/domma-reactive.esm.js` (7,999 of its 9,587 lines)
+  and take the library from npm instead.
+- [ ] `retro64-games` - **no action required.** Tracked in `retro-64`. It is structurally a proper
+  plugin (four routes, admin view, per-game JSON store) and stays one; it is simply never a
+  marketplace plugin.
+- [x] `retro64-cors` - **core feature landed**: `cors.publicPrefixes` in `config/server.json`, with
+  `server/services/publicCors.js`, 5 tests, and the hook wired in `server.js`. `publicPrefixes` is
+  stripped before the `@fastify/cors` register call rather than passed as an unknown option, and the
+  `skip-override` trick is not needed in core because the hook attaches to the root instance.
+  **The plugin is NOT deleted yet**: the feature has to reach `retro-64` in a CMS release first, or
+  there would be a window with neither. Deleting it, and setting
+  `cors.publicPrefixes: ["/public/retro64/"]` on that site, belongs to that release.
+- [ ] `cache-autoflush` - promote into core. **Own task, not this plan**, unchanged (see the spec's
+  [Promoting a plugin into core](../2026-09-22-dcms-marketplace-design.md#promoting-a-plugin-into-core)):
+  it needs a `config/cache.json` block, a startup hook in `server.js`, and a retirement migration
+  modelled on `search-migration.js`. Until then it stays where it is and keeps working.
+- [x] `shopping-cart` - **untouched scaffolder output**: every route commented out, `onEnable` empty.
+  Reserved in `reserved.json`, nothing imported. Free is the right tier once something exists.
+- [x] `domma-cms-site` needs nothing - it is tracked in the manager repo, as above.
+
+**Exit: met**, except `retro64-cors`'s plugin deletion, which waits on a release.
+
+---
+
+## Phase 7 - Withdraw seo-pro
+
+**Order is load-bearing: the bundle first, then the licences.**
+
+**Done 2026-09-22**, in the stated order.
+
+- [x] `seo-pro` removed from `proBundle` **first**. Confirmed no `settings.proBundle` override exists
+  in the manager's `config/plugins.json`, so the default is the whole answer.
+- [x] Three licences revoked. `licenceManager.list({pluginName: 'seo-pro'})` returns three `revoked`
+  records and nothing else. Ledger still 26 records.
+- [x] Files deleted from `pinpointzero`, `retro-64`, `atlas-learning` and from `paid-plugins/`,
+  archived first to `var/phase7-seo-pro-20260922T104908.tar.gz`.
+- [x] `seo-pro` pruned from `proPlugins` on all three sites, so the PRO badge stays honest.
+- [x] Already reserved in `reserved.json`, and never imported into the monorepo.
+
+**Exit: met.** All four affected domains verified 200 afterwards.
+
+### `rescindPlugin()` was not used, and no restart was forced
+
+`rescindPlugin()` restarts the child through `processManager`. **That only works from inside the
+manager's own process**, which forks and supervises each site: a `processManager.start()` called from
+a standalone script would parent the site to that script and orphan it on exit. Restarting a fleet
+site has to go through the Site Manager API, not a node one-liner.
+
+It turned out not to be needed. Nothing on any site referenced `/api/plugins/seo-pro/meta`, and
+removing a plugin's files does not unregister its route from a process that already loaded it - so the
+plugin simply stops existing at each site's next restart, whenever that happens. `registerPlugins`
+iterates discovered manifests, so a stale `enabled` entry for a missing plugin is ignored rather than
+an error; the config entries were dropped anyway.
+
+---
+
+## Phase 8 - Retire the hand-maintained lists
+
+**Done 2026-09-22.**
+
+- [x] `KNOWN_HUES` deleted. Every hue is derived from the plugin name, which is what the fallback did
+  anyway. `_template` stays colourless.
+- [x] `README.md`'s Bundled Plugins table regenerated from the manifests actually present - the eight
+  free-tier plugins - with a pointer to the marketplace for the rest.
+- [x] Already recorded in the spec that `proBundle` moves into `plugin-terms.json` at step 5.
+
+**Exit: met.** The only plugin list left in `domma-cms` is `CORE_PLUGINS`, which is a mechanism rather
+than an inventory. Suite at **1,555 passing**.
+
+---
+
+## Verification
+
+Run after every phase, not only at the end. The fleet is live throughout.
+
+- [ ] `npm test` in `domma-cms` passes, serially. Restore any polluted config file.
+- [ ] All nine customer domains respond. Apache proxies every one through the manager, so a manager
+  fault takes them all out at once.
+- [ ] Each site's admin Plugins screen loads and reports no plugin in a failed-load state
+  (`getPluginLoadFailures()`).
+- [ ] `getEntitlements()` reports no orphan state on any site: nothing installed-but-unlicensed,
+  nothing licensed-but-missing.
+- [ ] A fresh `npm run build` succeeds and `_publish/plugins/` contains exactly the free tier plus
+  `_lib` and `_template`.
+- [ ] `git clone` of the monorepo, then a diff of each plugin against its live deployed copy,
+  accounts for every difference as minification.
+
+## Out of scope
+
+Everything in spec steps 3 to 6: the Ed25519 key and catalogue generation, the envelope format,
+export and import, entitlement verification, the terms store and the Plugin Terms view, and wiring
+the marketplace client to the manager. This plan only moves code, licences and lists into the shape
+those steps assume.

package/docs/superpowers/specs/plans/2026-09-22-marketplace-step3-catalogue-and-key.md

@@ -0,0 +1,154 @@
+# Marketplace Step 3 - The Signing Key and the Catalogue
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Generate the Ed25519 key `marketplace-1` offline, retire `manager-2026` from the CMS,
+and turn the monorepo's 20 plugins into a signed, publishable catalogue.
+
+**Architecture:** `make catalogue` walks `plugins/*/plugin.json` and emits `catalogue.json` plus one
+tarball and detached signature per plugin, all signed with a key that never touches the manager host.
+`terms.json` is a separate file on a separate lifecycle, so a price change is a save rather than a
+release. The CMS gains the new public key and loses the old one.
+
+**Spec:** `docs/superpowers/specs/2026-09-22-dcms-marketplace-design.md` (sequencing step 3, and
+[Signing keys](../2026-09-22-dcms-marketplace-design.md#signing-keys))
+
+**Prerequisite, already done:** `scripts/entitlement.js` and `scripts/issue-entitlement.js` exist in
+`dcms-marketplace` and are tested. They need only a key to become useful.
+
+**Critical project rules** (from `CLAUDE.md` + memory):
+
+- The private key is generated on a machine that is **not** the manager host and is never copied onto
+  it. This server is the manager host.
+- Server on port **4096** is always running; never start or stop it.
+- `npm test` is serial. `domma-cms` is worked on concurrently - commit early, named paths only.
+- Do not publish to npm as part of this plan.
+
+**Ordering constraint:** the key exists before anything is signed, and `manager-2026` leaves
+`TRUSTED_KEYS` in the same release that adds `marketplace-1`. Shipping the new key while keeping the
+old one would leave a window where a bundle signed by a lost key is still accepted.
+
+---
+
+## Phase 1 - Generate and place the key - DONE (on this host, deliberately)
+
+**Generated 2026-09-22 on the manager host**, which is a deliberate deviation from this phase's own
+instruction - see the spec's Custody section, which records it rather than pretending otherwise.
+
+- [x] Pair generated:
+  ```sh
+  openssl genpkey -algorithm ed25519 -out marketplace-1.pem
+  openssl pkey -in marketplace-1.pem -pubout -out marketplace-1.pub
+  ```
+- [x] Private half at `~/.domma-keys/marketplace-1.pem` (dir 0700, key 0600), outside every
+  repository.
+- [x] **Second copy held off this disk**, confirmed by the owner 2026-09-22. Recorded as reported
+  rather than verified: this host has a single filesystem, no removable media and no network mounts,
+  so a backup here is by definition somewhere I cannot see.
+
+  This was the failure being recovered from - `plugin-signing-2026.pem` was named in the code and
+  existed nowhere. The key has now signed a catalogue, so losing it would mean re-signing everything
+  under a new keyId and shipping a CMS release before anyone trusted it.
+- [x] `marketplace-1.pub` committed to `dcms-marketplace/keys/`; `*.pem` is gitignored there, and
+  `git check-ignore` confirms the private half cannot land by accident.
+- [ ] Record in `PROVENANCE.md` where the private key lives - the location, not the key.
+
+**Exit:** `keys/marketplace-1.pub` is committed, the private half is in two safe places, and
+`git log -p` shows no `.pem` anywhere.
+
+## Phase 2 - Swap the key in the CMS - DONE
+
+- [x] `marketplace-1` added, `manager-2026` deleted, verifier switched to `crypto.verify(null, …)`.
+- [ ] Delete the `PLACEHOLDER` guard if it no longer applies, or keep it if a placeholder is still
+  conceivable. It exists so a stub key can never verify anything.
+- [x] Tests added via a new `trustedKeyIds()` export, so the contract is checkable without key
+  material: exactly one key trusted, `manager-2026` gone, the trusted key is **Ed25519** (an RSA
+  paste would verify fine and only fail in the field), and `manager-2026` is refused by name before
+  any signature check.
+- [ ] Still to do: the signed-bundle install round trip, which needs the catalogue build of Phase 3
+  to produce a real bundle.
+- [ ] `npm test` passes.
+
+**Exit:** the CMS trusts exactly one key, and the retired one is refused by name.
+
+## Phase 3 - Catalogue generation - DONE
+
+- [x] `scripts/build-catalogue.js`, wired to `make catalogue KEY=...`, emitting:
+  ```
+  dist/catalogue.json            signed index
+  dist/catalogue.json.sig
+  dist/bundles/<slug>-<version>.tar.gz
+  dist/bundles/<slug>-<version>.tar.gz.sig
+  ```
+- [x] Entries carry **artifact facts only**: `slug`, `version`, `displayName`, `description`, `tier`,
+  `icon`, `supersedes`, `requires`, `minCmsVersion`. No prices - those live in `terms.json`.
+- [x] **Refuses any slug in `reserved.json`**, and aborts with `dist/` untouched. `seo-pro`, `shopping-cart`, `form-builder` and
+  `site-search` must not be publishable by someone adding a directory and forgetting why the name was
+  held. `scripts/verify.js` already fails a reserved slug; the catalogue build must too.
+- [x] Excludes `data/`, `backups/`, `node_modules/` and `CLAUDE.md` from every tarball. `data-transfer` writes backup trees at
+  runtime and one site had 28 of them.
+- [x] Tarball format **proven**, not assumed, through `pluginInstaller.extractTar()`: which strips the leading
+  path component and ignores symlinks. **Generate a tarball and install it on a scratch CMS** rather
+  than assuming the formats agree.
+- [x] Reuses `canonicalise()` for the catalogue signature, so there is one
+  canonical-JSON implementation in the repo rather than two that can drift.
+
+**Exit: met.** 14 plugins, 2 free and 12 paid. A generated `mongodb-adapter` bundle installed on the
+dev CMS through the real installer and its files landed correctly; a copy with one byte flipped was
+refused with "Plugin signature invalid". The catalogue signature verifies and fails on tampering.
+
+### Found while building: validation order
+
+The first version wiped `dist/` and then validated as it went, so **one bad manifest destroyed the
+last good catalogue on its way to failing**. Surfaced by testing the reserved-slug refusal, which is
+precisely the case that would hit it in practice. Validation now runs first and a failed build leaves
+the previous output exactly where it was.
+
+Builds are also reproducible - `--sort=name`, fixed mtime, `gzip -n` - so unchanged code produces
+identical signatures. Without it every release would churn every signature and customers would
+re-download code that had not changed.
+
+## Phase 4 - The free-tier sync
+
+- [ ] `scripts/sync-free-tier.js`, wired to `make sync-free-tier`: copy every `tier: "free"` plugin
+  into `domma-cms/plugins/`, so `npm install domma-cms` stays a complete offline plugin-development
+  environment.
+- [ ] It must **not** touch `_lib` or `_template`, which live in `domma-cms` and are its own.
+- [ ] Decide the direction of truth first. Today `domma-cms` is still the working copy for free
+  plugins, and this script would make the monorepo authoritative. Whichever is chosen, only one of
+  them can be edited afterwards, and the other is generated. **This is open question 5 in the spec
+  and should be settled before the script exists**, because a two-way sync is how both copies end up
+  wrong.
+
+**Exit:** the free subset in `domma-cms` is reproducible from the monorepo by one command, and it is
+documented which side is authoritative.
+
+## Phase 5 - Publish
+
+- [ ] Put `dist/` on object storage plus CDN. Static files only: no application server on the public
+  path, which is the whole point of signing offline.
+- [ ] `terms.json` publishes alongside, rewritten whenever a price changes. It does **not** require a
+  catalogue rebuild.
+- [ ] Verify a plain `curl` of the catalogue and one bundle from an unauthenticated client, since
+  that is exactly what a CMS does.
+
+**Exit:** a CMS with no credentials can fetch and verify the catalogue and a free bundle.
+
+## Verification
+
+- [ ] `npm test` in `domma-cms` passes, serially.
+- [ ] `make verify` and `make test` pass in `dcms-marketplace`.
+- [ ] All nine customer domains respond; the fleet is untouched by any of this.
+- [ ] A bundle signed with a throwaway key is **refused** by a CMS trusting only `marketplace-1`.
+- [ ] `git log -p` across both repos contains no private key material.
+
+## Out of scope
+
+Step 4's envelope and export/import, step 5's entitlement verification and terms store, and step 6's
+wiring of the marketplace client. Issuing the owner wildcards is step 5 work and cannot happen until
+the verifier exists - though once the key from Phase 1 exists, the command itself is ready:
+
+```sh
+node scripts/issue-entitlement.js --key <private.pem> --slug '*' --model perpetual --no-support \
+    --purchaser-name "Domma (owner instance: dcm.dommajs.org)" --out entitlement.json
+```