From a5e1a4a35d01e09cbfd2c503370c95a8c2490867 Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Thu, 16 Apr 2026 16:01:04 +0300
Subject: [PATCH 01/56] Bump CLI dependencies (#5383)

---
 .changeset/cozy-wombats-burn.md | 5 +++++
 packages/cli/lib/util.js        | 4 ++--
 packages/cli/package.json       | 3 +--
 3 files changed, 8 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/cozy-wombats-burn.md

diff --git a/.changeset/cozy-wombats-burn.md b/.changeset/cozy-wombats-burn.md
new file mode 100644
index 0000000000..e04a363fcd
--- /dev/null
+++ b/.changeset/cozy-wombats-burn.md
@@ -0,0 +1,5 @@
+---
+"@apostrophecms/cli": patch
+---
+
+Bump and clean up depdendencies.
diff --git a/packages/cli/lib/util.js b/packages/cli/lib/util.js
index f531f47e77..566b3e75fc 100644
--- a/packages/cli/lib/util.js
+++ b/packages/cli/lib/util.js
@@ -7,7 +7,7 @@ const util = {};
 const _ = require('lodash');
 const cliVersion = require('../package.json').version;
 const confUtils = require('./conf-utils');
-const packageJson = require('package-json');
+const { execSync } = require('child_process');
 const semver = require('semver');
 const ora = require('ora');
 const { spawn } = require('child_process');
@@ -218,7 +218,7 @@ util.spawnWithSpinner = async function (command, options = {
 async function checkIfUpdated () {
   try {
     // Get the latest published version number.
-    const { version: latest } = await packageJson('@apostrophecms/cli');
+    const latest = execSync('npm show @apostrophecms/cli version', { encoding: 'utf8' }).trim();
 
     // Check if they've been notified for this version already. If so, bail out.
     const latestChecked = await confUtils.getConf('versionNotified');
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 25c13dcde7..ff9c72b249 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -23,12 +23,11 @@
     "conf": "^6.2.4",
     "lodash": "^4.18.1",
     "ora": "^5.4.1",
-    "package-json": "^6.5.0",
     "pkginfo": "^0.4.1",
     "prompts": "^2.3.2",
     "semver": "^7.3.2",
     "shell-quote": "^1.8.1",
-    "shelljs": "~0.3.x",
+    "shelljs": "^0.10.0",
     "sync-request": "^6.0.0",
     "uuid": "^8.0.0"
   },

From 9f458b5d9544d33239a0971b0050fff8bffe028a Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Thu, 16 Apr 2026 16:38:22 +0300
Subject: [PATCH 02/56] Fix choices IDs (#5379)

* Fix choices IDs

* Cleanup dots from ID values

* Update changelog

Co-authored-by: Robert Means <robert@apostrophecms.com>

---------

Co-authored-by: Robert Means <robert@apostrophecms.com>
---
 .changeset/clean-actors-laugh.md                             | 5 +++++
 .../schema/ui/apos/logic/AposInputCheckboxes.js              | 2 +-
 .../@apostrophecms/schema/ui/apos/logic/AposInputRadio.js    | 2 +-
 3 files changed, 7 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/clean-actors-laugh.md

diff --git a/.changeset/clean-actors-laugh.md b/.changeset/clean-actors-laugh.md
new file mode 100644
index 0000000000..5d78fab358
--- /dev/null
+++ b/.changeset/clean-actors-laugh.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": patch
+---
+
+Fix illegal HTML id attribute values generated by the admin UI
diff --git a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/logic/AposInputCheckboxes.js b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/logic/AposInputCheckboxes.js
index 45a8a4c6d0..73fa374d04 100644
--- a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/logic/AposInputCheckboxes.js
+++ b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/logic/AposInputCheckboxes.js
@@ -11,7 +11,7 @@ export default {
   },
   methods: {
     getChoiceId(uid, value) {
-      return (uid + JSON.stringify(value)).replace(/\s+/g, '');
+      return (uid + String(value)).replace(/[\s"'.]/g, '');
     },
     watchValue () {
       this.error = this.modelValue.error;
diff --git a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/logic/AposInputRadio.js b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/logic/AposInputRadio.js
index 97dffa11ed..f7d1b6f6e9 100644
--- a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/logic/AposInputRadio.js
+++ b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/logic/AposInputRadio.js
@@ -8,7 +8,7 @@ export default {
   mixins: [ AposInputMixin, AposInputChoicesMixin ],
   methods: {
     getChoiceId(uid, value) {
-      return (uid + JSON.stringify(value)).replace(/\s+/g, '');
+      return (uid + String(value)).replace(/[\s"'.]/g, '');
     },
     validate(value) {
       const validValue = this.choices.some((choice) => choice.value === value);

From b9b32bdd446add927c75d85e44d0a26814ba62b0 Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Fri, 17 Apr 2026 13:30:56 +0300
Subject: [PATCH 03/56] Native browser shortcuts work again (#5384)

---
 .changeset/full-symbols-obey.md                   |  5 +++++
 .../modules/@apostrophecms/area/index.js          | 15 ++++++++++-----
 .../ui/apos/components/TheAposCommandMenu.vue     | 12 +++++++++++-
 3 files changed, 26 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/full-symbols-obey.md

diff --git a/.changeset/full-symbols-obey.md b/.changeset/full-symbols-obey.md
new file mode 100644
index 0000000000..903395756e
--- /dev/null
+++ b/.changeset/full-symbols-obey.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": patch
+---
+
+Keyboard shortcuts for widget operations (copy, cut, paste, duplicate, remove) no longer block the browser's native clipboard behavior when no widget is focused. Previously, selecting and copying text on a page while logged in was prevented by the admin UI intercepting those shortcuts unconditionally.
diff --git a/packages/apostrophe/modules/@apostrophecms/area/index.js b/packages/apostrophe/modules/@apostrophecms/area/index.js
index 47b83516f1..a96d8248c8 100644
--- a/packages/apostrophe/modules/@apostrophecms/area/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/area/index.js
@@ -19,7 +19,8 @@ module.exports = {
           action: {
             type: 'command-menu-area-cut-widget'
           },
-          shortcut: 'Ctrl+X Meta+X'
+          shortcut: 'Ctrl+X Meta+X',
+          requireWidgetFocus: true
         },
         [`${self.__meta.name}:copy-widget`]: {
           type: 'item',
@@ -27,7 +28,8 @@ module.exports = {
           action: {
             type: 'command-menu-area-copy-widget'
           },
-          shortcut: 'Ctrl+C Meta+C'
+          shortcut: 'Ctrl+C Meta+C',
+          requireWidgetFocus: true
         },
         [`${self.__meta.name}:paste-widget`]: {
           type: 'item',
@@ -35,7 +37,8 @@ module.exports = {
           action: {
             type: 'command-menu-area-paste-widget'
           },
-          shortcut: 'Ctrl+V Meta+V'
+          shortcut: 'Ctrl+V Meta+V',
+          requireWidgetFocus: true
         },
         [`${self.__meta.name}:duplicate-widget`]: {
           type: 'item',
@@ -43,7 +46,8 @@ module.exports = {
           action: {
             type: 'command-menu-area-duplicate-widget'
           },
-          shortcut: 'Ctrl+Shift+D Meta+Shift+D'
+          shortcut: 'Ctrl+Shift+D Meta+Shift+D',
+          requireWidgetFocus: true
         },
         [`${self.__meta.name}:remove-widget`]: {
           type: 'item',
@@ -51,7 +55,8 @@ module.exports = {
           action: {
             type: 'command-menu-area-remove-widget'
           },
-          shortcut: 'Backspace'
+          shortcut: 'Backspace',
+          requireWidgetFocus: true
         }
       },
       modal: {
diff --git a/packages/apostrophe/modules/@apostrophecms/command-menu/ui/apos/components/TheAposCommandMenu.vue b/packages/apostrophe/modules/@apostrophecms/command-menu/ui/apos/components/TheAposCommandMenu.vue
index 6712ec169e..6003a5830d 100644
--- a/packages/apostrophe/modules/@apostrophecms/command-menu/ui/apos/components/TheAposCommandMenu.vue
+++ b/packages/apostrophe/modules/@apostrophecms/command-menu/ui/apos/components/TheAposCommandMenu.vue
@@ -10,6 +10,7 @@
 import { mapActions, mapState } from 'pinia';
 import AposThemeMixin from 'Modules/@apostrophecms/ui/mixins/AposThemeMixin';
 import { useModalStore } from 'Modules/@apostrophecms/ui/stores/modal';
+import { useWidgetStore } from 'Modules/@apostrophecms/ui/stores/widget';
 
 export default {
   name: 'TheAposCommandMenu',
@@ -50,7 +51,13 @@ export default {
               .flatMap(command => {
                 return command.shortcut
                   .split(' ')
-                  .map(shortcut => [ shortcut.toUpperCase(), command.action ]);
+                  .map(shortcut => [
+                    shortcut.toUpperCase(),
+                    {
+                      ...command.action,
+                      requireWidgetFocus: command.requireWidgetFocus || false
+                    }
+                  ]);
               });
           })
       );
@@ -111,6 +118,9 @@ export default {
             ? keys.slice('SHIFT+'.length)
             : keys];
         if (action) {
+          if (action.requireWidgetFocus && !useWidgetStore().focusedWidget) {
+            return;
+          }
           event.preventDefault();
           apos.bus.$emit(action.type, action.payload);
           return;

From 08845c5f23d95ead552ab9743a878daf997793a1 Mon Sep 17 00:00:00 2001
From: Robert Means <robert@apostrophecms.com>
Date: Wed, 22 Apr 2026 08:00:35 -0400
Subject: [PATCH 04/56] Pro 8838 charset (#5385)

* Removes encoding option and comments hardcoded encoding meta

* add changeset

* Response to first comments
---
 .changeset/fifty-hornets-follow.md                       | 7 +++++++
 packages/apostrophe/modules/@apostrophecms/i18n/index.js | 9 +--------
 .../@apostrophecms/template/views/outerLayoutBase.html   | 2 +-
 3 files changed, 9 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/fifty-hornets-follow.md

diff --git a/.changeset/fifty-hornets-follow.md b/.changeset/fifty-hornets-follow.md
new file mode 100644
index 0000000000..52da86bff8
--- /dev/null
+++ b/.changeset/fifty-hornets-follow.md
@@ -0,0 +1,7 @@
+---
+"apostrophe": minor
+---
+
+- Removed duplicate <meta charset> tag from `outerLayoutBase.html`
+- Standardized charset to utf-8 (removed legacy configuration option)
+- Altered unused/legacy i18n template helper to return `utf-8` (BC)
diff --git a/packages/apostrophe/modules/@apostrophecms/i18n/index.js b/packages/apostrophe/modules/@apostrophecms/i18n/index.js
index 96de6ad5ac..66d0aa9f8d 100644
--- a/packages/apostrophe/modules/@apostrophecms/i18n/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/i18n/index.js
@@ -29,10 +29,6 @@
 // in the same language as the website content.
 // Example: `defaultAdminLocale: 'fr'`.
 //
-// ### `encoding`
-//
-// Defaults to `'utf-8'`. You almost certainly do not want to change this.
-//
 // ### `slugDirection`
 //
 // Controls the default `direction` value of slug schema. Can be `ltr`, `rtl` or
@@ -81,8 +77,6 @@ module.exports = {
     },
     // If true, slugifying will strip accents from Latin characters
     stripUrlAccents: false,
-    // You almost certainly do not want to change this
-    encoding: 'utf-8',
     slugDirection: 'ltr'
   },
   async init(self) {
@@ -166,7 +160,6 @@ module.exports = {
     await self.i18next.init(i18nextOptions);
     self.addInitialResources();
     self.enableBrowserData();
-    self.encoding = self.options.encoding;
   },
   handlers(self) {
     return {
@@ -1369,7 +1362,7 @@ module.exports = {
   helpers(self) {
     return {
       encoding() {
-        return self.encoding;
+        return 'utf-8';
       }
     };
   }
diff --git a/packages/apostrophe/modules/@apostrophecms/template/views/outerLayoutBase.html b/packages/apostrophe/modules/@apostrophecms/template/views/outerLayoutBase.html
index 3ef25932f2..12c60de95f 100644
--- a/packages/apostrophe/modules/@apostrophecms/template/views/outerLayoutBase.html
+++ b/packages/apostrophe/modules/@apostrophecms/template/views/outerLayoutBase.html
@@ -2,6 +2,7 @@
 <html lang="{% block locale %}{{ data.locale }}{% endblock %}" dir="{% block direction %}{{ data.i18n.direction or 'ltr' }}{% endblock %}" {% block extraHtml %}{% endblock %}>
   <head>
     {% block encoding %}
+      {# Per spec (https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/meta#charset) the only allowed value for this attribute is `utf-8` and this meta element must be in the first 1kb of the document #}
       <meta charset="utf-8">
     {% endblock %}
     {% block startHead %}
@@ -15,7 +16,6 @@
 
     {% block standardHead %}
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <meta charset="{{ apos.i18n.encoding() }}">
     {% endblock %}
     {% component '@apostrophecms/template:inject' with { where: 'head', end: 'append', when: 'hmr' } %}
     {% component '@apostrophecms/template:inject' with { where: 'head', end: 'append' } %}

From d45e27f6d66cd25fde0cf9c7199ee9d014fa1518 Mon Sep 17 00:00:00 2001
From: haroun <1765606+haroun@users.noreply.github.com>
Date: Wed, 22 Apr 2026 16:10:15 +0200
Subject: [PATCH 05/56] Log aposResponse errors (#5386)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* log aposResponse errors

* add changeset

---------

Co-authored-by: Harouna Traoré <haroun@users.noreply.github.com>
---
 .changeset/wild-lies-film.md                  | 5 +++++
 packages/apostrophe-astro/lib/aposResponse.js | 5 ++++-
 2 files changed, 9 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/wild-lies-film.md

diff --git a/.changeset/wild-lies-film.md b/.changeset/wild-lies-film.md
new file mode 100644
index 0000000000..4070e1aea6
--- /dev/null
+++ b/.changeset/wild-lies-film.md
@@ -0,0 +1,5 @@
+---
+"@apostrophecms/apostrophe-astro": minor
+---
+
+Log aposResponse errors
diff --git a/packages/apostrophe-astro/lib/aposResponse.js b/packages/apostrophe-astro/lib/aposResponse.js
index ea4dcfb509..1f9f676080 100644
--- a/packages/apostrophe-astro/lib/aposResponse.js
+++ b/packages/apostrophe-astro/lib/aposResponse.js
@@ -49,7 +49,7 @@ export default async function aposResponse(req) {
 
     const aposUrl = new URL(aposHost + pathname);
     aposUrl.search = url.search;
- 
+
     // Prepare headers, excluding any specified in config
     const requestHeaders = {};
     for (const [name, value] of req.headers) {
@@ -111,6 +111,7 @@ export default async function aposResponse(req) {
           }
           // Skip unknown encodings silently
         } catch (decompressError) {
+          console.error(decompressError);
           // If decompression fails, return original response
           return new Response(new Uint8Array(bodyArrayBuffer), {
             ...rest,
@@ -133,10 +134,12 @@ export default async function aposResponse(req) {
         headers: responseHeaders
       });
     } catch (bodyError) {
+      console.error(bodyError);
       // If we can't process the body, fall back to the original response
       return new Response(res.body, { ...rest, status: statusCode, headers: responseHeaders });
     }
   } catch (error) {
+    console.error(error);
     // Handle any unexpected errors
     return new Response(`Server error: ${error.message}`, { status: 500 });
   }

From f3501f4de0448d4d0f8a01a1db4dc2fcf52c6218 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Thu, 23 Apr 2026 09:21:40 -0400
Subject: [PATCH 06/56] merge back the thanks (#5388)

---
 .changeset/wild-lies-film.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.changeset/wild-lies-film.md b/.changeset/wild-lies-film.md
index 4070e1aea6..3b608070dd 100644
--- a/.changeset/wild-lies-film.md
+++ b/.changeset/wild-lies-film.md
@@ -2,4 +2,4 @@
 "@apostrophecms/apostrophe-astro": minor
 ---
 
-Log aposResponse errors
+Log aposResponse errors server side in the Astro process. Thanks to [Harouna Traore](https://github.com/haroun).

From 0d857713c88b2d9d6393600baa2ca9f75c2d97ab Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Thu, 23 Apr 2026 09:22:01 -0400
Subject: [PATCH 07/56] Postgres (#5365)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* postgres experimental WIP

* astonishingly, all mocha tests of apostrophe pass with this

* mocha tests pass, actual sites work

* lint clean

* listDatabases support, but changes are coming

* wip

* dump and restore updates

* backpressure, adequate handling of ObjectId for our needs (becomes its hex representation)

* mild performance optimization

* profiling

* testing issue resolved

* refactored to db-connect module, introduced sqlite adapter

* sqlite WIP

* debugging

* programmatic API for dump/restore/copy dbs

* linting, documentation

* MIT license

* text ranking is more accurate, documentation is more complete

* good full text search for sqlite

* updates for compatibility with the rest of the public and private modules, plus a few fixes to genuinely ambiguous tests

* requirements found by testing private modules

* fixes from full cypress run

* eslint passing

* restore permissions

* maximize atomicity

* bug fixes

* * exit properly when asset tests fail
* "npm test" tests all three adapters

* ignore claude-tools in eslint

* postgres and sqlite-inclusive ci matrix attempt

* clean up logs

* We hit github's limit on total configurations because every package gets its own matrix.

Solve that with grouping:

* apostrophe core
* All regular ecosystem packages other than core
* non-database-requiring packges
* mongodb-specific packages

This will probably speed it up too because it won't have to spin up a container a bazillion times.

* hardened the asset tests, made them less timing sensitive, fixed a bad commit resulting from the
way they dodgily patch themselves without a robust cleanup mechanism

* fix a root cause of asset test instability

* log mess

* implemented missing $size operator

* test compatibility

* advanced permission uses regex in $in

* regex in $in

* .db() should not make false promises in plain postgres mode, it should fail

* ability to specify a default adapter

* obsolete file

* put escapeHost back where it belongs

* dead code removal, test cleanup

* emulate-mongo-3-driver only needed in db-connect

* no claude logs in repo (tools are welcome)

* * shared aggregation implementation, other shared things
* optimize $match when it is the first step in aggregation, don't fetch the whole collection 😜
* multipostgres listDatabases() and .db() should return and expect "fully qualified virtual database names," e.g. physical_db_name-schemaname

* vanilla postgres should not attempt to use .db() with alternate names in tests

* documentation corrections

* documentation errors

* listDatabases and documentation corrections

* more edge cases revealed by latest work from Miro

* anchored prefix regexps are optimized
documentation improvements

* * matchesQuery in the aggregation cursor implementation doesn't throw on unrecognized operators. It should, and it should support the same mongodb operators that the regular find()
  path does in postgres/sqlite (our official subset), unless there is an extraordinary reason not to.

  * Similarly, the main query implementation for normal queries should throw on unrecognized operators if it doesn't already.

  * The dump/restore programmatic APIs in db-connect concern me. These involve returning the entire database as a string, which could exhaust memory. This impacts both utilities and
  also copyDatabase(). Could these APIs return and expect async iterators instead of strings?

  * The test "anchored regex on an indexed field uses a btree index search" runs explain on a query that's hardcoded in the test. Instead these SQL based adapters should expose a means
  to get the SQL for a query, so it can be directly tested. Otherwise this test proves nothing as changes to the adapter accumulate in future.

  * Why is this test searching for "at least 1" and not exactly 1?

  it('should find documents with null value', async function() {
    const docs = await db.collection('test').find({ value: null }).toArray();
    // MongoDB matches both null and missing fields with { value: null }
    expect(docs.length).to.be.at.least(1);
  });

  * What is the maximum size of a db-connect document in the postgres and sqlite adapters?

  * Update the copyright year in db-connect/LICENSE.md to 2025.

  * The db-connect README mentions: sqlite://:memory: What happens if you try to use .db('some-name') with that? I think it would be best to just not support throwaway in-memory sqlite
  databases because I doubt anyone would intentionally store a website in one.

* do not swallow dump/restore errors on indexes

* cover how to run the utilities

* fix detection of source

* separate sanitization for index names

* regex prefix safety

* pnpm

---------

Co-authored-by: Thomas Boutell <boutell@vcs.trox.local>
---
 .github/workflows/monorepo.yml                |   68 +-
 .../scripts/detect-impacted-packages.mjs      |    7 +-
 .../scripts/expand-runtime-matrix.mjs         |  126 +-
 .gitignore                                    |    2 +
 claude-tools/run-core-tests.sh                |   37 +
 package.json                                  |    4 +-
 packages/apostrophe/.gitignore                |    3 +
 .../apostrophe/claude-tools/detect-handles.js |   46 +
 .../claude-tools/minimal-hang-test.js         |   28 +
 .../claude-tools/mongo-close-test.js          |   11 +
 .../apostrophe/claude-tools/stdin-ref-test.js |   14 +
 packages/apostrophe/eslint.config.js          |    3 +-
 .../modules/@apostrophecms/db/index.js        |   95 +-
 .../modules/@apostrophecms/http/index.js      |    2 +-
 .../modules/@apostrophecms/job/index.js       |   16 +-
 packages/apostrophe/package.json              |    8 +-
 .../apostrophe/scripts/find-heavy-npm-modules |    0
 packages/apostrophe/test-lib/util.js          |   64 +-
 .../add-missing-schema-fields-project/test.js |   14 +-
 packages/apostrophe/test/assets.js            |  177 +-
 packages/apostrophe/test/db-tools.js          |  365 ++
 packages/apostrophe/test/db.js                |   39 +-
 packages/apostrophe/test/default-adapter.js   |  256 ++
 packages/apostrophe/test/job.js               |    2 +-
 packages/broadband/package.json               |    3 +
 packages/cache-on-demand/package.json         |    3 +
 packages/db-connect/LICENSE.md                |    7 +
 packages/db-connect/README.md                 |  107 +
 packages/db-connect/adapters/mongodb.js       |   10 +
 packages/db-connect/adapters/postgres.js      | 2505 ++++++++++++
 packages/db-connect/adapters/sqlite.js        | 2398 ++++++++++++
 packages/db-connect/bin/apos-db-dump.js       |   42 +
 packages/db-connect/bin/apos-db-restore.js    |   30 +
 .../claude-tools/logs/dump-mongodb.log        |   11 +
 .../claude-tools/logs/dump-multipostgres.log  |   11 +
 .../claude-tools/logs/dump-postgres.log       |   11 +
 .../claude-tools/logs/dump-sqlite.log         |   11 +
 packages/db-connect/docs/aggregation.md       |  118 +
 packages/db-connect/docs/collections.md       |  293 ++
 packages/db-connect/docs/database.md          |   94 +
 packages/db-connect/docs/dump-restore.md      |  178 +
 packages/db-connect/docs/indexes.md           |  114 +
 packages/db-connect/docs/queries.md           |  233 ++
 packages/db-connect/docs/updates.md           |   99 +
 packages/db-connect/eslint.config.js          |    6 +
 packages/db-connect/index.js                  |   44 +
 packages/db-connect/lib/aggregation-cursor.js |  408 ++
 packages/db-connect/lib/copy-database.js      |   11 +
 packages/db-connect/lib/dump.js               |   91 +
 .../lib/mongodb-connect.js                    |    2 +-
 packages/db-connect/lib/restore.js            |  166 +
 packages/db-connect/lib/shared.js             |  438 +++
 packages/db-connect/package.json              |   29 +
 packages/db-connect/test/adapter.test.js      | 3361 +++++++++++++++++
 packages/db-connect/test/dump-restore.test.js |  180 +
 packages/db-connect/test/security.test.js     |  316 ++
 packages/db-connect/test/shared.test.js       |  121 +
 packages/emulate-mongo-3-driver/package.json  |    3 +
 packages/express-cache-on-demand/package.json |    3 +
 packages/form/test/test.js                    |    6 +-
 .../import-export/test/importDraftsOnly.js    |   12 +
 packages/import-export/test/index.js          |   93 +-
 .../import-export/test/overrideDuplicates.js  |    2 +-
 .../import-export/test/overrideLocales.js     |    5 +
 packages/mongodb-snapshot/package.json        |    3 +
 packages/uploadfs/webp-test.js                |    0
 66 files changed, 12764 insertions(+), 201 deletions(-)
 create mode 100755 claude-tools/run-core-tests.sh
 create mode 100644 packages/apostrophe/claude-tools/detect-handles.js
 create mode 100644 packages/apostrophe/claude-tools/minimal-hang-test.js
 create mode 100644 packages/apostrophe/claude-tools/mongo-close-test.js
 create mode 100644 packages/apostrophe/claude-tools/stdin-ref-test.js
 mode change 100755 => 100644 packages/apostrophe/scripts/find-heavy-npm-modules
 create mode 100644 packages/apostrophe/test/db-tools.js
 create mode 100644 packages/apostrophe/test/default-adapter.js
 create mode 100644 packages/db-connect/LICENSE.md
 create mode 100644 packages/db-connect/README.md
 create mode 100644 packages/db-connect/adapters/mongodb.js
 create mode 100644 packages/db-connect/adapters/postgres.js
 create mode 100644 packages/db-connect/adapters/sqlite.js
 create mode 100755 packages/db-connect/bin/apos-db-dump.js
 create mode 100755 packages/db-connect/bin/apos-db-restore.js
 create mode 100644 packages/db-connect/claude-tools/logs/dump-mongodb.log
 create mode 100644 packages/db-connect/claude-tools/logs/dump-multipostgres.log
 create mode 100644 packages/db-connect/claude-tools/logs/dump-postgres.log
 create mode 100644 packages/db-connect/claude-tools/logs/dump-sqlite.log
 create mode 100644 packages/db-connect/docs/aggregation.md
 create mode 100644 packages/db-connect/docs/collections.md
 create mode 100644 packages/db-connect/docs/database.md
 create mode 100644 packages/db-connect/docs/dump-restore.md
 create mode 100644 packages/db-connect/docs/indexes.md
 create mode 100644 packages/db-connect/docs/queries.md
 create mode 100644 packages/db-connect/docs/updates.md
 create mode 100644 packages/db-connect/eslint.config.js
 create mode 100644 packages/db-connect/index.js
 create mode 100644 packages/db-connect/lib/aggregation-cursor.js
 create mode 100644 packages/db-connect/lib/copy-database.js
 create mode 100644 packages/db-connect/lib/dump.js
 rename packages/{apostrophe => db-connect}/lib/mongodb-connect.js (96%)
 create mode 100644 packages/db-connect/lib/restore.js
 create mode 100644 packages/db-connect/lib/shared.js
 create mode 100644 packages/db-connect/package.json
 create mode 100644 packages/db-connect/test/adapter.test.js
 create mode 100644 packages/db-connect/test/dump-restore.test.js
 create mode 100644 packages/db-connect/test/security.test.js
 create mode 100644 packages/db-connect/test/shared.test.js
 mode change 100755 => 100644 packages/uploadfs/webp-test.js

diff --git a/.github/workflows/monorepo.yml b/.github/workflows/monorepo.yml
index 84746c945f..4276a83fe0 100644
--- a/.github/workflows/monorepo.yml
+++ b/.github/workflows/monorepo.yml
@@ -7,6 +7,7 @@ env:
   NODE_VERSIONS_JSON: "[20,22,24]"
   MONGODB_VERSIONS_JSON: '["7","8"]'
   REDIS_VERSION: "7"
+  POSTGRES_VERSION: "16"
 
 on:
   push:
@@ -124,7 +125,7 @@ jobs:
         run: |
           month='${{ steps.cache-month.outputs.value }}'
           mongo_suffix=$(jq -r '.[]' <<< '${{ env.MONGODB_VERSIONS_JSON }}' | paste -sd'-' -)
-          echo "key=docker-images-${month}-mongo${mongo_suffix}-redis${{ env.REDIS_VERSION }}" >> "$GITHUB_OUTPUT"
+          echo "key=docker-images-${month}-mongo${mongo_suffix}-redis${{ env.REDIS_VERSION }}-pg${{ env.POSTGRES_VERSION }}" >> "$GITHUB_OUTPUT"
 
       - name: Restore docker image cache
         id: docker-cache
@@ -143,6 +144,8 @@ jobs:
           done
           docker pull "redis:${{ env.REDIS_VERSION }}"
           docker save "redis:${{ env.REDIS_VERSION }}" -o ".github/docker-cache/redis-${{ env.REDIS_VERSION }}.tar"
+          docker pull "postgres:${{ env.POSTGRES_VERSION }}"
+          docker save "postgres:${{ env.POSTGRES_VERSION }}" -o ".github/docker-cache/postgres-${{ env.POSTGRES_VERSION }}.tar"
 
   warm-sharp-cache:
     name: Warm sharp/libvips cache (Node ${{ matrix.nodeVersion }})
@@ -216,7 +219,7 @@ jobs:
           du -sh ~/.npm/_libvips || true
 
   package-tests:
-    name: ${{ format('{0} ({1}, {2})', matrix.package, matrix.nodeVersion, matrix.needsMongo && matrix.mongodbVersion || 'n/a') }}
+    name: ${{ format('{0} ({1}, {2}{3})', matrix.group, matrix.nodeVersion, matrix.adapter || 'n/a', matrix.needsMongo && format(' mongo {0}', matrix.mongodbVersion) || '') }}
     needs:
       - setup
       - shared-runtime
@@ -279,7 +282,7 @@ jobs:
       - name: Restore docker image cache
         id: docker-cache-restore
         uses: actions/cache/restore@v4
-        if: matrix.needsMongo || matrix.needsRedis
+        if: matrix.needsMongo || matrix.needsRedis || matrix.needsPostgres
         with:
           path: .github/docker-cache
           key: ${{ needs.shared-runtime.outputs.docker-cache-key }}
@@ -300,6 +303,14 @@ jobs:
         if: steps.docker-cache-restore.outputs.cache-hit != 'true' && matrix.needsRedis
         run: docker pull redis:${{ env.REDIS_VERSION }}
 
+      - name: Load cached Postgres image
+        if: steps.docker-cache-restore.outputs.cache-hit == 'true' && matrix.needsPostgres
+        run: docker load -i ".github/docker-cache/postgres-${{ env.POSTGRES_VERSION }}.tar"
+
+      - name: Pull Postgres image (cache miss)
+        if: steps.docker-cache-restore.outputs.cache-hit != 'true' && matrix.needsPostgres
+        run: docker pull postgres:${{ env.POSTGRES_VERSION }}
+
       - name: Start MongoDB
         if: matrix.needsMongo
         run: |
@@ -358,15 +369,64 @@ jobs:
           docker logs redis
           exit 1
 
+      - name: Start PostgreSQL
+        if: matrix.needsPostgres
+        run: |
+          docker rm -f postgres >/dev/null 2>&1 || true
+          docker run -d \
+            --name postgres \
+            --publish 5432:5432 \
+            -e POSTGRES_HOST_AUTH_METHOD=trust \
+            --health-cmd "pg_isready -U postgres" \
+            --health-interval 5s \
+            --health-timeout 5s \
+            --health-retries 12 \
+            postgres:${{ env.POSTGRES_VERSION }}
+          echo "Waiting for PostgreSQL to report healthy..."
+          for attempt in $(seq 1 60); do
+            status=$(docker inspect --format='{{.State.Health.Status}}' postgres 2>/dev/null || echo "starting")
+            if [ "$status" = "healthy" ]; then
+              exit 0
+            fi
+            if [ "$status" = "unhealthy" ]; then
+              echo "PostgreSQL reported unhealthy" >&2
+              docker logs postgres
+              exit 1
+            fi
+            sleep 2
+          done
+          echo "PostgreSQL failed to become healthy in time" >&2
+          docker logs postgres
+          exit 1
+
       - name: Install workspace dependencies
         run: pnpm install --frozen-lockfile
 
       - name: Run package tests
-        run: pnpm run --filter "${{ matrix.package }}" --if-present test
+        run: |
+          failed=0
+          for pkg in $(echo '${{ matrix.packages }}' | jq -r '.[]'); do
+            echo "::group::Testing $pkg"
+            if ! pnpm run --filter "$pkg" --if-present test; then
+              echo "::error::Tests failed for $pkg"
+              failed=1
+            fi
+            echo "::endgroup::"
+          done
+          exit $failed
         env:
           CI: true
           # Yes we want import-export to test with automatic-translation
           TEST_WITH_PRO: "1"
+          # Adapter selection: mongodb (default), postgres, or sqlite.
+          # ADAPTER is used by db-connect tests, APOS_TEST_DB_PROTOCOL by apostrophe tests.
+          ADAPTER: ${{ matrix.adapter }}
+          APOS_TEST_DB_PROTOCOL: ${{ matrix.adapter }}
+          PGUSER: postgres
+
+      - name: Stop PostgreSQL
+        if: always() && matrix.needsPostgres
+        run: docker rm -f postgres || true
 
       - name: Stop Redis
         if: always() && matrix.needsRedis
diff --git a/.github/workflows/scripts/detect-impacted-packages.mjs b/.github/workflows/scripts/detect-impacted-packages.mjs
index 453f370938..392a29b6d1 100644
--- a/.github/workflows/scripts/detect-impacted-packages.mjs
+++ b/.github/workflows/scripts/detect-impacted-packages.mjs
@@ -73,7 +73,8 @@ async function main() {
       package: name,
       directory: packages.get(name).relativeDir,
       requiresMongo: packages.get(name).requiresMongo !== false,
-      requiresRedis: packages.get(name).requiresRedis === true
+      requiresRedis: packages.get(name).requiresRedis === true,
+      mongodbOnly: packages.get(name).mongodbOnly === true
     }))
   };
 
@@ -130,6 +131,7 @@ async function loadPackages() {
       const testConfig = manifest.apostropheTestConfig || {};
       const requiresMongo = testConfig.requiresMongo !== false;
       const requiresRedis = testConfig.requiresRedis === true;
+      const mongodbOnly = testConfig.mongodbOnly === true;
 
       map.set(manifest.name, {
         name: manifest.name,
@@ -137,7 +139,8 @@ async function loadPackages() {
         dependencies,
         hasTestScript,
         requiresMongo,
-        requiresRedis
+        requiresRedis,
+        mongodbOnly
       });
     }));
 
diff --git a/.github/workflows/scripts/expand-runtime-matrix.mjs b/.github/workflows/scripts/expand-runtime-matrix.mjs
index 0c0e46f690..3672fad06b 100644
--- a/.github/workflows/scripts/expand-runtime-matrix.mjs
+++ b/.github/workflows/scripts/expand-runtime-matrix.mjs
@@ -1,6 +1,21 @@
 #!/usr/bin/env node
-// Expands the impacted package matrix with runtime permutations supplied 
+// Expands the impacted package matrix with runtime permutations supplied
 // via env vars.
+//
+// Packages are grouped into jobs to stay within GitHub's 256-entry matrix limit:
+//   - "apostrophe" runs solo (the main package, benefits from its own status).
+//   - All other database packages are grouped into an "ecosystem" job.
+//   - mongodbOnly packages are grouped into "ecosystem-mongodb".
+//   - Non-database packages are grouped into "standalone".
+//
+// For groups that need a database, three adapter variants are emitted:
+//   1. mongodb  – all Node versions × all MongoDB versions
+//   2. postgres – latest LTS Node only, no MongoDB
+//   3. sqlite   – latest LTS Node only, no MongoDB
+//
+// The latest LTS Node version is the highest even-numbered entry in
+// NODE_VERSIONS_JSON.
+
 import { readFile } from 'fs/promises';
 
 const args = process.argv.slice(2);
@@ -36,25 +51,120 @@ function parseJsonArray(name, raw) {
 const nodeVersions = parseJsonArray('NODE_VERSIONS_JSON', process.env.NODE_VERSIONS_JSON);
 const mongodbVersions = parseJsonArray('MONGODB_VERSIONS_JSON', process.env.MONGODB_VERSIONS_JSON);
 
+// Latest LTS = highest even-numbered Node version
+const latestLts = [...nodeVersions]
+  .filter((v) => Number(v) % 2 === 0)
+  .sort((a, b) => Number(b) - Number(a))[0];
+
 const impact = JSON.parse(await readFile(impactPath, 'utf8'));
 const packages = impact?.matrix?.include || [];
-const include = [];
+
+// The main apostrophe package always gets its own jobs for clear CI status.
+const SOLO_PACKAGES = new Set(['apostrophe']);
+
+// Sort packages into groups
+const solo = [];
+const ecosystem = [];
+const ecosystemMongodbOnly = [];
+const standalone = [];
 
 for (const pkg of packages) {
-  const needsMongo = pkg.requiresMongo !== false;
-  const needsRedis = pkg.requiresRedis === true;
-  const mongoTargets = needsMongo ? mongodbVersions : [''];
+  const needsDb = pkg.requiresMongo !== false;
+  if (SOLO_PACKAGES.has(pkg.package)) {
+    solo.push(pkg);
+  } else if (needsDb && pkg.mongodbOnly) {
+    ecosystemMongodbOnly.push(pkg);
+  } else if (needsDb) {
+    ecosystem.push(pkg);
+  } else {
+    standalone.push(pkg);
+  }
+}
+
+const include = [];
+
+// Emit runtime combinations for a group of packages.
+function emitGroup(group, pkgs) {
+  if (!pkgs.length) {
+    return;
+  }
+  const packageNames = JSON.stringify(pkgs.map((p) => p.package));
+  const needsRedis = pkgs.some((p) => p.requiresRedis === true);
+  const mongodbOnly = pkgs.every((p) => p.mongodbOnly);
+
+  // mongodb: all Node versions × all MongoDB versions
   for (const nodeVersion of nodeVersions) {
-    for (const mongodbVersion of mongoTargets) {
+    for (const mongodbVersion of mongodbVersions) {
       include.push({
-        ...pkg,
+        group,
+        packages: packageNames,
         nodeVersion,
         mongodbVersion,
-        needsMongo,
+        adapter: 'mongodb',
+        needsMongo: true,
+        needsPostgres: false,
         needsRedis
       });
     }
   }
+  // postgres and sqlite: latest LTS only, skip for mongodb-only groups
+  if (!mongodbOnly) {
+    include.push({
+      group,
+      packages: packageNames,
+      nodeVersion: latestLts,
+      mongodbVersion: '',
+      adapter: 'postgres',
+      needsMongo: false,
+      needsPostgres: true,
+      needsRedis
+    });
+    include.push({
+      group,
+      packages: packageNames,
+      nodeVersion: latestLts,
+      mongodbVersion: '',
+      adapter: 'sqlite',
+      needsMongo: false,
+      needsPostgres: false,
+      needsRedis
+    });
+  }
+}
+
+// Emit non-database group (no adapter variants, just Node versions)
+function emitStandalone(group, pkgs) {
+  if (!pkgs.length) {
+    return;
+  }
+  const packageNames = JSON.stringify(pkgs.map((p) => p.package));
+  for (const nodeVersion of nodeVersions) {
+    include.push({
+      group,
+      packages: packageNames,
+      nodeVersion,
+      mongodbVersion: '',
+      adapter: '',
+      needsMongo: false,
+      needsPostgres: false,
+      needsRedis: false
+    });
+  }
+}
+
+// Solo packages each get their own group
+for (const pkg of solo) {
+  emitGroup(pkg.package, [pkg]);
+}
+
+if (ecosystem.length) {
+  emitGroup('ecosystem', ecosystem);
+}
+if (ecosystemMongodbOnly.length) {
+  emitGroup('ecosystem-mongodb', ecosystemMongodbOnly);
+}
+if (standalone.length) {
+  emitStandalone('standalone', standalone);
 }
 
 process.stdout.write(JSON.stringify({ include }));
diff --git a/.gitignore b/.gitignore
index 6bccc37b4b..e88b2189a4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,3 +6,5 @@ public/apos-frontend
 .DS_Store
 coverage/
 .nyc_output
+claude-tools/logs/
+.claude
diff --git a/claude-tools/run-core-tests.sh b/claude-tools/run-core-tests.sh
new file mode 100755
index 0000000000..eb8b77c009
--- /dev/null
+++ b/claude-tools/run-core-tests.sh
@@ -0,0 +1,37 @@
+#!/bin/bash
+# Run the apostrophe core test suite against a chosen DB adapter and log
+# output to claude-tools/logs/core-<adapter>.log. Usage:
+#
+#   ./claude-tools/run-core-tests.sh mongodb
+#   ./claude-tools/run-core-tests.sh postgres
+#   ./claude-tools/run-core-tests.sh sqlite
+#
+# NEVER run multiple adapters in parallel — the test suite is not designed
+# for concurrent runs and the host has limited resources.
+
+set -u
+adapter="${1:-}"
+if [[ -z "$adapter" ]]; then
+  echo "usage: $0 <mongodb|postgres|sqlite>" >&2
+  exit 2
+fi
+
+root="$(cd "$(dirname "$0")/.." && pwd)"
+logdir="$root/claude-tools/logs"
+mkdir -p "$logdir"
+log="$logdir/core-$adapter.log"
+: > "$log"
+
+echo "=== $adapter core tests ($(date -Is)) ===" | tee -a "$log"
+
+cd "$root/packages/apostrophe"
+
+extra=()
+if [[ "$adapter" == "postgres" ]]; then
+  extra=(env PGPASSWORD=testpassword)
+fi
+
+APOS_TEST_DB_PROTOCOL="$adapter" "${extra[@]}" npm run test:base >> "$log" 2>&1
+code=$?
+echo "=== exit=$code ===" | tee -a "$log"
+exit "$code"
diff --git a/package.json b/package.json
index 1fd8ccdf94..c80aee125e 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,8 @@
     "dev": "pnpm --parallel --recursive run dev",
     "build": "pnpm --recursive run build",
     "lint": "pnpm --recursive run lint",
-    "test": "pnpm --recursive run test",
+    "test": "APOS_TEST_DB_PROTOCOL=postgres pnpm run test:main && APOS_TEST_DB_PROTOCOL=mongodb pnpm run test:main && APOS_TEST_DB_PROTOCOL=sqlite pnpm run test:main && APOS_TEST_DB_PROTOCOL=multipostgres pnpm run test:main",
+    "test:main": "echo \"APOS_TEST_DB_PROTOCOL IS: $APOS_TEST_DB_PROTOCOL\" && pnpm --recursive run test",
     "eslint": "pnpm --recursive run eslint",
     "mocha": "pnpm --recursive run mocha",
     "clean": "pnpm -r exec rm -rf node_modules && rm -rf node_modules && rm pnpm-lock.yaml"
@@ -18,6 +19,7 @@
   },
   "pnpm": {
     "onlyBuiltDependencies": [
+      "better-sqlite3",
       "sharp",
       "vue-demi",
       "@parcel/watcher",
diff --git a/packages/apostrophe/.gitignore b/packages/apostrophe/.gitignore
index 894a9d6ba3..16ad414a99 100644
--- a/packages/apostrophe/.gitignore
+++ b/packages/apostrophe/.gitignore
@@ -42,3 +42,6 @@ test/public/uploads
 
 # vim swp files
 .*.sw*
+
+# claude-tools log files
+claude-tools/**/*.log
diff --git a/packages/apostrophe/claude-tools/detect-handles.js b/packages/apostrophe/claude-tools/detect-handles.js
new file mode 100644
index 0000000000..9cf711d976
--- /dev/null
+++ b/packages/apostrophe/claude-tools/detect-handles.js
@@ -0,0 +1,46 @@
+// Require this before running mocha to detect what activates process.stdin
+// Usage: npx mocha -t 10000 --require ./claude-tools/detect-handles.js test/assets.js
+
+console.log(`stdin paused at startup: ${process.stdin.isPaused()}`);
+console.log(`stdin readableFlowing at startup: ${process.stdin.readableFlowing}`);
+
+// Monkey-patch stdin.resume to capture the call stack
+const origResume = process.stdin.resume.bind(process.stdin);
+process.stdin.resume = function(...args) {
+  console.log('\n=== process.stdin.resume() called ===');
+  console.log(new Error().stack);
+  return origResume(...args);
+};
+
+// Monkey-patch stdin.on to detect 'data' listener additions
+const origOn = process.stdin.on.bind(process.stdin);
+process.stdin.on = function(event, ...args) {
+  if (event === 'data' || event === 'readable') {
+    console.log(`\n=== process.stdin.on('${event}') called ===`);
+    console.log(new Error().stack);
+  }
+  return origOn(event, ...args);
+};
+
+// Periodically check stdin state changes
+let lastState = process.stdin.readableFlowing;
+const checker = setInterval(() => {
+  if (process.stdin.readableFlowing !== lastState) {
+    console.log(`\n=== stdin readableFlowing changed: ${lastState} -> ${process.stdin.readableFlowing} ===`);
+    console.log(new Error().stack);
+    lastState = process.stdin.readableFlowing;
+  }
+}, 100);
+checker.unref();
+
+const origRun = require('mocha/lib/runner').prototype.run;
+require('mocha/lib/runner').prototype.run = function(fn) {
+  return origRun.call(this, function(failures) {
+    console.log(`\nstdin paused at end: ${process.stdin.isPaused()}`);
+    console.log(`stdin readableFlowing at end: ${process.stdin.readableFlowing}`);
+    setTimeout(() => {
+      process.exit(failures ? 3 : 0);
+    }, 2000);
+    if (fn) fn(failures);
+  });
+};
diff --git a/packages/apostrophe/claude-tools/minimal-hang-test.js b/packages/apostrophe/claude-tools/minimal-hang-test.js
new file mode 100644
index 0000000000..3d29952b7f
--- /dev/null
+++ b/packages/apostrophe/claude-tools/minimal-hang-test.js
@@ -0,0 +1,28 @@
+// Minimal test to isolate what causes the hang.
+// Must reference the test/ directory as root for proper module resolution.
+const t = require('../test-lib/test.js');
+const path = require('path');
+
+// Fake a module object rooted in test/ like the real tests do
+const fakeModule = {
+  id: path.join(__dirname, '../test/fake'),
+  filename: path.join(__dirname, '../test/fake.js'),
+  paths: [path.join(__dirname, '../test/node_modules')]
+};
+
+describe('Minimal hang test', function() {
+  this.timeout(60000);
+  let apos;
+
+  after(async function() {
+    await t.destroy(apos);
+    console.log('after: destroy complete');
+  });
+
+  it('should create and use apos without hanging', async function() {
+    apos = await t.create({
+      root: fakeModule
+    });
+    console.log('apos created successfully');
+  });
+});
diff --git a/packages/apostrophe/claude-tools/mongo-close-test.js b/packages/apostrophe/claude-tools/mongo-close-test.js
new file mode 100644
index 0000000000..360ce44299
--- /dev/null
+++ b/packages/apostrophe/claude-tools/mongo-close-test.js
@@ -0,0 +1,11 @@
+// Test whether a MongoDB connection keeps the process alive after close()
+const mongoConnect = require('../../../packages/db-connect/lib/mongodb-connect');
+
+(async () => {
+  const uri = 'mongodb://localhost:27017/test_handle_leak';
+  console.log('Connecting...');
+  const client = await mongoConnect(uri);
+  console.log('Connected. Closing...');
+  await client.close();
+  console.log('Closed. Process should exit now if no leaked handles.');
+})();
diff --git a/packages/apostrophe/claude-tools/stdin-ref-test.js b/packages/apostrophe/claude-tools/stdin-ref-test.js
new file mode 100644
index 0000000000..d562211bcb
--- /dev/null
+++ b/packages/apostrophe/claude-tools/stdin-ref-test.js
@@ -0,0 +1,14 @@
+// Check if process.stdin keeps the process alive
+// If this script hangs, stdin is ref'd. If it exits, stdin is unref'd.
+
+console.log(`stdin isTTY: ${process.stdin.isTTY}`);
+console.log(`stdin readableFlowing: ${process.stdin.readableFlowing}`);
+console.log(`stdin isPaused: ${process.stdin.isPaused()}`);
+
+// Check ref status
+if (typeof process.stdin.unref === 'function') {
+  console.log('stdin has unref method');
+}
+
+console.log('Waiting to see if process exits on its own...');
+// Don't do anything - just see if the process exits
diff --git a/packages/apostrophe/eslint.config.js b/packages/apostrophe/eslint.config.js
index 9377dc1974..969698e6ef 100644
--- a/packages/apostrophe/eslint.config.js
+++ b/packages/apostrophe/eslint.config.js
@@ -7,7 +7,8 @@ module.exports = defineConfig([
     '**/blueimp/**/*.js',
     'test/public',
     'test/apos-build',
-    'coverage'
+    'coverage',
+    'claude-tools'
   ]),
   apostrophe
 ]);
diff --git a/packages/apostrophe/modules/@apostrophecms/db/index.js b/packages/apostrophe/modules/@apostrophecms/db/index.js
index 8894adba94..58fac171ff 100644
--- a/packages/apostrophe/modules/@apostrophecms/db/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/db/index.js
@@ -4,11 +4,12 @@
 //
 // ### `uri`
 //
-// The MongoDB connection URI. See the [MongoDB URI documentation](https://docs.mongodb.com/manual/reference/connection-string/).
+// The databse connection URI. See the [MongoDB URI documentation](https://docs.mongodb.com/manual/reference/connection-string/)
+// and the postgres documentation.
 //
 // ### `connect`
 //
-// If present, this object is passed on as options to MongoDB's "connect"
+// If present, this object is passed on as options to the database adapters "connect"
 // method, along with the uri. See the [MongoDB connect settings documentation](http://mongodb.github.io/node-mongodb-native/2.2/reference/connecting/connection-settings/).
 //
 // By default, Apostrophe sets options to retry lost connections forever,
@@ -20,9 +21,16 @@
 //
 // ### `client`
 //
-// An existing MongoDB connection (MongoClient) object. If present, it is used
+// An existing MongoDB-compatible client object. If present, it is used
 // and `uri`, `host`, `connect`, etc. are ignored.
 //
+// ### `adapters`
+//
+// An array of adapters, each of which must provide `name`, `connect(uri, options)`,
+// and `protocols` properties. `name` may be used to override a core adapter,
+// such as `postgres` or `mongodb`. `connect` must resolve to a client object
+// supporting a sufficient subset of the mongodb API.
+//
 // ### `versionCheck`
 //
 // If `true`, check to make sure the database does not belong to an
@@ -49,15 +57,15 @@
 // in your project. However you may find it easier to just use the
 // `client` option.
 
-const mongodbConnect = require('../../../lib/mongodb-connect');
-const escapeHost = require('../../../lib/escape-host');
+const dbConnect = require('@apostrophecms/db-connect');
+const escapeHost = require('../../../lib/escape-host.js');
 
 module.exports = {
   options: {
     versionCheck: true
   },
   async init(self) {
-    await self.connectToMongo();
+    await self.connectToDb();
     await self.versionCheck();
   },
   handlers(self) {
@@ -81,14 +89,12 @@ module.exports = {
   },
   methods(self) {
     return {
-      // Open the database connection. Always uses MongoClient with its
-      // sensible defaults. Builds a URI if necessary, so we can call it
-      // in a consistent way.
-      //
-      // One default we override: if the connection is lost, we keep
-      // attempting to reconnect forever. This is the most sensible behavior
-      // for a persistent process that requires MongoDB in order to operate.
-      async connectToMongo() {
+      // Connect to the database and sets self.apos.dbClient
+      // and self.apos.db. Builds a mongodb URI by default,
+      // accepting host, port, user, password and name options
+      // if present. More typically a URI is specified via
+      // APOS_DB_URI, or via APOS_MONGODB_URI for bc.
+      async connectToDb() {
         if (self.options.client) {
           // Reuse a single client connection http://mongodb.github.io/node-mongodb-native/2.2/api/Db.html#db
           self.apos.dbClient = self.options.client;
@@ -96,32 +102,67 @@ module.exports = {
           self.connectionReused = true;
           return;
         }
-        let uri = 'mongodb://';
-        if (process.env.APOS_MONGODB_URI) {
-          uri = process.env.APOS_MONGODB_URI;
+        let uri;
+        const viaEnv = process.env.APOS_DB_URI || process.env.APOS_MONGODB_URI;
+        if (viaEnv) {
+          uri = viaEnv;
         } else if (self.options.uri) {
           uri = self.options.uri;
         } else {
-          if (self.options.user) {
-            uri += self.options.user + ':' + self.options.password + '@';
-          }
-          if (!self.options.host) {
-            self.options.host = 'localhost';
-          }
-          if (!self.options.port) {
-            self.options.port = 27017;
+          const validAdapters = [ 'mongodb', 'sqlite', 'postgres', 'multipostgres' ];
+          const adapter = process.env.APOS_DEFAULT_DB_ADAPTER || self.options.defaultAdapter || 'mongodb';
+          if (!validAdapters.includes(adapter)) {
+            throw new Error(`Invalid defaultAdapter: "${adapter}". Must be one of: ${validAdapters.join(', ')}`);
           }
           if (!self.options.name) {
             self.options.name = self.apos.shortName;
           }
-          uri += escapeHost(self.options.host) + ':' + self.options.port + '/' + self.options.name;
+          if (adapter === 'sqlite') {
+            const path = require('path');
+            uri = `sqlite://${path.resolve(self.apos.rootDir, 'data', self.options.name + '.sqlite')}`;
+          } else {
+            const credentials = self.options.user
+              ? encodeURIComponent(self.options.user) + ':' + encodeURIComponent(self.options.password) + '@'
+              : '';
+            if (adapter === 'mongodb') {
+              if (!self.options.host) {
+                self.options.host = 'localhost';
+              }
+              if (!self.options.port) {
+                self.options.port = 27017;
+              }
+              uri = 'mongodb://' + credentials + escapeHost(self.options.host) + ':' + self.options.port + '/' + self.options.name;
+            } else {
+              // postgres or multipostgres
+              if (!self.options.host) {
+                self.options.host = 'localhost';
+              }
+              if (!self.options.port) {
+                self.options.port = 5432;
+              }
+              uri = adapter + '://' + credentials + escapeHost(self.options.host) + ':' + self.options.port + '/' + self.options.name;
+            }
+          }
         }
 
-        self.apos.dbClient = await mongodbConnect(uri, self.options.connect);
+        self.apos.dbClient = await dbConnect(uri, {
+          ...self.options.connect,
+          adapters: self.options.adapters
+        });
         self.uri = uri;
         // Automatically uses the db name in the connection string
         self.apos.db = self.apos.dbClient.db();
       },
+      // Connect to a database using the appropriate adapter based on the URI protocol.
+      // Returns a client object compatible with the MongoDB driver interface.
+      // This method has no side effects — it does not set apos.db or apos.dbClient.
+      // It can be used to make temporary connections, e.g. for dropping a test database.
+      async connectToAdapter(uri, options) {
+        return dbConnect(uri, {
+          ...options,
+          adapters: self.options.adapters
+        });
+      },
       async versionCheck() {
         if (!self.options.versionCheck) {
           return;
diff --git a/packages/apostrophe/modules/@apostrophecms/http/index.js b/packages/apostrophe/modules/@apostrophecms/http/index.js
index f7a7b04797..a715259ca3 100644
--- a/packages/apostrophe/modules/@apostrophecms/http/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/http/index.js
@@ -2,7 +2,7 @@ const _ = require('lodash');
 const qs = require('qs');
 const fetch = require('node-fetch');
 const tough = require('tough-cookie');
-const escapeHost = require('../../../lib/escape-host');
+const escapeHost = require('../../../lib/escape-host.js');
 const util = require('util');
 
 module.exports = {
diff --git a/packages/apostrophe/modules/@apostrophecms/job/index.js b/packages/apostrophe/modules/@apostrophecms/job/index.js
index eeda4a2f14..425e5a85d4 100644
--- a/packages/apostrophe/modules/@apostrophecms/job/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/job/index.js
@@ -244,7 +244,9 @@ module.exports = {
               },
               setTotal (n) {
                 total = n;
-                return self.setTotal(job, n);
+                const result = self.setTotal(job, n);
+                promises.push(result);
+                return result;
               },
               setResults (_results) {
                 results = _results;
@@ -412,12 +414,12 @@ module.exports = {
       //
       // No promise is returned as this method just updates
       // the job tracking information in the background.
-      setTotal(job, total) {
-        self.db.updateOne({ _id: job._id }, { $set: { total } }, function (err) {
-          if (err) {
-            self.apos.util.error(err);
-          }
-        });
+      async setTotal(job, total) {
+        try {
+          await self.db.updateOne({ _id: job._id }, { $set: { total } });
+        } catch (err) {
+          self.apos.util.error(err);
+        }
       },
       // Mark the given job as ended. If `success`
       // is true the job is reported as an overall
diff --git a/packages/apostrophe/package.json b/packages/apostrophe/package.json
index 09b882f9bf..a01079b6d2 100644
--- a/packages/apostrophe/package.json
+++ b/packages/apostrophe/package.json
@@ -5,10 +5,9 @@
   "main": "index.js",
   "scripts": {
     "pretest": "npm run lint",
-    "test": "npm run test:base && npm run test:missing && npm run test:assets && npm run test:esm",
-    "test:base": "nyc mocha -t 10000 --ignore=test/assets.js",
+    "test": "npm run test:base && npm run test:missing && npm run test:esm",
+    "test:base": "nyc mocha -t 10000",
     "test:missing": "nyc mocha -t 10000 test/add-missing-schema-fields-project/test.js",
-    "test:assets": "nyc mocha -t 10000 test/assets.js",
     "test:esm": "mocha -t 1000 test/esm-project/esm.js",
     "eslint": "eslint .",
     "eslint-fix": "npm run eslint -- --fix",
@@ -38,7 +37,7 @@
   "author": "Apostrophe Technologies, Inc.",
   "license": "MIT",
   "dependencies": {
-    "@apostrophecms/emulate-mongo-3-driver": "workspace:^",
+    "@apostrophecms/db-connect": "workspace:^",
     "@apostrophecms/vue-material-design-icons": "^1.0.0",
     "@ctrl/tinycolor": "^4.1.0",
     "@floating-ui/dom": "^1.5.3",
@@ -141,6 +140,7 @@
     "xregexp": "^2.0.0"
   },
   "devDependencies": {
+    "chai": "^4.3.10",
     "eslint": "^9.39.1",
     "eslint-config-apostrophe": "workspace:^",
     "form-data": "^4.0.4",
diff --git a/packages/apostrophe/scripts/find-heavy-npm-modules b/packages/apostrophe/scripts/find-heavy-npm-modules
old mode 100755
new mode 100644
diff --git a/packages/apostrophe/test-lib/util.js b/packages/apostrophe/test-lib/util.js
index 2f60d88f8f..373d8bfd9b 100644
--- a/packages/apostrophe/test-lib/util.js
+++ b/packages/apostrophe/test-lib/util.js
@@ -1,5 +1,27 @@
 const { createId } = require('@paralleldrive/cuid2');
-const mongodbConnect = require('../lib/mongodb-connect');
+
+const testDbProtocol = process.env.APOS_TEST_DB_PROTOCOL || 'mongodb';
+
+// Build a test database URI for postgres based on the shortName.
+// Returns undefined for mongodb, letting the default logic handle it.
+function getTestDbUri(shortName) {
+  if (testDbProtocol === 'postgres') {
+    // PostgreSQL database names cannot contain hyphens
+    const dbName = shortName.replace(/-/g, '_');
+    return `postgres://localhost:5432/${dbName}`;
+  }
+  if (testDbProtocol === 'multipostgres') {
+    // Multi-schema mode: shared real database, per-test schema
+    const schemaName = shortName.replace(/-/g, '_').replace(/[^a-zA-Z0-9_]/g, '');
+    return `multipostgres://localhost:5432/apos_test-${schemaName}`;
+  }
+  if (testDbProtocol === 'sqlite') {
+    const os = require('os');
+    const path = require('path');
+    const dbName = shortName.replace(/-/g, '_').replace(/[^a-zA-Z0-9_]/g, '');
+    return `sqlite://${path.join(os.tmpdir(), `apos_test_${dbName}.db`)}`;
+  }
+}
 
 // Properly clean up an apostrophe instance and drop its
 // database collections to create a sane environment for the next test.
@@ -10,23 +32,23 @@ const mongodbConnect = require('../lib/mongodb-connect');
 // If `apos` is null, no work is done.
 
 async function destroy(apos) {
-  if (!apos) {
+  if (!apos || apos._destroyed) {
     return;
   }
+  apos._destroyed = true;
+  const dbModule = apos.modules['@apostrophecms/db'];
+  const { uri } = dbModule;
+  const dbName = apos.db && (apos.db.databaseName || apos.db._name);
   await apos.destroy();
-  const { uri } = apos.modules['@apostrophecms/db'];
-  const dbName = apos.db && apos.db.databaseName;
-  // TODO at some point accommodate nonsense like testing remote databases
-  // that won't let us use dropDatabase, no shell available etc., but the
-  // important principle here is that we should not have to have an apos
-  // object to clean up the database, otherwise we have to get hold of one
-  // when initialization failed and that's really not apostrophe's concern
-  if (dbName && uri) {
-    const client = await mongodbConnect(`${uri}${dbName}`);
-    const db = client.db(dbName);
-    await db.dropDatabase();
-    await client.close();
+  if (!uri || !dbName) {
+    return;
   }
+  // Make a fresh connection (the original was closed by destroy)
+  // and use it to drop the test database
+  const client = await dbModule.connectToAdapter(uri);
+  const db = client.db(dbName);
+  await db.dropDatabase();
+  await client.close();
 };
 
 async function create(options = {}) {
@@ -55,6 +77,18 @@ async function create(options = {}) {
     express.options.session.secret = express.options.session.secret || 'test';
     config.modules['@apostrophecms/express'] = express;
   }
+  // When APOS_TEST_DB_PROTOCOL=postgres, automatically configure the db
+  // module to use a postgres URI unless already explicitly configured
+  const testUri = getTestDbUri(config.shortName);
+  if (testUri) {
+    config.modules = config.modules || {};
+    const dbModule = config.modules['@apostrophecms/db'] || {};
+    dbModule.options = dbModule.options || {};
+    if (!dbModule.options.uri && !dbModule.options.client) {
+      dbModule.options.uri = testUri;
+    }
+    config.modules['@apostrophecms/db'] = dbModule;
+  }
   return require('../index.js')(config);
 }
 
@@ -151,5 +185,7 @@ module.exports = {
   loginAs,
   logout,
   getUserJar,
+  getTestDbUri,
+  testDbProtocol,
   timeout: (process.env.TEST_TIMEOUT && parseInt(process.env.TEST_TIMEOUT)) || 20000
 };
diff --git a/packages/apostrophe/test/add-missing-schema-fields-project/test.js b/packages/apostrophe/test/add-missing-schema-fields-project/test.js
index f2c142c3be..819a96c445 100644
--- a/packages/apostrophe/test/add-missing-schema-fields-project/test.js
+++ b/packages/apostrophe/test/add-missing-schema-fields-project/test.js
@@ -11,10 +11,18 @@ describe('Apostrophe - add-missing-schema-fields task', function() {
 
   let apos;
 
+  // When APOS_TEST_DB_PROTOCOL is set, child processes that run `node app.js`
+  // need the matching APOS_DB_URI so they use the same database as t.create()
+  const projectCwd = path.resolve(process.cwd(), 'test/add-missing-schema-fields-project/');
+  const testDbUri = t.getTestDbUri('add-missing-schema-fields-project');
+  const execEnv = testDbUri
+    ? { env: { ...process.env, APOS_DB_URI: testDbUri } }
+    : {};
+
   before(async function() {
     await util.promisify(exec)(
       'npm install',
-      { cwd: path.resolve(process.cwd(), 'test/add-missing-schema-fields-project/') }
+      { cwd: projectCwd }
     );
   });
 
@@ -25,7 +33,7 @@ describe('Apostrophe - add-missing-schema-fields task', function() {
   it('should not run migrations when running the task', async function() {
     await util.promisify(exec)(
       'node app.js @apostrophecms/migration:add-missing-schema-fields',
-      { cwd: path.resolve(process.cwd(), 'test/add-missing-schema-fields-project/') }
+      { cwd: projectCwd, ...execEnv }
     );
 
     apos = await t.create({
@@ -64,7 +72,7 @@ describe('Apostrophe - add-missing-schema-fields task', function() {
   it('should run migrations when running @apostrophecms/migration:migrate task', async function() {
     await util.promisify(exec)(
       'node app.js @apostrophecms/migration:migrate',
-      { cwd: path.resolve(process.cwd(), 'test/add-missing-schema-fields-project/') }
+      { cwd: projectCwd, ...execEnv }
     );
 
     apos = await t.create({
diff --git a/packages/apostrophe/test/assets.js b/packages/apostrophe/test/assets.js
index f5b31454b2..afe6538656 100644
--- a/packages/apostrophe/test/assets.js
+++ b/packages/apostrophe/test/assets.js
@@ -98,15 +98,75 @@ describe('Assets', function() {
     retryAssertTrue
   } = loadUtils();
 
+  // Wait for the chokidar watcher to be ready before writing files.
+  // Without this, writes can happen before chokidar has finished its
+  // initial scan, so the change event is never emitted. This is
+  // especially visible with slower adapters like sqlite.
+  function waitForWatcherReady(watcher, timeoutMs = 10000) {
+    if (watcher._readyEmitted) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('Watcher ready timeout')), timeoutMs);
+      watcher.on('ready', () => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+  }
+
+  // Many asset tests modify source files in test/modules/ to trigger
+  // rebuilds, then restore them at the end. If a test fails mid-execution
+  // the files stay dirty and poison subsequent runs. To prevent this we
+  // snapshot every mutable file before the suite and restore them
+  // automatically after each test via afterEach. The before hook also
+  // cleans up build artifacts and webpack cache from prior runs.
+  const mutableFiles = [
+    'test/modules/bundle-page/ui/src/extra.js',
+    'test/modules/default-page/ui/src/index.js',
+    'test/modules/default-page/ui/src/index.scss',
+    'test/modules/default-page/ui/public/index.js',
+    'test/modules/default-page/ui/public/index.css',
+    'test/modules/default-page/ui/apos/components/FakeComponent.vue',
+    'test/package-lock.json'
+  ].map((rel) => path.join(process.cwd(), rel));
+  const snapshots = new Map();
+
+  before(async function() {
+    // Snapshot every mutable file so afterEach can restore them
+    for (const file of mutableFiles) {
+      try {
+        snapshots.set(file, await fs.readFile(file));
+      } catch (e) {
+        // File might not exist yet, that's OK
+      }
+    }
+    // Start clean: remove build artifacts and cache from prior runs
+    await deleteBuiltFolders(publicFolderPath, true);
+    await removeCache();
+  });
+
   after(async function() {
     await deleteBuiltFolders(publicFolderPath, true);
     await removeCache();
     await t.destroy(apos);
   });
 
-  afterEach(function() {
+  afterEach(async function() {
     // Prevent hang forever if particular tests fail while testing prod.
     process.env.NODE_ENV = 'development';
+    // Restore any files that were modified by the test
+    for (const [ file, content ] of snapshots) {
+      try {
+        const current = await fs.readFile(file);
+        if (!current.equals(content)) {
+          await fs.writeFile(file, content);
+        }
+      } catch (e) {
+        // If the file was deleted, restore it
+        await fs.writeFile(file, content);
+      }
+    }
   });
 
   this.timeout(5 * 60 * 1000);
@@ -162,6 +222,7 @@ describe('Assets', function() {
   });
 
   it('should get webpack extensions from modules and fill extra bundles', async function () {
+    await t.destroy(apos);
     const expectedEntryPointsNames = {
       js: [ 'company', 'main', 'another', 'extra', 'extra2' ],
       css: [ 'company', 'main', 'extra' ]
@@ -309,6 +370,7 @@ describe('Assets', function() {
   });
 
   it('should build with cache and gain performance', async function() {
+    await t.destroy(apos);
     await removeCache();
     await removeCache(cacheFolderPath.replace('/webpack-cache', '/changed'));
 
@@ -346,9 +408,11 @@ describe('Assets', function() {
     assert(meta2['default:apos']);
     assert(meta2['default:src']);
 
-    // Expect at least 40% gain, in reallity it should be 50+
+    // Caching should provide a measurable speedup. The threshold is kept
+    // low (10%) to avoid flaky failures on loaded CI runners where the
+    // cold run can be fast due to OS-level caching.
     const gain = (execTime - execTimeCached) / execTime * 100;
-    assert(gain >= 20, `Expected gain >=20%, got ${gain}%`);
+    assert(gain >= 10, `Expected gain >=10%, got ${gain}%`);
 
     // Modification times
     assert(meta['default:apos'].mdate);
@@ -509,11 +573,11 @@ describe('Assets', function() {
     assert(apos.asset.restartId);
     assert(!result.builds);
     assert(!result.changes);
+    await waitForWatcherReady(apos.asset.buildWatcher);
 
     // Modify asset and rebuild
     const assetPath = path.join(process.cwd(), 'test/modules/bundle-page/ui/src/extra.js');
     const assetPathPublic = path.join(process.cwd(), 'test/public/apos-frontend/default/extra-module-bundle.js');
-    const assetContent = fs.readFileSync(assetPath, 'utf-8');
     fs.writeFileSync(
       assetPath,
       'export default () => { \'bundle-page-watcher-test-src\'; };\n',
@@ -524,34 +588,33 @@ describe('Assets', function() {
       async () => (await fs.readFile(assetPathPublic, 'utf8')).match(/bundle-page-watcher-test-src/),
       'Unable to verify public asset was rebuilt by the watcher',
       500,
-      10000
+      20000
     );
 
     await retryAssertTrue(
       () => apos.asset.restartId !== restartId,
       'Unable to verify restartId has been changed',
       500,
-      10000
+      20000
     );
 
     await retryAssertTrue(
       () => result.builds.length === 1 && result.builds.includes('src'),
       'Unable to verify build "src" has been triggered',
       50,
-      1000
+      2000
     );
 
     await retryAssertTrue(
       () => result.changes.length === 1 && result.changes[0].includes('modules/bundle-page/ui/src/extra.js'),
       'Unable to verify changes contain the proper file',
       50,
-      1000
+      2000
     );
 
     await t.destroy(apos);
     assert.equal(apos.asset.buildWatcher, null);
     apos = null;
-    fs.writeFileSync(assetPath, assetContent, 'utf8');
   });
 
   it('should watch and rebuild assets and reload page in development (src)', async function() {
@@ -567,12 +630,6 @@ describe('Assets', function() {
     const assetPathPublicCss = path.join(rootPath, 'test/public/apos-frontend/default/public-bundle.css');
     const assetPathAposJs = path.join(rootPath, 'test/public/apos-frontend/default/apos-module-bundle.js');
     const assetPathAposCss = path.join(rootPath, 'test/public/apos-frontend/default/apos-bundle.css');
-    const assetContentJs = fs.readFileSync(assetPathJs, 'utf-8');
-    const assetContentScss = fs.readFileSync(assetPathScss, 'utf-8');
-    // Resurrect the default assets content if test has failed
-    fs.writeFileSync(assetPathJs, assetContentJs, 'utf8');
-    fs.writeFileSync(assetPathScss, assetContentScss, 'utf8');
-
     apos = await t.create({
       root: module,
       autoBuild: true,
@@ -595,6 +652,7 @@ describe('Assets', function() {
     assert(apos.asset.restartId);
     assert(!result.builds);
     assert(!result.changes);
+    await waitForWatcherReady(apos.asset.buildWatcher);
 
     // * modify assets and rebuild
     fs.writeFileSync(
@@ -613,13 +671,13 @@ describe('Assets', function() {
       async () => (await fs.readFile(assetPathPublicJs, 'utf8')).match(/default-page-watcher-test-src/),
       'Unable to verify public JS asset was rebuilt by the watcher',
       500,
-      10000
+      20000
     );
     await retryAssertTrue(
       async () => (await fs.readFile(assetPathPublicCss, 'utf8')).match(/\.default-page-watcher-test-src/),
       'Unable to verify public CSS asset was rebuilt by the watcher',
       500,
-      10000
+      20000
     );
 
     // * change is in the apos bundle
@@ -627,13 +685,13 @@ describe('Assets', function() {
       async () => (await fs.readFile(assetPathAposJs, 'utf8')).match(/default-page-watcher-test-src/),
       'Unable to verify apos JS asset was rebuilt by the watcher',
       500,
-      10000
+      20000
     );
     await retryAssertTrue(
       async () => (await fs.readFile(assetPathAposCss, 'utf8')).match(/\.default-page-watcher-test-src/),
       'Unable to verify apos CSS asset was rebuilt by the watcher',
       500,
-      10000
+      20000
     );
 
     // * page has been restarted
@@ -641,7 +699,7 @@ describe('Assets', function() {
       () => apos.asset.restartId !== restartId,
       'Unable to verify restartId has been changed',
       500,
-      10000
+      20000
     );
 
     // * only src related builds were triggered
@@ -650,7 +708,7 @@ describe('Assets', function() {
         result.builds.includes('src'),
       'Unable to verify build "src" has been triggered',
       50,
-      1000
+      2000
     );
 
     // * changes detected
@@ -665,14 +723,12 @@ describe('Assets', function() {
           .length === 2,
       'Unable to verify changes contain the proper source files',
       50,
-      1000
+      2000
     );
 
     await t.destroy(apos);
     assert.equal(apos.asset.buildWatcher, null);
     apos = null;
-    fs.writeFileSync(assetPathJs, assetContentJs, 'utf8');
-    fs.writeFileSync(assetPathScss, assetContentScss, 'utf8');
   });
 
   it('should watch and rebuild assets and reload page in development (public)', async function() {
@@ -688,12 +744,6 @@ describe('Assets', function() {
     const assetPathPublicCss = path.join(rootPath, 'test/public/apos-frontend/default/public-bundle.css');
     const assetPathAposJs = path.join(rootPath, 'test/public/apos-frontend/default/apos-module-bundle.js');
     const assetPathAposCss = path.join(rootPath, 'test/public/apos-frontend/default/apos-bundle.css');
-    const assetContentJs = fs.readFileSync(assetPathJs, 'utf-8');
-    const assetContentScss = fs.readFileSync(assetPathCss, 'utf-8');
-    // Resurrect the default assets content if test has failed
-    fs.writeFileSync(assetPathJs, assetContentJs, 'utf8');
-    fs.writeFileSync(assetPathCss, assetContentScss, 'utf8');
-
     apos = await t.create({
       root: module,
       autoBuild: true,
@@ -716,6 +766,7 @@ describe('Assets', function() {
     assert(apos.asset.restartId);
     assert(!result.builds);
     assert(!result.changes);
+    await waitForWatcherReady(apos.asset.buildWatcher);
 
     // * modify assets and rebuild
     fs.writeFileSync(
@@ -734,13 +785,13 @@ describe('Assets', function() {
       async () => (await fs.readFile(assetPathPublicJs, 'utf8')).match(/default-page-watcher-test-public/),
       'Unable to verify public JS asset was rebuilt by the watcher',
       500,
-      10000
+      20000
     );
     await retryAssertTrue(
       async () => (await fs.readFile(assetPathPublicCss, 'utf8')).match(/\.default-page-watcher-test-public/),
       'Unable to verify public CSS asset was rebuilt by the watcher',
       500,
-      10000
+      20000
     );
 
     // * change is in the apos bundle
@@ -748,13 +799,13 @@ describe('Assets', function() {
       async () => (await fs.readFile(assetPathAposJs, 'utf8')).match(/default-page-watcher-test-public/),
       'Unable to verify apos JS asset was rebuilt by the watcher',
       500,
-      10000
+      20000
     );
     await retryAssertTrue(
       async () => (await fs.readFile(assetPathAposCss, 'utf8')).match(/\.default-page-watcher-test-public/),
       'Unable to verify apos CSS asset was rebuilt by the watcher',
       500,
-      10000
+      20000
     );
 
     // * page has been restarted
@@ -762,7 +813,7 @@ describe('Assets', function() {
       () => apos.asset.restartId !== restartId,
       'Unable to verify restartId has been changed',
       500,
-      10000
+      20000
     );
 
     // * only public build was triggered
@@ -771,7 +822,7 @@ describe('Assets', function() {
         result.builds.includes('public'),
       'Unable to verify build "public" has been triggered',
       50,
-      1000
+      2000
     );
 
     // * changes detected
@@ -786,14 +837,12 @@ describe('Assets', function() {
           .length === 2,
       'Unable to verify changes contain the proper source files',
       50,
-      1000
+      2000
     );
 
     await t.destroy(apos);
     assert.equal(apos.asset.buildWatcher, null);
     apos = null;
-    fs.writeFileSync(assetPathJs, assetContentJs, 'utf8');
-    fs.writeFileSync(assetPathCss, assetContentScss, 'utf8');
   });
 
   it('should watch and rebuild assets and reload page in development (apos)', async function() {
@@ -836,6 +885,7 @@ describe('Assets', function() {
     assert(apos.asset.restartId);
     assert(!result.builds);
     assert(!result.changes);
+    await waitForWatcherReady(apos.asset.buildWatcher);
 
     // * modify assets and rebuild
     fs.writeFileSync(
@@ -850,7 +900,7 @@ describe('Assets', function() {
         .includes('default-page-watcher-test-apos'),
       'Unable to verify apos JS asset was rebuilt by the watcher',
       500,
-      20000
+      40000
     );
 
     // * page has been restarted
@@ -858,7 +908,7 @@ describe('Assets', function() {
       () => apos.asset.restartId !== restartId,
       'Unable to verify restartId has been changed',
       500,
-      10000
+      20000
     );
 
     // * only apos build was triggered
@@ -867,7 +917,7 @@ describe('Assets', function() {
         result.builds.includes('apos'),
       'Unable to verify build "apos" has been triggered',
       50,
-      1000
+      2000
     );
 
     // * changes detected
@@ -877,13 +927,12 @@ describe('Assets', function() {
         result.changes[0].includes('modules/default-page/ui/apos/components/FakeComponent.vue'),
       'Unable to verify changes contain the proper source files',
       50,
-      1000
+      2000
     );
 
     await t.destroy(apos);
     assert.equal(apos.asset.buildWatcher, null);
     apos = null;
-    fs.writeFileSync(assetPathJs, assetContentJs, 'utf8');
   });
 
   it('should watch and recover after build error in development', async function() {
@@ -898,9 +947,6 @@ describe('Assets', function() {
     const assetPathScss = path.join(rootPath, 'test/modules/default-page/ui/src/index.scss');
     const assetPathPublicCss = path.join(rootPath, 'test/public/apos-frontend/default/public-bundle.css');
     const assetPathAposCss = path.join(rootPath, 'test/public/apos-frontend/default/apos-bundle.css');
-    const assetContentScss = '.default-page {color:red;}\n';
-    // Resurrect the default assets content if test has failed
-    fs.writeFileSync(assetPathScss, assetContentScss, 'utf8');
 
     apos = await t.create({
       root: module,
@@ -924,6 +970,7 @@ describe('Assets', function() {
     assert(apos.asset.restartId);
     assert(!result.builds);
     assert(!result.changes);
+    await waitForWatcherReady(apos.asset.buildWatcher);
 
     // * modify assets and rebuild
     fs.writeFileSync(
@@ -937,7 +984,7 @@ describe('Assets', function() {
       () => called === 1 && result.builds.length === 0,
       'Unable to verify build with error was triggered',
       100,
-      10000
+      20000
     );
 
     // * page has NOT been restarted
@@ -945,7 +992,7 @@ describe('Assets', function() {
       () => apos.asset.restartId === restartId,
       'Unable to verify restartId has been changed',
       100,
-      10000
+      20000
     );
 
     // * modify assets and recover
@@ -960,7 +1007,7 @@ describe('Assets', function() {
       async () => (await fs.readFile(assetPathPublicCss, 'utf8')).match(/\.default-page-watcher-test-recover/),
       'Unable to verify public CSS asset was rebuilt by the watcher',
       500,
-      10000
+      20000
     );
 
     // * change is in the apos bundle
@@ -968,7 +1015,7 @@ describe('Assets', function() {
       async () => (await fs.readFile(assetPathAposCss, 'utf8')).match(/\.default-page-watcher-test-recover/),
       'Unable to verify apos CSS asset was rebuilt by the watcher',
       500,
-      10000
+      20000
     );
 
     // * page has been restarted
@@ -976,7 +1023,7 @@ describe('Assets', function() {
       () => apos.asset.restartId !== restartId,
       'Unable to verify restartId has been changed',
       500,
-      10000
+      20000
     );
 
     // * only src related builds were triggered
@@ -985,7 +1032,7 @@ describe('Assets', function() {
         result.builds.includes('src'),
       'Unable to verify build "src" have been triggered',
       50,
-      1000
+      2000
     );
 
     // * changes detected
@@ -999,13 +1046,12 @@ describe('Assets', function() {
           .length === 1,
       'Unable to verify changes contain the proper source files',
       50,
-      1000
+      2000
     );
 
     await t.destroy(apos);
     assert.equal(apos.asset.buildWatcher, null);
     apos = null;
-    fs.writeFileSync(assetPathScss, assetContentScss, 'utf8');
   });
 
   it('should watch but not rebuild assets and not reload page when changes are not in use', async function() {
@@ -1023,12 +1069,6 @@ describe('Assets', function() {
     const assetPathPublicCss = path.join(rootPath, 'test/public/apos-frontend/default/public-bundle.css');
     const assetPathAposJs = path.join(rootPath, 'test/public/apos-frontend/default/apos-module-bundle.js');
     const assetPathAposCss = path.join(rootPath, 'test/public/apos-frontend/default/apos-bundle.css');
-    const assetContentJs = fs.readFileSync(assetPathJs, 'utf-8');
-    const assetContentScss = fs.readFileSync(assetPathScss, 'utf-8');
-    // Resurrect the default assets content if test has failed
-    fs.writeFileSync(assetPathJs, assetContentJs, 'utf8');
-    fs.writeFileSync(assetPathScss, assetContentScss, 'utf8');
-
     apos = await t.create({
       root: module,
       autoBuild: true,
@@ -1051,6 +1091,7 @@ describe('Assets', function() {
     assert(!result.builds);
     assert(!result.changes);
     assert.equal(rebuilt, false);
+    await waitForWatcherReady(apos.asset.buildWatcher);
 
     // * modify assets
     fs.writeFileSync(
@@ -1139,8 +1180,6 @@ describe('Assets', function() {
     await t.destroy(apos);
     assert.equal(apos.asset.buildWatcher, null);
     apos = null;
-    fs.writeFileSync(assetPathJs, assetContentJs, 'utf8');
-    fs.writeFileSync(assetPathScss, assetContentScss, 'utf8');
   });
 
   it('should watch and rebuild assets in a debounced queue', async function() {
@@ -1167,10 +1206,10 @@ describe('Assets', function() {
       }
     });
     assert(apos.asset.buildWatcher);
+    await waitForWatcherReady(apos.asset.buildWatcher);
 
     const assetPath = path.join(process.cwd(), 'test/modules/bundle-page/ui/src/extra.js');
     const assetPathPublic = path.join(process.cwd(), 'test/public/apos-frontend/default/extra-module-bundle.js');
-    const assetContent = fs.readFileSync(assetPath, 'utf-8');
 
     // Modify below the debounce rate
     for (const i of [ 1, 2, 3 ]) {
@@ -1195,7 +1234,9 @@ describe('Assets', function() {
       5000
     );
 
-    // Modify above the debounce rate, test the queue cap
+    // Modify well above the debounce rate (default 1000ms) so each
+    // write triggers its own rebuild. Use 2000ms to avoid flaky
+    // failures on loaded CI runners.
     timesRebuilt = 0;
     for (const i of [ 1, 2, 3 ]) {
       await fs.writeFile(
@@ -1203,7 +1244,7 @@ describe('Assets', function() {
         `export default () => { 'bundle-page-watcher-test-${i}0'; };\n`,
         'utf8'
       );
-      await Promise.delay(1050);
+      await Promise.delay(2000);
     }
     await retryAssertTrue(
       async () => (await fs.readFile(assetPathPublic, 'utf8')).match(/bundle-page-watcher-test-30/),
@@ -1220,10 +1261,10 @@ describe('Assets', function() {
 
     await t.destroy(apos);
     apos = null;
-    fs.writeFileSync(assetPath, assetContent, 'utf8');
   });
 
   it('should be able to setup the debounce time', async function() {
+    await t.destroy(apos);
 
     apos = await t.create({
       root: module,
@@ -1317,6 +1358,7 @@ describe('Assets', function() {
   });
 
   it('should pass the right options to webpack extensions from all modules', async function() {
+    await t.destroy(apos);
     const { extConfig1, extConfig2 } = getWebpackConfigsForExtensionOptions();
 
     apos = await t.create({
@@ -1347,6 +1389,7 @@ describe('Assets', function() {
   });
 
   it('should allow two modules extending each others to pass options to the same webpack extension', async function() {
+    await t.destroy(apos);
     const { extConfig1, extConfig2 } = getWebpackConfigsForExtensionOptions();
 
     apos = await t.create({
diff --git a/packages/apostrophe/test/db-tools.js b/packages/apostrophe/test/db-tools.js
new file mode 100644
index 0000000000..2bc33de36a
--- /dev/null
+++ b/packages/apostrophe/test/db-tools.js
@@ -0,0 +1,365 @@
+const assert = require('assert');
+const { execFile } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const dbConnect = require('@apostrophecms/db-connect');
+
+const dumpBin = require.resolve('@apostrophecms/db-connect/bin/apos-db-dump.js');
+const restoreBin = require.resolve('@apostrophecms/db-connect/bin/apos-db-restore.js');
+
+const testDbProtocol = process.env.APOS_TEST_DB_PROTOCOL || 'mongodb';
+
+function testUri(dbName) {
+  const dbSafe = dbName.replace(/-/g, '_').replace(/[^a-zA-Z0-9_]/g, '');
+  if (testDbProtocol === 'sqlite') {
+    return `sqlite://${path.join(os.tmpdir(), `${dbSafe}.db`)}`;
+  }
+  if (testDbProtocol === 'postgres') {
+    return `postgres://localhost:5432/${dbSafe}`;
+  }
+  const baseUri = process.env.DB_URI || 'mongodb://localhost:27017';
+  return `${baseUri}/${dbName}`;
+}
+
+function run(bin, args) {
+  return new Promise((resolve, reject) => {
+    execFile(process.execPath, [ bin, ...args ], {
+      timeout: 30000,
+      maxBuffer: 50 * 1024 * 1024
+    }, (err, stdout, stderr) => {
+      if (err) {
+        err.stdout = stdout;
+        err.stderr = stderr;
+        return reject(err);
+      }
+      resolve({
+        stdout,
+        stderr
+      });
+    });
+  });
+}
+
+async function dropAll(uri) {
+  let client;
+  try {
+    client = await dbConnect(uri);
+  } catch (e) {
+    return;
+  }
+  const db = client.db();
+  const collections = await db.listCollections().toArray();
+  for (const col of collections) {
+    await db.collection(col.name).drop();
+  }
+  await client.close();
+}
+
+describe('apos-db-dump and apos-db-restore', function () {
+  this.timeout(30000);
+
+  const sourceUri = testUri('dbtest_dump_source');
+  const targetUri = testUri('dbtest_dump_target');
+  let tmpFile;
+
+  before(async function () {
+    tmpFile = path.join(os.tmpdir(), `apos-db-test-${process.pid}.ndjson`);
+    await dropAll(sourceUri);
+    await dropAll(targetUri);
+  });
+
+  after(async function () {
+    await dropAll(sourceUri);
+    await dropAll(targetUri);
+    try {
+      fs.unlinkSync(tmpFile);
+    } catch (e) {
+      // ignore
+    }
+  });
+
+  it('should dump an empty database without error', async function () {
+    const { stdout } = await run(dumpBin, [ sourceUri ]);
+    assert.strictEqual(stdout.trim(), '');
+  });
+
+  it('should dump and restore documents', async function () {
+    // Insert test data
+    const client = await dbConnect(sourceUri);
+    const db = client.db();
+    await db.collection('aposDocs').insertMany([
+      {
+        _id: 'doc1',
+        title: 'Hello',
+        tags: [ 'a', 'b' ]
+      },
+      {
+        _id: 'doc2',
+        title: 'World'
+      }
+    ]);
+    await db.collection('aposCache').insertMany([
+      {
+        _id: 'cache1',
+        value: 42
+      }
+    ]);
+    await client.close();
+
+    // Dump to file
+    await run(dumpBin, [ sourceUri, `--output=${tmpFile}` ]);
+    const content = fs.readFileSync(tmpFile, 'utf8');
+    const lines = content.split('\n').filter(l => l.trim());
+
+    // Should have header + docs for each collection
+    assert(lines.length >= 4, `Expected at least 4 lines, got ${lines.length}`);
+
+    // Every line should be valid JSON
+    for (const line of lines) {
+      JSON.parse(line);
+    }
+
+    // Should have collection headers
+    const headers = lines
+      .map(l => JSON.parse(l))
+      .filter(e => e._collection && !e._doc);
+    const collNames = headers.map(h => h._collection).sort();
+    assert(collNames.includes('aposDocs'));
+    assert(collNames.includes('aposCache'));
+
+    // Restore to target
+    await run(restoreBin, [ targetUri, `--input=${tmpFile}` ]);
+
+    // Verify target has the data
+    const client2 = await dbConnect(targetUri);
+    const db2 = client2.db();
+    const docs = await db2.collection('aposDocs').find({}).sort({ _id: 1 }).toArray();
+    assert.strictEqual(docs.length, 2);
+    assert.strictEqual(docs[0]._id, 'doc1');
+    assert.strictEqual(docs[0].title, 'Hello');
+    assert.deepStrictEqual(docs[0].tags, [ 'a', 'b' ]);
+    assert.strictEqual(docs[1]._id, 'doc2');
+
+    const cacheDoc = await db2.collection('aposCache').findOne({ _id: 'cache1' });
+    assert(cacheDoc);
+    assert.strictEqual(cacheDoc.value, 42);
+    await client2.close();
+  });
+
+  it('should preserve Date objects via $date serialization', async function () {
+    await dropAll(sourceUri);
+    const client = await dbConnect(sourceUri);
+    const db = client.db();
+    const testDate = new Date('2024-06-15T10:30:00.000Z');
+    await db.collection('aposDocs').insertOne({
+      _id: 'dateDoc',
+      createdAt: testDate,
+      nested: { updatedAt: testDate }
+    });
+    await client.close();
+
+    // Dump and check format
+    const { stdout } = await run(dumpBin, [ sourceUri ]);
+    assert(stdout.includes('"$date"'));
+    assert(stdout.includes('2024-06-15T10:30:00.000Z'), 'Should contain ISO date string');
+
+    // Restore and verify dates come back as Date objects
+    await dropAll(targetUri);
+    await run(dumpBin, [ sourceUri, `--output=${tmpFile}` ]);
+    await run(restoreBin, [ targetUri, `--input=${tmpFile}` ]);
+
+    const client2 = await dbConnect(targetUri);
+    const db2 = client2.db();
+    const doc = await db2.collection('aposDocs').findOne({ _id: 'dateDoc' });
+    assert(doc.createdAt instanceof Date);
+    assert.strictEqual(doc.createdAt.toISOString(), '2024-06-15T10:30:00.000Z');
+    assert(doc.nested.updatedAt instanceof Date);
+    assert.strictEqual(doc.nested.updatedAt.toISOString(), '2024-06-15T10:30:00.000Z');
+    await client2.close();
+  });
+
+  it('should dump and restore indexes', async function () {
+    await dropAll(sourceUri);
+    const client = await dbConnect(sourceUri);
+    const db = client.db();
+    const col = db.collection('aposDocs');
+    await col.insertMany([
+      {
+        _id: 'idx1',
+        slug: 'hello',
+        price: 10
+      },
+      {
+        _id: 'idx2',
+        slug: 'world',
+        price: 20
+      }
+    ]);
+    await col.createIndex({ slug: 1 });
+    await col.createIndex({ slug: 1 }, {
+      unique: true,
+      name: 'slug_unique'
+    });
+    await col.createIndex({ price: 1 }, { type: 'number' });
+    await client.close();
+
+    // Dump
+    await run(dumpBin, [ sourceUri, `--output=${tmpFile}` ]);
+
+    const content = fs.readFileSync(tmpFile, 'utf8');
+    const header = JSON.parse(content.split('\n')[0]);
+    assert(header._indexes, 'Header should contain _indexes');
+    assert(header._indexes.length >= 2, 'Should have at least 2 custom indexes');
+
+    // Restore
+    await dropAll(targetUri);
+    await run(restoreBin, [ targetUri, `--input=${tmpFile}` ]);
+
+    // Verify indexes exist on target
+    const client2 = await dbConnect(targetUri);
+    const db2 = client2.db();
+    const indexes = await db2.collection('aposDocs').indexes();
+    assert(indexes.find(i => i.key && i.key.slug === 1 && !i.unique),
+      'Should have regular slug index');
+    assert(indexes.find(i => i.key && i.key.slug === 1 && i.unique),
+      'Should have unique slug index');
+
+    // Verify unique constraint is enforced
+    try {
+      await db2.collection('aposDocs').insertOne({
+        _id: 'idx3',
+        slug: 'hello'
+      });
+      assert.fail('Should have rejected duplicate slug');
+    } catch (e) {
+      assert(e.code === 11000 || /duplicate|unique|already exists/i.test(e.message));
+    }
+
+    await client2.close();
+  });
+
+  it('should handle piped stdout-to-stdin', async function () {
+    await dropAll(sourceUri);
+    const client = await dbConnect(sourceUri);
+    const db = client.db();
+    await db.collection('aposDocs').insertMany([
+      {
+        _id: 'pipe1',
+        title: 'Piped'
+      }
+    ]);
+    await client.close();
+
+    // Dump to file, then restore from file (simulating pipe)
+    const { stdout } = await run(dumpBin, [ sourceUri ]);
+
+    // Write stdout to tmp, restore from it
+    fs.writeFileSync(tmpFile, stdout);
+    await dropAll(targetUri);
+    await run(restoreBin, [ targetUri, `--input=${tmpFile}` ]);
+
+    const client2 = await dbConnect(targetUri);
+    const db2 = client2.db();
+    const doc = await db2.collection('aposDocs').findOne({ _id: 'pipe1' });
+    assert(doc);
+    assert.strictEqual(doc.title, 'Piped');
+    await client2.close();
+  });
+
+  it('should handle large collections in batches', async function () {
+    await dropAll(sourceUri);
+    const client = await dbConnect(sourceUri);
+    const db = client.db();
+    const docs = [];
+    for (let i = 0; i < 350; i++) {
+      docs.push({
+        _id: `batch${String(i).padStart(4, '0')}`,
+        value: i
+      });
+    }
+    await db.collection('aposDocs').insertMany(docs);
+    await client.close();
+
+    // Dump
+    await run(dumpBin, [ sourceUri, `--output=${tmpFile}` ]);
+
+    const content = fs.readFileSync(tmpFile, 'utf8');
+    const lines = content.split('\n').filter(l => l.trim());
+    // 1 header + 350 doc lines
+    assert.strictEqual(lines.length, 351);
+
+    // Docs should be sorted by _id
+    const docLines = lines.slice(1).map(l => JSON.parse(l));
+    for (let i = 1; i < docLines.length; i++) {
+      assert(docLines[i]._doc._id > docLines[i - 1]._doc._id,
+        'Docs should be sorted by _id');
+    }
+
+    // Restore and verify count
+    await dropAll(targetUri);
+    await run(restoreBin, [ targetUri, `--input=${tmpFile}` ]);
+
+    const client2 = await dbConnect(targetUri);
+    const db2 = client2.db();
+    const count = await db2.collection('aposDocs').countDocuments({});
+    assert.strictEqual(count, 350);
+    await client2.close();
+  });
+
+  it('should restore to a clean state (drop existing data)', async function () {
+    // Put some pre-existing data in target
+    const client = await dbConnect(targetUri);
+    const db = client.db();
+    try {
+      await db.collection('aposDocs').drop();
+    } catch (e) {
+      // ignore
+    }
+    await db.collection('aposDocs').insertOne({
+      _id: 'old',
+      title: 'Should be removed'
+    });
+    await client.close();
+
+    // Set up source with different data
+    await dropAll(sourceUri);
+    const client2 = await dbConnect(sourceUri);
+    const db2 = client2.db();
+    await db2.collection('aposDocs').insertOne({
+      _id: 'new',
+      title: 'Fresh data'
+    });
+    await client2.close();
+
+    // Dump source and restore to target
+    await run(dumpBin, [ sourceUri, `--output=${tmpFile}` ]);
+    await run(restoreBin, [ targetUri, `--input=${tmpFile}` ]);
+
+    // Target should only have the new data
+    const client3 = await dbConnect(targetUri);
+    const db3 = client3.db();
+    const all = await db3.collection('aposDocs').find({}).toArray();
+    assert.strictEqual(all.length, 1);
+    assert.strictEqual(all[0]._id, 'new');
+    await client3.close();
+  });
+
+  it('should fail with usage error when no URI is provided', async function () {
+    try {
+      await run(dumpBin, []);
+      assert.fail('Should have exited with error');
+    } catch (e) {
+      assert.strictEqual(e.code, 1);
+      assert(e.stderr.includes('Usage'));
+    }
+
+    try {
+      await run(restoreBin, []);
+      assert.fail('Should have exited with error');
+    } catch (e) {
+      assert.strictEqual(e.code, 1);
+      assert(e.stderr.includes('Usage'));
+    }
+  });
+});
diff --git a/packages/apostrophe/test/db.js b/packages/apostrophe/test/db.js
index 47afa4cf16..7a6134b4de 100644
--- a/packages/apostrophe/test/db.js
+++ b/packages/apostrophe/test/db.js
@@ -1,6 +1,10 @@
 const t = require('../test-lib/test.js');
 const assert = require('assert');
 
+const bogusUri = t.testDbProtocol === 'postgres'
+  ? 'postgres://this-will-not-work-unless-db-successfully-overrides-it/fail'
+  : 'mongodb://this-will-not-work-unless-db-successfully-overrides-it/fail';
+
 describe('Db', function() {
 
   let apos, apos2;
@@ -25,23 +29,28 @@ describe('Db', function() {
     assert(doc);
   });
 
-  it('should be able to launch a second instance reusing the connection', async function() {
-    // Often takes too long otherwise
-    this.timeout(10000);
-    apos2 = await t.create({
-      root: module,
-      modules: {
-        '@apostrophecms/db': {
-          options: {
-            client: apos.dbClient,
-            uri: 'mongodb://this-will-not-work-unless-db-successfully-overrides-it/fail'
+  // Client reuse with a different database name is only supported in
+  // mongodb and multipostgres mode, not simple postgres (which has no
+  // schema isolation)
+  if (t.testDbProtocol !== 'postgres') {
+    it('should be able to launch a second instance reusing the connection', async function() {
+      // Often takes too long otherwise
+      this.timeout(10000);
+      apos2 = await t.create({
+        root: module,
+        modules: {
+          '@apostrophecms/db': {
+            options: {
+              client: apos.dbClient,
+              uri: bogusUri
+            }
           }
         }
-      }
-    });
+      });
 
-    const doc = await apos2.doc.db.findOne();
+      const doc = await apos2.doc.db.findOne();
 
-    assert(doc);
-  });
+      assert(doc);
+    });
+  }
 });
diff --git a/packages/apostrophe/test/default-adapter.js b/packages/apostrophe/test/default-adapter.js
new file mode 100644
index 0000000000..ad8bc628e8
--- /dev/null
+++ b/packages/apostrophe/test/default-adapter.js
@@ -0,0 +1,256 @@
+const assert = require('assert');
+const path = require('path');
+
+describe('Default Adapter', function() {
+
+  this.timeout(20000);
+
+  // Save and restore env vars
+  let savedAposDefaultDbAdapter;
+  let savedAposDbUri;
+  let savedAposMongdbUri;
+
+  beforeEach(function() {
+    savedAposDefaultDbAdapter = process.env.APOS_DEFAULT_DB_ADAPTER;
+    savedAposDbUri = process.env.APOS_DB_URI;
+    savedAposMongdbUri = process.env.APOS_MONGODB_URI;
+    delete process.env.APOS_DEFAULT_DB_ADAPTER;
+    delete process.env.APOS_DB_URI;
+    delete process.env.APOS_MONGODB_URI;
+  });
+
+  afterEach(function() {
+    if (savedAposDefaultDbAdapter !== undefined) {
+      process.env.APOS_DEFAULT_DB_ADAPTER = savedAposDefaultDbAdapter;
+    } else {
+      delete process.env.APOS_DEFAULT_DB_ADAPTER;
+    }
+    if (savedAposDbUri !== undefined) {
+      process.env.APOS_DB_URI = savedAposDbUri;
+    } else {
+      delete process.env.APOS_DB_URI;
+    }
+    if (savedAposMongdbUri !== undefined) {
+      process.env.APOS_MONGODB_URI = savedAposMongdbUri;
+    } else {
+      delete process.env.APOS_MONGODB_URI;
+    }
+  });
+
+  // These tests verify URI construction by examining module internals
+  // without needing actual database connections.
+
+  it('builds mongodb:// URI by default', function() {
+    const uri = buildUri({ shortName: 'mysite' });
+    assert(uri.startsWith('mongodb://'));
+    assert(uri.includes('localhost:27017'));
+    assert(uri.includes('/mysite'));
+  });
+
+  it('builds mongodb:// URI when defaultAdapter is "mongodb"', function() {
+    const uri = buildUri({
+      shortName: 'mysite',
+      dbOptions: { defaultAdapter: 'mongodb' }
+    });
+    assert(uri.startsWith('mongodb://'));
+    assert(uri.includes('/mysite'));
+  });
+
+  it('builds sqlite:// URI when defaultAdapter is "sqlite"', function() {
+    const uri = buildUri({
+      shortName: 'mysite',
+      rootDir: '/app',
+      dbOptions: { defaultAdapter: 'sqlite' }
+    });
+    assert(uri.startsWith('sqlite://'));
+    assert(uri.includes(path.join('data', 'mysite.sqlite')));
+  });
+
+  it('builds postgres:// URI when defaultAdapter is "postgres"', function() {
+    const uri = buildUri({
+      shortName: 'mysite',
+      dbOptions: { defaultAdapter: 'postgres' }
+    });
+    assert(uri.startsWith('postgres://'));
+    assert(uri.includes('localhost:5432'));
+    assert(uri.includes('/mysite'));
+  });
+
+  it('builds multipostgres:// URI when defaultAdapter is "multipostgres"', function() {
+    const uri = buildUri({
+      shortName: 'mysite',
+      dbOptions: { defaultAdapter: 'multipostgres' }
+    });
+    assert(uri.startsWith('multipostgres://'));
+    assert(uri.includes('localhost:5432'));
+    assert(uri.includes('/mysite'));
+  });
+
+  it('includes URI-encoded credentials for postgres', function() {
+    const uri = buildUri({
+      shortName: 'mysite',
+      dbOptions: {
+        defaultAdapter: 'postgres',
+        user: 'admin',
+        password: 'p@ss:word/special'
+      }
+    });
+    assert(uri.startsWith('postgres://'));
+    assert(uri.includes('admin'));
+    assert(uri.includes(encodeURIComponent('p@ss:word/special')));
+    assert(!uri.includes('p@ss:word/special'));
+  });
+
+  it('includes URI-encoded credentials for mongodb', function() {
+    const uri = buildUri({
+      shortName: 'mysite',
+      dbOptions: {
+        defaultAdapter: 'mongodb',
+        user: 'admin',
+        password: 'p@ss:word'
+      }
+    });
+    assert(uri.startsWith('mongodb://'));
+    assert(uri.includes(encodeURIComponent('p@ss:word')));
+  });
+
+  it('APOS_DEFAULT_DB_ADAPTER env var overrides the option', function() {
+    process.env.APOS_DEFAULT_DB_ADAPTER = 'postgres';
+    const uri = buildUri({
+      shortName: 'mysite',
+      dbOptions: { defaultAdapter: 'mongodb' }
+    });
+    assert(uri.startsWith('postgres://'));
+  });
+
+  it('throws for invalid adapter name', function() {
+    assert.throws(() => {
+      buildUri({
+        shortName: 'mysite',
+        dbOptions: { defaultAdapter: 'invalid' }
+      });
+    }, /Invalid defaultAdapter/);
+  });
+
+  it('explicit uri option overrides defaultAdapter', function() {
+    const uri = buildUri({
+      shortName: 'mysite',
+      dbOptions: {
+        defaultAdapter: 'postgres',
+        uri: 'mongodb://custom:27017/other'
+      }
+    });
+    assert.strictEqual(uri, 'mongodb://custom:27017/other');
+  });
+
+  it('APOS_DB_URI env var overrides everything', function() {
+    process.env.APOS_DB_URI = 'mongodb://envhost:27017/envdb';
+    const uri = buildUri({
+      shortName: 'mysite',
+      dbOptions: { defaultAdapter: 'postgres' }
+    });
+    assert.strictEqual(uri, 'mongodb://envhost:27017/envdb');
+  });
+
+  it('honors custom host and port for postgres', function() {
+    const uri = buildUri({
+      shortName: 'mysite',
+      dbOptions: {
+        defaultAdapter: 'postgres',
+        host: 'dbserver',
+        port: 5433
+      }
+    });
+    assert(uri.includes('dbserver:5433'));
+  });
+
+  it('honors custom host and port for mongodb', function() {
+    const uri = buildUri({
+      shortName: 'mysite',
+      dbOptions: {
+        defaultAdapter: 'mongodb',
+        host: 'mongohost',
+        port: 27018
+      }
+    });
+    assert(uri.includes('mongohost:27018'));
+  });
+
+  it('uses shortName as database name by default', function() {
+    const uri = buildUri({ shortName: 'my-app' });
+    assert(uri.endsWith('/my-app'));
+  });
+
+  it('uses name option over shortName when provided', function() {
+    const uri = buildUri({
+      shortName: 'my-app',
+      dbOptions: { name: 'custom-db' }
+    });
+    assert(uri.includes('/custom-db'));
+  });
+
+  it('ignores host/port/user/password for sqlite', function() {
+    const uri = buildUri({
+      shortName: 'mysite',
+      dbOptions: {
+        defaultAdapter: 'sqlite',
+        host: 'shouldbeignored',
+        port: 9999,
+        user: 'nobody',
+        password: 'nothing'
+      }
+    });
+    assert(uri.startsWith('sqlite://'));
+    assert(!uri.includes('shouldbeignored'));
+    assert(!uri.includes('9999'));
+    assert(!uri.includes('nobody'));
+  });
+});
+
+// Helper: simulate the URI construction logic from the db module
+// without actually connecting. This extracts the same logic path.
+function buildUri(options = {}) {
+  const escapeHost = require('../lib/escape-host.js');
+  const shortName = options.shortName || 'test-app';
+  const rootDir = options.rootDir || '/tmp/test-app';
+  const dbOptions = { ...(options.dbOptions || {}) };
+
+  // Simulate the connectToDb URI construction
+  const viaEnv = process.env.APOS_DB_URI || process.env.APOS_MONGODB_URI;
+  if (viaEnv) {
+    return viaEnv;
+  }
+  if (dbOptions.uri) {
+    return dbOptions.uri;
+  }
+
+  const validAdapters = [ 'mongodb', 'sqlite', 'postgres', 'multipostgres' ];
+  const adapter = process.env.APOS_DEFAULT_DB_ADAPTER || dbOptions.defaultAdapter || 'mongodb';
+  if (!validAdapters.includes(adapter)) {
+    throw new Error(`Invalid defaultAdapter: "${adapter}". Must be one of: ${validAdapters.join(', ')}`);
+  }
+
+  if (!dbOptions.name) {
+    dbOptions.name = shortName;
+  }
+
+  if (adapter === 'sqlite') {
+    const path = require('path');
+    return `sqlite://${path.resolve(rootDir, 'data', dbOptions.name + '.sqlite')}`;
+  }
+
+  const credentials = dbOptions.user
+    ? encodeURIComponent(dbOptions.user) + ':' + encodeURIComponent(dbOptions.password) + '@'
+    : '';
+
+  if (adapter === 'mongodb') {
+    const host = dbOptions.host || 'localhost';
+    const port = dbOptions.port || 27017;
+    return 'mongodb://' + credentials + escapeHost(host) + ':' + port + '/' + dbOptions.name;
+  }
+
+  // postgres or multipostgres
+  const host = dbOptions.host || 'localhost';
+  const port = dbOptions.port || 5432;
+  return adapter + '://' + credentials + escapeHost(host) + ':' + port + '/' + dbOptions.name;
+}
diff --git a/packages/apostrophe/test/job.js b/packages/apostrophe/test/job.js
index 75b1ad47b9..803368256e 100644
--- a/packages/apostrophe/test/job.js
+++ b/packages/apostrophe/test/job.js
@@ -311,7 +311,7 @@ describe('Job module', function() {
         req,
         async function(_req, reporters) {
           let count = 1;
-          reporters.setTotal(articleIds.length);
+          await reporters.setTotal(articleIds.length);
 
           for (const id of articleIds) {
             await delay(3);
diff --git a/packages/broadband/package.json b/packages/broadband/package.json
index 63400ffb0c..83ee406f23 100644
--- a/packages/broadband/package.json
+++ b/packages/broadband/package.json
@@ -32,6 +32,9 @@
   "dependencies": {
     "lodash": "^4.18.1"
   },
+  "apostropheTestConfig": {
+    "mongodbOnly": true
+  },
   "devDependencies": {
     "eslint": "^9.39.1",
     "eslint-config-apostrophe": "workspace:^",
diff --git a/packages/cache-on-demand/package.json b/packages/cache-on-demand/package.json
index 9df4c1297a..7fec6b29ff 100644
--- a/packages/cache-on-demand/package.json
+++ b/packages/cache-on-demand/package.json
@@ -30,6 +30,9 @@
   "bugs": {
     "url": "https://github.com/punkave/cache-on-demand/issues"
   },
+  "apostropheTestConfig": {
+    "requiresMongo": false
+  },
   "devDependencies": {
     "eslint": "^9.39.1",
     "eslint-config-apostrophe": "workspace:^",
diff --git a/packages/db-connect/LICENSE.md b/packages/db-connect/LICENSE.md
new file mode 100644
index 0000000000..7a8ddbb5ed
--- /dev/null
+++ b/packages/db-connect/LICENSE.md
@@ -0,0 +1,7 @@
+Copyright (c) 2025 Apostrophe Technologies, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/packages/db-connect/README.md b/packages/db-connect/README.md
new file mode 100644
index 0000000000..b1cf3aa6e6
--- /dev/null
+++ b/packages/db-connect/README.md
@@ -0,0 +1,107 @@
+# @apostrophecms/db-connect
+
+`@apostrophecms/db-connect` defines the database connection API for [ApostropheCMS](https://apostrophecms.com). It provides adapters for MongoDB, PostgreSQL, and SQLite, and includes the `apos-db-dump` and `apos-db-restore` command-line utilities for database migration and backup.
+
+The db-connect API is compatible with a large subset of the MongoDB API. However, after this introductory note, this document describes the **db-connect API** on its own terms. For projects that need to work across all three databases, it is necessary to use only the functionality defined here.
+
+## Supported Connection URLs
+
+### MongoDB
+
+```
+mongodb://localhost:27017/mydb
+mongodb+srv://user:pass@cluster.example.com/mydb
+```
+
+Standard MongoDB connection strings. The MongoDB adapter is a thin wrapper around the existing driver.
+
+### PostgreSQL
+
+```
+postgres://localhost:5432/mydb
+```
+
+Single-database mode. All collections are stored as tables in the `public` schema.
+
+### SQLite
+
+```
+sqlite:///path/to/database.db
+```
+
+File-based SQLite databases using `better-sqlite3`. In-memory databases
+(`sqlite://:memory:`) are not supported — the adapter assumes a persistent
+store suitable for hosting an ApostropheCMS site.
+
+### Multi-Schema PostgreSQL (multipostgres)
+
+```
+multipostgres://localhost:5432/shareddb-tenant1
+```
+
+Designed for use with the ApostropheCMS [multisite](https://apostrophecms.com/extensions/multisite-2) module. In this mode, each site gets its own PostgreSQL schema within a single physical database.
+
+The URL path is split at the **last hyphen**:
+
+- Everything before the last hyphen is the real PostgreSQL database name (`shareddb`)
+- Everything after is the schema name (`tenant1`)
+
+Each schema is created automatically on first use and dropped cleanly when the database is dropped. This provides true multi-tenant isolation — no cross-tenant data leakage — while sharing a single PostgreSQL instance efficiently.
+
+## Connecting
+
+```js
+const connect = require('@apostrophecms/db-connect');
+
+const client = await connect('postgres://localhost:5432/mydb');
+const db = client.db();
+const articles = db.collection('articles');
+
+// Insert a document
+const result = await articles.insertOne({ title: 'Hello', status: 'draft' });
+
+// Query documents
+const docs = await articles.find({ status: 'draft' })
+  .sort({ title: 1 })
+  .limit(10)
+  .toArray();
+
+// Update a document
+await articles.updateOne(
+  { _id: result.insertedId },
+  { $set: { status: 'published' } }
+);
+
+await client.close();
+```
+
+`connect(uri)` returns a client. Call `client.db()` to get a database, then `db.collection(name)` to get a collection.
+
+## Atomicity
+
+`insertOne` and `deleteOne` are always atomic.
+
+`updateOne` without `upsert` is atomic when it uses only the following operators:
+
+- **`$set`**, **`$inc`**, **`$unset`**, **`$currentDate`** — always atomic
+- **`$push`**, **`$pull`**, **`$addToSet`** — atomic when all values are **scalars** (strings, numbers, booleans). Object or array values fall back to read-modify-write.
+
+These operators can be freely combined in a single `updateOne` call and the entire update will be atomic. This covers the most common patterns: counters, status flags, timestamps, field cleanup, and adding/removing items to/from arrays.
+
+**The following operations are NOT guaranteed to be atomic** and use a read-modify-write pattern (the document is read, the update is applied in JavaScript, and the result is written back):
+
+- `updateOne` with **`$rename`** or **`upsert: true`**
+- `updateOne` with `$push`, `$pull`, or `$addToSet` using **non-scalar** values
+- **`updateMany`**, **`findOneAndUpdate`**, and **`replaceOne`**
+
+For operations that must be atomic and aren't covered above, use advisory locking (`apos.lock`) to serialize access. Apostrophe core already uses advisory locking where atomicity matters (e.g., `apos.lock.lock` around critical sections).
+
+## API Reference
+
+- [Database and Client](./docs/database.md) — `client.db(name)`, listing collections, dropping databases
+- [Collection Methods](./docs/collections.md) — CRUD operations, cursors, and bulk writes
+- [Query Operators](./docs/queries.md) — filtering documents with comparison, logical, element, and array operators
+- [Update Operators](./docs/updates.md) — modifying documents with `$set`, `$inc`, `$push`, and more
+- [Indexes](./docs/indexes.md) — creating and managing indexes, including numeric and date types
+- [Aggregation](./docs/aggregation.md) — pipeline stages and group accumulators
+- [Dump and Restore](./docs/dump-restore.md) — CLI tools and programmatic API for backup and migration
diff --git a/packages/db-connect/adapters/mongodb.js b/packages/db-connect/adapters/mongodb.js
new file mode 100644
index 0000000000..1bf260d273
--- /dev/null
+++ b/packages/db-connect/adapters/mongodb.js
@@ -0,0 +1,10 @@
+// MongoDB adapter - thin wrapper around existing driver compatibility stack
+const mongodbConnect = require('../lib/mongodb-connect');
+
+module.exports = {
+  name: 'mongodb',
+  protocols: [ 'mongodb', 'mongodb+srv' ],
+  async connect(uri, options) {
+    return mongodbConnect(uri, options);
+  }
+};
diff --git a/packages/db-connect/adapters/postgres.js b/packages/db-connect/adapters/postgres.js
new file mode 100644
index 0000000000..7e99980a21
--- /dev/null
+++ b/packages/db-connect/adapters/postgres.js
@@ -0,0 +1,2505 @@
+// PostgreSQL Adapter for MongoDB-compatible interface
+// Stores documents as JSONB with _id as primary key
+
+const { Pool } = require('pg');
+const crypto = require('crypto');
+const {
+  serializeValue,
+  serializeDocument,
+  deserializeDocument,
+  getNestedField,
+  setNestedField,
+  deepEqual,
+  applyProjection,
+  applyUpdate,
+  extractAnchoredLiteralPrefix,
+  prefixUpperBound,
+  validateInteger
+} = require('../lib/shared');
+const { AggregationCursor } = require('../lib/aggregation-cursor');
+
+// =============================================================================
+// PROFILING: Accumulated timing data for performance analysis
+// Enable with POSTGRES_PROFILE=1 environment variable
+// Print report with: require('.../postgres').profileReport()
+// =============================================================================
+
+const PROFILING = !!process.env.POSTGRES_PROFILE;
+
+const profile = {
+  buildWhereClause: {
+    calls: 0,
+    totalMs: 0
+  },
+  buildOrderBy: {
+    calls: 0,
+    totalMs: 0
+  },
+  serializeDocument: {
+    calls: 0,
+    totalMs: 0
+  },
+  convertDates: {
+    calls: 0,
+    totalMs: 0
+  },
+  applyProjection: {
+    calls: 0,
+    totalMs: 0
+  },
+  applyUpdate: {
+    calls: 0,
+    totalMs: 0
+  },
+  pgQuery: {
+    calls: 0,
+    totalMs: 0
+  },
+  ensureTable: {
+    calls: 0,
+    totalMs: 0
+  },
+  findOne: {
+    calls: 0,
+    totalMs: 0
+  },
+  findToArray: {
+    calls: 0,
+    totalMs: 0
+  },
+  cursorNext: {
+    calls: 0,
+    totalMs: 0
+  },
+  updateOne: {
+    calls: 0,
+    totalMs: 0
+  },
+  insertOne: {
+    calls: 0,
+    totalMs: 0
+  },
+  countDocuments: {
+    calls: 0,
+    totalMs: 0
+  },
+  distinct: {
+    calls: 0,
+    totalMs: 0
+  }
+};
+
+// Per-query tracking: SQL text -> { calls, totalMs }
+const queryProfile = {};
+
+function profileStart() {
+  if (!PROFILING) {
+    return 0;
+  }
+  return performance.now();
+}
+
+function profileEnd(category, start) {
+  if (!PROFILING) {
+    return;
+  }
+  const elapsed = performance.now() - start;
+  profile[category].calls++;
+  profile[category].totalMs += elapsed;
+}
+
+function profileQuery(sql, start) {
+  if (!PROFILING) {
+    return;
+  }
+  const elapsed = performance.now() - start;
+  profile.pgQuery.calls++;
+  profile.pgQuery.totalMs += elapsed;
+  // Normalize SQL for grouping: collapse $N params and specific values
+  const normalized = sql.replace(/\$\d+/g, '$?').replace(/\s+/g, ' ').trim().substring(0, 120);
+  if (!queryProfile[normalized]) {
+    queryProfile[normalized] = {
+      calls: 0,
+      totalMs: 0
+    };
+  }
+  queryProfile[normalized].calls++;
+  queryProfile[normalized].totalMs += elapsed;
+}
+
+function profileReport() {
+  console.log('\n=== PostgreSQL Adapter Profile ===\n');
+
+  // High-level categories
+  console.log('--- Cumulative time by category ---');
+  const sorted = Object.entries(profile)
+    .filter(([ , v ]) => v.calls > 0)
+    .sort((a, b) => b[1].totalMs - a[1].totalMs);
+  for (const [ name, data ] of sorted) {
+    console.log(`  ${name.padEnd(20)} ${data.totalMs.toFixed(1).padStart(8)}ms  (${data.calls} calls, ${(data.totalMs / data.calls).toFixed(3)}ms avg)`);
+  }
+
+  // Per-query breakdown
+  console.log('\n--- Top queries by total time ---');
+  const querySorted = Object.entries(queryProfile)
+    .sort((a, b) => b[1].totalMs - a[1].totalMs)
+    .slice(0, 20);
+  for (const [ sql, data ] of querySorted) {
+    console.log(`  ${data.totalMs.toFixed(1).padStart(8)}ms  (${String(data.calls).padStart(4)} calls, ${(data.totalMs / data.calls).toFixed(3)}ms avg)  ${sql}`);
+  }
+
+  console.log('\n=== End Profile ===\n');
+}
+
+function profileReset() {
+  for (const key of Object.keys(profile)) {
+    profile[key].calls = 0;
+    profile[key].totalMs = 0;
+  }
+  for (const key of Object.keys(queryProfile)) {
+    delete queryProfile[key];
+  }
+}
+
+// =============================================================================
+// SECURITY: Input Validation and Escaping
+// =============================================================================
+
+// Strict pattern for table/index names (PostgreSQL identifier limitations)
+const SAFE_IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+// Validate and sanitize a table/collection name
+function validateTableName(name) {
+  if (typeof name !== 'string' || name.length === 0 || name.length > 63) {
+    throw new Error('Invalid table name: must be a non-empty string up to 63 characters');
+  }
+  // Replace hyphens with underscores (common in MongoDB collection names)
+  const sanitized = name.replace(/-/g, '_');
+  if (!SAFE_IDENTIFIER_PATTERN.test(sanitized)) {
+    throw new Error(`Invalid table name: "${name}" contains disallowed characters`);
+  }
+  return sanitized;
+}
+
+// Sanitize a caller-supplied index name so it is safe to use as a
+// PostgreSQL identifier. Unlike validateTableName() (which rejects unsafe
+// input as a security measure against malicious table names), index names
+// frequently arrive from cross-backend JSONL dumps — MongoDB's
+// default/auto-generated index names contain characters like "." that are
+// illegal PostgreSQL identifiers. Silently replacing those characters
+// with "_" is safe: the name is an internal identifier, not user data,
+// and the adapter is the one consulting the _indexes map by the sanitized
+// form.
+function sanitizeIndexName(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    return null;
+  }
+  const truncated = name.substring(0, 63);
+  const sanitized = truncated.replace(/[^a-zA-Z0-9_]/g, '_');
+  if (/^[0-9]/.test(sanitized)) {
+    return '_' + sanitized.substring(0, 62);
+  }
+  return sanitized;
+}
+
+// Escape a PostgreSQL identifier (table name, index name) for use in double quotes
+// PostgreSQL: double any internal double quotes
+function escapeIdentifier(name) {
+  return name.replace(/"/g, '""');
+}
+
+// Escape a string for use in single quotes (JSON path segments)
+// PostgreSQL: double any internal single quotes
+function escapeString(str) {
+  return str.replace(/'/g, '\'\'');
+}
+
+// Create a MongoDB-compatible duplicate key error from a PostgreSQL 23505 error
+function makeDuplicateKeyError(pgError) {
+  let field = null;
+  let value = null;
+  // Parse PostgreSQL detail to extract keyValue for MongoDB compatibility
+  // Detail format: Key ((data ->> 'field'::text))=(value) already exists.
+  // or for _id: Key (_id)=(value) already exists.
+  // Note: PostgreSQL wraps expression indexes in double parens
+  if (pgError.detail) {
+    const match = pgError.detail.match(/Key \((.+?)\)=\((.+?)\) already exists/);
+    if (match) {
+      const expr = match[1];
+      value = match[2];
+      if (expr === '_id') {
+        field = '_id';
+      } else {
+        // Try to map the PostgreSQL expression back to a field name
+        // e.g., (data ->> 'username'::text) -> username
+        const fieldMatch = expr.match(/>>\s*'([^']+)'/);
+        if (fieldMatch) {
+          field = fieldMatch[1];
+        }
+      }
+    }
+  }
+  const message = field && value
+    ? `Duplicate key error: ${field} "${value}" already exists`
+    : 'Duplicate key error';
+  const error = new Error(message);
+  error.code = 11000;
+  if (field && value) {
+    error.keyValue = { [field]: value };
+  }
+  return error;
+}
+
+// Generate a MongoDB-style ObjectId-like string
+function generateId() {
+  return crypto.randomBytes(12).toString('hex');
+}
+
+// Parse a PostgreSQL index definition (from pg_indexes.indexdef) back into
+// our abstract index metadata: { key, unique, sparse, type }.
+// This only handles the patterns our own createIndex generates — it is not
+// a general SQL parser.
+function parseIndexDef(indexdef) {
+  const unique = /\bUNIQUE\b/.test(indexdef);
+  const sparse = /\bWHERE\b/.test(indexdef);
+  const isGin = /\bUSING gin\b/.test(indexdef);
+
+  // Strip COLLATE "C" annotations so the existing expression patterns match
+  // regardless of whether the JSON path has an explicit collation (introduced
+  // to make byte-wise comparisons match MongoDB semantics).
+  indexdef = indexdef.replace(/\s*COLLATE\s+"[^"]+"/gi, '');
+
+  if (isGin) {
+    // Text index: USING gin(to_tsvector('simple', coalesce(data->>'field', '') ...))
+    // PostgreSQL normalizes to: COALESCE((data ->> 'field'::text), ''::text)
+    const key = {};
+    const fieldPattern = /coalesce\(\s*\(*(data(?:\s*->\s*'[^']*'(?:::text)?)*\s*->>\s*'[^']*'(?:::text)?)\)*\s*,\s*''(?:::text)?\s*\)/gi;
+    let m;
+    while ((m = fieldPattern.exec(indexdef)) !== null) {
+      const fieldName = jsonPathToFieldName(m[1]);
+      if (fieldName) {
+        key[fieldName] = 'text';
+      }
+    }
+    return {
+      key,
+      unique,
+      ...(sparse ? { sparse: true } : {})
+    };
+  }
+
+  // Regular or unique index: extract expressions from the column list
+  // The column list is inside the last pair of parentheses before an
+  // optional WHERE clause
+  let colSection = indexdef;
+  const wherePos = colSection.indexOf(' WHERE ');
+  if (wherePos !== -1) {
+    colSection = colSection.substring(0, wherePos);
+  }
+  // Find the last opening paren that starts the column list
+  // For: CREATE INDEX ... ON tablename (expr1, expr2)
+  // or:  CREATE INDEX ... ON tablename USING btree (expr1, expr2)
+  const onMatch = colSection.match(/\bON\b\s+\S+\s+(?:USING \w+\s+)?\((.+)\)\s*$/);
+  if (!onMatch) {
+    return {
+      key: {},
+      unique,
+      ...(sparse ? { sparse: true } : {})
+    };
+  }
+
+  const exprList = onMatch[1];
+  const key = {};
+  let type;
+
+  // Split on commas that are not inside parentheses
+  const exprs = splitExpressions(exprList);
+
+  for (const expr of exprs) {
+    const trimmed = expr.trim();
+
+    // Check for _id column
+    if (/^_id\b/.test(trimmed)) {
+      const direction = /\bDESC\b/.test(trimmed) ? -1 : 1;
+      key._id = direction;
+      continue;
+    }
+
+    // Numeric type: ((data->>'field')::numeric) or nested variant
+    const numericMatch = trimmed.match(/::numeric/);
+    if (numericMatch) {
+      type = 'number';
+      const fieldName = jsonPathToFieldName(trimmed);
+      if (fieldName) {
+        const direction = /\bDESC\b/.test(trimmed) ? -1 : 1;
+        key[fieldName] = direction;
+      }
+      continue;
+    }
+
+    // Date type: data->'field'->>'$date' (or PostgreSQL normalized:
+    // (data -> 'createdAt'::text) ->> '$date'::text)
+    const dateMatch = trimmed.match(/->>?\s*'\$date'/);
+    if (dateMatch) {
+      type = 'date';
+      // The jsonPathToFieldName helper already skips $date segments,
+      // so we can pass the whole expression
+      const fieldName = jsonPathToFieldName(trimmed);
+      if (fieldName) {
+        const direction = /\bDESC\b/.test(trimmed) ? -1 : 1;
+        key[fieldName] = direction;
+      }
+      continue;
+    }
+
+    // Default text type: data->>'field' or data->'a'->>'b'
+    const fieldName = jsonPathToFieldName(trimmed);
+    if (fieldName) {
+      const direction = /\bDESC\b/.test(trimmed) ? -1 : 1;
+      key[fieldName] = direction;
+    }
+  }
+
+  return {
+    key,
+    unique,
+    ...(sparse ? { sparse: true } : {}),
+    ...(type ? { type } : {})
+  };
+}
+
+// Convert a JSONB path expression like data->>'slug' or data->'user'->>'name'
+// back into a dot-separated field name like 'slug' or 'user.name'.
+// Handles PostgreSQL's normalized output which adds spaces, ::text casts,
+// and extra parentheses (e.g. ((data ->> 'a'::text))).
+function jsonPathToFieldName(expr) {
+  // Remove outer parens, ::text and ::numeric casts, ASC/DESC
+  let cleaned = expr
+    .replace(/\(+/g, '')
+    .replace(/\)+/g, '')
+    .replace(/::(?:text|numeric)/g, '')
+    .replace(/\s+(ASC|DESC)\s*$/i, '')
+    .trim();
+
+  // Must start with 'data'
+  if (!cleaned.startsWith('data')) {
+    return null;
+  }
+  // Remove the 'data' prefix
+  cleaned = cleaned.substring(4);
+
+  const parts = [];
+  // Match ->> 'name' or -> 'name' segments (with optional spaces around arrows)
+  const segmentPattern = /\s*->>\s*'([^']*)'\s*|\s*->\s*'([^']*)'\s*/g;
+  let m;
+  while ((m = segmentPattern.exec(cleaned)) !== null) {
+    // ->> captures in group 1, -> captures in group 2
+    const name = m[1] !== undefined ? m[1] : m[2];
+    // Skip the $date pseudo-field used for date indexes
+    if (name === '$date') {
+      continue;
+    }
+    parts.push(name);
+  }
+
+  return parts.length > 0 ? parts.join('.') : null;
+}
+
+// Split a comma-separated expression list, respecting parentheses nesting.
+// E.g. "((data->>'a')::numeric) DESC, (data->>'b') ASC" → two expressions.
+function splitExpressions(str) {
+  const results = [];
+  let depth = 0;
+  let current = '';
+  for (const ch of str) {
+    if (ch === '(') {
+      depth++;
+    } else if (ch === ')') {
+      depth--;
+    }
+    if (ch === ',' && depth === 0) {
+      results.push(current);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) {
+    results.push(current);
+  }
+  return results;
+}
+
+// =============================================================================
+// Query Building (with validated inputs only)
+//
+// IMPORTANT: buildWhereClause and buildOperatorClause MUTATE the `params` array
+// by pushing values onto it. The returned SQL string contains positional
+// placeholders ($1, $2, etc.) that reference these array indices. The current
+// length of `params` determines the next placeholder number.
+//
+// Correct usage:
+//   const params = [];
+//   const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+//   // params is now populated, whereClause contains matching $N references
+//   await pool.query(`SELECT * FROM t WHERE ${whereClause}`, params);
+//
+// DO NOT reuse a params array across independent queries.
+// =============================================================================
+
+// Build a single JSON arrow step for a path part.
+// Numeric parts (array indices) use -> N, string parts use -> 'name'.
+function jsonArrow(part) {
+  return /^\d+$/.test(part) ? `->${part}` : `->'${escapeString(part)}'`;
+}
+
+// Build JSON path for nested fields (returns jsonb)
+function buildJsonPath(field, prefix = 'data') {
+  const parts = field.split('.');
+  let path = prefix;
+  for (const part of parts) {
+    path += jsonArrow(part);
+  }
+  return path;
+}
+
+// Build JSON text path for nested fields (returns text, not jsonb).
+//
+// The result is wrapped with `COLLATE "C"` so string comparisons and sorts
+// follow byte-wise Unicode code point order, matching MongoDB's default
+// (non-collated) string semantics. Without this, Postgres would use the
+// database/OS locale (typically en_US.UTF-8) which produces user-visible
+// divergences from MongoDB in $gt/$lt/sort/range queries and also defeats
+// btree indexes built on the same expression whenever predicates and
+// indexes disagree on collation.
+function buildJsonTextPath(field, prefix = 'data') {
+  const parts = field.split('.');
+  let path = prefix;
+  for (let i = 0; i < parts.length - 1; i++) {
+    path += jsonArrow(parts[i]);
+  }
+  // Last segment uses ->> for text extraction
+  const last = parts[parts.length - 1];
+  path += /^\d+$/.test(last) ? `->>${last}` : `->>'${escapeString(last)}'`;
+  return `(${path}) COLLATE "C"`;
+}
+
+/**
+ * Convert a MongoDB query object to a PostgreSQL WHERE clause.
+ *
+ * MUTATES `params` by pushing values for parameterized query placeholders.
+ * The returned SQL references these values as $1, $2, etc., based on their
+ * position in `params` at the time each value is added.
+ *
+ * @param {Object} query - MongoDB-style query object
+ * @param {Array} params - Array to append parameter values to (MUTATED)
+ * @param {string} [prefix='data'] - Column name prefix for JSONB access
+ * @returns {string} SQL WHERE clause (without "WHERE" keyword)
+ */
+// Build a SQL condition matching `textExpr` against `regex`.
+//
+// When the regex is anchored and begins with a literal prefix, emit
+// `textExpr >= P AND textExpr < upper(P) AND textExpr ~ src`. The range
+// predicate is btree-indexable; the residual regex preserves correctness
+// for any trailing pattern. MUTATES `params`.
+function buildRegexMatchSql(textExpr, regex, params) {
+  const flags = regex.ignoreCase ? '*' : '';
+  const { prefix } = extractAnchoredLiteralPrefix(regex);
+  const parts = [];
+  if (prefix) {
+    params.push(prefix);
+    parts.push(`${textExpr} >= $${params.length}`);
+    const upper = prefixUpperBound(prefix);
+    if (upper !== null) {
+      params.push(upper);
+      parts.push(`${textExpr} < $${params.length}`);
+    }
+  }
+  params.push(regex.source);
+  parts.push(`${textExpr} ~${flags} $${params.length}`);
+  return parts.length > 1 ? `(${parts.join(' AND ')})` : parts[0];
+}
+
+function buildWhereClause(query, params, prefix = 'data', options = {}) {
+  const _pStart = profileStart();
+  const conditions = [];
+
+  for (const [ key, value ] of Object.entries(query || {})) {
+    if (key === '$and') {
+      if (!Array.isArray(value)) {
+        throw new Error('$and must be an array');
+      }
+      const andConditions = value.map(subQuery => {
+        const subClause = buildWhereClause(subQuery, params, prefix, options);
+        return `(${subClause})`;
+      });
+      conditions.push(`(${andConditions.join(' AND ')})`);
+    } else if (key === '$or') {
+      if (!Array.isArray(value)) {
+        throw new Error('$or must be an array');
+      }
+      const orConditions = value.map(subQuery => {
+        const subClause = buildWhereClause(subQuery, params, prefix, options);
+        return `(${subClause})`;
+      });
+      conditions.push(`(${orConditions.join(' OR ')})`);
+    } else if (key === '$text') {
+      // Full-text search: { $text: { $search: "term" } }
+      // Search against the text index fields stored in the table.
+      // We use PostgreSQL's to_tsvector/to_tsquery for this.
+      const searchTerm = value.$search;
+      if (typeof searchTerm !== 'string') {
+        throw new Error('$text.$search must be a string');
+      }
+      const textFields = options.textFields || [
+        'highSearchText', 'lowSearchText', 'title', 'searchBoost'
+      ];
+      const tsvectorExpr = buildTsvectorExpr(textFields);
+      const tsqueryExpr = buildTsqueryParam(searchTerm, params);
+      if (!tsqueryExpr) {
+        conditions.push('FALSE');
+      } else {
+        conditions.push(`${tsvectorExpr} @@ ${tsqueryExpr}`);
+      }
+    } else if (key === '_id') {
+      // _id is a separate column, handle specially
+      if (value instanceof RegExp) {
+        conditions.push(buildRegexMatchSql('_id', value, params));
+      } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        conditions.push(buildOperatorClause('_id', value, params, true));
+      } else {
+        params.push(value);
+        conditions.push(`_id = $${params.length}`);
+      }
+    } else if (key.startsWith('$')) {
+      throw new Error(`Unsupported top-level operator: ${key}`);
+    } else if (typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date) && !(value instanceof RegExp)) {
+      // Check if it's an operator object
+      const keys = Object.keys(value);
+      if (keys.some(k => k.startsWith('$'))) {
+        conditions.push(buildOperatorClause(key, value, params, false));
+      } else {
+        // Nested object equality
+        params.push(JSON.stringify(value));
+        conditions.push(`${prefix}->>'${escapeString(key)}' = $${params.length}`);
+      }
+    } else if (value instanceof RegExp) {
+      const jsonPath = buildJsonPath(key, prefix);
+      const textExpr = buildJsonTextPath(key, prefix);
+      // Scalar match uses the indexable range + residual regex rewrite.
+      const scalarMatch = buildRegexMatchSql(textExpr, value, params);
+      // Array-element fallback (regex only — no per-element index to exploit).
+      const flags = value.ignoreCase ? '*' : '';
+      params.push(value.source);
+      const arrayMatch = `(jsonb_typeof(${jsonPath}) = 'array' AND EXISTS(SELECT 1 FROM jsonb_array_elements_text(${jsonPath}) elem WHERE elem ~${flags} $${params.length}))`;
+      conditions.push(`(${scalarMatch} OR ${arrayMatch})`);
+    } else if (value === null || value === undefined) {
+      // MongoDB: { field: null } and { field: undefined } both match
+      // explicit null AND missing field
+      const jsonPath = buildJsonPath(key, prefix);
+      conditions.push(`(${jsonPath} IS NULL OR ${jsonPath} = 'null'::jsonb)`);
+    } else {
+      // Simple equality: use per-field @> which handles both scalar
+      // equality AND array-contains-scalar in one operation, replacing
+      // the previous two-branch OR with a single containment check.
+      const jsonPath = buildJsonPath(key, prefix);
+      const serialized = serializeValue(value);
+      params.push(JSON.stringify(serialized));
+      conditions.push(`${jsonPath} @> $${params.length}::jsonb`);
+    }
+  }
+
+  profileEnd('buildWhereClause', _pStart);
+  return conditions.length > 0 ? conditions.join(' AND ') : 'TRUE';
+}
+
+/**
+ * Build SQL conditions for MongoDB query operators ($eq, $gt, $in, etc.).
+ *
+ * MUTATES `params` by pushing values for parameterized query placeholders.
+ * Called by buildWhereClause for fields with operator objects.
+ *
+ * @param {string} field - Field name to apply operators to
+ * @param {Object} operators - Object with MongoDB operators (e.g., { $gt: 5, $lt: 10 })
+ * @param {Array} params - Array to append parameter values to (MUTATED)
+ * @param {boolean} [isIdField=false] - True if operating on _id column directly
+ * @returns {string} SQL condition string (e.g., "field > $1 AND field < $2")
+ */
+function buildOperatorClause(field, operators, params, isIdField = false) {
+  const conditions = [];
+
+  const jsonPath = isIdField ? '_id' : buildJsonPath(field);
+  const jsonTextPath = isIdField ? '_id' : buildJsonTextPath(field);
+
+  for (const [ op, opValue ] of Object.entries(operators)) {
+    switch (op) {
+      case '$eq':
+        if (isIdField) {
+          if (opValue === null || opValue === undefined) {
+            conditions.push('_id IS NULL');
+          } else {
+            params.push(opValue);
+            conditions.push(`_id = $${params.length}`);
+          }
+        } else {
+          if (opValue === null || opValue === undefined) {
+            // $eq: null matches both missing fields and explicit null values
+            conditions.push(`(${jsonPath} IS NULL OR ${jsonPath} = 'null'::jsonb)`);
+          } else {
+            params.push(JSON.stringify(serializeValue(opValue)));
+            conditions.push(`${jsonPath} = $${params.length}::jsonb`);
+          }
+        }
+        break;
+
+      case '$ne':
+        if (isIdField) {
+          if (opValue === null || opValue === undefined) {
+            conditions.push('_id IS NOT NULL');
+          } else {
+            params.push(opValue);
+            conditions.push(`(_id IS NULL OR _id != $${params.length})`);
+          }
+        } else {
+          if (opValue === null || opValue === undefined) {
+            // $ne: null means "field exists and is not null"
+            // Must exclude both missing fields (IS NULL) and JSON null values
+            conditions.push(`(${jsonPath} IS NOT NULL AND ${jsonPath} != 'null'::jsonb)`);
+          } else {
+            params.push(JSON.stringify(serializeValue(opValue)));
+            conditions.push(`(${jsonPath} IS NULL OR ${jsonPath} != $${params.length}::jsonb)`);
+          }
+        }
+        break;
+
+      case '$gt':
+        if (isIdField) {
+          params.push(opValue);
+          conditions.push(`_id > $${params.length}`);
+        } else if (opValue instanceof Date) {
+          params.push(opValue.toISOString());
+          conditions.push(`${jsonPath}->>'$date' > $${params.length}`);
+        } else if (typeof opValue === 'string') {
+          params.push(opValue);
+          conditions.push(`${jsonTextPath} > $${params.length}`);
+        } else {
+          params.push(opValue);
+          conditions.push(`(NULLIF(${jsonTextPath}, ''))::numeric > $${params.length}`);
+        }
+        break;
+
+      case '$gte':
+        if (isIdField) {
+          params.push(opValue);
+          conditions.push(`_id >= $${params.length}`);
+        } else if (opValue instanceof Date) {
+          params.push(opValue.toISOString());
+          conditions.push(`${jsonPath}->>'$date' >= $${params.length}`);
+        } else if (typeof opValue === 'string') {
+          params.push(opValue);
+          conditions.push(`${jsonTextPath} >= $${params.length}`);
+        } else {
+          params.push(opValue);
+          conditions.push(`(NULLIF(${jsonTextPath}, ''))::numeric >= $${params.length}`);
+        }
+        break;
+
+      case '$lt':
+        if (isIdField) {
+          params.push(opValue);
+          conditions.push(`_id < $${params.length}`);
+        } else if (opValue instanceof Date) {
+          params.push(opValue.toISOString());
+          conditions.push(`${jsonPath}->>'$date' < $${params.length}`);
+        } else if (typeof opValue === 'string') {
+          params.push(opValue);
+          conditions.push(`${jsonTextPath} < $${params.length}`);
+        } else {
+          params.push(opValue);
+          conditions.push(`(NULLIF(${jsonTextPath}, ''))::numeric < $${params.length}`);
+        }
+        break;
+
+      case '$lte':
+        if (isIdField) {
+          params.push(opValue);
+          conditions.push(`_id <= $${params.length}`);
+        } else if (opValue instanceof Date) {
+          params.push(opValue.toISOString());
+          conditions.push(`${jsonPath}->>'$date' <= $${params.length}`);
+        } else if (typeof opValue === 'string') {
+          params.push(opValue);
+          conditions.push(`${jsonTextPath} <= $${params.length}`);
+        } else {
+          params.push(opValue);
+          conditions.push(`(NULLIF(${jsonTextPath}, ''))::numeric <= $${params.length}`);
+        }
+        break;
+
+      case '$in':
+        if (!Array.isArray(opValue)) {
+          throw new Error('$in requires an array');
+        }
+        if (opValue.length === 0) {
+          // $in with empty array matches nothing
+          conditions.push('FALSE');
+        } else if (isIdField) {
+          // Single array parameter allows PostgreSQL to cache the plan
+          // regardless of how many IDs are passed
+          params.push(opValue);
+          conditions.push(`_id = ANY($${params.length}::text[])`);
+        } else {
+          const hasNull = opValue.includes(null);
+          const regexValues = opValue.filter(v => v instanceof RegExp);
+          const nonNullValues = opValue.filter(v => v !== null && !(v instanceof RegExp));
+          const parts = [];
+          if (nonNullValues.length > 0) {
+            params.push(nonNullValues.map(v => JSON.stringify(serializeValue(v))));
+            parts.push(`${jsonPath} @> ANY($${params.length}::jsonb[])`);
+          }
+          if (hasNull) {
+            parts.push(`${jsonPath} IS NULL`);
+          }
+          // MongoDB supports RegExp values inside $in for pattern matching
+          for (const regex of regexValues) {
+            parts.push(buildRegexMatchSql(jsonTextPath, regex, params));
+          }
+          conditions.push(parts.length > 1 ? `(${parts.join(' OR ')})` : parts[0]);
+        }
+        break;
+
+      case '$nin':
+        if (!Array.isArray(opValue)) {
+          throw new Error('$nin requires an array');
+        }
+        if (opValue.length === 0) {
+          // $nin with empty array matches everything
+          conditions.push('TRUE');
+        } else if (isIdField) {
+          const placeholders = opValue.map(v => {
+            params.push(v);
+            return `$${params.length}`;
+          });
+          conditions.push(`(_id IS NULL OR _id NOT IN (${placeholders.join(', ')}))`);
+        } else {
+          const hasNull = opValue.includes(null);
+          const nonNullValues = opValue.filter(v => v !== null);
+          const parts = [];
+          if (nonNullValues.length > 0) {
+            params.push(nonNullValues.map(v => JSON.stringify(serializeValue(v))));
+            parts.push(`NOT ${jsonPath} @> ANY($${params.length}::jsonb[])`);
+          }
+          if (hasNull) {
+            // $nin with null means exclude docs where field is null/missing
+            parts.push(`${jsonPath} IS NOT NULL`);
+          } else {
+            // When null is NOT in $nin, still allow null/missing fields through
+            parts.push(`${jsonPath} IS NULL`);
+          }
+          conditions.push(`(${parts.join(hasNull ? ' AND ' : ' OR ')})`);
+        }
+        break;
+
+      case '$exists':
+        if (isIdField) {
+          conditions.push(opValue ? '_id IS NOT NULL' : '_id IS NULL');
+        } else {
+          conditions.push(opValue ? `${jsonPath} IS NOT NULL` : `${jsonPath} IS NULL`);
+        }
+        break;
+
+      case '$not': {
+        if (typeof opValue !== 'object' || opValue === null) {
+          throw new Error('$not requires an object');
+        }
+        const negatedClause = buildOperatorClause(
+          field, opValue, params, isIdField
+        );
+        conditions.push(`NOT (${negatedClause})`);
+        break;
+      }
+
+      case '$regex': {
+        const pattern = opValue instanceof RegExp
+          ? opValue.source
+          : String(opValue);
+        const regexOptions = operators.$options || '';
+        const caseInsensitive = regexOptions.includes('i');
+        // Reconstruct a RegExp so the helper can analyze the pattern uniformly.
+        let regex;
+        try {
+          regex = new RegExp(pattern, caseInsensitive ? 'i' : '');
+        } catch (e) {
+          // Fall back to direct emission if the pattern isn't a valid JS RegExp
+          params.push(pattern);
+          conditions.push(
+            `${isIdField ? '_id' : jsonTextPath} ~${caseInsensitive ? '*' : ''} $${params.length}`
+          );
+          break;
+        }
+        conditions.push(
+          buildRegexMatchSql(isIdField ? '_id' : jsonTextPath, regex, params)
+        );
+        break;
+      }
+
+      case '$options':
+        // Handled with $regex, skip
+        break;
+
+      case '$all':
+        if (!Array.isArray(opValue)) {
+          throw new Error('$all requires an array');
+        }
+        params.push(JSON.stringify(opValue));
+        conditions.push(`${jsonPath} @> $${params.length}::jsonb`);
+        break;
+
+      case '$size':
+        params.push(opValue);
+        conditions.push(
+          `jsonb_typeof(${jsonPath}) = 'array' AND jsonb_array_length(${jsonPath}) = $${params.length}`
+        );
+        break;
+
+      default:
+        throw new Error(`Unsupported operator: ${op}`);
+    }
+  }
+
+  return conditions.join(' AND ');
+}
+
+// Build the tsvector SQL expression for a given list of text fields.
+// Used by both the WHERE clause ($text matching) and SELECT (ts_rank scoring).
+function buildTsvectorExpr(textFields) {
+  const parts = textFields.map(f => {
+    const fieldParts = f.split('.');
+    let path = 'data';
+    for (let i = 0; i < fieldParts.length - 1; i++) {
+      path += `->'${escapeString(fieldParts[i])}'`;
+    }
+    path += `->>'${escapeString(fieldParts[fieldParts.length - 1])}'`;
+    // COLLATE "C" here is ignored for the tsvector output but keeps this
+    // expression textually identical to the CREATE INDEX expression
+    // produced by createIndex so the planner can match the gin index.
+    return `coalesce((${path}) COLLATE "C", '')`;
+  });
+  return `to_tsvector('simple', ${parts.join(' || \' \' || ')})`;
+}
+
+// Build the tsquery SQL expression from a search string.
+// Returns { expr, params } where expr contains $N placeholders.
+function buildTsqueryParam(searchTerm, params) {
+  const words = searchTerm.trim().split(/\s+/).filter(w => w.length > 0);
+  if (words.length === 0) {
+    return null;
+  }
+  params.push(words.map(w => w.replace(/[&|!():*<>'"]/g, ' ')).join(' | '));
+  return `to_tsquery('simple', $${params.length})`;
+}
+
+// Check if a query object contains a $text operator with a non-empty search string.
+function queryHasText(query) {
+  if (!query || typeof query !== 'object' || !('$text' in query)) {
+    return false;
+  }
+  const search = query.$text && query.$text.$search;
+  if (typeof search !== 'string') {
+    return false;
+  }
+  return search.trim().split(/\s+/).filter(w => w.length > 0).length > 0;
+}
+
+// Build ORDER BY clause
+function buildOrderBy(sort, options = {}) {
+  const _pStart = profileStart();
+  const clauses = [];
+
+  if (sort && Object.keys(sort).length > 0) {
+    for (const [ field, direction ] of Object.entries(sort)) {
+      if (direction && typeof direction === 'object' && direction.$meta === 'textScore') {
+        // Sort by text search relevance score (descending — higher is better)
+        if (options.hasTextScore) {
+          clauses.push('_score DESC');
+        }
+        continue;
+      }
+      if (field === '_id') {
+        clauses.push(`_id ${direction === -1 ? 'DESC' : 'ASC'}`);
+      } else {
+        const jsonPath = buildJsonTextPath(field);
+        clauses.push(`${jsonPath} ${direction === -1 ? 'DESC' : 'ASC'}`);
+      }
+    }
+  }
+
+  // Always add _order as final tiebreaker to match MongoDB's
+  // insertion-order stability among equal sort keys
+  clauses.push('_order ASC');
+  profileEnd('buildOrderBy', _pStart);
+  return `ORDER BY ${clauses.join(', ')}`;
+}
+
+// =============================================================================
+// Cursor Implementation
+// =============================================================================
+
+class PostgresCursor {
+  constructor(collection, query, options = {}) {
+    this._collection = collection;
+    this._query = query;
+    this._projection = options.projection || null;
+    this._sort = null;
+    this._limit = null;
+    this._skip = null;
+    this._cursorClient = null;
+    this._cursorName = null;
+    this._exhausted = false;
+  }
+
+  project(projection) {
+    this._projection = projection;
+    return this;
+  }
+
+  sort(sort) {
+    this._sort = sort;
+    return this;
+  }
+
+  limit(n) {
+    // MongoDB convention: limit(0) means no limit
+    const val = validateInteger(n, 'limit');
+    this._limit = val === 0 ? null : val;
+    return this;
+  }
+
+  skip(n) {
+    this._skip = validateInteger(n, 'skip');
+    return this;
+  }
+
+  clone() {
+    const cloned = new PostgresCursor(this._collection, this._query);
+    cloned._projection = this._projection;
+    cloned._sort = this._sort;
+    cloned._limit = this._limit;
+    cloned._skip = this._skip;
+    return cloned;
+  }
+
+  // Build the SELECT SQL + params that this cursor would execute. Shared
+  // by toArray/_next and exposed via explain() so tests and callers can
+  // introspect the planned query without re-deriving the SQL by hand.
+  _buildFindSql() {
+    const params = [];
+    const queryOptions = this._collection._queryOptions();
+    const qualifiedName = this._collection._qualifiedName();
+    const whereClause = buildWhereClause(this._query, params, 'data', queryOptions);
+    const hasText = queryHasText(this._query);
+    const orderBy = buildOrderBy(this._sort, { hasTextScore: hasText });
+
+    // When a $text query is active, compute ts_rank as _score
+    let selectCols = '_id, data';
+    if (hasText) {
+      const textFields = queryOptions.textFields || [
+        'highSearchText', 'lowSearchText', 'title', 'searchBoost'
+      ];
+      const tsvectorExpr = buildTsvectorExpr(textFields);
+      const tsqueryExpr = buildTsqueryParam(this._query.$text.$search, params);
+      if (tsqueryExpr) {
+        selectCols += `, ts_rank(${tsvectorExpr}, ${tsqueryExpr}) AS _score`;
+      }
+    }
+
+    let sql = `SELECT ${selectCols} FROM ${qualifiedName} WHERE ${whereClause} ${orderBy}`;
+    if (this._limit != null) {
+      sql += ` LIMIT ${this._limit}`;
+    }
+    if (this._skip != null) {
+      sql += ` OFFSET ${this._skip}`;
+    }
+    return {
+      sql,
+      params
+    };
+  }
+
+  // Returns the SQL and parameter values the adapter would execute for
+  // this cursor's current query/sort/limit/skip/projection. Useful for
+  // EXPLAIN-based tests and for debugging query planner behavior. The
+  // returned SQL uses the adapter's native placeholder style ($N for
+  // PostgreSQL).
+  async explain() {
+    await this._collection._ensureTable();
+    return this._buildFindSql();
+  }
+
+  async toArray() {
+    const _pStart = profileStart();
+    await this._collection._ensureTable();
+
+    const { sql, params } = this._buildFindSql();
+
+    const _qStart = profileStart();
+    const result = await this._collection._pool.query(sql, params);
+    profileQuery(sql, _qStart);
+    const rows = result.rows.map(row => {
+      const doc = deserializeDocument(row.data, row._id);
+      const meta = row._score != null ? { textScore: parseFloat(row._score) } : {};
+      return this._projection ? applyProjection(doc, this._projection, meta) : doc;
+    });
+    profileEnd('findToArray', _pStart);
+    return rows;
+  }
+
+  next(callback) {
+    const promise = this._next();
+    if (callback) {
+      promise.then(doc => callback(null, doc), err => callback(err));
+      return;
+    }
+    return promise;
+  }
+
+  async _next() {
+    if (this._peeked !== undefined) {
+      const doc = this._peeked;
+      this._peeked = undefined;
+      if (doc === null) {
+        this._exhausted = true;
+      }
+      return doc;
+    }
+    if (this._exhausted) {
+      return null;
+    }
+    if (!this._cursorClient) {
+      await this._collection._ensureTable();
+      this._cursorClient = await this._collection._pool.connect();
+      this._cursorName = `cur_${generateId()}`;
+
+      const { sql, params } = this._buildFindSql();
+
+      const escapedCursorName = escapeIdentifier(this._cursorName);
+      await this._cursorClient.query('BEGIN');
+      await this._cursorClient.query(
+        `DECLARE "${escapedCursorName}" CURSOR FOR ${sql}`,
+        params
+      );
+    }
+
+    const escapedCursorName = escapeIdentifier(this._cursorName);
+    const result = await this._cursorClient.query(
+      `FETCH NEXT FROM "${escapedCursorName}"`
+    );
+
+    if (result.rows.length === 0) {
+      this._exhausted = true;
+      await this._cursorClient.query('COMMIT');
+      this._cursorClient.release();
+      this._cursorClient = null;
+      return null;
+    }
+
+    const row = result.rows[0];
+    const doc = deserializeDocument(row.data, row._id);
+    const meta = row._score != null ? { textScore: parseFloat(row._score) } : {};
+    return this._projection ? applyProjection(doc, this._projection, meta) : doc;
+  }
+
+  async hasNext() {
+    if (this._exhausted) {
+      return false;
+    }
+    if (this._peeked !== undefined) {
+      return this._peeked !== null;
+    }
+    this._peeked = await this._next();
+    return this._peeked !== null;
+  }
+
+  async close() {
+    if (this._cursorClient) {
+      const escapedCursorName = escapeIdentifier(this._cursorName);
+      await this._cursorClient.query(`CLOSE "${escapedCursorName}"`);
+      await this._cursorClient.query('COMMIT');
+      this._cursorClient.release();
+      this._cursorClient = null;
+      this._exhausted = true;
+    }
+  }
+
+  addCursorFlag() {
+    // No-op for PostgreSQL — flags like noCursorTimeout are MongoDB-specific
+    return this;
+  }
+
+  [Symbol.asyncIterator]() {
+    return {
+      cursor: this,
+      async next() {
+        const doc = await this.cursor._next();
+        if (doc === null) {
+          return {
+            done: true,
+            value: undefined
+          };
+        }
+        return {
+          done: false,
+          value: doc
+        };
+      }
+    };
+  }
+
+  async count() {
+    const _pStart = profileStart();
+    await this._collection._ensureTable();
+
+    const params = [];
+    const qualifiedName = this._collection._qualifiedName();
+    const whereClause = buildWhereClause(this._query, params, 'data', this._collection._queryOptions());
+    const sql = `SELECT COUNT(*) as count FROM ${qualifiedName} WHERE ${whereClause}`;
+    const _qStart = profileStart();
+    const result = await this._collection._pool.query(sql, params);
+    profileQuery(sql, _qStart);
+    profileEnd('countDocuments', _pStart);
+    return parseInt(result.rows[0].count, 10);
+  }
+}
+
+// =============================================================================
+// Collection Implementation
+// =============================================================================
+
+class PostgresCollection {
+  constructor(db, name) {
+    this._db = db;
+    this._pool = db._pool;
+    this._tableName = validateTableName(name);
+    this._schema = db._schema || null;
+    this._name = name;
+    this._indexes = new Map();
+    this._textFields = null;
+    this._initialized = false;
+  }
+
+  // Returns the schema-qualified table name for use in SQL.
+  // In multi-schema mode: "schemaname"."tablename"
+  // In simple mode: "tablename"
+  _qualifiedName() {
+    const table = `"${escapeIdentifier(this._tableName)}"`;
+    if (this._schema) {
+      return `"${escapeIdentifier(this._schema)}".${table}`;
+    }
+    return table;
+  }
+
+  _queryOptions() {
+    return this._textFields ? { textFields: this._textFields } : {};
+  }
+
+  get collectionName() {
+    return this._name;
+  }
+
+  get name() {
+    return this._name;
+  }
+
+  async _ensureTable() {
+    if (this._initialized) {
+      return;
+    }
+    const _pStart = profileStart();
+
+    // In multi-schema mode, ensure the schema exists
+    if (this._schema) {
+      await this._pool.query(
+        `CREATE SCHEMA IF NOT EXISTS "${escapeIdentifier(this._schema)}"`
+      );
+    }
+
+    const qualifiedName = this._qualifiedName();
+    await this._pool.query(`
+      CREATE TABLE IF NOT EXISTS ${qualifiedName} (
+        _id TEXT COLLATE "C" PRIMARY KEY,
+        _order SERIAL,
+        data JSONB NOT NULL
+      )
+    `);
+    // Add _order column to tables created before it existed
+    try {
+      await this._pool.query(`
+        ALTER TABLE ${qualifiedName} ADD COLUMN IF NOT EXISTS _order SERIAL
+      `);
+    } catch (e) {
+      // Column already exists, ignore
+    }
+    profileEnd('ensureTable', _pStart);
+    this._initialized = true;
+  }
+
+  async insertOne(doc) {
+    await this._ensureTable();
+
+    const id = doc._id != null ? String(doc._id) : generateId();
+    const docWithoutId = { ...doc };
+    delete docWithoutId._id;
+
+    const qualifiedName = this._qualifiedName();
+    try {
+      await this._pool.query(
+        `INSERT INTO ${qualifiedName} (_id, data) VALUES ($1, $2)`,
+        [ id, serializeDocument(docWithoutId) ]
+      );
+      return {
+        acknowledged: true,
+        insertedId: id,
+        insertedCount: 1,
+        ops: [ {
+          ...doc,
+          _id: id
+        } ],
+        result: { ok: 1 }
+      };
+    } catch (e) {
+      if (e.code === '23505') {
+        throw makeDuplicateKeyError(e);
+      }
+      throw e;
+    }
+  }
+
+  async insertMany(docs) {
+    await this._ensureTable();
+
+    const insertedIds = {};
+    let insertedCount = 0;
+
+    for (let i = 0; i < docs.length; i++) {
+      const result = await this.insertOne(docs[i]);
+      insertedIds[i] = result.insertedId;
+      insertedCount++;
+    }
+
+    return {
+      acknowledged: true,
+      insertedCount,
+      insertedIds,
+      result: { ok: 1 }
+    };
+  }
+
+  async findOne(query, options = {}) {
+    const _pStart = profileStart();
+    await this._ensureTable();
+
+    const params = [];
+    const qualifiedName = this._qualifiedName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+    const sql = `SELECT _id, data FROM ${qualifiedName} WHERE ${whereClause} LIMIT 1`;
+
+    const _qStart = profileStart();
+    const result = await this._pool.query(sql, params);
+    profileQuery(sql, _qStart);
+    if (result.rows.length === 0) {
+      profileEnd('findOne', _pStart);
+      return null;
+    }
+
+    const doc = deserializeDocument(result.rows[0].data, result.rows[0]._id);
+    const final = options.projection ? applyProjection(doc, options.projection) : doc;
+    profileEnd('findOne', _pStart);
+    return final;
+  }
+
+  find(query, options) {
+    return new PostgresCursor(this, query, options);
+  }
+
+  async updateOne(query, update, options = {}) {
+    const _pStart = profileStart();
+    await this._ensureTable();
+
+    // Handle legacy callback as third argument (ignore the callback, PostgreSQL
+    // adapter is Promise-based)
+    if (typeof options === 'function') {
+      options = {};
+    }
+
+    // Single-statement fast path: when the update uses only simple
+    // operators without upsert, execute a single UPDATE statement
+    // instead of the read-modify-write cycle. $push, $pull and
+    // $addToSet are included only when all their values are scalars.
+    if (!options.upsert) {
+      const atomicOps = [
+        '$inc', '$set', '$unset', '$currentDate',
+        '$push', '$pull', '$addToSet'
+      ];
+      const ops = Object.keys(update);
+      const isAtomicCompatible = ops.length > 0 &&
+        ops.every(op => atomicOps.includes(op));
+      if (isAtomicCompatible) {
+        const allScalar = [ '$push', '$pull', '$addToSet' ].every(op => {
+          if (!update[op]) {
+            return true;
+          }
+          return Object.values(update[op]).every(v =>
+            typeof v === 'string' ||
+            typeof v === 'number' ||
+            typeof v === 'boolean'
+          );
+        });
+        if (allScalar) {
+          const result = await this._atomicUpdateOne(query, update);
+          profileEnd('updateOne', _pStart);
+          return result;
+        }
+      }
+    }
+
+    const params = [];
+    const qualifiedName = this._qualifiedName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+
+    const selectSql = `SELECT _id, data FROM ${qualifiedName} WHERE ${whereClause} LIMIT 1`;
+    const _qStart = profileStart();
+    const selectResult = await this._pool.query(selectSql, params);
+    profileQuery(selectSql, _qStart);
+
+    if (selectResult.rows.length === 0) {
+      if (options.upsert) {
+        let newDoc = {};
+        if (query._id) {
+          newDoc._id = query._id;
+        }
+        newDoc = applyUpdate(newDoc, update);
+        const insertResult = await this.insertOne(newDoc);
+        return {
+          acknowledged: true,
+          matchedCount: 0,
+          modifiedCount: 0,
+          upsertedId: insertResult.insertedId,
+          upsertedCount: 1,
+          result: {
+            nModified: 0,
+            n: 1
+          }
+        };
+      }
+      return {
+        acknowledged: true,
+        matchedCount: 0,
+        modifiedCount: 0,
+        result: {
+          nModified: 0,
+          n: 0
+        }
+      };
+    }
+
+    const row = selectResult.rows[0];
+    const existing = deserializeDocument(row.data, row._id);
+    const updated = applyUpdate(existing, update);
+    const { _id, ...dataWithoutId } = updated;
+
+    try {
+      await this._pool.query(
+        `UPDATE ${qualifiedName} SET data = $1 WHERE _id = $2`,
+        [ serializeDocument(dataWithoutId), selectResult.rows[0]._id ]
+      );
+    } catch (e) {
+      if (e.code === '23505') {
+        throw makeDuplicateKeyError(e);
+      }
+      throw e;
+    }
+
+    return {
+      acknowledged: true,
+      matchedCount: 1,
+      modifiedCount: 1,
+      result: {
+        nModified: 1,
+        n: 1
+      }
+    };
+  }
+
+  // Atomic update using SQL expressions for $inc, $set, $unset,
+  // $currentDate, $push, $pull, $addToSet (no read-modify-write race)
+  async _atomicUpdateOne(query, update) {
+    const params = [];
+    const qualifiedName = this._qualifiedName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+
+    // Build a chain of jsonb_set / #- calls for atomic update
+    let dataExpr = 'data';
+
+    if (update.$set) {
+      for (const [ field, value ] of Object.entries(update.$set)) {
+        const pathArray = field.split('.');
+        const pathLiteral = `'{${pathArray.map(p => escapeString(p)).join(',')}}'`;
+        const serialized = serializeValue(value);
+        params.push(JSON.stringify(serialized));
+        dataExpr = `jsonb_set(${dataExpr}, ${pathLiteral}, $${params.length}::jsonb, true)`;
+      }
+    }
+
+    if (update.$inc) {
+      for (const [ field, value ] of Object.entries(update.$inc)) {
+        const pathArray = field.split('.');
+        const pathLiteral = `'{${pathArray.map(p => escapeString(p)).join(',')}}'`;
+        let readPath = 'data';
+        for (let i = 0; i < pathArray.length - 1; i++) {
+          readPath += `->'${escapeString(pathArray[i])}'`;
+        }
+        readPath += `->>'${escapeString(pathArray[pathArray.length - 1])}'`;
+        params.push(value);
+        dataExpr = `jsonb_set(${dataExpr}, ${pathLiteral}, to_jsonb(COALESCE((${readPath})::numeric, 0) + $${params.length}), true)`;
+      }
+    }
+
+    if (update.$unset) {
+      const fields = Array.isArray(update.$unset)
+        ? update.$unset
+        : Object.keys(update.$unset);
+      for (const field of fields) {
+        const pathArray = field.split('.');
+        const pathLiteral = `'{${pathArray.map(p => escapeString(p)).join(',')}}'`;
+        dataExpr = `(${dataExpr}) #- ${pathLiteral}`;
+      }
+    }
+
+    if (update.$currentDate) {
+      for (const [ field, value ] of Object.entries(update.$currentDate)) {
+        if (value === true || (value && value.$type === 'date')) {
+          const pathArray = field.split('.');
+          const pathLiteral = `'{${pathArray.map(p => escapeString(p)).join(',')}}'`;
+          const dateVal = JSON.stringify(serializeValue(new Date()));
+          params.push(dateVal);
+          dataExpr = `jsonb_set(${dataExpr}, ${pathLiteral}, $${params.length}::jsonb, true)`;
+        }
+      }
+    }
+
+    // $push: append scalar value to array
+    if (update.$push) {
+      for (const [ field, value ] of Object.entries(update.$push)) {
+        const pathArray = field.split('.');
+        const pathLiteral = `'{${pathArray.map(p => escapeString(p)).join(',')}}'`;
+        const readPath = pathArray.map(p => `'${escapeString(p)}'`).join('->');
+        const coalesced = `COALESCE(data->${readPath}, '[]'::jsonb)`;
+        params.push(JSON.stringify(value));
+        dataExpr = `jsonb_set(${dataExpr}, ${pathLiteral}, ${coalesced} || $${params.length}::jsonb, true)`;
+      }
+    }
+
+    // $pull: remove scalar value from array
+    if (update.$pull) {
+      for (const [ field, value ] of Object.entries(update.$pull)) {
+        const pathArray = field.split('.');
+        const pathLiteral = `'{${pathArray.map(p => escapeString(p)).join(',')}}'`;
+        const readPath = pathArray.map(p => `'${escapeString(p)}'`).join('->');
+        params.push(JSON.stringify(value));
+        dataExpr = `jsonb_set(${dataExpr}, ${pathLiteral}, ` +
+          '(SELECT COALESCE(jsonb_agg(elem), \'[]\'::jsonb) ' +
+          `FROM jsonb_array_elements(COALESCE(data->${readPath}, '[]'::jsonb)) AS elem ` +
+          `WHERE elem != $${params.length}::jsonb), true)`;
+      }
+    }
+
+    // $addToSet: add scalar value to array if not already present
+    if (update.$addToSet) {
+      for (const [ field, value ] of Object.entries(update.$addToSet)) {
+        const pathArray = field.split('.');
+        const pathLiteral = `'{${pathArray.map(p => escapeString(p)).join(',')}}'`;
+        const readPath = pathArray.map(p => `'${escapeString(p)}'`).join('->');
+        const coalesced = `COALESCE(data->${readPath}, '[]'::jsonb)`;
+        params.push(JSON.stringify(value));
+        dataExpr = `jsonb_set(${dataExpr}, ${pathLiteral}, ` +
+          `CASE WHEN ${coalesced} @> $${params.length}::jsonb ` +
+          `THEN ${coalesced} ` +
+          `ELSE ${coalesced} || $${params.length}::jsonb END, true)`;
+      }
+    }
+
+    const sql = `UPDATE ${qualifiedName} SET data = ${dataExpr} WHERE ${whereClause}`;
+    try {
+      const _qStart = profileStart();
+      const result = await this._pool.query(sql, params);
+      profileQuery(sql, _qStart);
+      const matched = result.rowCount > 0 ? 1 : 0;
+      return {
+        acknowledged: true,
+        matchedCount: matched,
+        modifiedCount: matched,
+        result: {
+          nModified: matched,
+          n: matched
+        }
+      };
+    } catch (e) {
+      if (e.code === '23505') {
+        throw makeDuplicateKeyError(e);
+      }
+      throw e;
+    }
+  }
+
+  async updateMany(query, update, options = {}) {
+    await this._ensureTable();
+
+    const params = [];
+    const qualifiedName = this._qualifiedName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+
+    const selectSql = `SELECT _id, data FROM ${qualifiedName} WHERE ${whereClause}`;
+    const selectResult = await this._pool.query(selectSql, params);
+
+    if (selectResult.rows.length === 0) {
+      return {
+        acknowledged: true,
+        matchedCount: 0,
+        modifiedCount: 0,
+        result: {
+          nModified: 0,
+          n: 0
+        }
+      };
+    }
+
+    let modifiedCount = 0;
+    for (const row of selectResult.rows) {
+      const existing = deserializeDocument(row.data, row._id);
+      const updated = applyUpdate(existing, update);
+      const { _id, ...dataWithoutId } = updated;
+
+      await this._pool.query(
+        `UPDATE ${qualifiedName} SET data = $1 WHERE _id = $2`,
+        [ serializeDocument(dataWithoutId), row._id ]
+      );
+      modifiedCount++;
+    }
+
+    return {
+      acknowledged: true,
+      matchedCount: selectResult.rows.length,
+      modifiedCount,
+      result: {
+        nModified: modifiedCount,
+        n: selectResult.rows.length
+      }
+    };
+  }
+
+  async replaceOne(query, replacement, options = {}) {
+    await this._ensureTable();
+
+    const params = [];
+    const qualifiedName = this._qualifiedName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+
+    const selectSql = `SELECT _id FROM ${qualifiedName} WHERE ${whereClause} LIMIT 1`;
+    const selectResult = await this._pool.query(selectSql, params);
+
+    if (selectResult.rows.length === 0) {
+      if (options.upsert) {
+        const result = await this.insertOne(replacement);
+        return {
+          acknowledged: true,
+          matchedCount: 0,
+          modifiedCount: 0,
+          upsertedId: result.insertedId,
+          upsertedCount: 1
+        };
+      }
+      return {
+        acknowledged: true,
+        matchedCount: 0,
+        modifiedCount: 0
+      };
+    }
+
+    const { _id, ...dataWithoutId } = replacement;
+    try {
+      await this._pool.query(
+        `UPDATE ${qualifiedName} SET data = $1 WHERE _id = $2`,
+        [ serializeDocument(dataWithoutId), selectResult.rows[0]._id ]
+      );
+    } catch (e) {
+      if (e.code === '23505') {
+        throw makeDuplicateKeyError(e);
+      }
+      throw e;
+    }
+
+    return {
+      acknowledged: true,
+      matchedCount: 1,
+      modifiedCount: 1
+    };
+  }
+
+  async deleteOne(query) {
+    await this._ensureTable();
+
+    const params = [];
+    const qualifiedName = this._qualifiedName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+
+    const result = await this._pool.query(
+      `DELETE FROM ${qualifiedName} WHERE _id IN (
+        SELECT _id FROM ${qualifiedName} WHERE ${whereClause} LIMIT 1
+      )`,
+      params
+    );
+
+    return {
+      acknowledged: true,
+      deletedCount: result.rowCount,
+      result: { ok: 1 }
+    };
+  }
+
+  async deleteMany(query) {
+    await this._ensureTable();
+
+    const params = [];
+    const qualifiedName = this._qualifiedName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+
+    const result = await this._pool.query(
+      `DELETE FROM ${qualifiedName} WHERE ${whereClause}`,
+      params
+    );
+
+    return {
+      acknowledged: true,
+      deletedCount: result.rowCount,
+      result: { ok: 1 }
+    };
+  }
+
+  // Legacy MongoDB method aliases used by ApostropheCMS
+  async remove(query) {
+    return this.deleteMany(query);
+  }
+
+  async removeOne(query) {
+    return this.deleteOne(query);
+  }
+
+  async removeMany(query) {
+    return this.deleteMany(query);
+  }
+
+  async countDocuments(query = {}) {
+    const _pStart = profileStart();
+    await this._ensureTable();
+
+    const params = [];
+    const qualifiedName = this._qualifiedName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+    const sql = `SELECT COUNT(*) as count FROM ${qualifiedName} WHERE ${whereClause}`;
+
+    const _qStart = profileStart();
+    const result = await this._pool.query(sql, params);
+    profileQuery(sql, _qStart);
+    profileEnd('countDocuments', _pStart);
+    return parseInt(result.rows[0].count, 10);
+  }
+
+  async distinct(field, query = {}) {
+    const _pStart = profileStart();
+    await this._ensureTable();
+
+    const params = [];
+    const qualifiedName = this._qualifiedName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+
+    if (field === '_id') {
+      const sql = `SELECT DISTINCT _id as value FROM ${qualifiedName} WHERE ${whereClause}`;
+      const _qStart = profileStart();
+      const result = await this._pool.query(sql, params);
+      profileQuery(sql, _qStart);
+      profileEnd('distinct', _pStart);
+      return result.rows.map(row => row.value).filter(v => v !== null);
+    }
+
+    const jsonPath = buildJsonPath(field);
+    // MongoDB's distinct() automatically flattens arrays.
+    // Use LATERAL with jsonb_array_elements to unwind array values,
+    // and fall back to the value itself for scalars.
+    // Use jsonb_array_elements (not _text) to preserve types for non-string values.
+    const sql = `SELECT DISTINCT elem as value FROM ${qualifiedName}, LATERAL jsonb_array_elements(
+      CASE WHEN jsonb_typeof(${jsonPath}) = 'array' THEN ${jsonPath} ELSE jsonb_build_array(${jsonPath}) END
+    ) AS elem WHERE ${whereClause} AND ${jsonPath} IS NOT NULL`;
+    const _qStart = profileStart();
+    const result = await this._pool.query(sql, params);
+    profileQuery(sql, _qStart);
+
+    const values = result.rows
+      .map(row => {
+        const v = row.value;
+        if (v === null || v === undefined) {
+          return null;
+        }
+        // pg driver parses jsonb automatically, returning JS types.
+        // For jsonb strings, we already get JS strings.
+        // For jsonb numbers/booleans/objects, we get those types.
+        // No additional parsing needed.
+        return v;
+      })
+      .filter(v => v !== null);
+    profileEnd('distinct', _pStart);
+    return values;
+  }
+
+  aggregate(pipeline) {
+    return new AggregationCursor(this, pipeline);
+  }
+
+  async bulkWrite(operations) {
+    await this._ensureTable();
+
+    let insertedCount = 0;
+    let modifiedCount = 0;
+    let deletedCount = 0;
+    let upsertedCount = 0;
+    const insertedIds = {};
+    const upsertedIds = {};
+
+    for (let i = 0; i < operations.length; i++) {
+      const op = operations[i];
+
+      if (op.insertOne) {
+        const result = await this.insertOne(op.insertOne.document);
+        insertedIds[i] = result.insertedId;
+        insertedCount++;
+      } else if (op.updateOne) {
+        const result = await this.updateOne(
+          op.updateOne.filter,
+          op.updateOne.update,
+          { upsert: op.updateOne.upsert }
+        );
+        modifiedCount += result.modifiedCount;
+        if (result.upsertedId) {
+          upsertedIds[i] = result.upsertedId;
+          upsertedCount++;
+        }
+      } else if (op.updateMany) {
+        const result = await this.updateMany(
+          op.updateMany.filter,
+          op.updateMany.update,
+          { upsert: op.updateMany.upsert }
+        );
+        modifiedCount += result.modifiedCount;
+      } else if (op.deleteOne) {
+        const result = await this.deleteOne(op.deleteOne.filter);
+        deletedCount += result.deletedCount;
+      } else if (op.deleteMany) {
+        const result = await this.deleteMany(op.deleteMany.filter);
+        deletedCount += result.deletedCount;
+      } else if (op.replaceOne) {
+        const result = await this.replaceOne(
+          op.replaceOne.filter,
+          op.replaceOne.replacement,
+          { upsert: op.replaceOne.upsert }
+        );
+        modifiedCount += result.modifiedCount;
+        if (result.upsertedId) {
+          upsertedIds[i] = result.upsertedId;
+          upsertedCount++;
+        }
+      }
+    }
+
+    return {
+      acknowledged: true,
+      insertedCount,
+      modifiedCount,
+      deletedCount,
+      upsertedCount,
+      insertedIds,
+      upsertedIds
+    };
+  }
+
+  async findOneAndUpdate(query, update, options = {}) {
+    await this._ensureTable();
+
+    const params = [];
+    const qualifiedName = this._qualifiedName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+
+    const selectSql = `SELECT _id, data FROM ${qualifiedName} WHERE ${whereClause} LIMIT 1`;
+    const selectResult = await this._pool.query(selectSql, params);
+
+    if (selectResult.rows.length === 0) {
+      if (options.upsert) {
+        let newDoc = {};
+        if (query._id) {
+          newDoc._id = query._id;
+        }
+        newDoc = applyUpdate(newDoc, update);
+        await this.insertOne(newDoc);
+        return options.returnDocument === 'after' ? newDoc : null;
+      }
+      return null;
+    }
+
+    const row = selectResult.rows[0];
+    const existing = deserializeDocument(row.data, row._id);
+    const updated = applyUpdate(existing, update);
+    const { _id, ...dataWithoutId } = updated;
+
+    await this._pool.query(
+      `UPDATE ${qualifiedName} SET data = $1 WHERE _id = $2`,
+      [ serializeDocument(dataWithoutId), selectResult.rows[0]._id ]
+    );
+
+    return options.returnDocument === 'after' ? updated : existing;
+  }
+
+  /**
+   * Create an index on one or more fields.
+   *
+   * @param {Object} keys - Fields to index,
+   *   e.g. { fieldName: 1 } or { fieldName: -1 }
+   * @param {Object} options - Index options
+   * @param {string} [options.name] - Custom index name
+   * @param {boolean} [options.unique] - Unique index
+   * @param {boolean} [options.sparse] - Sparse/partial index
+   *   (only index docs where field exists)
+   * @param {string} [options.type] - Field type for range
+   *   query optimization:
+   *   - 'number': numeric cast for $gt/$lt on numbers
+   *   - 'date': date extraction for $gt/$lt on dates
+   *   - undefined: text (for $eq, $in, $regex)
+   *
+   * IMPORTANT: The `type` option is required for
+   * PostgreSQL to efficiently use indexes on range
+   * queries ($gt, $gte, $lt, $lte). MongoDB ignores it.
+   *
+   * @example
+   * // Text/equality index (default) - efficient for $eq, $in, $regex
+   * await collection.createIndex({ slug: 1 });
+   *
+   * // Numeric index - efficient for $gt, $lt on numbers
+   * await collection.createIndex({ price: 1 }, { type: 'number' });
+   *
+   * // Date index - for $gt, $lt on dates
+   * await collection.createIndex(
+   *   { createdAt: 1 }, { type: 'date' }
+   * );
+   *
+   * // Unique sparse date index
+   * await collection.createIndex(
+   *   { publishedAt: 1 },
+   *   { type: 'date', unique: true, sparse: true }
+   * );
+   */
+  async createIndex(keys, options = {}) {
+    await this._ensureTable();
+
+    const keyEntries = Object.entries(keys);
+    const indexType = options.type; // 'number', 'date', or undefined (text)
+
+    // Helper to build JSON path expression for index
+    // (handles nested fields like 'user.name').
+    // The type parameter determines the expression
+    // for range query optimization
+    const buildIndexPath = (field, type) => {
+      const parts = field.split('.');
+
+      if (type === 'date') {
+        // Dates are stored as { $date: "ISO string" } in UTC
+        // ISO 8601 strings sort correctly as text (YYYY-MM-DDTHH:MM:SS.sssZ format)
+        // We index the raw text because timestamp casts aren't IMMUTABLE in PostgreSQL
+        let path = 'data';
+        for (const part of parts) {
+          path += `->'${escapeString(part)}'`;
+        }
+        // Extract $date text value (no cast - text sorts correctly for ISO dates)
+        return `${path}->>'$date'`;
+      }
+
+      if (type === 'number') {
+        // Build path to extract text and cast to numeric
+        let path = 'data';
+        if (parts.length === 1) {
+          path = `data->>'${escapeString(parts[0])}'`;
+        } else {
+          for (let i = 0; i < parts.length - 1; i++) {
+            path += `->'${escapeString(parts[i])}'`;
+          }
+          path += `->>'${escapeString(parts[parts.length - 1])}'`;
+        }
+        return `(${path})::numeric`;
+      }
+
+      // Default: text extraction for equality/text queries.
+      //
+      // Wrapped with COLLATE "C" to match buildJsonTextPath so that query
+      // predicates and this index expression agree on collation; otherwise
+      // the planner cannot use the index for range/equality comparisons.
+      // Byte-wise ordering also matches MongoDB's default string semantics.
+      if (parts.length === 1) {
+        return `(data->>'${escapeString(parts[0])}') COLLATE "C"`;
+      }
+      // For nested: data->'user'->>'name'
+      let path = 'data';
+      for (let i = 0; i < parts.length - 1; i++) {
+        path += `->'${escapeString(parts[i])}'`;
+      }
+      path += `->>'${escapeString(parts[parts.length - 1])}'`;
+      return `(${path}) COLLATE "C"`;
+    };
+
+    // Helper to build JSON path for existence check (returns jsonb, not text)
+    const buildIndexPathJsonb = (field) => {
+      const parts = field.split('.');
+      let path = 'data';
+      for (const part of parts) {
+        path += `->'${escapeString(part)}'`;
+      }
+      return path;
+    };
+
+    // Generate a safe index name
+    const safeFieldNames = keyEntries.map(([ k ]) => k.replace(/[^a-zA-Z0-9]/g, '_')).join('_');
+    const indexName = options.name
+      ? sanitizeIndexName(options.name)
+      : `idx_${this._tableName}_${safeFieldNames}`.substring(0, 63);
+
+    // Generate MongoDB-compatible index name for indexInformation() compatibility
+    const mongoName = options.name || keyEntries.map(([ k, v ]) => `${k}_${v}`).join('_');
+
+    // Store index metadata
+    this._indexes.set(indexName, {
+      keys,
+      options,
+      mongoName
+    });
+
+    const qualifiedName = this._qualifiedName();
+    const escapedIndexName = escapeIdentifier(indexName);
+
+    // Build WHERE clause for sparse indexes (PostgreSQL partial index)
+    let whereClause = '';
+    if (options.sparse) {
+      const sparseConditions = keyEntries.map(([ field ]) => {
+        if (field === '_id') {
+          return '_id IS NOT NULL';
+        }
+        return `${buildIndexPathJsonb(field)} IS NOT NULL`;
+      });
+      whereClause = ` WHERE ${sparseConditions.join(' AND ')}`;
+    }
+
+    // Handle text indexes (full-text search, always uses text extraction)
+    const hasTextIndex = keyEntries.some(([ , v ]) => v === 'text');
+    if (hasTextIndex) {
+      let textFields = keyEntries.filter(([ , v ]) => v === 'text').map(([ k ]) => k);
+      // MongoDB dumps store text indexes as { _fts: 'text', _ftsx: 1 }
+      // The real field names are in options.weights
+      if (textFields.length === 1 && textFields[0] === '_fts' && options.weights) {
+        textFields = Object.keys(options.weights);
+      }
+      // Store the text index fields so $text queries use them
+      this._textFields = textFields;
+      const tsvectorExpr = textFields
+        .map(f => `coalesce(${buildIndexPath(f, null)}, '')`)
+        .join(' || \' \' || ');
+
+      await this._pool.query(`
+        CREATE INDEX IF NOT EXISTS "${escapedIndexName}"
+        ON ${qualifiedName}
+        USING gin(to_tsvector('simple', ${tsvectorExpr}))${whereClause}
+      `);
+      return indexName;
+    }
+
+    // Handle unique constraint
+    if (options.unique) {
+      const indexExprs = keyEntries.map(([ field ]) => {
+        return field === '_id' ? '_id' : `(${buildIndexPath(field, indexType)})`;
+      });
+
+      await this._pool.query(`
+        CREATE UNIQUE INDEX IF NOT EXISTS "${escapedIndexName}"
+        ON ${qualifiedName} (${indexExprs.join(', ')})${whereClause}
+      `);
+      return indexName;
+    }
+
+    // Handle regular indexes (single or compound)
+    const indexExprs = keyEntries.map(([ field, direction ]) => {
+      if (field === '_id') {
+        return `_id ${direction === -1 ? 'DESC' : 'ASC'}`;
+      }
+      return `(${buildIndexPath(field, indexType)}) ${direction === -1 ? 'DESC' : 'ASC'}`;
+    });
+
+    await this._pool.query(`
+      CREATE INDEX IF NOT EXISTS "${escapedIndexName}"
+      ON ${qualifiedName} (${indexExprs.join(', ')})${whereClause}
+    `);
+
+    return indexName;
+  }
+
+  async ensureIndex(keys, options) {
+    return this.createIndex(keys, options);
+  }
+
+  async dropIndex(indexName) {
+    // Look up by MongoDB-compatible name first (in case caller uses that)
+    let pgName = null;
+    for (const [ pgKey, meta ] of this._indexes.entries()) {
+      if (meta.mongoName === indexName) {
+        pgName = pgKey;
+        break;
+      }
+    }
+    if (!pgName) {
+      // Try as a direct postgres index name. Use the same sanitizer as
+      // createIndex so a name like "slug_unique" created via createIndex
+      // can be dropped with the same string, and MongoDB-style names with
+      // illegal characters don't throw.
+      pgName = sanitizeIndexName(indexName);
+    }
+    this._indexes.delete(pgName);
+    const escapedIndexName = escapeIdentifier(pgName);
+    if (this._schema) {
+      await this._pool.query(
+        `DROP INDEX IF EXISTS "${escapeIdentifier(this._schema)}"."${escapedIndexName}"`
+      );
+    } else {
+      await this._pool.query(`DROP INDEX IF EXISTS "${escapedIndexName}"`);
+    }
+  }
+
+  async indexes() {
+    await this._ensureTable();
+
+    const schemaName = this._schema || 'public';
+    const result = await this._pool.query(`
+      SELECT indexname, indexdef
+      FROM pg_indexes
+      WHERE schemaname = $1 AND tablename = $2
+    `, [ schemaName, this._tableName ]);
+
+    const indexes = [ {
+      name: '_id_',
+      key: { _id: 1 },
+      unique: true
+    } ];
+
+    for (const row of result.rows) {
+      if (row.indexname === `${this._tableName}_pkey`) {
+        continue;
+      }
+
+      const storedIndex = this._indexes.get(row.indexname);
+      if (storedIndex) {
+        indexes.push({
+          name: storedIndex.mongoName || row.indexname,
+          key: storedIndex.keys,
+          unique: storedIndex.options.unique || false,
+          ...(storedIndex.options.sparse ? { sparse: true } : {}),
+          ...(storedIndex.options.type ? { type: storedIndex.options.type } : {})
+        });
+      } else {
+        indexes.push({
+          name: row.indexname,
+          ...parseIndexDef(row.indexdef)
+        });
+      }
+    }
+
+    return indexes;
+  }
+
+  async indexInformation() {
+    const indexes = await this.indexes();
+    const info = {};
+    for (const idx of indexes) {
+      info[idx.name] = Object.entries(idx.key).map(([ k, v ]) => [ k, v ]);
+    }
+    return info;
+  }
+
+  // Legacy MongoDB method: insert (alias for insertOne or insertMany)
+  async insert(docs) {
+    if (Array.isArray(docs)) {
+      return this.insertMany(docs);
+    }
+    return this.insertOne(docs);
+  }
+
+  initializeUnorderedBulkOp() {
+    const collection = this;
+    const operations = [];
+
+    return {
+      find(query) {
+        return {
+          updateOne(update) {
+            operations.push({
+              updateOne: {
+                filter: query,
+                update
+              }
+            });
+          },
+          update(update) {
+            operations.push({
+              updateMany: {
+                filter: query,
+                update
+              }
+            });
+          },
+          upsert() {
+            return {
+              updateOne(update) {
+                operations.push({
+                  updateOne: {
+                    filter: query,
+                    update,
+                    upsert: true
+                  }
+                });
+              },
+              update(update) {
+                operations.push({
+                  updateMany: {
+                    filter: query,
+                    update,
+                    upsert: true
+                  }
+                });
+              },
+              replaceOne(doc) {
+                operations.push({
+                  replaceOne: {
+                    filter: query,
+                    replacement: doc,
+                    upsert: true
+                  }
+                });
+              }
+            };
+          },
+          deleteOne() {
+            operations.push({ deleteOne: { filter: query } });
+          },
+          delete() {
+            operations.push({ deleteMany: { filter: query } });
+          }
+        };
+      },
+      async execute() {
+        return collection.bulkWrite(operations);
+      }
+    };
+  }
+
+  async drop() {
+    const qualifiedName = this._qualifiedName();
+    await this._pool.query(`DROP TABLE IF EXISTS ${qualifiedName}`);
+    this._initialized = false;
+    this._indexes.clear();
+  }
+
+  async rename(newName) {
+    const oldName = this._name;
+    const newCollName = validateTableName(newName);
+    const qualifiedName = this._qualifiedName();
+    const escapedNewTableName = escapeIdentifier(newCollName);
+    await this._pool.query(`ALTER TABLE ${qualifiedName} RENAME TO "${escapedNewTableName}"`);
+
+    // Update internal state
+    this._tableName = newCollName;
+    this._name = newName;
+
+    // Update the database's collection cache
+    this._db._collections.delete(oldName);
+    this._db._collections.set(newName, this);
+  }
+}
+
+// =============================================================================
+// Database Implementation
+// =============================================================================
+
+class PostgresDb {
+  constructor(client, name, schema) {
+    this._client = client;
+    this._pool = client._pool;
+    this._name = name;
+    this._schema = schema || null;
+    this._multiSchema = client._multiSchema || false;
+    this.databaseName = name;
+    this._collections = new Map();
+  }
+
+  collection(name) {
+    if (!this._collections.has(name)) {
+      this._collections.set(name, new PostgresCollection(this, name));
+    }
+    return this._collections.get(name);
+  }
+
+  async createCollection(name) {
+    const col = this.collection(name);
+    await col._ensureTable();
+    return col;
+  }
+
+  admin() {
+    const pool = this._pool;
+    const multiSchema = this._multiSchema;
+    const name = this._name;
+    const realDb = this._client._realDb;
+    return {
+      async listDatabases() {
+        if (multiSchema) {
+          // List all non-system schemas as virtual "databases",
+          // prefixed with the real PostgreSQL database name
+          const result = await pool.query(`
+            SELECT schema_name FROM information_schema.schemata
+            WHERE schema_name NOT IN ('public', 'information_schema', 'pg_catalog', 'pg_toast')
+            AND schema_name NOT LIKE 'pg_%'
+          `);
+          const databases = result.rows.map(row => ({
+            name: realDb + '-' + row.schema_name
+          }));
+          return { databases };
+        }
+        // Simple mode: just return this database
+        return { databases: [ { name } ] };
+      }
+    };
+  }
+
+  async dropDatabase() {
+    if (!this._name) {
+      return;
+    }
+    if (this._multiSchema && this._schema) {
+      // Multi-schema mode: drop the schema
+      await this._pool.query(
+        `DROP SCHEMA IF EXISTS "${escapeIdentifier(this._schema)}" CASCADE`
+      );
+    } else {
+      // Simple mode: drop all tables in public schema
+      const result = await this._pool.query(
+        'SELECT tablename FROM pg_tables WHERE schemaname = \'public\''
+      );
+      for (const row of result.rows) {
+        await this._pool.query(
+          `DROP TABLE IF EXISTS "${escapeIdentifier(row.tablename)}" CASCADE`
+        );
+      }
+    }
+    this._collections.clear();
+  }
+
+  async collections() {
+    const list = await this.listCollections().toArray();
+    return list.map(entry => this.collection(entry.name));
+  }
+
+  listCollections() {
+    const self = this;
+    const schemaName = this._schema || 'public';
+    return {
+      async toArray() {
+        const result = await self._pool.query(`
+          SELECT tablename as name
+          FROM pg_tables
+          WHERE schemaname = $1
+        `, [ schemaName ]);
+        return result.rows.map(row => ({
+          name: row.name
+        }));
+      }
+    };
+  }
+}
+
+// =============================================================================
+// Client Implementation
+// =============================================================================
+
+class PostgresClient {
+  constructor(pool, defaultDb, uri, options) {
+    this._pool = pool;
+    this._defaultDb = defaultDb;
+    this._uri = uri;
+    this._options = options;
+    this._multiSchema = options._multiSchema || false;
+    this._defaultSchema = options._defaultSchema || null;
+    this._realDb = options._realDb || null;
+    this._databases = new Map();
+  }
+
+  db(name) {
+    if (!this._multiSchema) {
+      // Simple mode: only the database from the connection URI is allowed.
+      if (name && name !== this._defaultDb) {
+        throw new Error(
+          `Cannot switch to database "${name}" in simple postgres:// mode.\n` +
+          'All database names would share the same tables, causing data collisions.\n' +
+          'Use a multipostgres:// URI for independent per-name data (via schemas).'
+        );
+      }
+      if (!this._databases.has(this._defaultDb)) {
+        this._databases.set(this._defaultDb, new PostgresDb(this, this._defaultDb, null));
+      }
+      return this._databases.get(this._defaultDb);
+    }
+    // Multi-schema mode: the virtual database name must start with
+    // the real PostgreSQL database name followed by a hyphen.
+    // The schema is derived from what follows that prefix.
+    const dbName = name || this._defaultDb;
+    const prefix = this._realDb + '-';
+    if (!dbName.startsWith(prefix)) {
+      throw new Error(
+        `Invalid virtual database name "${dbName}": must start with "${prefix}".`
+      );
+    }
+    const schema = dbName.substring(prefix.length);
+    if (!this._databases.has(dbName)) {
+      this._databases.set(dbName, new PostgresDb(this, dbName, schema));
+    }
+    return this._databases.get(dbName);
+  }
+
+  async close() {
+    if (!this._poolEnded) {
+      this._poolEnded = true;
+      await this._pool.end();
+    }
+  }
+}
+
+// =============================================================================
+// Module Export
+// =============================================================================
+
+module.exports = {
+  name: 'postgres',
+  // Native protocol schemes for this adapter
+  protocols: [ 'postgres', 'postgresql', 'multipostgres' ],
+
+  /**
+   * Connect to PostgreSQL and return a client with MongoDB-compatible interface.
+   *
+   * Supports two modes:
+   * - postgres:// — Simple single-database mode, unprefixed tables in public schema
+   * - multipostgres:// — Multi-schema mode for multisite.
+   *   URI: multipostgres://host/realdb-schemaname
+   *   Last hyphen-separated component is the default schema,
+   *   everything before is the real PostgreSQL database name.
+   *
+   * @param {string} uri - Connection URI
+   * @param {Object} [options={}] - Additional pg Pool options
+   * @returns {Promise<PostgresClient>} Client with db(), close() methods
+   */
+  async connect(uri, options = {}) {
+    const url = new URL(uri);
+    let database;
+    let multiSchema = false;
+    let defaultSchema = null;
+    let realDb = null;
+    let connectionUri = uri;
+
+    if (url.protocol === 'multipostgres:') {
+      // Multi-schema mode: multipostgres://host/realdb-schemaname
+      // The full path is the virtual "database name" (like MongoDB's database name).
+      // The real PostgreSQL database is everything before the last hyphen.
+      // The default schema is everything after the last hyphen.
+      multiSchema = true;
+      const path = url.pathname.slice(1); // e.g. 'shared-db-dashboard'
+      const lastHyphen = path.lastIndexOf('-');
+      if (lastHyphen === -1) {
+        throw new Error(
+          'multipostgres:// URI must contain at least one hyphen in the path: ' +
+          'multipostgres://host/realdb-schemaname'
+        );
+      }
+      realDb = path.substring(0, lastHyphen);
+      defaultSchema = path.substring(lastHyphen + 1);
+      // The virtual database name is the full path, matching MongoDB conventions
+      database = path;
+
+      // Rewrite URI to postgres:// for the actual pg Pool connection
+      const connUrl = new URL(uri);
+      connUrl.protocol = 'postgres:';
+      connUrl.pathname = '/' + realDb;
+      connectionUri = connUrl.toString();
+    } else {
+      // Simple single-database mode
+      database = url.pathname.slice(1) || undefined;
+    }
+
+    let pool = new Pool({
+      connectionString: connectionUri,
+      ...options
+    });
+
+    // Test connection, creating the database if it doesn't exist
+    // (matching MongoDB's implicit database creation behavior)
+    try {
+      await pool.query('SELECT 1');
+    } catch (e) {
+      // 3D000 = invalid_catalog_name (database does not exist)
+      const pgDatabase = new URL(connectionUri).pathname.slice(1);
+      if (e.code === '3D000' && pgDatabase) {
+        await pool.end();
+        // Connect to the default 'postgres' database to create the target
+        const adminUrl = new URL(connectionUri);
+        adminUrl.pathname = '/postgres';
+        const adminPool = new Pool({
+          connectionString: adminUrl.toString(),
+          ...options
+        });
+        try {
+          await adminPool.query(`CREATE DATABASE "${escapeIdentifier(pgDatabase)}"`);
+        } catch (createErr) {
+          // 42P04 = duplicate_database (another process just created it, that's fine)
+          if (createErr.code !== '42P04') {
+            throw createErr;
+          }
+        } finally {
+          await adminPool.end();
+        }
+        // Reconnect to the now-existing database
+        pool = new Pool({
+          connectionString: connectionUri,
+          ...options
+        });
+        await pool.query('SELECT 1');
+      } else {
+        throw e;
+      }
+    }
+
+    return new PostgresClient(pool, database, uri, {
+      ...options,
+      _multiSchema: multiSchema,
+      _defaultSchema: defaultSchema,
+      _realDb: realDb
+    });
+  },
+  profileReport,
+  profileReset
+};
diff --git a/packages/db-connect/adapters/sqlite.js b/packages/db-connect/adapters/sqlite.js
new file mode 100644
index 0000000000..dbece06df6
--- /dev/null
+++ b/packages/db-connect/adapters/sqlite.js
@@ -0,0 +1,2398 @@
+// SQLite Adapter for MongoDB-compatible interface
+// Stores documents as JSON text with _id as primary key
+// Uses better-sqlite3 for synchronous, high-performance SQLite access
+
+const Database = require('better-sqlite3');
+const crypto = require('crypto');
+const path = require('path');
+const fs = require('fs');
+const {
+  serializeValue,
+  serializeDocument,
+  deserializeDocument,
+  getNestedField,
+  setNestedField,
+  deepEqual,
+  applyProjection,
+  applyUpdate,
+  extractAnchoredLiteralPrefix,
+  prefixUpperBound,
+  validateInteger
+} = require('../lib/shared');
+const { AggregationCursor } = require('../lib/aggregation-cursor');
+
+// =============================================================================
+// SECURITY: Input Validation and Escaping
+// =============================================================================
+
+const SAFE_IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+function validateTableName(name) {
+  if (typeof name !== 'string' || name.length === 0 || name.length > 63) {
+    throw new Error('Invalid table name: must be a non-empty string up to 63 characters');
+  }
+  const sanitized = name.replace(/-/g, '_');
+  if (!SAFE_IDENTIFIER_PATTERN.test(sanitized)) {
+    throw new Error(`Invalid table name: "${name}" contains disallowed characters`);
+  }
+  return sanitized;
+}
+
+// Sanitize a caller-supplied index name so it is safe to use as a SQLite
+// identifier. Unlike validateTableName() (which rejects unsafe input as a
+// security measure against malicious table names), index names frequently
+// arrive from cross-backend JSONL dumps — MongoDB's default/auto-generated
+// index names contain characters like "." that are illegal SQLite
+// identifiers. Silently replacing those characters with "_" is safe: the
+// name is an internal identifier, not user data, and the adapter is the
+// one consulting the _indexes map by the sanitized form.
+function sanitizeIndexName(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    return null;
+  }
+  const truncated = name.substring(0, 63);
+  const sanitized = truncated.replace(/[^a-zA-Z0-9_]/g, '_');
+  // Identifiers must start with a letter or underscore.
+  if (/^[0-9]/.test(sanitized)) {
+    return '_' + sanitized.substring(0, 62);
+  }
+  return sanitized;
+}
+
+function escapeIdentifier(name) {
+  return name.replace(/"/g, '""');
+}
+
+function escapeString(str) {
+  return str.replace(/'/g, '\'\'');
+}
+
+// Convert a dot-path like "body.items.0.sublabel" to a SQLite JSON path
+// like "$.body.items[0].sublabel". Numeric segments become array indices.
+function toJsonPath(dotPath) {
+  return '$.' + dotPath.split('.').map(p =>
+    /^\d+$/.test(p) ? `[${p}]` : escapeString(p)
+  ).join('.').replace(/\.\[/g, '[');
+}
+
+// Generate a MongoDB-style ObjectId-like string
+function generateId() {
+  return crypto.randomBytes(12).toString('hex');
+}
+
+// =============================================================================
+// SQLite Duplicate Key Error
+// =============================================================================
+
+function makeDuplicateKeyError(sqliteError, collection, doc) {
+  const message = 'Duplicate key error: already exists';
+  const error = new Error(message);
+  error.code = 11000;
+  if (sqliteError.message) {
+    // For _id primary key: "UNIQUE constraint failed: tablename._id"
+    const colMatch = sqliteError.message.match(/UNIQUE constraint failed:\s*\S+\.(\S+)/);
+    if (colMatch && colMatch[1] === '_id') {
+      error.keyValue = { _id: doc ? doc._id : null };
+    }
+    // For expression indexes: "UNIQUE constraint failed: index 'indexname'"
+    const idxMatch = sqliteError.message.match(/UNIQUE constraint failed:\s*index '([^']+)'/);
+    if (idxMatch && collection && collection._indexes) {
+      const indexMeta = collection._indexes.get(idxMatch[1]);
+      if (indexMeta && indexMeta.keys) {
+        error.keyValue = {};
+        for (const field of Object.keys(indexMeta.keys)) {
+          error.keyValue[field] = doc ? getNestedField(doc, field) : null;
+        }
+      }
+    }
+  }
+  return error;
+}
+
+// =============================================================================
+// Query Building for SQLite
+// =============================================================================
+
+// Build a json_extract path for a field: json_extract(data, '$.field.nested')
+function buildJsonExtractPath(field) {
+  const parts = field.split('.');
+  let path = '$';
+  for (const p of parts) {
+    if (/^\d+$/.test(p)) {
+      // Array index — no dot before bracket notation
+      path += `[${p}]`;
+    } else {
+      path += `.${p.replace(/'/g, '\'\'')}`;
+    }
+  }
+  return `'${path}'`;
+}
+
+// Build full json_extract expression
+function buildJsonExtract(field, prefix = 'data') {
+  return `json_extract(${prefix}, ${buildJsonExtractPath(field)})`;
+}
+
+/**
+ * Convert a MongoDB query object to a SQLite WHERE clause.
+ *
+ * MUTATES `params` by pushing values for parameterized query placeholders.
+ * The returned SQL string contains ? placeholders.
+ */
+// Build a SQL condition matching `textExpr` against `regex`.
+//
+// When the regex is anchored and begins with a literal prefix, emit
+// `textExpr >= ? AND textExpr < upper(?) AND regexp(?, textExpr)`. The
+// range predicate is btree-indexable on any expression index over
+// `textExpr`; the residual regex call preserves correctness for any
+// trailing pattern. MUTATES `params`.
+function buildRegexMatchSql(textExpr, regex, params) {
+  const regexpFn = regex.ignoreCase ? 'regexp_i' : 'regexp';
+  const { prefix } = extractAnchoredLiteralPrefix(regex);
+  const parts = [];
+  if (prefix) {
+    params.push(prefix);
+    parts.push(`${textExpr} >= ?`);
+    const upper = prefixUpperBound(prefix);
+    if (upper !== null) {
+      params.push(upper);
+      parts.push(`${textExpr} < ?`);
+    }
+  }
+  params.push(regex.source);
+  parts.push(`${regexpFn}(?, ${textExpr})`);
+  return parts.length > 1 ? `(${parts.join(' AND ')})` : parts[0];
+}
+
+function buildWhereClause(query, params, prefix = 'data', options = {}) {
+  const conditions = [];
+
+  for (const [ key, value ] of Object.entries(query || {})) {
+    if (key === '$and') {
+      if (!Array.isArray(value)) {
+        throw new Error('$and must be an array');
+      }
+      const andConditions = value.map(subQuery => {
+        const subClause = buildWhereClause(subQuery, params, prefix, options);
+        return `(${subClause})`;
+      });
+      conditions.push(`(${andConditions.join(' AND ')})`);
+    } else if (key === '$or') {
+      if (!Array.isArray(value)) {
+        throw new Error('$or must be an array');
+      }
+      const orConditions = value.map(subQuery => {
+        const subClause = buildWhereClause(subQuery, params, prefix, options);
+        return `(${subClause})`;
+      });
+      conditions.push(`(${orConditions.join(' OR ')})`);
+    } else if (key === '$text') {
+      const searchTerm = value.$search;
+      if (typeof searchTerm !== 'string') {
+        throw new Error('$text.$search must be a string');
+      }
+      const words = searchTerm.trim().split(/\s+/).filter(w => w.length > 0);
+      if (words.length === 0) {
+        conditions.push('0');
+      } else if (options.ftsTable) {
+        // FTS5 search: match against the virtual table by rowid
+        // FTS5 query: OR the words together for MongoDB-compatible semantics
+        const ftsQuery = words.map(w => `"${w.replace(/"/g, '""')}"`).join(' OR ');
+        params.push(ftsQuery);
+        const rowidRef = options.mainTable ? `${options.mainTable}.rowid` : 'rowid';
+        conditions.push(
+          `${rowidRef} IN (SELECT rowid FROM ${options.ftsTable} WHERE ${options.ftsTable} MATCH ?)`
+        );
+      } else {
+        // Fallback LIKE-based search when no FTS5 table exists
+        const fieldNames = options.textFields || [
+          'highSearchText', 'lowSearchText', 'title', 'searchBoost'
+        ];
+        const textFields = fieldNames.map(f => {
+          const jsonPath = '$.' + f.split('.').map(p => escapeString(p)).join('.');
+          return `COALESCE(json_extract(${prefix}, '${jsonPath}'), '')`;
+        });
+        const textExpr = textFields.join(' || \' \' || ');
+        const wordConditions = words.map(w => {
+          params.push(`%${w}%`);
+          return `(${textExpr}) LIKE ?`;
+        });
+        conditions.push(`(${wordConditions.join(' OR ')})`);
+      }
+    } else if (key === '_id') {
+      if (value instanceof RegExp) {
+        conditions.push(buildRegexMatchSql('_id', value, params));
+      } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        conditions.push(buildOperatorClause('_id', value, params, true));
+      } else {
+        params.push(value);
+        conditions.push('_id = ?');
+      }
+    } else if (key.startsWith('$')) {
+      throw new Error(`Unsupported top-level operator: ${key}`);
+    } else if (typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date) && !(value instanceof RegExp)) {
+      const keys = Object.keys(value);
+      if (keys.some(k => k.startsWith('$'))) {
+        conditions.push(buildOperatorClause(key, value, params, false));
+      } else {
+        // Nested object equality
+        params.push(JSON.stringify(value));
+        conditions.push(`json_extract(${prefix}, '$.${escapeString(key)}') = ?`);
+      }
+    } else if (value instanceof RegExp) {
+      const jsonExtract = buildJsonExtract(key, prefix);
+      // Scalar match uses the indexable range + residual regex rewrite.
+      const scalarMatch = buildRegexMatchSql(jsonExtract, value, params);
+      // Array-element fallback (regex only — no per-element index to exploit).
+      const regexpFn = value.ignoreCase ? 'regexp_i' : 'regexp';
+      params.push(value.source);
+      const arrayMatch = `(json_type(${prefix}, ${buildJsonExtractPath(key)}) = 'array' AND EXISTS(SELECT 1 FROM json_each(${jsonExtract}) WHERE ${regexpFn}(?, value)))`;
+      conditions.push(`(${scalarMatch} OR ${arrayMatch})`);
+    } else if (value === null || value === undefined) {
+      // MongoDB: { field: null } and { field: undefined } both match
+      // explicit null AND missing field
+      const jsonExtract = buildJsonExtract(key, prefix);
+      conditions.push(`(${jsonExtract} IS NULL OR json_type(${prefix}, ${buildJsonExtractPath(key)}) = 'null')`);
+    } else {
+      // Simple equality: handle both scalar equality AND array-contains-scalar
+      const jsonExtract = buildJsonExtract(key, prefix);
+      const serialized = serializeValue(value);
+      if (typeof serialized === 'boolean') {
+        // SQLite json_extract returns 1/0 for boolean
+        const boolVal = serialized ? 1 : 0;
+        params.push(boolVal);
+        params.push(JSON.stringify(serialized));
+        conditions.push(`(${jsonExtract} = ? OR (json_type(${prefix}, ${buildJsonExtractPath(key)}) = 'array' AND EXISTS(SELECT 1 FROM json_each(${jsonExtract}) WHERE value = ?)))`);
+      } else if (typeof serialized === 'object' && serialized !== null) {
+        // Date or nested object
+        params.push(JSON.stringify(serialized));
+        params.push(JSON.stringify(serialized));
+        conditions.push(`(json(${jsonExtract}) = json(?) OR (json_type(${prefix}, ${buildJsonExtractPath(key)}) = 'array' AND EXISTS(SELECT 1 FROM json_each(${jsonExtract}) WHERE json(value) = json(?))))`);
+      } else {
+        params.push(serialized);
+        params.push(serialized);
+        conditions.push(`(${jsonExtract} = ? OR (json_type(${prefix}, ${buildJsonExtractPath(key)}) = 'array' AND EXISTS(SELECT 1 FROM json_each(${jsonExtract}) WHERE value = ?)))`);
+      }
+    }
+  }
+
+  return conditions.length > 0 ? conditions.join(' AND ') : '1';
+}
+
+/**
+ * Build SQL conditions for MongoDB query operators.
+ */
+function buildOperatorClause(field, operators, params, isIdField = false) {
+  const conditions = [];
+
+  const jsonExtract = isIdField ? '_id' : buildJsonExtract(field);
+  const jsonExtractPath = isIdField ? null : buildJsonExtractPath(field);
+
+  for (const [ op, opValue ] of Object.entries(operators)) {
+    switch (op) {
+      case '$eq':
+        if (isIdField) {
+          if (opValue === null || opValue === undefined) {
+            conditions.push('_id IS NULL');
+          } else {
+            params.push(opValue);
+            conditions.push('_id = ?');
+          }
+        } else {
+          const serialized = serializeValue(opValue);
+          if (serialized === null || serialized === undefined) {
+            // SQL: = NULL is always false, must use IS NULL
+            conditions.push(`(${jsonExtract} IS NULL OR json_type(data, ${jsonExtractPath}) = 'null')`);
+          } else if (typeof serialized === 'object' && serialized !== null) {
+            params.push(JSON.stringify(serialized));
+            conditions.push(`json(${jsonExtract}) = json(?)`);
+          } else if (typeof serialized === 'boolean') {
+            params.push(serialized ? 1 : 0);
+            conditions.push(`${jsonExtract} = ?`);
+          } else {
+            params.push(serialized);
+            conditions.push(`${jsonExtract} = ?`);
+          }
+        }
+        break;
+
+      case '$ne':
+        if (isIdField) {
+          if (opValue === null || opValue === undefined) {
+            conditions.push('_id IS NOT NULL');
+          } else {
+            params.push(opValue);
+            conditions.push('(_id IS NULL OR _id != ?)');
+          }
+        } else {
+          const serialized = serializeValue(opValue);
+          if (serialized === null || serialized === undefined) {
+            // $ne: null means "field exists and is not null"
+            // SQL: != NULL is always false, must use IS NOT NULL
+            conditions.push(`(${jsonExtract} IS NOT NULL AND json_type(data, ${jsonExtractPath}) != 'null')`);
+          } else if (typeof serialized === 'object' && serialized !== null) {
+            params.push(JSON.stringify(serialized));
+            conditions.push(`(${jsonExtract} IS NULL OR json(${jsonExtract}) != json(?))`);
+          } else if (typeof serialized === 'boolean') {
+            params.push(serialized ? 1 : 0);
+            conditions.push(`(${jsonExtract} IS NULL OR ${jsonExtract} != ?)`);
+          } else {
+            params.push(serialized);
+            conditions.push(`(${jsonExtract} IS NULL OR ${jsonExtract} != ?)`);
+          }
+        }
+        break;
+
+      case '$gt':
+        if (isIdField) {
+          params.push(opValue);
+          conditions.push('_id > ?');
+        } else if (opValue instanceof Date) {
+          params.push(opValue.toISOString());
+          conditions.push(`json_extract(data, '$.${escapeString(field)}.$date') > ?`);
+        } else if (typeof opValue === 'string') {
+          params.push(opValue);
+          conditions.push(`${jsonExtract} > ?`);
+        } else {
+          params.push(opValue);
+          conditions.push(`CAST(${jsonExtract} AS NUMERIC) > ?`);
+        }
+        break;
+
+      case '$gte':
+        if (isIdField) {
+          params.push(opValue);
+          conditions.push('_id >= ?');
+        } else if (opValue instanceof Date) {
+          params.push(opValue.toISOString());
+          conditions.push(`json_extract(data, '$.${escapeString(field)}.$date') >= ?`);
+        } else if (typeof opValue === 'string') {
+          params.push(opValue);
+          conditions.push(`${jsonExtract} >= ?`);
+        } else {
+          params.push(opValue);
+          conditions.push(`CAST(${jsonExtract} AS NUMERIC) >= ?`);
+        }
+        break;
+
+      case '$lt':
+        if (isIdField) {
+          params.push(opValue);
+          conditions.push('_id < ?');
+        } else if (opValue instanceof Date) {
+          params.push(opValue.toISOString());
+          conditions.push(`json_extract(data, '$.${escapeString(field)}.$date') < ?`);
+        } else if (typeof opValue === 'string') {
+          params.push(opValue);
+          conditions.push(`${jsonExtract} < ?`);
+        } else {
+          params.push(opValue);
+          conditions.push(`CAST(${jsonExtract} AS NUMERIC) < ?`);
+        }
+        break;
+
+      case '$lte':
+        if (isIdField) {
+          params.push(opValue);
+          conditions.push('_id <= ?');
+        } else if (opValue instanceof Date) {
+          params.push(opValue.toISOString());
+          conditions.push(`json_extract(data, '$.${escapeString(field)}.$date') <= ?`);
+        } else if (typeof opValue === 'string') {
+          params.push(opValue);
+          conditions.push(`${jsonExtract} <= ?`);
+        } else {
+          params.push(opValue);
+          conditions.push(`CAST(${jsonExtract} AS NUMERIC) <= ?`);
+        }
+        break;
+
+      case '$in':
+        if (!Array.isArray(opValue)) {
+          throw new Error('$in requires an array');
+        }
+        if (opValue.length === 0) {
+          conditions.push('0');
+        } else if (isIdField) {
+          const placeholders = opValue.map(v => {
+            params.push(v);
+            return '?';
+          });
+          conditions.push(`_id IN (${placeholders.join(', ')})`);
+        } else {
+          const hasNull = opValue.includes(null);
+          const regexValues = opValue.filter(v => v instanceof RegExp);
+          const nonNullValues = opValue.filter(v => v !== null && !(v instanceof RegExp));
+          const parts = [];
+          if (nonNullValues.length > 0) {
+            // For each value, check if the field equals it
+            // OR (if field is array) contains it
+            const valueParts = nonNullValues.map(v => {
+              const serialized = serializeValue(v);
+              if (typeof serialized === 'boolean') {
+                params.push(serialized ? 1 : 0);
+                return `${jsonExtract} = ?`;
+              } else if (typeof serialized === 'object' && serialized !== null) {
+                params.push(JSON.stringify(serialized));
+                return `json(${jsonExtract}) = json(?)`;
+              } else {
+                params.push(serialized);
+                return `${jsonExtract} = ?`;
+              }
+            });
+            // Also check if field is an array containing any of the values
+            const arrayParts = nonNullValues.map(v => {
+              const serialized = serializeValue(v);
+              if (typeof serialized === 'boolean') {
+                params.push(serialized ? 1 : 0);
+                return `EXISTS(SELECT 1 FROM json_each(${jsonExtract}) WHERE value = ?)`;
+              } else if (typeof serialized === 'object' && serialized !== null) {
+                params.push(JSON.stringify(serialized));
+                return `EXISTS(SELECT 1 FROM json_each(${jsonExtract}) WHERE json(value) = json(?))`;
+              } else {
+                params.push(serialized);
+                return `EXISTS(SELECT 1 FROM json_each(${jsonExtract}) WHERE value = ?)`;
+              }
+            });
+            parts.push(`(${valueParts.join(' OR ')} OR (json_type(data, ${jsonExtractPath}) = 'array' AND (${arrayParts.join(' OR ')})))`);
+          }
+          if (hasNull) {
+            parts.push(`(${jsonExtract} IS NULL OR json_type(data, ${jsonExtractPath}) = 'null')`);
+          }
+          // MongoDB supports RegExp values inside $in for pattern matching
+          for (const regex of regexValues) {
+            parts.push(buildRegexMatchSql(jsonExtract, regex, params));
+          }
+          conditions.push(parts.length > 1 ? `(${parts.join(' OR ')})` : parts[0]);
+        }
+        break;
+
+      case '$nin':
+        if (!Array.isArray(opValue)) {
+          throw new Error('$nin requires an array');
+        }
+        if (opValue.length === 0) {
+          conditions.push('1');
+        } else if (isIdField) {
+          const placeholders = opValue.map(v => {
+            params.push(v);
+            return '?';
+          });
+          conditions.push(`(_id IS NULL OR _id NOT IN (${placeholders.join(', ')}))`);
+        } else {
+          const hasNull = opValue.includes(null);
+          const nonNullValues = opValue.filter(v => v !== null);
+          const parts = [];
+          if (nonNullValues.length > 0) {
+            const valueParts = nonNullValues.map(v => {
+              const serialized = serializeValue(v);
+              if (typeof serialized === 'boolean') {
+                params.push(serialized ? 1 : 0);
+                return `${jsonExtract} != ?`;
+              } else if (typeof serialized === 'object' && serialized !== null) {
+                params.push(JSON.stringify(serialized));
+                return `json(${jsonExtract}) != json(?)`;
+              } else {
+                params.push(serialized);
+                return `${jsonExtract} != ?`;
+              }
+            });
+            parts.push(`(${jsonExtract} IS NULL OR (${valueParts.join(' AND ')}))`);
+          }
+          if (hasNull) {
+            parts.push(`(${jsonExtract} IS NOT NULL AND json_type(data, ${jsonExtractPath}) != 'null')`);
+          } else if (nonNullValues.length === 0) {
+            parts.push(`${jsonExtract} IS NULL`);
+          }
+          conditions.push(`(${parts.join(hasNull ? ' AND ' : ' OR ')})`);
+        }
+        break;
+
+      case '$exists':
+        if (isIdField) {
+          conditions.push(opValue ? '_id IS NOT NULL' : '_id IS NULL');
+        } else {
+          if (opValue) {
+            // $exists: true — field must be present in the JSON (even if null)
+            conditions.push(`json_type(data, ${jsonExtractPath}) IS NOT NULL`);
+          } else {
+            // $exists: false — field must be absent from the JSON
+            conditions.push(`json_type(data, ${jsonExtractPath}) IS NULL`);
+          }
+        }
+        break;
+
+      case '$not': {
+        if (typeof opValue !== 'object' || opValue === null) {
+          throw new Error('$not requires an object');
+        }
+        const negatedClause = buildOperatorClause(
+          field, opValue, params, isIdField
+        );
+        conditions.push(`NOT (${negatedClause})`);
+        break;
+      }
+
+      case '$regex': {
+        const pattern = opValue instanceof RegExp
+          ? opValue.source
+          : String(opValue);
+        const regexOptions = operators.$options || '';
+        const caseInsensitive = regexOptions.includes('i');
+        let regex;
+        try {
+          regex = new RegExp(pattern, caseInsensitive ? 'i' : '');
+        } catch (e) {
+          // Fall back to direct emission if the pattern isn't valid
+          params.push(pattern);
+          const regexpFn = caseInsensitive ? 'regexp_i' : 'regexp';
+          conditions.push(
+            isIdField ? `${regexpFn}(?, _id)` : `${regexpFn}(?, ${jsonExtract})`
+          );
+          break;
+        }
+        conditions.push(
+          buildRegexMatchSql(isIdField ? '_id' : jsonExtract, regex, params)
+        );
+        break;
+      }
+
+      case '$options':
+        // Handled with $regex, skip
+        break;
+
+      case '$all':
+        if (!Array.isArray(opValue)) {
+          throw new Error('$all requires an array');
+        }
+        // Each value in the $all array must exist in the array field
+        for (const item of opValue) {
+          const serialized = serializeValue(item);
+          params.push(typeof serialized === 'object' && serialized !== null ? JSON.stringify(serialized) : serialized);
+          if (typeof serialized === 'boolean') {
+            conditions.push(`EXISTS(SELECT 1 FROM json_each(${jsonExtract}) WHERE value = ?)`);
+          } else if (typeof serialized === 'object' && serialized !== null) {
+            conditions.push(`EXISTS(SELECT 1 FROM json_each(${jsonExtract}) WHERE json(value) = json(?))`);
+          } else {
+            conditions.push(`EXISTS(SELECT 1 FROM json_each(${jsonExtract}) WHERE value = ?)`);
+          }
+        }
+        break;
+
+      case '$size':
+        params.push(opValue);
+        conditions.push(
+          `json_type(data, ${jsonExtractPath}) = 'array' AND json_array_length(${jsonExtract}) = ?`
+        );
+        break;
+
+      default:
+        throw new Error(`Unsupported operator: ${op}`);
+    }
+  }
+
+  return conditions.join(' AND ');
+}
+
+// Build ORDER BY clause for SQLite
+function queryHasText(query) {
+  if (!query || typeof query !== 'object' || !('$text' in query)) {
+    return false;
+  }
+  const search = query.$text && query.$text.$search;
+  if (typeof search !== 'string') {
+    return false;
+  }
+  return search.trim().split(/\s+/).filter(w => w.length > 0).length > 0;
+}
+
+function buildOrderBy(sort, options = {}) {
+  const clauses = [];
+
+  if (sort && Object.keys(sort).length > 0) {
+    for (const [ field, direction ] of Object.entries(sort)) {
+      if (direction && typeof direction === 'object' && direction.$meta === 'textScore') {
+        if (options.hasTextScore) {
+          clauses.push('_score DESC');
+        }
+        continue;
+      }
+      if (direction && typeof direction === 'object' && direction.$meta) {
+        continue;
+      }
+      if (field === '_id') {
+        clauses.push(`_id ${direction === -1 ? 'DESC' : 'ASC'}`);
+      } else {
+        const jsonExtract = buildJsonExtract(field);
+        clauses.push(`${jsonExtract} ${direction === -1 ? 'DESC' : 'ASC'}`);
+      }
+    }
+  }
+
+  // Use rowid as insertion-order tiebreaker (replaces postgres _order SERIAL).
+  // When joining with FTS5, qualify with the main table name to avoid ambiguity.
+  const rowidRef = options.mainTable ? `${options.mainTable}.rowid` : 'rowid';
+  clauses.push(`${rowidRef} ASC`);
+  return `ORDER BY ${clauses.join(', ')}`;
+}
+
+
+// =============================================================================
+// Parse SQLite index definitions from sqlite_master
+// =============================================================================
+
+function parseIndexDef(sql) {
+  if (!sql) {
+    return {
+      key: {},
+      unique: false
+    };
+  }
+  const unique = /\bUNIQUE\b/i.test(sql);
+  const sparse = /\bWHERE\b/i.test(sql);
+
+  const key = {};
+  let type;
+
+  // Extract expressions from CREATE INDEX ... ON tablename (expr1, expr2)
+  // Normalize whitespace to simplify matching across multi-line SQL
+  const normalizedSql = sql.replace(/\s+/g, ' ').trim();
+  const onMatch = normalizedSql.match(/\bON\b\s+\S+\s*\((.+)\)(?:\s+WHERE\b.*)?$/i);
+  if (!onMatch) {
+    return {
+      key: {},
+      unique,
+      ...(sparse ? { sparse: true } : {})
+    };
+  }
+
+  const exprList = onMatch[1];
+  const exprs = splitExpressions(exprList);
+
+  for (const expr of exprs) {
+    // Strip outer parentheses that SQLite adds around expression indexes.
+    // e.g. "(json_extract(data, '$.slug')) ASC" → "json_extract(data, '$.slug') ASC"
+    let trimmed = stripOuterParens(expr.trim());
+
+    if (/^_id\b/.test(trimmed)) {
+      const direction = /\bDESC\b/i.test(trimmed) ? -1 : 1;
+      key._id = direction;
+      continue;
+    }
+
+    // Numeric type: CAST(... AS NUMERIC)
+    if (/CAST\b.*\bAS\s+NUMERIC\b/i.test(trimmed)) {
+      type = 'number';
+      const fieldName = jsonExtractToFieldName(trimmed);
+      if (fieldName) {
+        const direction = /\bDESC\b/i.test(trimmed) ? -1 : 1;
+        key[fieldName] = direction;
+      }
+      continue;
+    }
+
+    // Date type: json_extract(data, '$.field.$date')
+    if (/\.\$date/i.test(trimmed)) {
+      type = 'date';
+      const fieldName = jsonExtractToFieldName(trimmed);
+      if (fieldName) {
+        const direction = /\bDESC\b/i.test(trimmed) ? -1 : 1;
+        key[fieldName] = direction;
+      }
+      continue;
+    }
+
+    // Text index (COALESCE pattern)
+    if (/\bCOALESCE\b/i.test(trimmed)) {
+      const fieldPattern = /json_extract\s*\(\s*data\s*,\s*'(\$\.[^']+)'\s*\)/gi;
+      let m;
+      while ((m = fieldPattern.exec(trimmed)) !== null) {
+        const path = m[1].replace(/^\$\./, '');
+        key[path] = 'text';
+      }
+      continue;
+    }
+
+    // Default text type: json_extract(data, '$.field')
+    const fieldName = jsonExtractToFieldName(trimmed);
+    if (fieldName) {
+      const direction = /\bDESC\b/i.test(trimmed) ? -1 : 1;
+      key[fieldName] = direction;
+    }
+  }
+
+  return {
+    key,
+    unique,
+    ...(sparse ? { sparse: true } : {}),
+    ...(type ? { type } : {})
+  };
+}
+
+// Convert a json_extract expression back to a field name
+function jsonExtractToFieldName(expr) {
+  const match = expr.match(/json_extract\s*\(\s*data\s*,\s*'(\$\.[^']+)'\s*\)/i);
+  if (!match) {
+    return null;
+  }
+  let path = match[1].replace(/^\$\./, '');
+  // Remove .$date suffix for date indexes
+  path = path.replace(/\.\$date$/, '');
+  return path || null;
+}
+
+// Strip one layer of outer parentheses from an expression, preserving
+// any trailing ASC/DESC. SQLite wraps expression-index columns in
+// extra parens, e.g. "(json_extract(data, '$.slug')) ASC".
+function stripOuterParens(str) {
+  if (!str.startsWith('(')) {
+    return str;
+  }
+  let depth = 0;
+  for (let i = 0; i < str.length; i++) {
+    if (str[i] === '(') {
+      depth++;
+    } else if (str[i] === ')') {
+      depth--;
+      if (depth === 0) {
+        const rest = str.slice(i + 1).trim();
+        if (i > 0 && (/^(ASC|DESC)?$/i.test(rest))) {
+          return str.slice(1, i) + (rest ? ' ' + rest : '');
+        }
+        return str;
+      }
+    }
+  }
+  return str;
+}
+
+function splitExpressions(str) {
+  const results = [];
+  let depth = 0;
+  let current = '';
+  for (const ch of str) {
+    if (ch === '(') {
+      depth++;
+    } else if (ch === ')') {
+      depth--;
+    }
+    if (ch === ',' && depth === 0) {
+      results.push(current);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) {
+    results.push(current);
+  }
+  return results;
+}
+
+// =============================================================================
+// Cursor Implementation
+// =============================================================================
+
+class SqliteCursor {
+  constructor(collection, query, options = {}) {
+    this._collection = collection;
+    this._query = query;
+    this._projection = options.projection || null;
+    this._sort = null;
+    this._limit = null;
+    this._skip = null;
+    this._iterator = null;
+    this._exhausted = false;
+  }
+
+  project(projection) {
+    this._projection = projection;
+    return this;
+  }
+
+  sort(sort) {
+    this._sort = sort;
+    return this;
+  }
+
+  limit(n) {
+    const val = validateInteger(n, 'limit');
+    this._limit = val === 0 ? null : val;
+    return this;
+  }
+
+  skip(n) {
+    this._skip = validateInteger(n, 'skip');
+    return this;
+  }
+
+  clone() {
+    const cloned = new SqliteCursor(this._collection, this._query);
+    cloned._projection = this._projection;
+    cloned._sort = this._sort;
+    cloned._limit = this._limit;
+    cloned._skip = this._skip;
+    return cloned;
+  }
+
+  // Build the SELECT SQL + params this cursor would execute. Shared by
+  // toArray() and exposed via explain() for EXPLAIN-based tests and
+  // debugging. SQL uses SQLite's native `?` placeholders; `params` is a
+  // positional array in order.
+  _buildFindSql() {
+    const params = [];
+    const queryOptions = this._collection._queryOptions();
+    const tableName = this._collection._quotedTableName();
+    const whereClause = buildWhereClause(this._query, params, 'data', queryOptions);
+    const hasText = queryHasText(this._query) && queryOptions.ftsTable;
+    const orderBy = buildOrderBy(this._sort, {
+      hasTextScore: hasText,
+      mainTable: hasText ? tableName : null
+    });
+
+    let selectCols = `${tableName}._id, ${tableName}.data`;
+    let sql;
+    if (hasText) {
+      // Build WHERE from query without $text (the FTS JOIN handles text matching)
+      const nonTextQuery = { ...this._query };
+      delete nonTextQuery.$text;
+      const nonTextParams = [];
+      const nonTextWhere = buildWhereClause(nonTextQuery, nonTextParams, 'data', queryOptions);
+
+      const words = this._query.$text.$search.trim().split(/\s+/).filter(w => w.length > 0);
+      const ftsQuery = words.map(w => `"${w.replace(/"/g, '""')}"`).join(' OR ');
+
+      // bm25() returns negative values (lower = better), so negate for
+      // higher = better, matching MongoDB/PostgreSQL conventions
+      selectCols += `, -bm25(${queryOptions.ftsTable}) AS _score`;
+
+      sql = `SELECT ${selectCols} FROM ${tableName} JOIN ${queryOptions.ftsTable} ON ${tableName}.rowid = ${queryOptions.ftsTable}.rowid WHERE ${queryOptions.ftsTable} MATCH ? AND ${nonTextWhere} ${orderBy}`;
+      // Replace params with: ftsQuery first, then nonTextParams
+      params.length = 0;
+      params.push(ftsQuery, ...nonTextParams);
+    } else {
+      sql = `SELECT ${selectCols} FROM ${tableName} WHERE ${whereClause} ${orderBy}`;
+    }
+
+    if (this._limit != null) {
+      sql += ` LIMIT ${this._limit}`;
+    } else if (this._skip != null) {
+      sql += ' LIMIT -1';
+    }
+    if (this._skip != null) {
+      sql += ` OFFSET ${this._skip}`;
+    }
+    return {
+      sql,
+      params
+    };
+  }
+
+  // Returns the SQL and parameter values the adapter would execute for
+  // this cursor's current query/sort/limit/skip/projection. Useful for
+  // EXPLAIN-based tests and for debugging query planner behavior. The
+  // returned SQL uses SQLite's native `?` placeholder style.
+  async explain() {
+    this._collection._ensureTable();
+    return this._buildFindSql();
+  }
+
+  async toArray() {
+    this._collection._ensureTable();
+
+    const { sql, params } = this._buildFindSql();
+    const rows = this._collection._db._sqlite.prepare(sql).all(...params);
+    return rows.map(row => {
+      const doc = deserializeDocument(row.data, row._id);
+      const meta = row._score != null ? { textScore: row._score } : {};
+      return this._projection ? applyProjection(doc, this._projection, meta) : doc;
+    });
+  }
+
+  next(callback) {
+    const promise = this._next();
+    if (callback) {
+      promise.then(doc => callback(null, doc), err => callback(err));
+      return;
+    }
+    return promise;
+  }
+
+  async _next() {
+    if (this._exhausted) {
+      return null;
+    }
+    // Buffer all results on first call to avoid holding the database busy.
+    // better-sqlite3 is synchronous and an active .iterate() cursor blocks
+    // all other queries on the same connection.
+    if (!this._buffer) {
+      this._collection._ensureTable();
+
+      const params = [];
+      const queryOptions = this._collection._queryOptions();
+      const tableName = this._collection._quotedTableName();
+      const whereClause = buildWhereClause(this._query, params, 'data', queryOptions);
+      const hasText = queryHasText(this._query) && queryOptions.ftsTable;
+      const orderBy = buildOrderBy(this._sort, {
+        hasTextScore: hasText,
+        mainTable: hasText ? tableName : null
+      });
+
+      let selectCols = `${tableName}._id, ${tableName}.data`;
+      let sql;
+      if (hasText) {
+        const nonTextQuery = { ...this._query };
+        delete nonTextQuery.$text;
+        const nonTextParams = [];
+        const nonTextWhere = buildWhereClause(nonTextQuery, nonTextParams, 'data', queryOptions);
+
+        const words = this._query.$text.$search.trim().split(/\s+/).filter(w => w.length > 0);
+        const ftsQuery = words.map(w => `"${w.replace(/"/g, '""')}"`).join(' OR ');
+
+        selectCols += `, -bm25(${queryOptions.ftsTable}) AS _score`;
+        sql = `SELECT ${selectCols} FROM ${tableName} JOIN ${queryOptions.ftsTable} ON ${tableName}.rowid = ${queryOptions.ftsTable}.rowid WHERE ${queryOptions.ftsTable} MATCH ? AND ${nonTextWhere} ${orderBy}`;
+        params.length = 0;
+        params.push(ftsQuery, ...nonTextParams);
+      } else {
+        sql = `SELECT ${selectCols} FROM ${tableName} WHERE ${whereClause} ${orderBy}`;
+      }
+
+      if (this._limit != null) {
+        sql += ` LIMIT ${this._limit}`;
+      } else if (this._skip != null) {
+        sql += ' LIMIT -1';
+      }
+      if (this._skip != null) {
+        sql += ` OFFSET ${this._skip}`;
+      }
+
+      this._buffer = this._collection._db._sqlite.prepare(sql).all(...params);
+      this._bufferIndex = 0;
+    }
+
+    if (this._bufferIndex >= this._buffer.length) {
+      this._exhausted = true;
+      this._buffer = null;
+      return null;
+    }
+
+    const row = this._buffer[this._bufferIndex++];
+    const doc = deserializeDocument(row.data, row._id);
+    const meta = row._score != null ? { textScore: row._score } : {};
+    return this._projection ? applyProjection(doc, this._projection, meta) : doc;
+  }
+
+  async hasNext() {
+    if (this._exhausted) {
+      return false;
+    }
+    if (!this._buffer) {
+      // Force buffering by calling _next logic without consuming
+      await this._next();
+      if (this._exhausted) {
+        return false;
+      }
+      // Put the item back
+      this._bufferIndex--;
+      return true;
+    }
+    return this._bufferIndex < this._buffer.length;
+  }
+
+  async close() {
+    this._buffer = null;
+    this._exhausted = true;
+  }
+
+  addCursorFlag() {
+    return this;
+  }
+
+  [Symbol.asyncIterator]() {
+    return {
+      cursor: this,
+      async next() {
+        const doc = await this.cursor._next();
+        if (doc === null) {
+          return {
+            done: true,
+            value: undefined
+          };
+        }
+        return {
+          done: false,
+          value: doc
+        };
+      }
+    };
+  }
+
+  async count() {
+    this._collection._ensureTable();
+
+    const params = [];
+    const tableName = this._collection._quotedTableName();
+    const whereClause = buildWhereClause(this._query, params, 'data', this._collection._queryOptions());
+    const sql = `SELECT COUNT(*) as count FROM ${tableName} WHERE ${whereClause}`;
+    const row = this._collection._db._sqlite.prepare(sql).get(...params);
+    return row.count;
+  }
+}
+
+// =============================================================================
+// Collection Implementation
+// =============================================================================
+
+class SqliteCollection {
+  constructor(db, name) {
+    this._db = db;
+    this._tableName = validateTableName(name);
+    this._name = name;
+    this._indexes = new Map();
+    this._textFields = null;
+    this._initialized = false;
+  }
+
+  _quotedTableName() {
+    return `"${escapeIdentifier(this._tableName)}"`;
+  }
+
+  _ftsTableName() {
+    return `"${escapeIdentifier(this._tableName + '_fts')}"`;
+  }
+
+  _queryOptions() {
+    if (!this._textFields) {
+      return {};
+    }
+    return {
+      textFields: this._textFields,
+      ftsTable: this._ftsTableName(),
+      mainTable: this._quotedTableName()
+    };
+  }
+
+  // Extract text field values from a document for FTS5 indexing.
+  // Returns an array of string values in _textFields order, or null
+  // if no FTS5 table exists.
+  _extractFtsValues(doc) {
+    if (!this._textFields) {
+      return null;
+    }
+    return this._textFields.map(f => {
+      const val = getNestedField(doc, f);
+      return val != null ? String(val) : '';
+    });
+  }
+
+  // Sync FTS5 table after inserting a document
+  _syncFtsInsert(id, doc) {
+    const values = this._extractFtsValues(doc);
+    if (!values) {
+      return;
+    }
+    const fts = this._ftsTableName();
+    const placeholders = values.map(() => '?').join(', ');
+    this._db._sqlite.prepare(
+      `INSERT INTO ${fts} (rowid, ${this._textFields.map(f => `"${escapeIdentifier(f)}"`).join(', ')}) VALUES ((SELECT rowid FROM ${this._quotedTableName()} WHERE _id = ?), ${placeholders})`
+    ).run(id, ...values);
+  }
+
+  // Delete a document's FTS5 entry by its _id.
+  // With contentless_delete=1, we can delete by rowid without old values.
+  _syncFtsDelete(id) {
+    if (!this._textFields) {
+      return;
+    }
+    const tableName = this._quotedTableName();
+    const fts = this._ftsTableName();
+    const row = this._db._sqlite.prepare(
+      `SELECT rowid FROM ${tableName} WHERE _id = ?`
+    ).get(id);
+    if (!row) {
+      return;
+    }
+    this._db._sqlite.prepare(
+      `DELETE FROM ${fts} WHERE rowid = ?`
+    ).run(row.rowid);
+  }
+
+  get collectionName() {
+    return this._name;
+  }
+
+  get name() {
+    return this._name;
+  }
+
+  _ensureTable() {
+    if (this._initialized) {
+      return;
+    }
+
+    const tableName = this._quotedTableName();
+    this._db._sqlite.exec(`
+      CREATE TABLE IF NOT EXISTS ${tableName} (
+        _id TEXT PRIMARY KEY,
+        data TEXT NOT NULL
+      )
+    `);
+    this._initialized = true;
+  }
+
+  async insertOne(doc) {
+    this._ensureTable();
+
+    const id = doc._id != null ? String(doc._id) : generateId();
+    const docWithoutId = { ...doc };
+    delete docWithoutId._id;
+
+    const tableName = this._quotedTableName();
+    try {
+      this._db._sqlite.prepare(
+        `INSERT INTO ${tableName} (_id, data) VALUES (?, ?)`
+      ).run(id, serializeDocument(docWithoutId));
+      this._syncFtsInsert(id, doc);
+      return {
+        acknowledged: true,
+        insertedId: id,
+        insertedCount: 1,
+        ops: [ {
+          ...doc,
+          _id: id
+        } ],
+        result: { ok: 1 }
+      };
+    } catch (e) {
+      if (e.code === 'SQLITE_CONSTRAINT_PRIMARYKEY' || e.code === 'SQLITE_CONSTRAINT_UNIQUE' || (e.message && e.message.includes('UNIQUE constraint failed'))) {
+        throw makeDuplicateKeyError(e, this, {
+          ...doc,
+          _id: id
+        });
+      }
+      throw e;
+    }
+  }
+
+  async insertMany(docs) {
+    this._ensureTable();
+
+    const insertedIds = {};
+    let insertedCount = 0;
+
+    for (let i = 0; i < docs.length; i++) {
+      const result = await this.insertOne(docs[i]);
+      insertedIds[i] = result.insertedId;
+      insertedCount++;
+    }
+
+    return {
+      acknowledged: true,
+      insertedCount,
+      insertedIds,
+      result: { ok: 1 }
+    };
+  }
+
+  async findOne(query, options = {}) {
+    this._ensureTable();
+
+    const params = [];
+    const tableName = this._quotedTableName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+    const sql = `SELECT _id, data FROM ${tableName} WHERE ${whereClause} LIMIT 1`;
+
+    const row = this._db._sqlite.prepare(sql).get(...params);
+    if (!row) {
+      return null;
+    }
+
+    const doc = deserializeDocument(row.data, row._id);
+    return options.projection ? applyProjection(doc, options.projection) : doc;
+  }
+
+  find(query, options) {
+    return new SqliteCursor(this, query, options);
+  }
+
+  async updateOne(query, update, options = {}) {
+    this._ensureTable();
+
+    if (typeof options === 'function') {
+      options = {};
+    }
+
+    // Single-statement fast path: when the update uses only simple
+    // operators without upsert, execute a single UPDATE statement
+    // instead of the read-modify-write cycle. $push, $pull and
+    // $addToSet are included only when all their values are scalars
+    // (strings, numbers, booleans). Skip if any touched field is
+    // text-indexed (FTS sync requires the full read-modify-write path).
+    if (!options.upsert) {
+      const atomicOps = [
+        '$inc', '$set', '$unset', '$currentDate',
+        '$push', '$pull', '$addToSet'
+      ];
+      const ops = Object.keys(update);
+      const isAtomicCompatible = ops.length > 0 &&
+        ops.every(op => atomicOps.includes(op));
+      if (isAtomicCompatible) {
+        // $push/$pull/$addToSet only qualify when all values are scalars
+        const allScalar = [ '$push', '$pull', '$addToSet' ].every(op => {
+          if (!update[op]) {
+            return true;
+          }
+          return Object.values(update[op]).every(v =>
+            typeof v === 'string' ||
+            typeof v === 'number' ||
+            typeof v === 'boolean'
+          );
+        });
+        if (allScalar) {
+          const textFields = this._textFields || [];
+          const unsetKeys = Array.isArray(update.$unset)
+            ? update.$unset
+            : Object.keys(update.$unset || {});
+          const allKeys = [
+            ...Object.keys(update.$set || {}),
+            ...Object.keys(update.$inc || {}),
+            ...unsetKeys,
+            ...Object.keys(update.$currentDate || {}),
+            ...Object.keys(update.$push || {}),
+            ...Object.keys(update.$pull || {}),
+            ...Object.keys(update.$addToSet || {})
+          ];
+          const touchesTextFields =
+            allKeys.some(f => textFields.includes(f));
+          if (!touchesTextFields) {
+            return this._atomicUpdateOne(query, update);
+          }
+        }
+      }
+    }
+
+    const params = [];
+    const tableName = this._quotedTableName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+
+    const selectSql = `SELECT _id, data FROM ${tableName} WHERE ${whereClause} LIMIT 1`;
+    const selectResult = this._db._sqlite.prepare(selectSql).get(...params);
+
+    if (!selectResult) {
+      if (options.upsert) {
+        let newDoc = {};
+        if (query._id) {
+          newDoc._id = query._id;
+        }
+        newDoc = applyUpdate(newDoc, update);
+        const insertResult = await this.insertOne(newDoc);
+        return {
+          acknowledged: true,
+          matchedCount: 0,
+          modifiedCount: 0,
+          upsertedId: insertResult.insertedId,
+          upsertedCount: 1,
+          result: {
+            nModified: 0,
+            n: 1
+          }
+        };
+      }
+      return {
+        acknowledged: true,
+        matchedCount: 0,
+        modifiedCount: 0,
+        result: {
+          nModified: 0,
+          n: 0
+        }
+      };
+    }
+
+    const existing = deserializeDocument(selectResult.data, selectResult._id);
+    const updated = applyUpdate(existing, update);
+    const { _id, ...dataWithoutId } = updated;
+
+    try {
+      this._syncFtsDelete(selectResult._id);
+      this._db._sqlite.prepare(
+        `UPDATE ${tableName} SET data = ? WHERE _id = ?`
+      ).run(serializeDocument(dataWithoutId), selectResult._id);
+      this._syncFtsInsert(selectResult._id, updated);
+    } catch (e) {
+      if (e.code === 'SQLITE_CONSTRAINT_PRIMARYKEY' || e.code === 'SQLITE_CONSTRAINT_UNIQUE' || (e.message && e.message.includes('UNIQUE constraint failed'))) {
+        throw makeDuplicateKeyError(e, this, updated);
+      }
+      throw e;
+    }
+
+    return {
+      acknowledged: true,
+      matchedCount: 1,
+      modifiedCount: 1,
+      result: {
+        nModified: 1,
+        n: 1
+      }
+    };
+  }
+
+  _atomicUpdateOne(query, update) {
+    const tableName = this._quotedTableName();
+
+    // Build SET expression and its params first (they appear before WHERE in SQL)
+    const setParams = [];
+    let dataExpr = 'data';
+
+    if (update.$set) {
+      for (const [ field, value ] of Object.entries(update.$set)) {
+        const jsonPath = toJsonPath(field);
+        const serialized = serializeValue(value);
+        setParams.push(JSON.stringify(serialized));
+        dataExpr = `json_set(${dataExpr}, '${jsonPath}', json(?))`;
+      }
+    }
+
+    if (update.$inc) {
+      for (const [ field, value ] of Object.entries(update.$inc)) {
+        const jsonPath = toJsonPath(field);
+        setParams.push(value);
+        dataExpr = `json_set(${dataExpr}, '${jsonPath}', COALESCE(json_extract(data, '${jsonPath}'), 0) + ?)`;
+      }
+    }
+
+    if (update.$unset) {
+      const fields = Array.isArray(update.$unset)
+        ? update.$unset
+        : Object.keys(update.$unset);
+      for (const field of fields) {
+        const jsonPath = toJsonPath(field);
+        dataExpr = `json_remove(${dataExpr}, '${jsonPath}')`;
+      }
+    }
+
+    if (update.$currentDate) {
+      for (const [ field, value ] of Object.entries(update.$currentDate)) {
+        if (value === true || (value && value.$type === 'date')) {
+          const jsonPath = toJsonPath(field);
+          const dateVal = JSON.stringify(serializeValue(new Date()));
+          setParams.push(dateVal);
+          dataExpr = `json_set(${dataExpr}, '${jsonPath}', json(?))`;
+        }
+      }
+    }
+
+    // $push: append scalar value to array
+    if (update.$push) {
+      for (const [ field, value ] of Object.entries(update.$push)) {
+        const jsonPath = toJsonPath(field);
+        setParams.push(value);
+        const coalesced = `COALESCE(json_extract(data, '${jsonPath}'), json('[]'))`;
+        dataExpr = `json_set(${dataExpr}, '${jsonPath}', json_insert(${coalesced}, '$[#]', ?))`;
+      }
+    }
+
+    // $pull: remove scalar value from array
+    if (update.$pull) {
+      for (const [ field, value ] of Object.entries(update.$pull)) {
+        const jsonPath = toJsonPath(field);
+        setParams.push(value);
+        dataExpr = `json_set(${dataExpr}, '${jsonPath}', ` +
+          '(SELECT json_group_array(je.value) ' +
+          `FROM json_each(COALESCE(json_extract(data, '${jsonPath}'), '[]')) AS je ` +
+          'WHERE je.value != ?))';
+      }
+    }
+
+    // $addToSet: add scalar value to array if not already present
+    if (update.$addToSet) {
+      for (const [ field, value ] of Object.entries(update.$addToSet)) {
+        const jsonPath = toJsonPath(field);
+        setParams.push(value, value);
+        const coalesced = `COALESCE(json_extract(data, '${jsonPath}'), json('[]'))`;
+        dataExpr = `json_set(${dataExpr}, '${jsonPath}', ` +
+          `CASE WHEN EXISTS(SELECT 1 FROM json_each(${coalesced}) WHERE value = ?) ` +
+          `THEN ${coalesced} ` +
+          `ELSE json_insert(${coalesced}, '$[#]', ?) END)`;
+      }
+    }
+
+    // Build WHERE clause params second
+    const whereParams = [];
+    const whereClause = buildWhereClause(query, whereParams, 'data', this._queryOptions());
+
+    // Positional params: SET params first, then WHERE params
+    const params = [ ...setParams, ...whereParams ];
+    const sql = `UPDATE ${tableName} SET data = ${dataExpr} WHERE ${whereClause}`;
+    try {
+      const result = this._db._sqlite.prepare(sql).run(...params);
+      const matched = result.changes > 0 ? 1 : 0;
+      return {
+        acknowledged: true,
+        matchedCount: matched,
+        modifiedCount: matched,
+        result: {
+          nModified: matched,
+          n: matched
+        }
+      };
+    } catch (e) {
+      if (e.code === 'SQLITE_CONSTRAINT_PRIMARYKEY' || e.code === 'SQLITE_CONSTRAINT_UNIQUE' || (e.message && e.message.includes('UNIQUE constraint failed'))) {
+        // Build a pseudo-doc from $set values so makeDuplicateKeyError
+        // can report the conflicting key values
+        const pseudoDoc = {};
+        if (update.$set) {
+          for (const [ field, value ] of Object.entries(update.$set)) {
+            setNestedField(pseudoDoc, field, value);
+          }
+        }
+        throw makeDuplicateKeyError(e, this, pseudoDoc);
+      }
+      throw e;
+    }
+  }
+
+  async updateMany(query, update, options = {}) {
+    this._ensureTable();
+
+    const params = [];
+    const tableName = this._quotedTableName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+
+    const selectSql = `SELECT _id, data FROM ${tableName} WHERE ${whereClause}`;
+    const rows = this._db._sqlite.prepare(selectSql).all(...params);
+
+    if (rows.length === 0) {
+      return {
+        acknowledged: true,
+        matchedCount: 0,
+        modifiedCount: 0,
+        result: {
+          nModified: 0,
+          n: 0
+        }
+      };
+    }
+
+    let modifiedCount = 0;
+    const updateStmt = this._db._sqlite.prepare(
+      `UPDATE ${tableName} SET data = ? WHERE _id = ?`
+    );
+
+    for (const row of rows) {
+      const existing = deserializeDocument(row.data, row._id);
+      const updated = applyUpdate(existing, update);
+      const { _id, ...dataWithoutId } = updated;
+      this._syncFtsDelete(row._id);
+      updateStmt.run(serializeDocument(dataWithoutId), row._id);
+      this._syncFtsInsert(row._id, updated);
+      modifiedCount++;
+    }
+
+    return {
+      acknowledged: true,
+      matchedCount: rows.length,
+      modifiedCount,
+      result: {
+        nModified: modifiedCount,
+        n: rows.length
+      }
+    };
+  }
+
+  async replaceOne(query, replacement, options = {}) {
+    this._ensureTable();
+
+    const params = [];
+    const tableName = this._quotedTableName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+
+    const selectSql = `SELECT _id FROM ${tableName} WHERE ${whereClause} LIMIT 1`;
+    const selectResult = this._db._sqlite.prepare(selectSql).get(...params);
+
+    if (!selectResult) {
+      if (options.upsert) {
+        const result = await this.insertOne(replacement);
+        return {
+          acknowledged: true,
+          matchedCount: 0,
+          modifiedCount: 0,
+          upsertedId: result.insertedId,
+          upsertedCount: 1
+        };
+      }
+      return {
+        acknowledged: true,
+        matchedCount: 0,
+        modifiedCount: 0
+      };
+    }
+
+    const { _id, ...dataWithoutId } = replacement;
+    try {
+      this._syncFtsDelete(selectResult._id);
+      this._db._sqlite.prepare(
+        `UPDATE ${tableName} SET data = ? WHERE _id = ?`
+      ).run(serializeDocument(dataWithoutId), selectResult._id);
+      this._syncFtsInsert(selectResult._id, replacement);
+    } catch (e) {
+      if (e.code === 'SQLITE_CONSTRAINT_PRIMARYKEY' || e.code === 'SQLITE_CONSTRAINT_UNIQUE' || (e.message && e.message.includes('UNIQUE constraint failed'))) {
+        throw makeDuplicateKeyError(e, this, replacement);
+      }
+      throw e;
+    }
+
+    return {
+      acknowledged: true,
+      matchedCount: 1,
+      modifiedCount: 1
+    };
+  }
+
+  async deleteOne(query) {
+    this._ensureTable();
+
+    const params = [];
+    const tableName = this._quotedTableName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+
+    if (this._textFields) {
+      const fts = this._ftsTableName();
+      const row = this._db._sqlite.prepare(
+        `SELECT rowid FROM ${tableName} WHERE ${whereClause} LIMIT 1`
+      ).get(...params);
+      if (!row) {
+        return {
+          acknowledged: true,
+          deletedCount: 0,
+          result: { ok: 1 }
+        };
+      }
+      this._db._sqlite.prepare(`DELETE FROM ${fts} WHERE rowid = ?`).run(row.rowid);
+      this._db._sqlite.prepare(`DELETE FROM ${tableName} WHERE rowid = ?`).run(row.rowid);
+      return {
+        acknowledged: true,
+        deletedCount: 1,
+        result: { ok: 1 }
+      };
+    }
+
+    // Even without _textFields set, clean up FTS entries if the FTS table exists
+    const fts = this._ftsTableName();
+    const ftsExists = this._db._sqlite.prepare(
+      'SELECT 1 FROM sqlite_master WHERE type=\'table\' AND name=?'
+    ).get(this._tableName + '_fts');
+    if (ftsExists) {
+      const row = this._db._sqlite.prepare(
+        `SELECT rowid FROM ${tableName} WHERE ${whereClause} LIMIT 1`
+      ).get(...params);
+      if (!row) {
+        return {
+          acknowledged: true,
+          deletedCount: 0,
+          result: { ok: 1 }
+        };
+      }
+      this._db._sqlite.prepare(`DELETE FROM ${fts} WHERE rowid = ?`).run(row.rowid);
+      this._db._sqlite.prepare(`DELETE FROM ${tableName} WHERE rowid = ?`).run(row.rowid);
+      return {
+        acknowledged: true,
+        deletedCount: 1,
+        result: { ok: 1 }
+      };
+    }
+
+    const result = this._db._sqlite.prepare(
+      `DELETE FROM ${tableName} WHERE _id IN (
+        SELECT _id FROM ${tableName} WHERE ${whereClause} LIMIT 1
+      )`
+    ).run(...params);
+
+    return {
+      acknowledged: true,
+      deletedCount: result.changes,
+      result: { ok: 1 }
+    };
+  }
+
+  async deleteMany(query) {
+    this._ensureTable();
+
+    const params = [];
+    const tableName = this._quotedTableName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+
+    if (this._textFields) {
+      const fts = this._ftsTableName();
+      const rows = this._db._sqlite.prepare(
+        `SELECT rowid FROM ${tableName} WHERE ${whereClause}`
+      ).all(...params);
+      if (rows.length > 0) {
+        const deleteFts = this._db._sqlite.prepare(`DELETE FROM ${fts} WHERE rowid = ?`);
+        const deleteMain = this._db._sqlite.prepare(`DELETE FROM ${tableName} WHERE rowid = ?`);
+        for (const row of rows) {
+          deleteFts.run(row.rowid);
+          deleteMain.run(row.rowid);
+        }
+      }
+      return {
+        acknowledged: true,
+        deletedCount: rows.length,
+        result: { ok: 1 }
+      };
+    }
+
+    // Even without _textFields set (e.g. a separate connection that never
+    // called createIndex), clean up FTS entries if the FTS table exists.
+    // This prevents stale FTS data when external tools delete documents.
+    const fts = this._ftsTableName();
+    const ftsExists = this._db._sqlite.prepare(
+      'SELECT 1 FROM sqlite_master WHERE type=\'table\' AND name=?'
+    ).get(this._tableName + '_fts');
+    if (ftsExists) {
+      const rows = this._db._sqlite.prepare(
+        `SELECT rowid FROM ${tableName} WHERE ${whereClause}`
+      ).all(...params);
+      if (rows.length > 0) {
+        const deleteFts = this._db._sqlite.prepare(`DELETE FROM ${fts} WHERE rowid = ?`);
+        const deleteMain = this._db._sqlite.prepare(`DELETE FROM ${tableName} WHERE rowid = ?`);
+        for (const row of rows) {
+          deleteFts.run(row.rowid);
+          deleteMain.run(row.rowid);
+        }
+      }
+      return {
+        acknowledged: true,
+        deletedCount: rows.length,
+        result: { ok: 1 }
+      };
+    }
+
+    const result = this._db._sqlite.prepare(
+      `DELETE FROM ${tableName} WHERE ${whereClause}`
+    ).run(...params);
+
+    return {
+      acknowledged: true,
+      deletedCount: result.changes,
+      result: { ok: 1 }
+    };
+  }
+
+  async remove(query) {
+    return this.deleteMany(query);
+  }
+
+  async removeOne(query) {
+    return this.deleteOne(query);
+  }
+
+  async removeMany(query) {
+    return this.deleteMany(query);
+  }
+
+  async countDocuments(query = {}) {
+    this._ensureTable();
+
+    const params = [];
+    const tableName = this._quotedTableName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+    const sql = `SELECT COUNT(*) as count FROM ${tableName} WHERE ${whereClause}`;
+
+    const row = this._db._sqlite.prepare(sql).get(...params);
+    return row.count;
+  }
+
+  async distinct(field, query = {}) {
+    this._ensureTable();
+
+    const params = [];
+    const tableName = this._quotedTableName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+
+    if (field === '_id') {
+      const sql = `SELECT DISTINCT _id as value FROM ${tableName} WHERE ${whereClause}`;
+      const rows = this._db._sqlite.prepare(sql).all(...params);
+      return rows.map(row => row.value).filter(v => v !== null);
+    }
+
+    const jsonExtract = buildJsonExtract(field);
+    const jsonExtractPath = buildJsonExtractPath(field);
+    // Flatten arrays like MongoDB's distinct(), preserving type info for booleans.
+    // For arrays: json_each provides type; for scalars: json_type on the field itself.
+    // Use UNION to combine both cases.
+    const sql = `
+      SELECT DISTINCT je.value as value, je.type as type FROM ${tableName}, json_each(${jsonExtract}) AS je
+        WHERE ${whereClause} AND json_type(data, ${jsonExtractPath}) = 'array'
+      UNION
+      SELECT DISTINCT ${jsonExtract} as value, json_type(data, ${jsonExtractPath}) as type FROM ${tableName}
+        WHERE ${whereClause} AND ${jsonExtract} IS NOT NULL AND json_type(data, ${jsonExtractPath}) != 'array'
+    `;
+
+    const rows = this._db._sqlite.prepare(sql).all(...params, ...params);
+
+    return rows
+      .map(row => {
+        const v = row.value;
+        if (v === null || v === undefined) {
+          return null;
+        }
+        // Convert SQLite boolean representations back to JS booleans
+        // json_type returns 'true'/'false' for boolean values
+        if (row.type === 'true') {
+          return true;
+        }
+        if (row.type === 'false') {
+          return false;
+        }
+        // Parse JSON objects and arrays back to JS values
+        if (row.type === 'object' || row.type === 'array') {
+          return JSON.parse(v);
+        }
+        return v;
+      })
+      .filter(v => v !== null);
+  }
+
+  aggregate(pipeline) {
+    return new AggregationCursor(this, pipeline);
+  }
+
+  async bulkWrite(operations) {
+    this._ensureTable();
+
+    let insertedCount = 0;
+    let modifiedCount = 0;
+    let deletedCount = 0;
+    let upsertedCount = 0;
+    const insertedIds = {};
+    const upsertedIds = {};
+
+    for (let i = 0; i < operations.length; i++) {
+      const op = operations[i];
+
+      if (op.insertOne) {
+        const result = await this.insertOne(op.insertOne.document);
+        insertedIds[i] = result.insertedId;
+        insertedCount++;
+      } else if (op.updateOne) {
+        const result = await this.updateOne(
+          op.updateOne.filter,
+          op.updateOne.update,
+          { upsert: op.updateOne.upsert }
+        );
+        modifiedCount += result.modifiedCount;
+        if (result.upsertedId) {
+          upsertedIds[i] = result.upsertedId;
+          upsertedCount++;
+        }
+      } else if (op.updateMany) {
+        const result = await this.updateMany(
+          op.updateMany.filter,
+          op.updateMany.update,
+          { upsert: op.updateMany.upsert }
+        );
+        modifiedCount += result.modifiedCount;
+      } else if (op.deleteOne) {
+        const result = await this.deleteOne(op.deleteOne.filter);
+        deletedCount += result.deletedCount;
+      } else if (op.deleteMany) {
+        const result = await this.deleteMany(op.deleteMany.filter);
+        deletedCount += result.deletedCount;
+      } else if (op.replaceOne) {
+        const result = await this.replaceOne(
+          op.replaceOne.filter,
+          op.replaceOne.replacement,
+          { upsert: op.replaceOne.upsert }
+        );
+        modifiedCount += result.modifiedCount;
+        if (result.upsertedId) {
+          upsertedIds[i] = result.upsertedId;
+          upsertedCount++;
+        }
+      }
+    }
+
+    return {
+      acknowledged: true,
+      insertedCount,
+      modifiedCount,
+      deletedCount,
+      upsertedCount,
+      insertedIds,
+      upsertedIds
+    };
+  }
+
+  async findOneAndUpdate(query, update, options = {}) {
+    this._ensureTable();
+
+    const params = [];
+    const tableName = this._quotedTableName();
+    const whereClause = buildWhereClause(query, params, 'data', this._queryOptions());
+
+    const selectSql = `SELECT _id, data FROM ${tableName} WHERE ${whereClause} LIMIT 1`;
+    const selectResult = this._db._sqlite.prepare(selectSql).get(...params);
+
+    if (!selectResult) {
+      if (options.upsert) {
+        let newDoc = {};
+        if (query._id) {
+          newDoc._id = query._id;
+        }
+        newDoc = applyUpdate(newDoc, update);
+        await this.insertOne(newDoc);
+        return options.returnDocument === 'after' ? newDoc : null;
+      }
+      return null;
+    }
+
+    const existing = deserializeDocument(selectResult.data, selectResult._id);
+    const updated = applyUpdate(existing, update);
+    const { _id, ...dataWithoutId } = updated;
+
+    this._syncFtsDelete(selectResult._id);
+    this._db._sqlite.prepare(
+      `UPDATE ${tableName} SET data = ? WHERE _id = ?`
+    ).run(serializeDocument(dataWithoutId), selectResult._id);
+    this._syncFtsInsert(selectResult._id, updated);
+
+    return options.returnDocument === 'after' ? updated : existing;
+  }
+
+  async createIndex(keys, options = {}) {
+    this._ensureTable();
+
+    const keyEntries = Object.entries(keys);
+    const indexType = options.type;
+
+    const buildIndexPath = (field, type) => {
+      if (type === 'date') {
+        return `json_extract(data, '$.${escapeString(field)}.$date')`;
+      }
+      if (type === 'number') {
+        return `CAST(json_extract(data, '$.${escapeString(field)}') AS NUMERIC)`;
+      }
+      return `json_extract(data, '$.${escapeString(field)}')`;
+    };
+
+    const safeFieldNames = keyEntries.map(([ k ]) => k.replace(/[^a-zA-Z0-9]/g, '_')).join('_');
+    const indexName = options.name
+      ? sanitizeIndexName(options.name)
+      : `idx_${this._tableName}_${safeFieldNames}`.substring(0, 63);
+
+    const mongoName = options.name || keyEntries.map(([ k, v ]) => `${k}_${v}`).join('_');
+
+    this._indexes.set(indexName, {
+      keys,
+      options,
+      mongoName
+    });
+
+    const tableName = this._quotedTableName();
+    const escapedIndexName = escapeIdentifier(indexName);
+
+    // Build WHERE clause for sparse indexes
+    let whereClause = '';
+    if (options.sparse) {
+      const sparseConditions = keyEntries.map(([ field ]) => {
+        if (field === '_id') {
+          return '_id IS NOT NULL';
+        }
+        return `json_type(data, '$.${escapeString(field)}') IS NOT NULL`;
+      });
+      whereClause = ` WHERE ${sparseConditions.join(' AND ')}`;
+    }
+
+    // Handle text indexes — create an FTS5 virtual table
+    const hasTextIndex = keyEntries.some(([ , v ]) => v === 'text');
+    if (hasTextIndex) {
+      let textFields = keyEntries.filter(([ , v ]) => v === 'text').map(([ k ]) => k);
+      // MongoDB dumps store text indexes as { _fts: 'text', _ftsx: 1 }
+      // The real field names are in options.weights
+      if (textFields.length === 1 && textFields[0] === '_fts' && options.weights) {
+        textFields = Object.keys(options.weights);
+      }
+      this._textFields = textFields;
+
+      const fts = this._ftsTableName();
+      const cols = textFields.map(f => `"${escapeIdentifier(f)}"`).join(', ');
+
+      // Content-less FTS5 table — we manage inserts/deletes manually.
+      // content='' avoids duplicating data, contentless_delete=1 allows
+      // DELETE operations on the virtual table.
+      this._db._sqlite.exec(
+        `CREATE VIRTUAL TABLE IF NOT EXISTS ${fts} USING fts5(${cols}, content='', contentless_delete=1)`
+      );
+
+      // Clear any stale FTS entries (important during DB restore where
+      // deleteMany runs before createIndex sets _textFields, leaving
+      // orphaned FTS entries that cause incorrect search results)
+      this._db._sqlite.exec(`DELETE FROM ${fts}`);
+
+      // Backfill existing documents into the FTS5 table
+      const rows = this._db._sqlite.prepare(
+        `SELECT rowid, _id, data FROM ${tableName}`
+      ).all();
+      if (rows.length > 0) {
+        const insertFts = this._db._sqlite.prepare(
+          `INSERT OR REPLACE INTO ${fts} (rowid, ${cols}) VALUES (?, ${textFields.map(() => '?').join(', ')})`
+        );
+        const backfill = this._db._sqlite.transaction(() => {
+          for (const row of rows) {
+            const doc = deserializeDocument(row.data, row._id);
+            const values = this._extractFtsValues(doc);
+            insertFts.run(row.rowid, ...values);
+          }
+        });
+        backfill();
+      }
+
+      return indexName;
+    }
+
+    // Handle unique constraint
+    if (options.unique) {
+      const indexExprs = keyEntries.map(([ field ]) => {
+        return field === '_id' ? '_id' : `(${buildIndexPath(field, indexType)})`;
+      });
+
+      this._db._sqlite.exec(`
+        CREATE UNIQUE INDEX IF NOT EXISTS "${escapedIndexName}"
+        ON ${tableName} (${indexExprs.join(', ')})${whereClause}
+      `);
+      return indexName;
+    }
+
+    // Handle regular indexes
+    const indexExprs = keyEntries.map(([ field, direction ]) => {
+      if (field === '_id') {
+        return `_id ${direction === -1 ? 'DESC' : 'ASC'}`;
+      }
+      return `(${buildIndexPath(field, indexType)}) ${direction === -1 ? 'DESC' : 'ASC'}`;
+    });
+
+    this._db._sqlite.exec(`
+      CREATE INDEX IF NOT EXISTS "${escapedIndexName}"
+      ON ${tableName} (${indexExprs.join(', ')})${whereClause}
+    `);
+
+    return indexName;
+  }
+
+  async ensureIndex(keys, options) {
+    return this.createIndex(keys, options);
+  }
+
+  async dropIndex(indexName) {
+    let pgName = null;
+    for (const [ pgKey, meta ] of this._indexes.entries()) {
+      if (meta.mongoName === indexName) {
+        pgName = pgKey;
+        break;
+      }
+    }
+    if (!pgName) {
+      // Same sanitization rules as createIndex — tolerate MongoDB-style
+      // names (e.g. "slug.1") that would fail strict identifier checks.
+      pgName = sanitizeIndexName(indexName);
+    }
+    this._indexes.delete(pgName);
+    const escapedIndexName = escapeIdentifier(pgName);
+    this._db._sqlite.exec(`DROP INDEX IF EXISTS "${escapedIndexName}"`);
+  }
+
+  async indexes() {
+    this._ensureTable();
+
+    const rows = this._db._sqlite.prepare(
+      'SELECT name, sql FROM sqlite_master WHERE type = \'index\' AND tbl_name = ?'
+    ).all(this._tableName);
+
+    const indexes = [ {
+      name: '_id_',
+      key: { _id: 1 },
+      unique: true
+    } ];
+
+    const seen = new Set();
+    for (const row of rows) {
+      // Skip auto-created indexes (like the PRIMARY KEY index)
+      if (!row.sql) {
+        continue;
+      }
+
+      seen.add(row.name);
+      const storedIndex = this._indexes.get(row.name);
+      if (storedIndex) {
+        indexes.push({
+          name: storedIndex.mongoName || row.name,
+          key: storedIndex.keys,
+          unique: storedIndex.options.unique || false,
+          ...(storedIndex.options.sparse ? { sparse: true } : {}),
+          ...(storedIndex.options.type ? { type: storedIndex.options.type } : {})
+        });
+      } else {
+        indexes.push({
+          name: row.name,
+          ...parseIndexDef(row.sql)
+        });
+      }
+    }
+
+    // Include indexes tracked in _indexes but not in sqlite_master
+    // (e.g. FTS5 virtual table text indexes)
+    for (const [ name, storedIndex ] of this._indexes) {
+      if (!seen.has(name)) {
+        indexes.push({
+          name: storedIndex.mongoName || name,
+          key: storedIndex.keys,
+          unique: storedIndex.options.unique || false,
+          ...(storedIndex.options.sparse ? { sparse: true } : {}),
+          ...(storedIndex.options.type ? { type: storedIndex.options.type } : {})
+        });
+      }
+    }
+
+    return indexes;
+  }
+
+  async indexInformation() {
+    const indexes = await this.indexes();
+    const info = {};
+    for (const idx of indexes) {
+      info[idx.name] = Object.entries(idx.key).map(([ k, v ]) => [ k, v ]);
+    }
+    return info;
+  }
+
+  async insert(docs) {
+    if (Array.isArray(docs)) {
+      return this.insertMany(docs);
+    }
+    return this.insertOne(docs);
+  }
+
+  initializeUnorderedBulkOp() {
+    const collection = this;
+    const operations = [];
+
+    return {
+      find(query) {
+        return {
+          updateOne(update) {
+            operations.push({
+              updateOne: {
+                filter: query,
+                update
+              }
+            });
+          },
+          update(update) {
+            operations.push({
+              updateMany: {
+                filter: query,
+                update
+              }
+            });
+          },
+          upsert() {
+            return {
+              updateOne(update) {
+                operations.push({
+                  updateOne: {
+                    filter: query,
+                    update,
+                    upsert: true
+                  }
+                });
+              },
+              update(update) {
+                operations.push({
+                  updateMany: {
+                    filter: query,
+                    update,
+                    upsert: true
+                  }
+                });
+              },
+              replaceOne(doc) {
+                operations.push({
+                  replaceOne: {
+                    filter: query,
+                    replacement: doc,
+                    upsert: true
+                  }
+                });
+              }
+            };
+          },
+          deleteOne() {
+            operations.push({ deleteOne: { filter: query } });
+          },
+          delete() {
+            operations.push({ deleteMany: { filter: query } });
+          }
+        };
+      },
+      async execute() {
+        return collection.bulkWrite(operations);
+      }
+    };
+  }
+
+  async drop() {
+    if (this._textFields) {
+      const fts = this._ftsTableName();
+      this._db._sqlite.exec(`DROP TABLE IF EXISTS ${fts}`);
+      this._textFields = null;
+    }
+    const tableName = this._quotedTableName();
+    this._db._sqlite.exec(`DROP TABLE IF EXISTS ${tableName}`);
+    this._initialized = false;
+    this._indexes.clear();
+  }
+
+  async rename(newName) {
+    const oldName = this._name;
+    const newCollName = validateTableName(newName);
+    const tableName = this._quotedTableName();
+    const escapedNewTableName = escapeIdentifier(newCollName);
+
+    // Rename FTS5 table first if it exists
+    if (this._textFields) {
+      const oldFts = this._ftsTableName();
+      const newFtsName = escapeIdentifier(newCollName + '_fts');
+      this._db._sqlite.exec(`ALTER TABLE ${oldFts} RENAME TO "${newFtsName}"`);
+    }
+
+    this._db._sqlite.exec(`ALTER TABLE ${tableName} RENAME TO "${escapedNewTableName}"`);
+
+    this._tableName = newCollName;
+    this._name = newName;
+
+    this._db._collections.delete(oldName);
+    this._db._collections.set(newName, this);
+  }
+}
+
+// =============================================================================
+// Database Implementation
+// =============================================================================
+
+class SqliteDb {
+  constructor(client, name, sqliteInstance) {
+    this._client = client;
+    this._sqlite = sqliteInstance;
+    this._name = name;
+    this.databaseName = name;
+    this._collections = new Map();
+  }
+
+  collection(name) {
+    if (!this._collections.has(name)) {
+      this._collections.set(name, new SqliteCollection(this, name));
+    }
+    return this._collections.get(name);
+  }
+
+  async createCollection(name) {
+    const col = this.collection(name);
+    col._ensureTable();
+    return col;
+  }
+
+  admin() {
+    const client = this._client;
+    return {
+      async listDatabases() {
+        // List all sibling database files in the directory,
+        // matching the extension of the original database
+        const dir = path.dirname(client._dbPath);
+        const ext = client._ext;
+        const fs = require('fs');
+        let files;
+        try {
+          files = fs.readdirSync(dir);
+        } catch (e) {
+          return { databases: [] };
+        }
+        const databases = files
+          .filter(f => f.endsWith(ext))
+          .map(f => ({ name: f.slice(0, -ext.length) }));
+        return { databases };
+      }
+    };
+  }
+
+  async dropDatabase() {
+    // Drop all tables
+    const tables = this._sqlite.prepare(
+      'SELECT name FROM sqlite_master WHERE type = \'table\' AND name NOT LIKE \'sqlite_%\''
+    ).all();
+    for (const table of tables) {
+      this._sqlite.exec(`DROP TABLE IF EXISTS "${escapeIdentifier(table.name)}"`);
+    }
+    // Also drop all indexes
+    const indexes = this._sqlite.prepare(
+      'SELECT name FROM sqlite_master WHERE type = \'index\' AND name NOT LIKE \'sqlite_%\''
+    ).all();
+    for (const idx of indexes) {
+      this._sqlite.exec(`DROP INDEX IF EXISTS "${escapeIdentifier(idx.name)}"`);
+    }
+    this._collections.clear();
+  }
+
+  async collections() {
+    const list = await this.listCollections().toArray();
+    return list.map(entry => this.collection(entry.name));
+  }
+
+  listCollections() {
+    const self = this;
+    return {
+      async toArray() {
+        const rows = self._sqlite.prepare(
+          'SELECT name FROM sqlite_master WHERE type = \'table\' AND name NOT LIKE \'sqlite_%\' AND name NOT LIKE \'%\\_fts%\' ESCAPE \'\\\''
+        ).all();
+        return rows.map(row => ({ name: row.name }));
+      }
+    };
+  }
+}
+
+// =============================================================================
+// Client Implementation
+// =============================================================================
+
+class SqliteClient {
+  constructor(sqliteInstance, dbPath, defaultDbName) {
+    this._sqlite = sqliteInstance;
+    this._dbPath = dbPath;
+    this._defaultDbName = defaultDbName;
+    this._ext = path.extname(dbPath) || '.sqlite';
+    this._databases = new Map();
+    this._siblingDbs = new Map();
+  }
+
+  db(name) {
+    if (!name) {
+      if (!this._databases.has(this._defaultDbName)) {
+        this._databases.set(
+          this._defaultDbName,
+          new SqliteDb(this, this._defaultDbName, this._sqlite)
+        );
+      }
+      return this._databases.get(this._defaultDbName);
+    }
+
+    // For sibling databases, open a separate file in the same directory,
+    // using the same extension as the original database
+    if (!this._databases.has(name)) {
+      const dir = path.dirname(this._dbPath);
+      const siblingPath = path.join(dir, `${name}${this._ext}`);
+      let siblingDb;
+      if (this._siblingDbs.has(siblingPath)) {
+        siblingDb = this._siblingDbs.get(siblingPath);
+      } else {
+        siblingDb = new Database(siblingPath);
+        _registerFunctions(siblingDb);
+        this._siblingDbs.set(siblingPath, siblingDb);
+      }
+      this._databases.set(name, new SqliteDb(this, name, siblingDb));
+    }
+    return this._databases.get(name);
+  }
+
+  async close() {
+    if (!this._closed) {
+      this._closed = true;
+      this._sqlite.close();
+      for (const [ , db ] of this._siblingDbs) {
+        db.close();
+      }
+    }
+  }
+}
+
+// =============================================================================
+// Register custom regexp/regexp_i functions
+// =============================================================================
+
+function _registerFunctions(db) {
+  db.function('regexp', { deterministic: true }, (pattern, value) => {
+    if (value === null || value === undefined) {
+      return 0;
+    }
+    try {
+      return new RegExp(pattern).test(String(value)) ? 1 : 0;
+    } catch (e) {
+      return 0;
+    }
+  });
+
+  db.function('regexp_i', { deterministic: true }, (pattern, value) => {
+    if (value === null || value === undefined) {
+      return 0;
+    }
+    try {
+      return new RegExp(pattern, 'i').test(String(value)) ? 1 : 0;
+    } catch (e) {
+      return 0;
+    }
+  });
+}
+
+// =============================================================================
+// Module Export
+// =============================================================================
+
+module.exports = {
+  name: 'sqlite',
+  protocols: [ 'sqlite' ],
+
+  async connect(uri, options = {}) {
+    // Parse URI: sqlite:///path/to/file.sqlite or sqlite://path/to/file.db
+    const url = new URL(uri);
+    let dbPath;
+    if (url.hostname) {
+      // sqlite://relative/path/to/file.sqlite
+      dbPath = url.hostname + url.pathname;
+    } else {
+      // sqlite:///absolute/path/to/file.sqlite
+      dbPath = url.pathname;
+    }
+
+    // Reject in-memory / empty paths. The adapter does not support
+    // throwaway in-memory sqlite databases: an ApostropheCMS site needs
+    // a persistent store, and transient in-memory URIs would also
+    // interact poorly with multi-connection patterns (each new
+    // connection would get a fresh, empty database).
+    if (!dbPath || dbPath === ':memory:' || dbPath.endsWith('/:memory:')) {
+      throw new Error(
+        `sqlite adapter does not support in-memory databases (got "${uri}"). ` +
+        'Provide a file path, e.g. sqlite:///var/lib/mysite/data.db'
+      );
+    }
+
+    // Ensure directory exists
+    const dir = path.dirname(dbPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    const db = new Database(dbPath);
+
+    // Enable WAL mode for better concurrent access
+    db.pragma('journal_mode = WAL');
+    // Set busy timeout to wait up to 5 seconds for locks
+    db.pragma('busy_timeout = 5000');
+
+    // Register custom functions
+    _registerFunctions(db);
+
+    const dbName = path.basename(dbPath, path.extname(dbPath));
+
+    return new SqliteClient(db, dbPath, dbName);
+  }
+};
diff --git a/packages/db-connect/bin/apos-db-dump.js b/packages/db-connect/bin/apos-db-dump.js
new file mode 100755
index 0000000000..6a9511e0c1
--- /dev/null
+++ b/packages/db-connect/bin/apos-db-dump.js
@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const dump = require('../lib/dump');
+
+main().then(() => {
+  process.exit(0);
+}).catch(err => {
+  console.error(err.message || err);
+  process.exit(1);
+});
+
+async function main() {
+  const args = process.argv.slice(2);
+  const uri = args.find(a => !a.startsWith('--'));
+  const outputArg = args.find(a => a.startsWith('--output='));
+  const output = outputArg ? outputArg.split('=')[1] : null;
+
+  if (!uri) {
+    throw new Error('Usage: apos-db-dump <uri> [--output=filename]');
+  }
+
+  // Stream NDJSON lines directly to the sink so a large dump never sits
+  // fully in memory.
+  const sink = output
+    ? fs.createWriteStream(output)
+    : process.stdout;
+
+  try {
+    for await (const line of dump(uri)) {
+      if (!sink.write(line + '\n')) {
+        await new Promise(resolve => sink.once('drain', resolve));
+      }
+    }
+  } finally {
+    if (output) {
+      await new Promise((resolve, reject) => {
+        sink.end(err => err ? reject(err) : resolve());
+      });
+    }
+  }
+}
diff --git a/packages/db-connect/bin/apos-db-restore.js b/packages/db-connect/bin/apos-db-restore.js
new file mode 100755
index 0000000000..10abad25ce
--- /dev/null
+++ b/packages/db-connect/bin/apos-db-restore.js
@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const restore = require('../lib/restore');
+
+main().then(() => {
+  process.exit(0);
+}).catch(err => {
+  console.error(err.message || err);
+  process.exit(1);
+});
+
+async function main() {
+  const args = process.argv.slice(2);
+  const uri = args.find(a => !a.startsWith('--'));
+  const inputArg = args.find(a => a.startsWith('--input='));
+  const input = inputArg ? inputArg.split('=')[1] : null;
+
+  if (!uri) {
+    throw new Error('Usage: apos-db-restore <uri> [--input=filename]');
+  }
+
+  // Stream the dump into restore() line-by-line so a large dump never
+  // sits fully in memory. restore() accepts any Readable stream.
+  const source = input
+    ? fs.createReadStream(input, { encoding: 'utf8' })
+    : process.stdin;
+
+  await restore(uri, source);
+}
diff --git a/packages/db-connect/claude-tools/logs/dump-mongodb.log b/packages/db-connect/claude-tools/logs/dump-mongodb.log
new file mode 100644
index 0000000000..f144dba279
--- /dev/null
+++ b/packages/db-connect/claude-tools/logs/dump-mongodb.log
@@ -0,0 +1,11 @@
+
+
+  dump/restore programmatic API (mongodb)
+    ✔ dump yields an async iterable of NDJSON lines (73ms)
+    ✔ should restore a database from a dump stream (69ms)
+    ✔ should copy a database via copyDatabase() (76ms)
+    ✔ should produce independent databases after copy
+
+
+  4 passing (300ms)
+
diff --git a/packages/db-connect/claude-tools/logs/dump-multipostgres.log b/packages/db-connect/claude-tools/logs/dump-multipostgres.log
new file mode 100644
index 0000000000..9dc7b86271
--- /dev/null
+++ b/packages/db-connect/claude-tools/logs/dump-multipostgres.log
@@ -0,0 +1,11 @@
+
+
+  dump/restore programmatic API (multipostgres)
+    ✔ dump yields an async iterable of NDJSON lines (68ms)
+    ✔ should restore a database from a dump stream (78ms)
+    ✔ should copy a database via copyDatabase() (98ms)
+    ✔ should produce independent databases after copy (64ms)
+
+
+  4 passing (426ms)
+
diff --git a/packages/db-connect/claude-tools/logs/dump-postgres.log b/packages/db-connect/claude-tools/logs/dump-postgres.log
new file mode 100644
index 0000000000..5067056af0
--- /dev/null
+++ b/packages/db-connect/claude-tools/logs/dump-postgres.log
@@ -0,0 +1,11 @@
+
+
+  dump/restore programmatic API (postgres)
+    ✔ dump yields an async iterable of NDJSON lines (67ms)
+    ✔ should restore a database from a dump stream (75ms)
+    ✔ should copy a database via copyDatabase() (95ms)
+    ✔ should produce independent databases after copy (62ms)
+
+
+  4 passing (357ms)
+
diff --git a/packages/db-connect/claude-tools/logs/dump-sqlite.log b/packages/db-connect/claude-tools/logs/dump-sqlite.log
new file mode 100644
index 0000000000..a3feb36382
--- /dev/null
+++ b/packages/db-connect/claude-tools/logs/dump-sqlite.log
@@ -0,0 +1,11 @@
+
+
+  dump/restore programmatic API (sqlite)
+    ✔ dump yields an async iterable of NDJSON lines
+    ✔ should restore a database from a dump stream
+    ✔ should copy a database via copyDatabase()
+    ✔ should produce independent databases after copy
+
+
+  4 passing (118ms)
+
diff --git a/packages/db-connect/docs/aggregation.md b/packages/db-connect/docs/aggregation.md
new file mode 100644
index 0000000000..d426fb3ced
--- /dev/null
+++ b/packages/db-connect/docs/aggregation.md
@@ -0,0 +1,118 @@
+# Aggregation
+
+The `aggregate` method runs a pipeline of stages that transform and summarize documents. It returns a cursor with a `toArray()` method.
+
+```js
+const results = await collection.aggregate([
+  { $match: { type: 'order' } },
+  { $group: {
+    _id: '$status',
+    total: { $sum: '$amount' },
+    count: { $sum: 1 }
+  }},
+  { $sort: { total: -1 } }
+]).toArray();
+```
+
+When `$match` is the first pipeline stage, its query is passed to the database for filtering — only matching documents are loaded into memory. All subsequent stages are processed in memory. Place `$match` first whenever possible to reduce the working set.
+
+## Stages
+
+### $match
+
+Filters documents using standard [query operators](./queries.md). When `$match` is the first stage, filtering happens in the database — only matching documents are loaded into memory. Later `$match` stages filter in memory. Place `$match` first whenever possible.
+
+```js
+{ $match: { status: 'active', price: { $gt: 10 } } }
+```
+
+### $group
+
+Groups documents by a key and computes aggregate values. The `_id` field specifies the grouping expression — use a field path (prefixed with `$`) or `null` to group all documents together.
+
+```js
+{ $group: {
+  _id: '$category',
+  totalRevenue: { $sum: '$price' },
+  averagePrice: { $avg: '$price' },
+  count: { $sum: 1 }
+}}
+```
+
+#### Accumulators
+
+| Accumulator | Description |
+|-------------|-------------|
+| `$sum` | Sums numeric values. Use `{ $sum: 1 }` to count documents in each group. Use `{ $sum: '$fieldName' }` to sum a field's values. |
+| `$avg` | Computes the arithmetic mean of numeric values. |
+| `$first` | Returns the value from the *first* document in each group. Order depends on preceding `$sort` stages. |
+| `$last` | Returns the value from the *last* document in each group. |
+
+> **Not supported:** `$min`, `$max`, `$push`, `$addToSet`.
+
+### $project
+
+Reshapes documents by including or excluding fields. Uses the same projection syntax as [`find().project()`](./collections.md).
+
+```js
+{ $project: { name: 1, email: 1, _id: 0 } }
+```
+
+### $unwind
+
+Deconstructs an array field, outputting one document per array element. Each output document replaces the array with a single element.
+
+```js
+{ $unwind: '$tags' }
+
+// Object form also supported:
+{ $unwind: { path: '$tags' } }
+```
+
+Given `{ title: 'Post', tags: ['a', 'b'] }`, `$unwind` produces:
+
+```js
+{ title: 'Post', tags: 'a' }
+{ title: 'Post', tags: 'b' }
+```
+
+### $sort
+
+Sorts documents. `1` for ascending, `-1` for descending.
+
+```js
+{ $sort: { createdAt: -1 } }
+{ $sort: { category: 1, price: -1 } }
+```
+
+### $limit
+
+Limits the number of documents passed to the next stage.
+
+```js
+{ $limit: 10 }
+```
+
+### $skip
+
+Skips the specified number of documents.
+
+```js
+{ $skip: 20 }
+```
+
+## Example: Top Categories by Revenue
+
+```js
+const topCategories = await orders.aggregate([
+  { $match: { status: 'completed' } },
+  { $group: {
+    _id: '$category',
+    revenue: { $sum: '$total' },
+    orders: { $sum: 1 },
+    avgOrder: { $avg: '$total' }
+  }},
+  { $sort: { revenue: -1 } },
+  { $limit: 5 }
+]).toArray();
+```
diff --git a/packages/db-connect/docs/collections.md b/packages/db-connect/docs/collections.md
new file mode 100644
index 0000000000..3a84ac5aa3
--- /dev/null
+++ b/packages/db-connect/docs/collections.md
@@ -0,0 +1,293 @@
+# Collection Methods
+
+All collection methods are accessed from a collection object:
+
+```js
+const db = client.db();
+const articles = db.collection('articles');
+```
+
+## insertOne(doc)
+
+Inserts a single document. If `_id` is not provided, a random 24-character hex string is generated. If an ObjectId is passed as `_id`, it is converted to its hex string representation. `_id` is always a string.
+
+Throws a duplicate key error (code `11000`) if the `_id` or any unique index constraint is violated.
+
+```js
+const result = await collection.insertOne({ title: 'Hello' });
+```
+
+Returns:
+
+```js
+{
+  acknowledged: true,
+  insertedId: '64a1b2c3d4e5f6a7b8c9d0e1',
+  insertedCount: 1,
+  ops: [{ _id: '...', title: 'Hello' }],
+  result: { ok: 1 }
+}
+```
+
+## insertMany(docs)
+
+Inserts an array of documents. Documents are inserted sequentially; insertion stops on the first error.
+
+```js
+const result = await collection.insertMany([
+  { title: 'First' },
+  { title: 'Second' }
+]);
+```
+
+Returns:
+
+```js
+{
+  acknowledged: true,
+  insertedCount: 2,
+  insertedIds: { 0: 'id1', 1: 'id2' },
+  result: { ok: 1 }
+}
+```
+
+`insertedIds` is a map of array index to `_id`.
+
+## findOne(query, options)
+
+Returns the first matching document, or `null` if no documents match.
+
+```js
+const doc = await collection.findOne({ slug: 'hello' });
+
+// With projection
+const doc = await collection.findOne(
+  { slug: 'hello' },
+  { projection: { title: 1, slug: 1 } }
+);
+```
+
+**Options:**
+
+- `projection` — field inclusion or exclusion specification. `{ title: 1, slug: 1 }` returns only those fields plus `_id`. `{ body: 0 }` returns everything except `body`. `_id` is always included unless explicitly excluded with `{ _id: 0 }`.
+
+## find(query)
+
+Returns a cursor for iterating over matching documents. Cursor methods are chainable and must be called before `toArray()`.
+
+```js
+const docs = await collection.find({ type: 'article' })
+  .sort({ createdAt: -1 })
+  .limit(10)
+  .skip(20)
+  .project({ title: 1, slug: 1 })
+  .toArray();
+```
+
+### Cursor Methods
+
+| Method | Description |
+|--------|-------------|
+| `.sort(spec)` | Sort order. `{ field: 1 }` for ascending, `{ field: -1 }` for descending. Multiple fields are supported. |
+| `.limit(n)` | Maximum number of documents to return. `0` means no limit. |
+| `.skip(n)` | Number of documents to skip before returning results. |
+| `.project(spec)` | Field projection, same as the `projection` option on `findOne`. |
+| `.clone()` | Returns an independent copy of the cursor. |
+| `.toArray()` | Executes the query and returns all matching documents as an array. |
+| `.next()` | Returns the next document, or `null` when exhausted. Also accepts a `(err, doc)` callback. |
+| `.count()` | Returns the total count of matching documents. Ignores `limit` and `skip`. |
+| `.addCursorFlag()` | No-op, provided for MongoDB driver compatibility. |
+
+### Async Iteration
+
+Cursors support `for await...of`:
+
+```js
+for await (const doc of collection.find({ type: 'article' })) {
+  // process each document
+}
+```
+
+## updateOne(query, update, options)
+
+Updates the first document matching the query using [update operators](./updates.md).
+
+```js
+await collection.updateOne(
+  { slug: 'hello' },
+  { $set: { title: 'Updated' } }
+);
+
+// With upsert
+await collection.updateOne(
+  { slug: 'hello' },
+  { $set: { title: 'Upserted' } },
+  { upsert: true }
+);
+```
+
+**Options:**
+
+- `upsert` — if `true` and no document matches, inserts a new document. Fields from the query are merged into the new document along with the update operations.
+
+Returns:
+
+```js
+{
+  acknowledged: true,
+  matchedCount: 1,      // 0 if no match (and no upsert)
+  modifiedCount: 1,     // 0 if no changes made
+  upsertedId: null,     // set to the new _id when upserted
+  upsertedCount: 0,     // 1 when upserted
+  result: { nModified: 1, n: 1 }
+}
+```
+
+When upserting, `matchedCount` is `0`, `upsertedCount` is `1`, and `modifiedCount` is `0`.
+
+## updateMany(query, update, options)
+
+Updates all documents matching the query. Same options and return structure as `updateOne`, but counts reflect all matched documents.
+
+```js
+await collection.updateMany(
+  { status: 'draft' },
+  { $set: { status: 'published' } }
+);
+```
+
+## replaceOne(query, replacement, options)
+
+Replaces the entire document (except `_id`) with the given replacement object. This is not an update operation — the replacement document should not contain update operators.
+
+Supports `upsert: true`.
+
+```js
+await collection.replaceOne(
+  { slug: 'hello' },
+  { slug: 'hello', title: 'Replaced', body: 'New content' }
+);
+```
+
+Returns the same structure as `updateOne`.
+
+## deleteOne(query)
+
+Deletes the first document matching the query.
+
+```js
+const result = await collection.deleteOne({ slug: 'hello' });
+```
+
+Returns:
+
+```js
+{
+  acknowledged: true,
+  deletedCount: 1,  // 0 if no match
+  result: { ok: 1 }
+}
+```
+
+## deleteMany(query)
+
+Deletes all documents matching the query.
+
+```js
+const result = await collection.deleteMany({ status: 'archived' });
+// result.deletedCount — number of documents removed
+```
+
+## findOneAndUpdate(query, update, options)
+
+Finds a document, updates it, and returns it. Note: this operation uses a read-modify-write pattern and is **not atomic**. See the [Atomicity](../README.md#atomicity) section in the README.
+
+```js
+const result = await collection.findOneAndUpdate(
+  { slug: 'hello' },
+  { $inc: { views: 1 } },
+  { returnDocument: 'after' }
+);
+// result.value — the document
+```
+
+**Options:**
+
+- `returnDocument` — `'before'` (default) returns the document as it was before the update. `'after'` returns the updated document.
+- `upsert` — if `true`, inserts a new document when no match is found.
+
+## findOneAndReplace(query, replacement, options)
+
+Like `findOneAndUpdate`, but replaces the entire document. Same options.
+
+## countDocuments(query)
+
+Returns the count of documents matching the query.
+
+```js
+const count = await collection.countDocuments({ type: 'article' });
+```
+
+## distinct(field, query)
+
+Returns an array of distinct values for a field across all matching documents.
+
+Array fields are automatically flattened — if some documents have a scalar value and others have an array, all values are collected and deduplicated.
+
+```js
+const types = await collection.distinct('type');
+const tags = await collection.distinct('tags', { published: true });
+
+// If documents are: { tags: 'a' }, { tags: ['a', 'b'] }
+// Result: ['a', 'b']
+```
+
+## bulkWrite(operations)
+
+Executes an array of write operations in sequence.
+
+```js
+await collection.bulkWrite([
+  { insertOne: { document: { title: 'New' } } },
+  { updateOne: { filter: { slug: 'old' }, update: { $set: { title: 'Updated' } } } },
+  { updateMany: { filter: { status: 'draft' }, update: { $set: { reviewed: true } } } },
+  { replaceOne: { filter: { slug: 'replace-me' }, replacement: { slug: 'replace-me', title: 'Replaced' } } },
+  { deleteOne: { filter: { slug: 'gone' } } },
+  { deleteMany: { filter: { status: 'archived' } } }
+]);
+```
+
+Returns:
+
+```js
+{
+  acknowledged: true,
+  insertedCount: 1,
+  modifiedCount: 2,
+  deletedCount: 3,
+  upsertedCount: 0,
+  insertedIds: { 0: 'new-id' },
+  upsertedIds: {}
+}
+```
+
+## aggregate(pipeline)
+
+Runs an aggregation pipeline. See [Aggregation](./aggregation.md) for supported stages and accumulators.
+
+```js
+const results = await collection.aggregate([
+  { $match: { type: 'order' } },
+  { $group: { _id: '$status', total: { $sum: '$amount' } } }
+]).toArray();
+```
+
+## drop()
+
+Drops the collection and all its data.
+
+## rename(newName)
+
+Renames the collection.
+
+See also: [Database and Client Methods](./database.md) for `client.db()`, `db.listCollections()`, `db.dropDatabase()`, and other database-level operations.
diff --git a/packages/db-connect/docs/database.md b/packages/db-connect/docs/database.md
new file mode 100644
index 0000000000..a9caaa2371
--- /dev/null
+++ b/packages/db-connect/docs/database.md
@@ -0,0 +1,94 @@
+# Database and Client Methods
+
+## Client
+
+`connect(uri)` returns a client object. The client manages the connection pool and provides access to databases.
+
+```js
+const connect = require('@apostrophecms/db-connect');
+
+const client = await connect('postgres://localhost:5432/mydb');
+const db = client.db();
+// ...
+await client.close();
+```
+
+### client.db(name)
+
+Returns a database object. When called without a name, returns the default database derived from the connection URI.
+
+When called with a name, the behavior depends on the adapter:
+
+**MongoDB:** Behaves as in the native driver — each name accesses a separate MongoDB database on the same server.
+
+**PostgreSQL (single mode, `postgres://`):** `db()` or `db('mydb')` (matching the database name from the connection URI) both return the default database. Passing a different name throws an error — there is no schema isolation in single mode.
+
+**PostgreSQL (multi-schema mode, `multipostgres://`):** Each name must be a full virtual database name in the form `realdb-schema`, where `realdb` matches the physical database name from the connection URI. The schema name is everything after the **last** hyphen — this accommodates database names that themselves contain hyphens (e.g., `my-shared-db-tenant1` uses real database `my-shared-db` and schema `tenant1`). For example, if the URI is `multipostgres://localhost:5432/shareddb-tenant1`, then `db('shareddb-tenant2')` accesses the `tenant2` schema. Names that don't start with `realdb-` are rejected. Schemas are created automatically on first use.
+
+**SQLite:** Each name opens a separate file in the same directory as the original database file, using the same extension. For example, if the original URI points to `data/myapp.sqlite`, then `db('other')` opens `data/other.sqlite`. This provides true separation — each named database has its own tables and data.
+
+### client.close()
+
+Closes the connection pool. After calling `close()`, no further database operations should be attempted.
+
+## Database
+
+### db.collection(name)
+
+Returns a collection object. The collection is created automatically on first use (no need to call `createCollection` first). See [Collection Methods](./collections.md) for all available operations.
+
+```js
+const articles = db.collection('articles');
+```
+
+### db.listCollections()
+
+Returns a cursor-like object with a `toArray()` method that lists all collections in the database.
+
+```js
+const collections = await db.listCollections().toArray();
+// [{ name: 'articles' }, { name: 'users' }, ...]
+```
+
+### db.createCollection(name)
+
+Creates a collection explicitly. In practice this is rarely needed, since collections are created automatically when first accessed.
+
+```js
+await db.createCollection('newCollection');
+```
+
+### db.dropDatabase()
+
+Drops the entire database:
+
+- **MongoDB:** Drops the database.
+- **PostgreSQL (single mode):** Drops all collection tables.
+- **PostgreSQL (multi-schema mode):** Drops the schema and all its tables.
+- **SQLite:** Drops all tables and indexes, but does not delete the database file.
+
+```js
+await db.dropDatabase();
+```
+
+### db.admin().listDatabases()
+
+Returns a list of databases. In `multipostgres` mode, this lists schemas as full virtual database names.
+
+```js
+const { databases } = await db.admin().listDatabases();
+// MongoDB: [{ name: 'mydb' }, { name: 'otherdb' }, ...]
+// multipostgres: [{ name: 'shareddb-tenant1' }, { name: 'shareddb-tenant2' }, ...]
+```
+
+## Document Size Limits
+
+Each adapter has a different maximum document size. For portable applications, assume MongoDB's 16 MB cap applies everywhere — both PostgreSQL and SQLite accept considerably larger documents, but leaning on those higher ceilings makes the data non-portable between adapters and produces unpredictable query performance.
+
+| Adapter      | Per-document limit                                         |
+|--------------|------------------------------------------------------------|
+| MongoDB      | 16 MB (BSON `maxBsonObjectSize`)                           |
+| PostgreSQL   | JSONB field up to ~255 MB after TOAST compression (practical limit well under 1 GB)  |
+| SQLite       | Row/TEXT column capped by `SQLITE_MAX_LENGTH` (default 1 GB); `JSON1` parser also has internal limits |
+
+Exceeding the adapter-native limit produces an adapter-native error (not a portable one). Keep documents well under 16 MB to stay within the MongoDB cap and to avoid TOAST storage for most rows in PostgreSQL.
diff --git a/packages/db-connect/docs/dump-restore.md b/packages/db-connect/docs/dump-restore.md
new file mode 100644
index 0000000000..ab17cf018e
--- /dev/null
+++ b/packages/db-connect/docs/dump-restore.md
@@ -0,0 +1,178 @@
+# Dump and Restore
+
+`@apostrophecms/db-connect` ships CLI tools and a programmatic API for exporting and importing databases in a portable JSONL format. Because the format is adapter-agnostic, you can dump from one database type and restore to another.
+
+## CLI Tools
+
+### Running the commands
+
+Any ApostropheCMS project has `@apostrophecms/db-connect` installed as a transitive dependency, so the `apos-db-dump` and `apos-db-restore` binaries are present in `node_modules/.bin` of every Apostrophe project. There are three common ways to invoke them:
+
+**Project-local with `npx` (recommended for one-off use):**
+
+```bash
+cd /path/to/your/apostrophe/project
+npx apos-db-dump mongodb://localhost:27017/mydb --output=backup.jsonl
+npx apos-db-restore postgres://localhost:5432/mydb --input=backup.jsonl
+```
+
+`npx` finds the binary in the project's `node_modules/.bin`, so no global installation is needed.
+
+**Project-local via npm scripts:**
+
+Add entries to your project's `package.json`:
+
+```json
+{
+  "scripts": {
+    "db:dump": "apos-db-dump",
+    "db:restore": "apos-db-restore"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run db:dump -- mongodb://localhost:27017/mydb --output=backup.jsonl
+```
+
+**Globally installed (for operators who manage many projects):**
+
+```bash
+npm install -g @apostrophecms/db-connect
+apos-db-dump mongodb://localhost:27017/mydb --output=backup.jsonl
+```
+
+A global install puts `apos-db-dump` and `apos-db-restore` directly on your `PATH`. The global copy is independent of any particular project, so use the same major version you have installed in your projects to ensure the JSONL format matches.
+
+The examples in the rest of this document drop the `npx` prefix for readability. Prepend `npx` (or use one of the other invocation styles above) according to how you've set things up.
+
+### apos-db-dump
+
+```bash
+# Dump to a file
+apos-db-dump postgres://localhost:5432/mydb --output=backup.jsonl
+
+# Dump to stdout
+apos-db-dump sqlite:///path/to/db.sqlite
+```
+
+### apos-db-restore
+
+```bash
+# Restore from a file
+apos-db-restore postgres://localhost:5432/mydb --input=backup.jsonl
+
+# Restore from stdin
+cat backup.jsonl | apos-db-restore sqlite:///path/to/newdb.sqlite
+```
+
+### Cross-Database Migration
+
+Pipe `dump` output directly into `restore` to migrate between backends:
+
+```bash
+# MongoDB to PostgreSQL
+apos-db-dump mongodb://localhost:27017/mydb | apos-db-restore postgres://localhost:5432/mydb
+
+# PostgreSQL to SQLite
+apos-db-dump postgres://localhost:5432/mydb | apos-db-restore sqlite:///path/to/local.db
+```
+
+### multipostgres URIs
+
+`multipostgres://` URIs are fully supported. The URI path is a complete virtual database name, split at the **last hyphen** into a real PostgreSQL database name and a schema name. This lets you dump or restore a single tenant's schema directly from the command line:
+
+```bash
+# Dump just the tenant1 schema from the shareddb database
+apos-db-dump multipostgres://localhost:5432/shareddb-tenant1 --output=tenant1.jsonl
+
+# Restore into a different tenant's schema
+apos-db-restore multipostgres://localhost:5432/shareddb-tenant2 --input=tenant1.jsonl
+```
+
+The last-hyphen rule accommodates real database names that themselves contain hyphens — `multipostgres://localhost:5432/my-shared-db-tenant1` connects to the `my-shared-db` database and operates on the `tenant1` schema. A multipostgres URI with no hyphen in the path is rejected, since it cannot specify a complete virtual database.
+
+You can migrate between a single-database `postgres://` URI and a tenant schema by mixing protocols on either side of the pipe:
+
+```bash
+# Copy a standalone database into a tenant schema
+apos-db-dump postgres://localhost:5432/mydb | apos-db-restore multipostgres://localhost:5432/shareddb-tenant1
+
+# Extract a tenant schema into its own standalone database
+apos-db-dump multipostgres://localhost:5432/shareddb-tenant1 | apos-db-restore postgres://localhost:5432/tenant1db
+```
+
+## Programmatic API
+
+```js
+const { dump, restore, copyDatabase } = require('@apostrophecms/db-connect');
+```
+
+### dump(uri)
+
+Returns an **async iterable** that yields one JSONL record per line (no trailing newlines). The dump is produced incrementally so large databases never sit fully in memory.
+
+```js
+for await (const line of dump('postgres://localhost:5432/mydb')) {
+  process.stdout.write(line + '\n');
+}
+```
+
+To collect the entire dump as a string (only safe for small databases):
+
+```js
+const lines = [];
+for await (const line of dump(uri)) lines.push(line);
+const data = lines.join('\n') + '\n';
+```
+
+Also accepts an already-connected `db` object instead of a URI string.
+
+### restore(uri, source)
+
+Imports a JSONL stream into the database. `source` can be any of:
+
+- an async iterable of JSONL lines (as produced by `dump()`)
+- an iterable / array of JSONL lines
+- a Node Readable stream (e.g. `process.stdin`, `fs.createReadStream(...)`)
+- a single JSONL string — retained for convenience, not recommended for large dumps
+
+```js
+// Async iterable
+await restore('sqlite:///path/to/db.sqlite', dump(sourceUri));
+
+// Readable stream
+await restore('sqlite:///path/to/db.sqlite', fs.createReadStream('backup.jsonl'));
+
+// String (small dumps only)
+await restore('sqlite:///path/to/db.sqlite', dataString);
+```
+
+Also accepts an already-connected `db` object.
+
+### copyDatabase(sourceUri, destUri)
+
+Copies all data directly from one database to another by piping `dump()` straight into `restore()`. No intermediate buffer — works regardless of database size.
+
+```js
+await copyDatabase(
+  'postgres://localhost:5432/source',
+  'sqlite:///path/to/dest.db'
+);
+```
+
+## JSONL Format
+
+The dump format is JSONL (one JSON object per line). Each collection begins with a header line containing the collection name and index definitions, followed by one line per document.
+
+```
+{"collection":"articles","indexes":[{"key":{"slug":1},"unique":true}]}
+{"_id":"abc123","title":"Hello","slug":"hello"}
+{"_id":"def456","title":"World","slug":"world"}
+{"collection":"users","indexes":[]}
+{"_id":"user1","email":"alice@example.com"}
+```
+
+On restore, indexes are recreated from the header. Index creation failures are fatal — a failed `createIndex` is a real problem (invalid index name, conflicting definition, backend incompatibility) and should surface to the caller rather than being silently tolerated.
diff --git a/packages/db-connect/docs/indexes.md b/packages/db-connect/docs/indexes.md
new file mode 100644
index 0000000000..130c89500d
--- /dev/null
+++ b/packages/db-connect/docs/indexes.md
@@ -0,0 +1,114 @@
+# Indexes
+
+Indexes improve query performance and enforce uniqueness constraints.
+
+## createIndex(keys, options)
+
+Creates an index on one or more fields. Returns the index name as a string.
+
+```js
+await collection.createIndex({ slug: 1 });
+```
+
+Field values in the `keys` object:
+
+- `1` — ascending index
+- `-1` — descending index
+- `'text'` — full-text search index
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `name` | Custom index name. If omitted, a name is generated from the field names (e.g., `slug_1`). |
+| `unique` | If `true`, enforces a uniqueness constraint. Inserting a duplicate value throws a duplicate key error (code `11000`). |
+| `sparse` | If `true`, only indexes documents where the indexed field exists. Documents without the field are omitted from the index. |
+| `type` | Index value type: `'number'`, `'date'`, or omitted for the default text-based index. See below. |
+
+### Compound Indexes
+
+Pass multiple fields to create a compound index:
+
+```js
+await collection.createIndex({ type: 1, createdAt: -1 });
+await collection.createIndex({ email: 1, tenant: 1 }, { unique: true });
+```
+
+## Index Types
+
+By default, indexed values are extracted from the JSON document as text. This works correctly for equality checks (`$eq`, `$in`) and pattern matching (`$regex`), but **not** for range comparisons on numbers or dates, because text comparison produces incorrect ordering (e.g., `"9"` sorts after `"10"`).
+
+### Numeric Indexes
+
+Use `type: 'number'` when the field contains numeric values and you need range queries:
+
+```js
+await collection.createIndex({ price: 1 }, { type: 'number' });
+
+// Now these queries use the index correctly:
+await collection.find({ price: { $gt: 10, $lte: 100 } }).toArray();
+```
+
+Without the `number` type, the comparison is text-based and `{ $gt: 9 }` would not match `10`.
+
+### Date Indexes
+
+Use `type: 'date'` for fields that store dates. Dates are stored internally as `{ $date: "ISO-8601-string" }`, and the date index type extracts the ISO string for correct lexicographic ordering.
+
+```js
+await collection.createIndex({ createdAt: 1 }, { type: 'date' });
+
+await collection.find({ createdAt: { $gt: new Date('2024-01-01') } }).toArray();
+```
+
+ISO-8601 strings sort correctly in chronological order because they are fixed-width and most-significant-digit-first.
+
+### Text Indexes
+
+Use `'text'` as the field value (not as an option) to create a full-text search index:
+
+```js
+await collection.createIndex({ title: 'text', body: 'text' });
+
+await collection.find({ $text: { $search: 'tutorial' } }).toArray();
+```
+
+In PostgreSQL, this creates a GIN index using `to_tsvector`. In SQLite, this creates an FTS5 virtual table kept in sync with the collection, providing proper tokenized full-text search with BM25 relevance scoring.
+
+### Combined Options
+
+Index types can be combined with other options:
+
+```js
+await collection.createIndex(
+  { publishedAt: 1 },
+  { type: 'date', unique: true, sparse: true }
+);
+```
+
+## Array Fields
+
+When a query matches a scalar value against an array field, the adapters handle this transparently. For example, `{ tags: 'news' }` matches a document where `tags` is `['news', 'featured']`. This works with all query operators including `$in`, `$all`, and comparison operators.
+
+Indexes on array fields work with this behavior — scalar lookups against array elements use the index.
+
+## dropIndex(name)
+
+Drops an index by name.
+
+```js
+await collection.dropIndex('slug_1');
+```
+
+## indexes()
+
+Returns an array of index metadata for the collection.
+
+```js
+const idxs = await collection.indexes();
+// [
+//   { name: '_id_', key: { _id: 1 }, unique: true },
+//   { name: 'slug_1', key: { slug: 1 } },
+//   { name: 'price_1', key: { price: 1 }, type: 'number' }
+// ]
+```
diff --git a/packages/db-connect/docs/queries.md b/packages/db-connect/docs/queries.md
new file mode 100644
index 0000000000..4fffd40015
--- /dev/null
+++ b/packages/db-connect/docs/queries.md
@@ -0,0 +1,233 @@
+# Query Operators
+
+Queries filter documents by matching field values against conditions. A query is a plain object where each key is a field name (or a logical operator) and each value is a match condition.
+
+```js
+// Implicit $eq — matches documents where status is 'active'
+{ status: 'active' }
+
+// Explicit operator
+{ age: { $gte: 18 } }
+
+// Multiple fields — all must match (implicit $and)
+{ status: 'active', type: 'article' }
+```
+
+## Dot Notation
+
+Nested fields are accessed with dot notation:
+
+```js
+{ 'address.city': 'Portland' }
+{ 'meta.tags': 'featured' }
+```
+
+## Comparison Operators
+
+### $eq
+
+Matches documents where the field equals the given value. This is the default when a plain value is used.
+
+```js
+// These are equivalent:
+{ status: 'active' }
+{ status: { $eq: 'active' } }
+```
+
+**Null matching:** `{ field: null }` matches documents where the field is `null` *and* documents where the field is missing entirely.
+
+**Array matching:** When the field contains an array, `$eq` matches if *any element* of the array equals the value. `{ tags: 'news' }` matches `{ tags: ['news', 'featured'] }`.
+
+### $ne
+
+Matches documents where the field does *not* equal the given value. Documents where the field is missing also match (since missing is not equal to any value).
+
+```js
+{ status: { $ne: 'archived' } }
+```
+
+### $gt / $gte / $lt / $lte
+
+Range comparisons. For these to work correctly on numeric and date fields, ensure the appropriate [index type](./indexes.md) is set.
+
+```js
+{ price: { $gt: 10 } }
+{ price: { $gte: 10, $lte: 100 } }
+{ createdAt: { $gt: new Date('2024-01-01') } }
+```
+
+**Numbers:** Values are cast to numeric type before comparison, so `9` sorts before `10` (not after, as it would in a text comparison).
+
+**Dates:** Dates stored as `{ $date: "ISO-8601-string" }` are compared as ISO strings, which sort correctly for chronological order.
+
+**Missing fields:** Documents where the field is missing do *not* match range operators.
+
+### $in
+
+Matches documents where the field's value is any of the values in the given array.
+
+```js
+{ status: { $in: ['active', 'pending'] } }
+```
+
+An empty array matches nothing. If the array contains `null`, documents with missing fields also match.
+
+**Array fields:** If the document field is an array, matches if *any element* of the field is in the `$in` array.
+
+### $nin
+
+Matches documents where the field's value is *not* any of the values in the given array.
+
+```js
+{ status: { $nin: ['archived', 'deleted'] } }
+```
+
+An empty array matches everything. If the array contains `null`, documents with missing fields are *excluded*. If the array does not contain `null`, documents with missing fields *are* included.
+
+## Logical Operators
+
+### $and
+
+Matches documents that satisfy *all* of the given subqueries. Useful when you need multiple conditions on the same field.
+
+```js
+{ $and: [
+  { price: { $gte: 10 } },
+  { price: { $lte: 100 } }
+]}
+```
+
+Multiple conditions on different fields in a single object are already an implicit `$and`:
+
+```js
+// These are equivalent:
+{ status: 'active', type: 'article' }
+{ $and: [{ status: 'active' }, { type: 'article' }] }
+```
+
+### $or
+
+Matches documents that satisfy *at least one* of the given subqueries.
+
+```js
+{ $or: [
+  { status: 'active' },
+  { featured: true }
+]}
+```
+
+### $not
+
+Negates a single operator expression. Applied to a specific field.
+
+```js
+{ price: { $not: { $gt: 100 } } }
+```
+
+## Element Operators
+
+### $exists
+
+Matches documents based on whether a field is present in the document.
+
+```js
+{ optionalField: { $exists: true } }   // field is present (even if null)
+{ optionalField: { $exists: false } }  // field is absent
+```
+
+Note: `$exists: true` matches documents where the field is present, including when the value is `null`. This differs from `{ field: { $ne: null } }`, which excludes both missing and null-valued fields.
+
+## Evaluation Operators
+
+### $regex
+
+Matches string fields against a regular expression.
+
+```js
+{ name: { $regex: '^John' } }
+{ name: { $regex: 'smith', $options: 'i' } }  // case-insensitive
+```
+
+Use `$options: 'i'` for case-insensitive matching.
+
+**Array fields:** If the field contains an array of strings, matches if *any element* matches the pattern.
+
+A JavaScript `RegExp` object can also be passed directly as the value:
+
+```js
+{ name: /^John/i }
+```
+
+### $text
+
+Full-text search. Requires a [text index](./indexes.md) on the collection.
+
+```js
+{ $text: { $search: 'apostrophe tutorial' } }
+```
+
+The search uses OR semantics — a document matches if it contains *any* of the search terms. The text search examines the fields declared in the text index (for Apostrophe, typically `highSearchText`, `lowSearchText`, `title`, and `searchBoost`).
+
+**Ranking:** Results can be ordered by relevance using the MongoDB-compatible `{ $meta: 'textScore' }` sort, and the score can be projected as well:
+
+```js
+collection
+  .find({ $text: { $search: 'apostrophe tutorial' } })
+  .sort({ score: { $meta: 'textScore' } })
+  .project({ score: { $meta: 'textScore' } })
+  .toArray();
+```
+
+Without a `$meta: 'textScore'` sort, results are returned in unspecified order — use `.sort()` if you need a deterministic order.
+
+**PostgreSQL:** Uses `to_tsvector`/`to_tsquery` with the `simple` dictionary, backed by a GIN index. Relevance scoring uses `ts_rank`. Special characters in search terms are stripped.
+
+**SQLite:** Uses an FTS5 virtual table kept in sync with the collection via triggers. Relevance scoring uses BM25. Tokenization is FTS5's default (Unicode-aware, case-insensitive) — there is no stemming or stop word removal, so word forms are matched literally.
+
+## Array Operators
+
+### $all
+
+Matches documents where an array field contains *all* of the specified values.
+
+```js
+{ tags: { $all: ['javascript', 'tutorial'] } }
+```
+
+The array must contain every value in the `$all` array, but may contain additional values.
+
+### $size
+
+Matches documents where an array field has the specified number of elements.
+
+```js
+{ tags: { $size: 2 } }  // matches arrays with exactly 2 elements
+{ tags: { $size: 0 } }  // matches empty arrays
+```
+
+The value must be a non-negative integer. Only matches fields that are arrays — documents where the field is missing or not an array are excluded.
+
+## Array Field Matching
+
+Array fields are queried transparently. A scalar match against an array field succeeds if *any element* of the array matches:
+
+```js
+// Document: { tags: ['news', 'featured'] }
+
+{ tags: 'news' }                          // matches (element equality)
+{ tags: { $in: ['news', 'other'] } }     // matches (element in array)
+{ tags: { $regex: '^new' } }             // matches (element matches pattern)
+{ tags: { $all: ['news', 'featured'] } } // matches (all elements present)
+```
+
+### Array Matching and Index Usage
+
+In PostgreSQL and SQLite, there is a trade-off between transparent array matching and index usage.
+
+Simple equality queries like `{ tags: 'news' }` use PostgreSQL's `@>` (jsonb containment) operator, which transparently matches both scalar values and array elements. However, `@>` does not use standard btree indexes.
+
+Explicit operator queries like `{ tags: { $eq: 'news' } }` use strict equality (`=`), which can use btree indexes but does *not* match array elements — it only matches if the entire field value is the scalar `'news'`.
+
+The same applies to `$in`: simple `$in` uses containment (array-aware, not indexed by btree), while indexed fields are more efficient with direct equality lookups.
+
+For fields that are always arrays and need indexed queries, consider using `$all` or restructuring the query. For fields that are always scalars, `$eq` and btree indexes work as expected.
diff --git a/packages/db-connect/docs/updates.md b/packages/db-connect/docs/updates.md
new file mode 100644
index 0000000000..ed27a8bb1c
--- /dev/null
+++ b/packages/db-connect/docs/updates.md
@@ -0,0 +1,99 @@
+# Update Operators
+
+Update operators modify documents in place. They are used with `updateOne`, `updateMany`, `findOneAndUpdate`, and in `bulkWrite` operations.
+
+Multiple operators can be combined in a single update:
+
+```js
+await collection.updateOne(
+  { _id: 'abc' },
+  {
+    $set: { title: 'Updated' },
+    $inc: { revision: 1 },
+    $currentDate: { updatedAt: true }
+  }
+);
+```
+
+## $set
+
+Sets the value of one or more fields. Creates the field if it does not exist. Overwrites the existing value if it does.
+
+```js
+{ $set: { title: 'New Title' } }
+{ $set: { 'address.city': 'Portland', 'address.state': 'OR' } }
+```
+
+Dot notation creates nested structures automatically. An `undefined` value is stored as `null`.
+
+## $unset
+
+Removes one or more fields from the document. The value given for each field is ignored — any truthy value works.
+
+```js
+{ $unset: { obsoleteField: 1 } }
+{ $unset: { 'nested.field': '', otherField: true } }
+```
+
+## $inc
+
+Increments a numeric field by the given amount. If the field does not exist, it is created with the increment as its value (starting from `0`).
+
+```js
+{ $inc: { views: 1 } }           // increment by 1
+{ $inc: { stock: -3 } }          // decrement by 3
+{ $inc: { views: 1, shares: 1 } } // increment multiple fields
+```
+
+Use negative values to decrement.
+
+**Upsert behavior:** When used with `upsert: true` and no document matches, `$inc` creates the field with the increment value (e.g., `{ $inc: { count: 5 } }` creates `count: 5`).
+
+## $push
+
+Appends a value to an array field. Creates the array if the field does not exist.
+
+```js
+{ $push: { tags: 'new-tag' } }
+{ $push: { comments: { author: 'Alice', text: 'Great post' } } }
+```
+
+Each `$push` appends a single element. To append to multiple array fields, include them all in one `$push`:
+
+```js
+{ $push: { tags: 'new-tag', categories: 'tutorials' } }
+```
+
+> **Note:** The `$each` modifier is not supported. To add multiple elements, use multiple updates or a read-modify-write pattern.
+
+## $pull
+
+Removes *all* occurrences of a value from an array field. Uses deep equality, so it works with objects and nested arrays.
+
+```js
+{ $pull: { tags: 'old-tag' } }
+{ $pull: { items: { sku: 'ABC123' } } }  // removes matching objects
+```
+
+## $addToSet
+
+Adds a value to an array field only if it is not already present. Uses deep equality for comparison.
+
+```js
+{ $addToSet: { tags: 'unique-tag' } }
+```
+
+If the value already exists in the array, the array is not modified.
+
+> **Note:** The `$each` modifier is not supported.
+
+## $currentDate
+
+Sets a field to the current date as a JavaScript `Date` object.
+
+```js
+{ $currentDate: { updatedAt: true } }
+{ $currentDate: { updatedAt: { $type: 'date' } } }
+```
+
+Both forms are equivalent. Only the `'date'` type is supported.
diff --git a/packages/db-connect/eslint.config.js b/packages/db-connect/eslint.config.js
new file mode 100644
index 0000000000..e0cd3f580e
--- /dev/null
+++ b/packages/db-connect/eslint.config.js
@@ -0,0 +1,6 @@
+const apostrophe = require('eslint-config-apostrophe').default;
+const { defineConfig } = require('eslint/config');
+
+module.exports = defineConfig([
+  apostrophe
+]);
diff --git a/packages/db-connect/index.js b/packages/db-connect/index.js
new file mode 100644
index 0000000000..0d75439434
--- /dev/null
+++ b/packages/db-connect/index.js
@@ -0,0 +1,44 @@
+const mongodbAdapter = require(
+  './adapters/mongodb.js'
+);
+const postgresAdapter = require(
+  './adapters/postgres.js'
+);
+const sqliteAdapter = require(
+  './adapters/sqlite.js'
+);
+
+const connect = async function(uri, options = {}) {
+  // Build adapter map: built-ins first, then custom overrides
+  const named = new Map();
+  for (const adapter of [
+    mongodbAdapter,
+    postgresAdapter,
+    sqliteAdapter,
+    ...(options.adapters || [])
+  ]) {
+    named.set(adapter.name, adapter);
+  }
+
+  // Match protocol from URI
+  const matches = uri.match(/^([^:]+):\/\//);
+  if (!matches) {
+    throw new Error(`Invalid database URI: ${uri}`);
+  }
+  const protocol = matches[1];
+
+  for (const adapter of named.values()) {
+    if (adapter.protocols.includes(protocol)) {
+      return adapter.connect(uri, options);
+    }
+  }
+
+  throw new Error(
+    `No adapter found for protocol: ${protocol}`
+  );
+};
+
+module.exports = connect;
+module.exports.dump = require('./lib/dump');
+module.exports.restore = require('./lib/restore');
+module.exports.copyDatabase = require('./lib/copy-database');
diff --git a/packages/db-connect/lib/aggregation-cursor.js b/packages/db-connect/lib/aggregation-cursor.js
new file mode 100644
index 0000000000..31d0cd7883
--- /dev/null
+++ b/packages/db-connect/lib/aggregation-cursor.js
@@ -0,0 +1,408 @@
+const {
+  getNestedField,
+  setNestedField,
+  deepEqual,
+  validateInteger
+} = require('./shared');
+
+class AggregationCursor {
+  constructor(collection, pipeline) {
+    this._collection = collection;
+    this._pipeline = pipeline;
+  }
+
+  async toArray() {
+    let stages = this._pipeline;
+    let query = {};
+    if (stages.length > 0 && stages[0].$match) {
+      query = stages[0].$match;
+      stages = stages.slice(1);
+    }
+    let docs = await this._collection.find(query).toArray();
+
+    for (const stage of stages) {
+      const [ op, value ] = Object.entries(stage)[0];
+
+      switch (op) {
+        case '$match':
+          docs = docs.filter(doc => matchesQuery(doc, value));
+          break;
+        case '$group':
+          docs = this._processGroup(docs, value);
+          break;
+        case '$project':
+          docs = docs.map(doc => applyAggregateProject(doc, value));
+          break;
+        case '$unwind':
+          docs = this._processUnwind(docs, value);
+          break;
+        case '$sort':
+          docs = this._processSort(docs, value);
+          break;
+        case '$limit':
+          docs = docs.slice(0, validateInteger(value, '$limit'));
+          break;
+        case '$skip':
+          docs = docs.slice(validateInteger(value, '$skip'));
+          break;
+        default:
+          throw new Error(`Unsupported aggregation stage: ${op}`);
+      }
+    }
+
+    return docs;
+  }
+
+  _processGroup(docs, groupSpec) {
+    const groups = new Map();
+    const groupField = groupSpec._id;
+
+    for (const doc of docs) {
+      let groupKey;
+      if (typeof groupField === 'string' && groupField.startsWith('$')) {
+        groupKey = getNestedField(doc, groupField.substring(1));
+      } else if (groupField !== null && typeof groupField === 'object') {
+        groupKey = {};
+        for (const [ k, v ] of Object.entries(groupField)) {
+          if (typeof v === 'string' && v.startsWith('$')) {
+            groupKey[k] = getNestedField(doc, v.substring(1));
+          } else {
+            groupKey[k] = v;
+          }
+        }
+      } else {
+        groupKey = groupField;
+      }
+
+      const keyStr = JSON.stringify(groupKey);
+      if (!groups.has(keyStr)) {
+        groups.set(keyStr, {
+          _id: groupKey,
+          docs: []
+        });
+      }
+      groups.get(keyStr).docs.push(doc);
+    }
+
+    const results = [];
+    for (const [ , group ] of groups) {
+      const result = { _id: group._id };
+
+      for (const [ field, expr ] of Object.entries(groupSpec)) {
+        if (field === '_id') {
+          continue;
+        }
+
+        if (expr.$sum) {
+          const sumField = expr.$sum;
+          if (typeof sumField === 'string' && sumField.startsWith('$')) {
+            result[field] = group.docs.reduce((sum, doc) => {
+              return sum + (getNestedField(doc, sumField.substring(1)) || 0);
+            }, 0);
+          } else if (typeof sumField === 'number') {
+            result[field] = group.docs.length * sumField;
+          }
+        } else if (expr.$avg) {
+          const avgField = expr.$avg.substring(1);
+          const values = group.docs
+            .map(doc => getNestedField(doc, avgField))
+            .filter(v => v != null);
+          result[field] = values.length > 0
+            ? values.reduce((a, b) => a + b, 0) / values.length
+            : null;
+        } else if (expr.$first) {
+          const firstField = expr.$first.substring(1);
+          result[field] = group.docs.length > 0
+            ? getNestedField(group.docs[0], firstField)
+            : null;
+        } else if (expr.$last) {
+          const lastField = expr.$last.substring(1);
+          const last = group.docs[group.docs.length - 1];
+          result[field] = group.docs.length > 0
+            ? getNestedField(last, lastField)
+            : null;
+        }
+      }
+
+      results.push(result);
+    }
+
+    return results;
+  }
+
+  _processUnwind(docs, field) {
+    const fieldName = field.startsWith('$') ? field.substring(1) : field;
+    const results = [];
+
+    for (const doc of docs) {
+      const arr = getNestedField(doc, fieldName);
+      if (Array.isArray(arr)) {
+        for (const item of arr) {
+          const newDoc = JSON.parse(JSON.stringify(doc));
+          setNestedField(newDoc, fieldName, item);
+          results.push(newDoc);
+        }
+      } else {
+        results.push(doc);
+      }
+    }
+
+    return results;
+  }
+
+  _processSort(docs, sortSpec) {
+    return docs.slice().sort((a, b) => {
+      for (const [ field, direction ] of Object.entries(sortSpec)) {
+        const aVal = getNestedField(a, field);
+        const bVal = getNestedField(b, field);
+
+        if (aVal < bVal) {
+          return direction === -1 ? 1 : -1;
+        }
+        if (aVal > bVal) {
+          return direction === -1 ? -1 : 1;
+        }
+      }
+      return 0;
+    });
+  }
+}
+
+function applyAggregateProject(doc, spec) {
+  const result = {};
+  let includeId = true;
+  for (const [ key, value ] of Object.entries(spec)) {
+    if (key === '_id') {
+      if (value === 0 || value === false) {
+        includeId = false;
+      } else if (value === 1 || value === true) {
+        includeId = true;
+      }
+      continue;
+    }
+    if (value === 0 || value === false) {
+      continue;
+    }
+    if (value === 1 || value === true) {
+      const v = getNestedField(doc, key);
+      if (v !== undefined) {
+        setNestedField(result, key, v);
+      }
+    } else if (typeof value === 'string' && value.startsWith('$')) {
+      const refPath = value.slice(1);
+      const v = getNestedField(doc, refPath);
+      if (v !== undefined) {
+        setNestedField(result, key, v);
+      }
+    } else {
+      setNestedField(result, key, value);
+    }
+  }
+  if (includeId && doc._id !== undefined) {
+    result._id = doc._id;
+  }
+  return result;
+}
+
+// Operators supported inside a field's operator object, e.g.
+// { field: { $gt: 3, $lt: 10 } }. Kept in sync with the SQL adapters'
+// buildOperatorClause — any operator the main query path supports should
+// match here, and unknown operators throw rather than silently succeeding.
+const FIELD_OPERATORS = new Set([
+  '$eq', '$ne', '$gt', '$gte', '$lt', '$lte',
+  '$in', '$nin', '$exists', '$not',
+  '$regex', '$options', '$all', '$size'
+]);
+
+function matchesValueEq(docValue, target) {
+  // MongoDB semantics: a scalar match also matches when the field is an
+  // array containing that scalar.
+  if (Array.isArray(docValue) && !Array.isArray(target)) {
+    return docValue.some(item => deepEqual(item, target));
+  }
+  return deepEqual(docValue, target);
+}
+
+function matchesRegex(docValue, regex) {
+  if (Array.isArray(docValue)) {
+    return docValue.some(item => typeof item === 'string' && regex.test(item));
+  }
+  return typeof docValue === 'string' && regex.test(docValue);
+}
+
+function matchesQuery(doc, query) {
+  for (const [ key, value ] of Object.entries(query)) {
+    if (key === '$and') {
+      if (!value.every(subQuery => matchesQuery(doc, subQuery))) {
+        return false;
+      }
+      continue;
+    }
+    if (key === '$or') {
+      if (!value.some(subQuery => matchesQuery(doc, subQuery))) {
+        return false;
+      }
+      continue;
+    }
+    if (key.startsWith('$')) {
+      throw new Error(`Unsupported top-level operator: ${key}`);
+    }
+
+    const docValue = key === '_id' ? doc._id : getNestedField(doc, key);
+
+    if (value instanceof RegExp) {
+      if (!matchesRegex(docValue, value)) {
+        return false;
+      }
+      continue;
+    }
+
+    if (value === null || value === undefined) {
+      // MongoDB: { field: null } matches null, undefined, and missing
+      if (docValue !== null && docValue !== undefined) {
+        return false;
+      }
+      continue;
+    }
+
+    const isOperatorObject = typeof value === 'object' &&
+      !(value instanceof Date) &&
+      !Array.isArray(value) &&
+      Object.keys(value).some(k => k.startsWith('$'));
+
+    if (!isOperatorObject) {
+      if (!matchesValueEq(docValue, value)) {
+        return false;
+      }
+      continue;
+    }
+
+    for (const [ op, opValue ] of Object.entries(value)) {
+      if (!FIELD_OPERATORS.has(op)) {
+        throw new Error(`Unsupported operator: ${op}`);
+      }
+      switch (op) {
+        case '$eq':
+          // $eq null matches explicit null AND missing fields
+          if (opValue === null || opValue === undefined) {
+            if (docValue !== null && docValue !== undefined) {
+              return false;
+            }
+          } else if (!matchesValueEq(docValue, opValue)) {
+            return false;
+          }
+          break;
+        case '$ne':
+          if (opValue === null || opValue === undefined) {
+            if (docValue === null || docValue === undefined) {
+              return false;
+            }
+          } else if (matchesValueEq(docValue, opValue)) {
+            return false;
+          }
+          break;
+        case '$gt': if (!(docValue > opValue)) {
+          return false;
+        } break;
+        case '$gte': if (!(docValue >= opValue)) {
+          return false;
+        } break;
+        case '$lt': if (!(docValue < opValue)) {
+          return false;
+        } break;
+        case '$lte': if (!(docValue <= opValue)) {
+          return false;
+        } break;
+        case '$in': {
+          if (!Array.isArray(opValue)) {
+            throw new Error('$in requires an array');
+          }
+          const matched = opValue.some(candidate => {
+            if (candidate instanceof RegExp) {
+              return matchesRegex(docValue, candidate);
+            }
+            if (candidate === null || candidate === undefined) {
+              return docValue === null || docValue === undefined;
+            }
+            return matchesValueEq(docValue, candidate);
+          });
+          if (!matched) {
+            return false;
+          }
+          break;
+        }
+        case '$nin': {
+          if (!Array.isArray(opValue)) {
+            throw new Error('$nin requires an array');
+          }
+          const matched = opValue.some(candidate => {
+            if (candidate instanceof RegExp) {
+              return matchesRegex(docValue, candidate);
+            }
+            if (candidate === null || candidate === undefined) {
+              return docValue === null || docValue === undefined;
+            }
+            return matchesValueEq(docValue, candidate);
+          });
+          if (matched) {
+            return false;
+          }
+          break;
+        }
+        case '$exists': if ((docValue !== undefined) !== Boolean(opValue)) {
+          return false;
+        } break;
+        case '$not': {
+          if (typeof opValue !== 'object' || opValue === null) {
+            throw new Error('$not requires an object');
+          }
+          // Apply the inner operator object to the same field and negate
+          // the result. Errors from unknown inner operators propagate.
+          if (matchesQuery(doc, { [key]: opValue })) {
+            return false;
+          }
+          break;
+        }
+        case '$regex': {
+          const pattern = opValue instanceof RegExp ? opValue.source : String(opValue);
+          const flags = value.$options || (opValue instanceof RegExp ? opValue.flags : '');
+          const regex = new RegExp(pattern, flags);
+          if (!matchesRegex(docValue, regex)) {
+            return false;
+          }
+          break;
+        }
+        case '$options':
+          // Handled with $regex, skip
+          break;
+        case '$all': {
+          if (!Array.isArray(opValue)) {
+            throw new Error('$all requires an array');
+          }
+          if (!Array.isArray(docValue)) {
+            return false;
+          }
+          const allPresent = opValue.every(target =>
+            docValue.some(item => deepEqual(item, target))
+          );
+          if (!allPresent) {
+            return false;
+          }
+          break;
+        }
+        case '$size':
+          if (!Array.isArray(docValue) || docValue.length !== opValue) {
+            return false;
+          }
+          break;
+      }
+    }
+  }
+  return true;
+}
+
+module.exports = {
+  AggregationCursor,
+  matchesQuery,
+  applyAggregateProject
+};
diff --git a/packages/db-connect/lib/copy-database.js b/packages/db-connect/lib/copy-database.js
new file mode 100644
index 0000000000..83a2df67ec
--- /dev/null
+++ b/packages/db-connect/lib/copy-database.js
@@ -0,0 +1,11 @@
+const dump = require('./dump');
+const restore = require('./restore');
+
+// Copy a database by streaming NDJSON from source to destination — the
+// dump is never fully materialized in memory, so this works regardless
+// of database size.
+//
+// Accept either URI strings or already-connected db objects (or a mix).
+module.exports = async function copyDatabase(fromUriOrDb, toUriOrDb) {
+  await restore(toUriOrDb, dump(fromUriOrDb));
+};
diff --git a/packages/db-connect/lib/dump.js b/packages/db-connect/lib/dump.js
new file mode 100644
index 0000000000..3551fa8d8e
--- /dev/null
+++ b/packages/db-connect/lib/dump.js
@@ -0,0 +1,91 @@
+const dbConnect = require('..');
+
+const BATCH_SIZE = 100;
+
+// Dump a database as NDJSON. Returns an AsyncIterable that yields one
+// string per NDJSON record (no trailing newline). The first record of
+// each collection is a header `{ _collection, _indexes? }`; subsequent
+// records are `{ _collection, _doc }`.
+//
+// The dump is yielded incrementally so a large database can be piped to
+// disk or a destination adapter without materializing the whole payload
+// in memory at any point.
+//
+// Accept either a URI string or an already-connected db object. When a
+// db object is passed, the caller owns the connection lifecycle; when a
+// URI is passed, this module connects and closes the client on its own.
+async function *dump(uriOrDb) {
+  let db;
+  let client;
+  if (typeof uriOrDb === 'string') {
+    client = await dbConnect(uriOrDb);
+    db = client.db();
+  } else {
+    db = uriOrDb;
+  }
+
+  try {
+    const collections = await db.listCollections().toArray();
+
+    for (const collInfo of collections) {
+      const name = collInfo.name;
+      const col = db.collection(name);
+      const indexes = await col.indexes();
+      const customIndexes = indexes.filter(idx => idx.name !== '_id_');
+
+      const header = { _collection: name };
+      if (customIndexes.length > 0) {
+        header._indexes = customIndexes;
+      }
+      yield JSON.stringify(header);
+
+      let lastId = null;
+      while (true) {
+        const query = lastId ? { _id: { $gt: lastId } } : {};
+        const batch = await col.find(query).sort({ _id: 1 }).limit(BATCH_SIZE).toArray();
+        if (batch.length === 0) {
+          break;
+        }
+        for (const doc of batch) {
+          yield JSON.stringify({
+            _collection: name,
+            _doc: serializeValue(doc)
+          });
+        }
+        lastId = batch[batch.length - 1]._id;
+        if (batch.length < BATCH_SIZE) {
+          break;
+        }
+      }
+    }
+  } finally {
+    if (client) {
+      await client.close();
+    }
+  }
+}
+
+function serializeValue(obj) {
+  if (obj instanceof Date) {
+    return { $date: obj.toISOString() };
+  }
+  if (obj === null || obj === undefined) {
+    return obj;
+  }
+  if (typeof obj === 'object' && obj.constructor && obj.constructor.name === 'ObjectId') {
+    return obj.toHexString();
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(serializeValue);
+  }
+  if (typeof obj === 'object') {
+    const result = {};
+    for (const [ k, v ] of Object.entries(obj)) {
+      result[k] = serializeValue(v);
+    }
+    return result;
+  }
+  return obj;
+}
+
+module.exports = dump;
diff --git a/packages/apostrophe/lib/mongodb-connect.js b/packages/db-connect/lib/mongodb-connect.js
similarity index 96%
rename from packages/apostrophe/lib/mongodb-connect.js
rename to packages/db-connect/lib/mongodb-connect.js
index 1668862346..8348d77137 100644
--- a/packages/apostrophe/lib/mongodb-connect.js
+++ b/packages/db-connect/lib/mongodb-connect.js
@@ -29,7 +29,7 @@ module.exports = async (uri, options) => {
   }
   const records = await dns.promises.lookup('localhost', { all: true });
   if (!records.length) {
-    // The computer that reaches this point has bigger problems 😅
+    // The computer that reaches this point has bigger problems
     throw new Error('Unable to resolve localhost to an IP address.');
   }
   return new Promise((resolve, reject) => {
diff --git a/packages/db-connect/lib/restore.js b/packages/db-connect/lib/restore.js
new file mode 100644
index 0000000000..4cf16498c9
--- /dev/null
+++ b/packages/db-connect/lib/restore.js
@@ -0,0 +1,166 @@
+const readline = require('readline');
+const dbConnect = require('..');
+
+const BATCH_SIZE = 100;
+
+// Restore a database from NDJSON. `source` is streamed one line at a
+// time to avoid holding the entire dump in memory. Accepted `source`
+// shapes:
+//
+//   - an AsyncIterable<string> of NDJSON records (as produced by dump()),
+//   - an Iterable<string>,
+//   - a Node Readable stream (e.g. process.stdin, fs.createReadStream()) —
+//     lines are extracted with the built-in readline module,
+//   - a single string containing the entire dump — retained for
+//     convenience in small cases; for large dumps prefer a stream.
+//
+// Accept either a URI string or an already-connected db object. When a
+// db object is passed, the caller owns the connection lifecycle.
+module.exports = async function restore(uriOrDb, source) {
+  let db;
+  let client;
+  if (typeof uriOrDb === 'string') {
+    client = await dbConnect(uriOrDb);
+    db = client.db();
+  } else {
+    db = uriOrDb;
+  }
+
+  try {
+    let col = null;
+    let batch = [];
+
+    for await (const rawLine of linesOf(source)) {
+      const line = rawLine.trim();
+      if (!line) {
+        continue;
+      }
+      const entry = JSON.parse(line);
+
+      if (entry._doc) {
+        batch.push(deserializeValue(entry._doc));
+        if (batch.length >= BATCH_SIZE) {
+          await col.insertMany(batch);
+          batch = [];
+        }
+      } else if (entry._collection) {
+        if (batch.length > 0) {
+          await col.insertMany(batch);
+          batch = [];
+        }
+
+        col = db.collection(entry._collection);
+
+        // Clear existing data. Use deleteMany instead of drop to
+        // preserve the table structure — important when the database
+        // is being used by a running application (e.g. Cypress tests)
+        try {
+          await col.deleteMany({});
+        } catch (e) {
+          // Collection may not exist yet, ignore
+        }
+
+        if (entry._indexes && entry._indexes.length > 0) {
+          for (const idx of entry._indexes) {
+            const options = {};
+            if (idx.name) {
+              options.name = idx.name;
+            }
+            if (idx.unique) {
+              options.unique = true;
+            }
+            if (idx.sparse) {
+              options.sparse = true;
+            }
+            if (idx.type) {
+              options.type = idx.type;
+            }
+            // Text index support: preserve weights and language options
+            if (idx.weights) {
+              options.weights = idx.weights;
+            }
+            if (idx.default_language) {
+              options.default_language = idx.default_language;
+            }
+            if (idx.language_override) {
+              options.language_override = idx.language_override;
+            }
+            if (idx.textIndexVersion) {
+              options.textIndexVersion = idx.textIndexVersion;
+            }
+            // TTL index support
+            if (idx.expireAfterSeconds != null) {
+              options.expireAfterSeconds = idx.expireAfterSeconds;
+            }
+            await col.createIndex(idx.key, options);
+          }
+        }
+      }
+    }
+
+    if (batch.length > 0 && col) {
+      await col.insertMany(batch);
+    }
+
+    // For SQLite: force a WAL checkpoint to ensure all changes are
+    // visible to other connections immediately
+    if (db._sqlite) {
+      const result = db._sqlite.pragma('wal_checkpoint(PASSIVE)');
+      if (result && result[0]) {
+        // Log checkpoint result for debugging
+        const { log, checkpointed } = result[0];
+        if (log !== checkpointed) {
+          // Some pages weren't checkpointed, try harder
+          db._sqlite.pragma('wal_checkpoint(TRUNCATE)');
+        }
+      }
+    }
+  } finally {
+    if (client) {
+      await client.close();
+    }
+  }
+};
+
+// Normalize `source` into an async iterable of NDJSON lines.
+function linesOf(source) {
+  if (source == null) {
+    throw new Error('restore: source is required');
+  }
+  if (typeof source === 'string') {
+    return source.split('\n');
+  }
+  // Check for Readable stream BEFORE async iterable: Node Readables are
+  // themselves async iterables, but iterating them yields chunks
+  // (Buffer/string), not lines. Use readline to split on newline.
+  if (typeof source.on === 'function' && typeof source.pipe === 'function') {
+    return readline.createInterface({
+      input: source,
+      crlfDelay: Infinity
+    });
+  }
+  if (typeof source[Symbol.asyncIterator] === 'function' ||
+      typeof source[Symbol.iterator] === 'function') {
+    // Already an (async) iterable of line strings — e.g. the iterable
+    // returned by dump(), or an array of lines.
+    return source;
+  }
+  throw new Error('restore: source must be a string, iterable of lines, or a Readable stream');
+}
+
+function deserializeValue(obj) {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+  if (obj.$date) {
+    return new Date(obj.$date);
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(deserializeValue);
+  }
+  const result = {};
+  for (const [ k, v ] of Object.entries(obj)) {
+    result[k] = deserializeValue(v);
+  }
+  return result;
+}
diff --git a/packages/db-connect/lib/shared.js b/packages/db-connect/lib/shared.js
new file mode 100644
index 0000000000..6098583f6e
--- /dev/null
+++ b/packages/db-connect/lib/shared.js
@@ -0,0 +1,438 @@
+// Shared helper functions used by both the SQLite and PostgreSQL adapters.
+// These operate on plain JavaScript objects and have no database-specific logic.
+
+// =============================================================================
+// Value Serialization (Date handling)
+// =============================================================================
+
+// Recursively convert Date objects to { $date: ... } wrapper and
+// undefined to null (matching MongoDB's BSON behavior where undefined
+// is stored as null). This is called before JSON.stringify because
+// JSON.stringify calls toJSON() on Dates before any replacer sees them,
+// and omits properties with undefined values.
+function serializeValue(obj) {
+  if (obj === undefined) {
+    return null;
+  }
+  if (obj === null) {
+    return null;
+  }
+  if (obj instanceof Date) {
+    return { $date: obj.toISOString() };
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(serializeValue);
+  }
+  if (typeof obj === 'object') {
+    const result = {};
+    for (const [ key, value ] of Object.entries(obj)) {
+      result[key] = serializeValue(value);
+    }
+    return result;
+  }
+  return obj;
+}
+
+function serializeDocument(doc) {
+  return JSON.stringify(serializeValue(doc));
+}
+
+// Convert $date wrappers back to Date objects, returning the original
+// object reference when no conversions occurred in a subtree.
+// Most document subtrees (rich text, widget configs) have zero dates,
+// so this avoids rebuilding the entire object tree on every read.
+function convertDates(obj) {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+  if (obj.$date) {
+    return new Date(obj.$date);
+  }
+  if (Array.isArray(obj)) {
+    let changed = false;
+    const result = obj.map(item => {
+      const c = convertDates(item);
+      if (c !== item) {
+        changed = true;
+      }
+      return c;
+    });
+    return changed ? result : obj;
+  }
+  let changed = false;
+  const result = {};
+  for (const [ key, value ] of Object.entries(obj)) {
+    const c = convertDates(value);
+    result[key] = c;
+    if (c !== value) {
+      changed = true;
+    }
+  }
+  return changed ? result : obj;
+}
+
+function deserializeDocument(data, id) {
+  const parsed = typeof data === 'string' ? JSON.parse(data) : data;
+  const doc = convertDates(parsed);
+  if (doc === parsed) {
+    // No dates found — shallow copy to add _id without mutating parsed data
+    return {
+      _id: id,
+      ...doc
+    };
+  }
+  doc._id = id;
+  return doc;
+}
+
+// =============================================================================
+// Nested Field Operations
+// =============================================================================
+
+function getNestedField(obj, path) {
+  const parts = path.split('.');
+  let current = obj;
+  for (const part of parts) {
+    if (current == null) {
+      return undefined;
+    }
+    current = current[part];
+  }
+  return current;
+}
+
+function setNestedField(obj, path, value) {
+  const parts = path.split('.');
+  if (parts.includes('__proto__')) {
+    return;
+  }
+  let current = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (current[parts[i]] == null) {
+      current[parts[i]] = {};
+    }
+    current = current[parts[i]];
+  }
+  current[parts[parts.length - 1]] = value;
+}
+
+function unsetNestedField(obj, path) {
+  const parts = path.split('.');
+  let current = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (current[parts[i]] == null) {
+      return;
+    }
+    current = current[parts[i]];
+  }
+  delete current[parts[parts.length - 1]];
+}
+
+function deepEqual(a, b) {
+  if (a === b) {
+    return true;
+  }
+  if (a == null || b == null) {
+    return false;
+  }
+  if (typeof a !== typeof b) {
+    return false;
+  }
+  if (typeof a !== 'object') {
+    return false;
+  }
+  if (Array.isArray(a) !== Array.isArray(b)) {
+    return false;
+  }
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+  for (const key of keysA) {
+    if (!deepEqual(a[key], b[key])) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// =============================================================================
+// Projection (in-memory)
+// =============================================================================
+
+function applyProjection(doc, projection, meta = {}) {
+  if (!projection || Object.keys(projection).length === 0) {
+    return doc;
+  }
+
+  // Separate $meta projections (e.g. score: { $meta: 'textScore' })
+  // from regular field projections
+  const metaFields = Object.entries(projection).filter(
+    ([ k, v ]) => v && typeof v === 'object' && v.$meta
+  );
+  const fields = Object.entries(projection).filter(
+    ([ k, v ]) => !(v && typeof v === 'object' && v.$meta)
+  );
+
+  const applyMeta = (result) => {
+    for (const [ field, spec ] of metaFields) {
+      if (spec.$meta === 'textScore' && meta.textScore != null) {
+        result[field] = meta.textScore;
+      }
+    }
+    return result;
+  };
+
+  if (fields.length === 0) {
+    return applyMeta({ ...doc });
+  }
+  const isInclusion = fields.some(([ k, v ]) => v && k !== '_id');
+
+  if (isInclusion) {
+    const result = {};
+    for (const [ field, include ] of fields) {
+      if (include) {
+        const value = getNestedField(doc, field);
+        if (value !== undefined) {
+          setNestedField(result, field, value);
+        }
+      }
+    }
+    // Always include _id unless explicitly excluded
+    if (projection._id !== 0 && projection._id !== false) {
+      result._id = doc._id;
+    }
+    return applyMeta(result);
+  } else {
+    const result = JSON.parse(JSON.stringify(doc));
+    for (const [ field, include ] of fields) {
+      if (!include) {
+        unsetNestedField(result, field);
+      }
+    }
+    return applyMeta(result);
+  }
+}
+
+// =============================================================================
+// Update Operations (in-memory)
+// =============================================================================
+
+function applyUpdate(doc, update) {
+  // Pipeline-form update: array of stages like [{ $unset: [...] }, { $set: {...} }]
+  if (Array.isArray(update)) {
+    let result = { ...doc };
+    for (const stage of update) {
+      result = applyUpdate(result, stage);
+    }
+    return result;
+  }
+
+  const result = { ...doc };
+
+  for (const [ op, fields ] of Object.entries(update)) {
+    switch (op) {
+      case '$set':
+        for (const [ field, value ] of Object.entries(fields)) {
+          setNestedField(result, field, value);
+        }
+        break;
+      case '$unset':
+        if (Array.isArray(fields)) {
+          // Pipeline form: $unset takes an array of field names
+          for (const field of fields) {
+            unsetNestedField(result, field);
+          }
+        } else {
+          for (const field of Object.keys(fields)) {
+            unsetNestedField(result, field);
+          }
+        }
+        break;
+      case '$inc':
+        for (const [ field, value ] of Object.entries(fields)) {
+          const current = getNestedField(result, field) || 0;
+          setNestedField(result, field, current + value);
+        }
+        break;
+      case '$push':
+        for (const [ field, value ] of Object.entries(fields)) {
+          const arr = getNestedField(result, field) || [];
+          arr.push(value);
+          setNestedField(result, field, arr);
+        }
+        break;
+      case '$pull':
+        for (const [ field, value ] of Object.entries(fields)) {
+          const arr = getNestedField(result, field) || [];
+          setNestedField(result, field, arr.filter(item => !deepEqual(item, value)));
+        }
+        break;
+      case '$addToSet':
+        for (const [ field, value ] of Object.entries(fields)) {
+          const arr = getNestedField(result, field) || [];
+          if (!arr.some(item => deepEqual(item, value))) {
+            arr.push(value);
+          }
+          setNestedField(result, field, arr);
+        }
+        break;
+      case '$currentDate':
+        for (const [ field, value ] of Object.entries(fields)) {
+          if (value === true || (value && value.$type === 'date')) {
+            setNestedField(result, field, new Date());
+          }
+        }
+        break;
+      case '$rename':
+        for (const [ oldField, newField ] of Object.entries(fields)) {
+          const value = getNestedField(result, oldField);
+          if (value !== undefined) {
+            unsetNestedField(result, oldField);
+            setNestedField(result, newField, value);
+          }
+        }
+        break;
+      default:
+        throw new Error(`Unsupported update operator: ${op}`);
+    }
+  }
+
+  return result;
+}
+
+// =============================================================================
+// Anchored-Literal Prefix Extraction (for indexable regex queries)
+// =============================================================================
+
+// Characters that are regex metacharacters when unescaped. Anything not in
+// this set is a literal and can contribute to the prefix.
+const REGEX_META = new Set([ '.', '*', '+', '?', '(', ')', '[', ']', '{', '}', '|', '^', '$', '\\' ]);
+
+// Extract the literal prefix from a regex rooted at the start of the string,
+// for use as an indexable range predicate. Returns an object
+// { prefix, anchored } where `prefix` is the literal string that every match
+// must begin with, and `anchored` indicates the regex begins with `^`.
+//
+// Returns { prefix: '', anchored: false } when no useful rewrite is possible
+// (unanchored regex, case-insensitive regex, or the regex begins with a
+// metacharacter).
+//
+// Example:
+//   extractAnchoredLiteralPrefix(/^\/parent\/child\/./)
+//     -> { prefix: '/parent/child/', anchored: true }
+//   extractAnchoredLiteralPrefix(/^foo.*bar/)
+//     -> { prefix: 'foo', anchored: true }
+//   extractAnchoredLiteralPrefix(/foo/)
+//     -> { prefix: '', anchored: false }
+function extractAnchoredLiteralPrefix(regex) {
+  if (!(regex instanceof RegExp)) {
+    return {
+      prefix: '',
+      anchored: false
+    };
+  }
+  // Case-insensitive regex cannot align with a case-sensitive btree range scan.
+  if (regex.ignoreCase) {
+    return {
+      prefix: '',
+      anchored: false
+    };
+  }
+  const source = regex.source;
+  if (source.length === 0 || source[0] !== '^') {
+    return {
+      prefix: '',
+      anchored: false
+    };
+  }
+  let i = 1;
+  let prefix = '';
+  while (i < source.length) {
+    const ch = source[i];
+    if (ch === '\\') {
+      // Escape sequence: the next character may be a literal or a character class
+      if (i + 1 >= source.length) {
+        break;
+      }
+      const next = source[i + 1];
+      // Single-character escapes for a literal character (\. \/ \- \( \\ etc.)
+      // — anything that is a regex metacharacter, plus '/' and similar. These
+      // contribute the escaped character itself to the prefix.
+      if (REGEX_META.has(next) || next === '/' || next === '-' || next === '=' || next === '!' || next === ':' || next === ',' || next === '#' || next === ' ' || next === '"' || next === '\'' || next === '<' || next === '>' || next === '@' || next === '~' || next === '`' || next === '%' || next === '&' || next === ';') {
+        prefix += next;
+        i += 2;
+        continue;
+      }
+      // Any other escape (\d, \w, \s, \b, \n, \t, \uXXXX, \xXX, etc.) is not
+      // a simple literal — stop here.
+      break;
+    }
+    if (REGEX_META.has(ch)) {
+      // Top-level alternation (`|`) means the regex can match a completely
+      // different string on the other side of the pipe. Any prefix we've
+      // accumulated so far is not guaranteed to appear in every match, so
+      // we must discard it entirely.
+      if (ch === '|') {
+        prefix = '';
+        break;
+      }
+      // Unescaped metacharacter ends the literal prefix. Quantifiers (`?`,
+      // `*`, `{`) make the *preceding* literal optional or zero-or-more, so
+      // that character is not guaranteed to appear in matches and must be
+      // dropped from the prefix. `+` guarantees at least one occurrence of
+      // the preceding literal, so the literal stays.
+      if ((ch === '?' || ch === '*' || ch === '{') && prefix.length > 0) {
+        prefix = prefix.slice(0, -1);
+      }
+      break;
+    }
+    prefix += ch;
+    i++;
+  }
+  return {
+    prefix,
+    anchored: true
+  };
+}
+
+// Given a literal prefix P, return the exclusive upper bound string U such
+// that a string S starts with P iff P <= S < U. Returns null when no safe
+// upper bound can be constructed (empty prefix, or last char is the maximum
+// BMP code point 0xFFFF). Callers should treat a null result as "emit only
+// the lower-bound predicate".
+function prefixUpperBound(prefix) {
+  if (!prefix) {
+    return null;
+  }
+  const lastCode = prefix.charCodeAt(prefix.length - 1);
+  if (lastCode === 0xFFFF) {
+    return null;
+  }
+  return prefix.slice(0, -1) + String.fromCharCode(lastCode + 1);
+}
+
+function validateInteger(value, name) {
+  const num = Number(value);
+  if (!Number.isInteger(num) || num < 0) {
+    throw new Error(`${name} must be a non-negative integer`);
+  }
+  return num;
+}
+
+module.exports = {
+  serializeValue,
+  serializeDocument,
+  convertDates,
+  deserializeDocument,
+  getNestedField,
+  setNestedField,
+  unsetNestedField,
+  deepEqual,
+  applyProjection,
+  applyUpdate,
+  extractAnchoredLiteralPrefix,
+  prefixUpperBound,
+  validateInteger
+};
diff --git a/packages/db-connect/package.json b/packages/db-connect/package.json
new file mode 100644
index 0000000000..5eeedf8aac
--- /dev/null
+++ b/packages/db-connect/package.json
@@ -0,0 +1,29 @@
+{
+  "name": "@apostrophecms/db-connect",
+  "version": "1.0.0",
+  "description": "Database connection library and dump/restore tools for ApostropheCMS",
+  "main": "index.js",
+  "bin": {
+    "apos-db-dump": "./bin/apos-db-dump.js",
+    "apos-db-restore": "./bin/apos-db-restore.js"
+  },
+  "scripts": {
+    "test": "mocha test/**/*.test.js --timeout 30000",
+    "test:mongodb": "ADAPTER=mongodb mocha test/**/*.test.js --timeout 30000",
+    "test:postgres": "ADAPTER=postgres mocha test/**/*.test.js --timeout 30000",
+    "test:sqlite": "ADAPTER=sqlite mocha test/**/*.test.js --timeout 30000",
+    "lint": "eslint .",
+    "eslint": "eslint ."
+  },
+  "devDependencies": {
+    "chai": "^4.3.10",
+    "eslint": "^9.39.1",
+    "eslint-config-apostrophe": "workspace:^",
+    "mocha": "^11.7.1"
+  },
+  "dependencies": {
+    "@apostrophecms/emulate-mongo-3-driver": "workspace:^",
+    "better-sqlite3": "^11.0.0",
+    "pg": "^8.11.3"
+  }
+}
diff --git a/packages/db-connect/test/adapter.test.js b/packages/db-connect/test/adapter.test.js
new file mode 100644
index 0000000000..3d00f00122
--- /dev/null
+++ b/packages/db-connect/test/adapter.test.js
@@ -0,0 +1,3361 @@
+/* global describe, it, before, after, beforeEach */
+/* eslint-disable no-unused-expressions */
+const { expect } = require('chai');
+
+// Test suite for the universal database adapter
+// Based on actual MongoDB usage patterns in ApostropheCMS
+
+const ADAPTER = process.env.ADAPTER || process.env.APOS_TEST_DB_PROTOCOL || 'mongodb';
+const TEST_DB_NAME = 'dbtest-adapter';
+
+describe(`Database Adapter (${ADAPTER})`, function() {
+  let client;
+  let db;
+
+  before(async function() {
+    if (ADAPTER === 'mongodb') {
+      const mongodb = require('../adapters/mongodb');
+      client = await mongodb.connect(`mongodb://localhost:27017/${TEST_DB_NAME}`);
+      db = client.db();
+    } else if (ADAPTER === 'postgres') {
+      const postgres = require('../adapters/postgres');
+      const user = process.env.PGUSER || process.env.USER;
+      const password = process.env.PGPASSWORD || '';
+      const auth = password ? `${user}:${password}@` : `${user}@`;
+      client = await postgres.connect(`postgres://${auth}localhost:5432/dbtest_adapter`);
+      db = client.db();
+    } else if (ADAPTER === 'multipostgres') {
+      const postgres = require('../adapters/postgres');
+      const user = process.env.PGUSER || process.env.USER;
+      const password = process.env.PGPASSWORD || '';
+      const auth = password ? `${user}:${password}@` : `${user}@`;
+      client = await postgres.connect(`multipostgres://${auth}localhost:5432/dbtest_adapter-testschema`);
+      db = client.db();
+    } else if (ADAPTER === 'sqlite') {
+      const sqlite = require('../adapters/sqlite');
+      const os = require('os');
+      const pathModule = require('path');
+      const fs = require('fs');
+      const dbPath = pathModule.join(os.tmpdir(), 'dbtest-adapter.db');
+      try {
+        fs.unlinkSync(dbPath);
+      } catch (e) { /* ignore */ }
+      client = await sqlite.connect(`sqlite://${dbPath}`);
+      db = client.db();
+    }
+  });
+
+  after(async function() {
+    if (db) {
+      // Clean up test database
+      const collections = await db.listCollections().toArray();
+      for (const col of collections) {
+        await db.collection(col.name).drop();
+      }
+    }
+    if (client) {
+      await client.close();
+    }
+  });
+
+  beforeEach(async function() {
+    // Clean up test collection before each test
+    try {
+      await db.collection('test').drop();
+    } catch (e) {
+      // Collection may not exist, ignore
+    }
+  });
+
+  // ============================================
+  // SECTION 1: Basic CRUD Operations
+  // ============================================
+
+  describe('insertOne', function() {
+    it('should insert a document and return insertedId', async function() {
+      const result = await db.collection('test').insertOne({
+        _id: 'doc1',
+        title: 'Test Document',
+        value: 42
+      });
+      expect(result.insertedId).to.equal('doc1');
+      expect(result.acknowledged).to.equal(true);
+    });
+
+    it('should auto-generate _id if not provided', async function() {
+      const result = await db.collection('test').insertOne({
+        title: 'Auto ID Document'
+      });
+      expect(result.insertedId).to.exist;
+      expect(result.acknowledged).to.equal(true);
+    });
+
+    it('should reject duplicate _id', async function() {
+      await db.collection('test').insertOne({
+        _id: 'dup',
+        value: 1
+      });
+      try {
+        await db.collection('test').insertOne({
+          _id: 'dup',
+          value: 2
+        });
+        expect.fail('Should have thrown duplicate key error');
+      } catch (e) {
+        expect(e.message).to.match(/duplicate|unique|already exists/i);
+      }
+    });
+  });
+
+  describe('insertMany', function() {
+    it('should insert multiple documents', async function() {
+      const docs = [
+        {
+          _id: 'many1',
+          title: 'First'
+        },
+        {
+          _id: 'many2',
+          title: 'Second'
+        },
+        {
+          _id: 'many3',
+          title: 'Third'
+        }
+      ];
+      const result = await db.collection('test').insertMany(docs);
+      expect(result.insertedCount).to.equal(3);
+      expect(result.acknowledged).to.equal(true);
+      expect(Object.keys(result.insertedIds)).to.have.lengthOf(3);
+    });
+
+    it('should reject if any document has duplicate _id', async function() {
+      await db.collection('test').insertOne({
+        _id: 'existing',
+        value: 1
+      });
+      try {
+        await db.collection('test').insertMany([
+          {
+            _id: 'new1',
+            value: 2
+          },
+          {
+            _id: 'existing',
+            value: 3
+          }
+        ]);
+        expect.fail('Should have thrown duplicate key error');
+      } catch (e) {
+        expect(e.message).to.match(/duplicate|unique|already exists/i);
+      }
+    });
+  });
+
+  describe('findOne', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'find1',
+          type: 'article',
+          title: 'First Article',
+          views: 100
+        },
+        {
+          _id: 'find2',
+          type: 'article',
+          title: 'Second Article',
+          views: 200
+        },
+        {
+          _id: 'find3',
+          type: 'page',
+          title: 'Home Page',
+          views: 500
+        }
+      ]);
+    });
+
+    it('should find a document by _id', async function() {
+      const doc = await db.collection('test').findOne({ _id: 'find1' });
+      expect(doc).to.exist;
+      expect(doc._id).to.equal('find1');
+      expect(doc.title).to.equal('First Article');
+    });
+
+    it('should find a document by field value', async function() {
+      const doc = await db.collection('test').findOne({ type: 'page' });
+      expect(doc).to.exist;
+      expect(doc._id).to.equal('find3');
+    });
+
+    it('should return null if no match', async function() {
+      const doc = await db.collection('test').findOne({ _id: 'nonexistent' });
+      expect(doc).to.be.null;
+    });
+
+    it('should support projection', async function() {
+      const doc = await db.collection('test').findOne(
+        { _id: 'find1' },
+        { projection: { title: 1 } }
+      );
+      expect(doc).to.exist;
+      expect(doc._id).to.equal('find1');
+      expect(doc.title).to.equal('First Article');
+      expect(doc.type).to.be.undefined;
+      expect(doc.views).to.be.undefined;
+    });
+
+    it('should support projection exclusion', async function() {
+      const doc = await db.collection('test').findOne(
+        { _id: 'find1' },
+        { projection: { views: 0 } }
+      );
+      expect(doc).to.exist;
+      expect(doc._id).to.equal('find1');
+      expect(doc.title).to.equal('First Article');
+      expect(doc.type).to.equal('article');
+      expect(doc.views).to.be.undefined;
+    });
+  });
+
+  describe('find', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'a1',
+          type: 'article',
+          title: 'Alpha',
+          order: 1,
+          tags: [ 'news', 'featured' ]
+        },
+        {
+          _id: 'a2',
+          type: 'article',
+          title: 'Beta',
+          order: 2,
+          tags: [ 'news' ]
+        },
+        {
+          _id: 'a3',
+          type: 'article',
+          title: 'Gamma',
+          order: 3,
+          tags: [ 'featured' ]
+        },
+        {
+          _id: 'p1',
+          type: 'page',
+          title: 'Home',
+          order: 1,
+          tags: []
+        },
+        {
+          _id: 'p2',
+          type: 'page',
+          title: 'About',
+          order: 2,
+          tags: [ 'info' ]
+        }
+      ]);
+    });
+
+    it('should find all documents with toArray()', async function() {
+      const docs = await db.collection('test').find({}).toArray();
+      expect(docs).to.have.lengthOf(5);
+    });
+
+    it('should find documents matching criteria', async function() {
+      const docs = await db.collection('test').find({ type: 'article' }).toArray();
+      expect(docs).to.have.lengthOf(3);
+      docs.forEach(doc => expect(doc.type).to.equal('article'));
+    });
+
+    it('should support sort()', async function() {
+      const docs = await db.collection('test')
+        .find({ type: 'article' })
+        .sort({ order: -1 })
+        .toArray();
+      expect(docs).to.have.lengthOf(3);
+      expect(docs[0]._id).to.equal('a3');
+      expect(docs[1]._id).to.equal('a2');
+      expect(docs[2]._id).to.equal('a1');
+    });
+
+    it('should support limit()', async function() {
+      const docs = await db.collection('test')
+        .find({})
+        .sort({ _id: 1 })
+        .limit(2)
+        .toArray();
+      expect(docs).to.have.lengthOf(2);
+    });
+
+    it('should support skip()', async function() {
+      const docs = await db.collection('test')
+        .find({})
+        .sort({ _id: 1 })
+        .skip(2)
+        .toArray();
+      expect(docs).to.have.lengthOf(3);
+    });
+
+    it('should support skip() and limit() together', async function() {
+      const docs = await db.collection('test')
+        .find({})
+        .sort({ _id: 1 })
+        .skip(1)
+        .limit(2)
+        .toArray();
+      expect(docs).to.have.lengthOf(2);
+      expect(docs[0]._id).to.equal('a2');
+      expect(docs[1]._id).to.equal('a3');
+    });
+
+    it('should support project()', async function() {
+      const docs = await db.collection('test')
+        .find({ _id: 'a1' })
+        .project({ title: 1 })
+        .toArray();
+      expect(docs).to.have.lengthOf(1);
+      expect(docs[0]._id).to.equal('a1');
+      expect(docs[0].title).to.equal('Alpha');
+      expect(docs[0].type).to.be.undefined;
+    });
+
+    it('should support count()', async function() {
+      const count = await db.collection('test')
+        .find({ type: 'article' })
+        .count();
+      expect(count).to.equal(3);
+    });
+
+    it('should support clone()', async function() {
+      const cursor = db.collection('test').find({ type: 'article' });
+      const cloned = cursor.clone();
+      const docs1 = await cursor.toArray();
+      const docs2 = await cloned.toArray();
+      expect(docs1).to.have.lengthOf(3);
+      expect(docs2).to.have.lengthOf(3);
+    });
+
+    it('should support next() with promises', async function() {
+      const cursor = db.collection('test')
+        .find({ type: 'article' })
+        .sort({ _id: 1 });
+      const doc1 = await cursor.next();
+      expect(doc1).to.exist;
+      expect(doc1._id).to.equal('a1');
+      const doc2 = await cursor.next();
+      expect(doc2).to.exist;
+      expect(doc2._id).to.equal('a2');
+      const doc3 = await cursor.next();
+      expect(doc3).to.exist;
+      expect(doc3._id).to.equal('a3');
+      const doc4 = await cursor.next();
+      expect(doc4).to.be.null;
+    });
+
+    it('should support next() with callbacks', function(done) {
+      const cursor = db.collection('test')
+        .find({ type: 'page' })
+        .sort({ _id: 1 });
+      cursor.next(function(err, doc1) {
+        if (err) {
+          return done(err);
+        }
+        expect(doc1).to.exist;
+        expect(doc1._id).to.equal('p1');
+        cursor.next(function(err, doc2) {
+          if (err) {
+            return done(err);
+          }
+          expect(doc2).to.exist;
+          expect(doc2._id).to.equal('p2');
+          cursor.next(function(err, doc3) {
+            if (err) {
+              return done(err);
+            }
+            expect(doc3).to.be.null;
+            done();
+          });
+        });
+      });
+    });
+
+    it('should support next() with projection', async function() {
+      const cursor = db.collection('test')
+        .find({ _id: 'a1' })
+        .project({ title: 1 });
+      const doc = await cursor.next();
+      expect(doc).to.exist;
+      expect(doc._id).to.equal('a1');
+      expect(doc.title).to.equal('Alpha');
+      expect(doc.type).to.be.undefined;
+      // Close cursor to release the connection/transaction
+      if (cursor.close) {
+        await cursor.close();
+      }
+    });
+
+    if (ADAPTER === 'postgres' || ADAPTER === 'multipostgres' || ADAPTER === 'sqlite') {
+      it('should support close() for early termination', async function() {
+        const cursor = db.collection('test')
+          .find({})
+          .sort({ _id: 1 });
+        const doc1 = await cursor.next();
+        expect(doc1).to.exist;
+        await cursor.close();
+        const doc2 = await cursor.next();
+        expect(doc2).to.be.null;
+      });
+    }
+  });
+
+  describe('updateOne', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'u1',
+          title: 'Original',
+          views: 10,
+          active: true
+        },
+        {
+          _id: 'u2',
+          title: 'Another',
+          views: 20,
+          active: false
+        }
+      ]);
+    });
+
+    it('should update a single document', async function() {
+      const result = await db.collection('test').updateOne(
+        { _id: 'u1' },
+        { $set: { title: 'Updated' } }
+      );
+      expect(result.matchedCount).to.equal(1);
+      expect(result.modifiedCount).to.equal(1);
+      expect(result.acknowledged).to.equal(true);
+
+      const doc = await db.collection('test').findOne({ _id: 'u1' });
+      expect(doc.title).to.equal('Updated');
+      expect(doc.views).to.equal(10);
+    });
+
+    it('should return matchedCount 0 if no match', async function() {
+      const result = await db.collection('test').updateOne(
+        { _id: 'nonexistent' },
+        { $set: { title: 'Updated' } }
+      );
+      expect(result.matchedCount).to.equal(0);
+      expect(result.modifiedCount).to.equal(0);
+    });
+
+    it('should support upsert', async function() {
+      const result = await db.collection('test').updateOne(
+        { _id: 'new1' },
+        {
+          $set: {
+            title: 'Upserted',
+            value: 100
+          }
+        },
+        { upsert: true }
+      );
+      expect(result.upsertedId).to.equal('new1');
+      expect(result.upsertedCount).to.equal(1);
+
+      const doc = await db.collection('test').findOne({ _id: 'new1' });
+      expect(doc.title).to.equal('Upserted');
+    });
+  });
+
+  describe('updateMany', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'm1',
+          type: 'article',
+          status: 'draft'
+        },
+        {
+          _id: 'm2',
+          type: 'article',
+          status: 'draft'
+        },
+        {
+          _id: 'm3',
+          type: 'page',
+          status: 'draft'
+        }
+      ]);
+    });
+
+    it('should update multiple documents', async function() {
+      const result = await db.collection('test').updateMany(
+        { type: 'article' },
+        { $set: { status: 'published' } }
+      );
+      expect(result.matchedCount).to.equal(2);
+      expect(result.modifiedCount).to.equal(2);
+
+      const docs = await db.collection('test').find({ status: 'published' }).toArray();
+      expect(docs).to.have.lengthOf(2);
+    });
+  });
+
+  describe('replaceOne', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertOne({
+        _id: 'r1',
+        title: 'Original',
+        extra: 'field',
+        count: 5
+      });
+    });
+
+    it('should replace entire document', async function() {
+      const result = await db.collection('test').replaceOne(
+        { _id: 'r1' },
+        {
+          _id: 'r1',
+          title: 'Replaced',
+          newField: 'value'
+        }
+      );
+      expect(result.matchedCount).to.equal(1);
+      expect(result.modifiedCount).to.equal(1);
+
+      const doc = await db.collection('test').findOne({ _id: 'r1' });
+      expect(doc.title).to.equal('Replaced');
+      expect(doc.newField).to.equal('value');
+      expect(doc.extra).to.be.undefined;
+      expect(doc.count).to.be.undefined;
+    });
+
+    it('should support upsert', async function() {
+      const result = await db.collection('test').replaceOne(
+        { _id: 'r2' },
+        {
+          _id: 'r2',
+          title: 'New Doc'
+        },
+        { upsert: true }
+      );
+      expect(result.upsertedId).to.equal('r2');
+    });
+  });
+
+  describe('deleteOne', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'd1',
+          value: 1
+        },
+        {
+          _id: 'd2',
+          value: 2
+        }
+      ]);
+    });
+
+    it('should delete a single document', async function() {
+      const result = await db.collection('test').deleteOne({ _id: 'd1' });
+      expect(result.deletedCount).to.equal(1);
+      expect(result.acknowledged).to.equal(true);
+
+      const doc = await db.collection('test').findOne({ _id: 'd1' });
+      expect(doc).to.be.null;
+    });
+
+    it('should return deletedCount 0 if no match', async function() {
+      const result = await db.collection('test').deleteOne({ _id: 'nonexistent' });
+      expect(result.deletedCount).to.equal(0);
+    });
+  });
+
+  describe('deleteMany', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'dm1',
+          type: 'temp',
+          value: 1
+        },
+        {
+          _id: 'dm2',
+          type: 'temp',
+          value: 2
+        },
+        {
+          _id: 'dm3',
+          type: 'keep',
+          value: 3
+        }
+      ]);
+    });
+
+    it('should delete multiple documents', async function() {
+      const result = await db.collection('test').deleteMany({ type: 'temp' });
+      expect(result.deletedCount).to.equal(2);
+
+      const docs = await db.collection('test').find({}).toArray();
+      expect(docs).to.have.lengthOf(1);
+      expect(docs[0]._id).to.equal('dm3');
+    });
+
+    it('should delete all documents with empty filter', async function() {
+      const result = await db.collection('test').deleteMany({});
+      expect(result.deletedCount).to.equal(3);
+    });
+  });
+
+  // ============================================
+  // SECTION 2: Query Operators
+  // ============================================
+
+  describe('Query Operators', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'q1',
+          name: 'Alice',
+          age: 25,
+          active: true,
+          tags: [ 'admin', 'user' ]
+        },
+        {
+          _id: 'q2',
+          name: 'Bob',
+          age: 30,
+          active: false,
+          tags: [ 'user' ]
+        },
+        {
+          _id: 'q3',
+          name: 'Carol',
+          age: 35,
+          active: true,
+          tags: [ 'guest' ]
+        },
+        {
+          _id: 'q4',
+          name: 'Dave',
+          age: 25,
+          active: true,
+          tags: []
+        },
+        {
+          _id: 'q5',
+          name: 'Eve',
+          age: 40,
+          optional: 'present',
+          tags: [ 'admin' ]
+        }
+      ]);
+    });
+
+    describe('Comparison Operators', function() {
+      it('$eq - should match equal values', async function() {
+        const docs = await db.collection('test').find({ age: { $eq: 25 } }).toArray();
+        expect(docs).to.have.lengthOf(2);
+      });
+
+      it('$ne - should match not equal values', async function() {
+        const docs = await db.collection('test').find({ age: { $ne: 25 } }).toArray();
+        expect(docs).to.have.lengthOf(3);
+      });
+
+      it('$ne: null - should match docs where field exists and is not null', async function() {
+        // Only q5 (Eve) has the `optional` field set
+        const docs = await db.collection('test').find({ optional: { $ne: null } }).toArray();
+        expect(docs).to.have.lengthOf(1);
+        expect(docs[0]._id).to.equal('q5');
+      });
+
+      it('$eq: null - should match docs where field is null or missing', async function() {
+        // q1-q4 lack the `optional` field entirely
+        const docs = await db.collection('test').find({ optional: { $eq: null } }).toArray();
+        expect(docs).to.have.lengthOf(4);
+        const ids = docs.map(d => d._id).sort();
+        expect(ids).to.deep.equal([ 'q1', 'q2', 'q3', 'q4' ]);
+      });
+
+      it('$gt - should match greater than', async function() {
+        const docs = await db.collection('test').find({ age: { $gt: 30 } }).toArray();
+        expect(docs).to.have.lengthOf(2);
+      });
+
+      it('$gte - should match greater than or equal', async function() {
+        const docs = await db.collection('test').find({ age: { $gte: 30 } }).toArray();
+        expect(docs).to.have.lengthOf(3);
+      });
+
+      it('$lt - should match less than', async function() {
+        const docs = await db.collection('test').find({ age: { $lt: 30 } }).toArray();
+        expect(docs).to.have.lengthOf(2);
+      });
+
+      it('$lte - should match less than or equal', async function() {
+        const docs = await db.collection('test').find({ age: { $lte: 30 } }).toArray();
+        expect(docs).to.have.lengthOf(3);
+      });
+
+      it('$in - should match values in array', async function() {
+        const docs = await db.collection('test').find({ age: { $in: [ 25, 35 ] } }).toArray();
+        expect(docs).to.have.lengthOf(3);
+      });
+
+      it('$nin - should match values not in array', async function() {
+        const docs = await db.collection('test').find({ age: { $nin: [ 25, 35 ] } }).toArray();
+        expect(docs).to.have.lengthOf(2);
+      });
+    });
+
+    describe('Logical Operators', function() {
+      it('$and - should match all conditions', async function() {
+        const docs = await db.collection('test').find({
+          $and: [
+            { age: { $gte: 25 } },
+            { active: true }
+          ]
+        }).toArray();
+        expect(docs).to.have.lengthOf(3);
+      });
+
+      it('$or - should match any condition', async function() {
+        const docs = await db.collection('test').find({
+          $or: [
+            { name: 'Alice' },
+            { name: 'Bob' }
+          ]
+        }).toArray();
+        expect(docs).to.have.lengthOf(2);
+      });
+
+      it('$not - should negate condition', async function() {
+        const docs = await db.collection('test').find({
+          age: { $not: { $gt: 30 } }
+        }).toArray();
+        expect(docs).to.have.lengthOf(3);
+      });
+
+      it('should support implicit $and with multiple fields', async function() {
+        const docs = await db.collection('test').find({
+          age: 25,
+          active: true
+        }).toArray();
+        expect(docs).to.have.lengthOf(2);
+      });
+    });
+
+    describe('Element Operators', function() {
+      it('$exists: true - should match documents with field', async function() {
+        const docs = await db.collection('test').find({ optional: { $exists: true } }).toArray();
+        expect(docs).to.have.lengthOf(1);
+        expect(docs[0].name).to.equal('Eve');
+      });
+
+      it('$exists: false - should match documents without field', async function() {
+        const docs = await db.collection('test').find({ optional: { $exists: false } }).toArray();
+        expect(docs).to.have.lengthOf(4);
+      });
+    });
+
+    describe('String Operators', function() {
+      it('$regex - should match regex pattern', async function() {
+        const docs = await db.collection('test').find({ name: { $regex: /^[AB]/ } }).toArray();
+        expect(docs).to.have.lengthOf(2);
+      });
+
+      it('$regex - should support string pattern', async function() {
+        const docs = await db.collection('test').find({
+          name: {
+            $regex: 'li',
+            $options: 'i'
+          }
+        }).toArray();
+        expect(docs).to.have.lengthOf(1);
+        expect(docs[0].name).to.equal('Alice');
+      });
+    });
+
+    // Anchored-literal-prefix regex queries mirror the ApostropheCMS page-tree
+    // descendants pattern (matchDescendants). Under the covers, the postgres
+    // and sqlite adapters rewrite these to an indexable range predicate
+    // plus a residual regex. Verify correctness here; index-usage is verified
+    // separately in the Indexes describe block below.
+    describe('Anchored regex (prefix rewrite)', function() {
+      beforeEach(async function() {
+        await db.collection('test2').deleteMany({});
+        await db.collection('test2').insertMany([
+          {
+            _id: 'p1',
+            path: '/'
+          },
+          {
+            _id: 'p2',
+            path: '/parent'
+          },
+          {
+            _id: 'p3',
+            path: '/parent/child-a'
+          },
+          {
+            _id: 'p4',
+            path: '/parent/child-a/grandchild'
+          },
+          {
+            _id: 'p5',
+            path: '/parent/child-b'
+          },
+          {
+            _id: 'p6',
+            path: '/parentx'
+          }, // sibling, must not match a /parent/ prefix
+          {
+            _id: 'p7',
+            path: '/other/child'
+          }
+        ]);
+      });
+      after(async function() {
+        await db.collection('test2').deleteMany({});
+      });
+
+      it('matches exactly the descendants of a path (MongoDB semantics)', async function() {
+        // ApostropheCMS matchDescendants: /^<path>\/./
+        const docs = await db.collection('test2')
+          .find({ path: /^\/parent\/./ })
+          .toArray();
+        const ids = docs.map(d => d._id).sort();
+        expect(ids).to.deep.equal([ 'p3', 'p4', 'p5' ]);
+      });
+
+      it('does not falsely match siblings that share a prefix without the separator', async function() {
+        // /parentx must not match /^\/parent\/./ even though they share '/parent'
+        const docs = await db.collection('test2')
+          .find({ path: /^\/parent\// })
+          .toArray();
+        const ids = docs.map(d => d._id).sort();
+        expect(ids).to.deep.equal([ 'p3', 'p4', 'p5' ]);
+      });
+
+      it('excludes the parent itself from its descendants (trailing `.` enforcement)', async function() {
+        const docs = await db.collection('test2')
+          .find({ path: /^\/parent\/./ })
+          .toArray();
+        const ids = docs.map(d => d._id);
+        expect(ids).to.not.include('p2'); // /parent is not its own descendant
+      });
+
+      it('works via $regex with $options', async function() {
+        const docs = await db.collection('test2')
+          .find({ path: { $regex: '^/parent/' } })
+          .toArray();
+        const ids = docs.map(d => d._id).sort();
+        expect(ids).to.deep.equal([ 'p3', 'p4', 'p5' ]);
+      });
+
+      it('works for _id prefix queries', async function() {
+        const docs = await db.collection('test2')
+          .find({ _id: /^p/ })
+          .toArray();
+        expect(docs.length).to.equal(7);
+        const noneMatch = await db.collection('test2')
+          .find({ _id: /^z/ })
+          .toArray();
+        expect(noneMatch).to.have.lengthOf(0);
+      });
+
+      it('returns no results when the literal prefix has no matches', async function() {
+        const docs = await db.collection('test2')
+          .find({ path: /^\/nonexistent\// })
+          .toArray();
+        expect(docs).to.have.lengthOf(0);
+      });
+
+      it('matches results beyond the prefix via the residual regex', async function() {
+        // Prefix '/parent/child-', then [ab] picks just the two direct children
+        const docs = await db.collection('test2')
+          .find({ path: /^\/parent\/child-[ab]$/ })
+          .toArray();
+        const ids = docs.map(d => d._id).sort();
+        expect(ids).to.deep.equal([ 'p3', 'p5' ]);
+      });
+
+      it('case-insensitive anchored regex still matches correctly (no range rewrite)', async function() {
+        const docs = await db.collection('test2')
+          .find({ path: /^\/PARENT\//i })
+          .toArray();
+        const ids = docs.map(d => d._id).sort();
+        expect(ids).to.deep.equal([ 'p3', 'p4', 'p5' ]);
+      });
+
+      it('unanchored regex still works (no rewrite)', async function() {
+        const docs = await db.collection('test2')
+          .find({ path: /child-b/ })
+          .toArray();
+        expect(docs).to.have.lengthOf(1);
+        expect(docs[0]._id).to.equal('p5');
+      });
+    });
+
+    describe('Array Operators', function() {
+      it('should match array containing value (implicit)', async function() {
+        const docs = await db.collection('test').find({ tags: 'admin' }).toArray();
+        expect(docs).to.have.lengthOf(2);
+      });
+
+      it('$all - should match arrays containing all values', async function() {
+        const docs = await db.collection('test').find({ tags: { $all: [ 'admin', 'user' ] } }).toArray();
+        expect(docs).to.have.lengthOf(1);
+        expect(docs[0].name).to.equal('Alice');
+      });
+
+      it('$size - should match arrays with exact length', async function() {
+        const docs = await db.collection('test').find({ tags: { $size: 2 } }).toArray();
+        expect(docs).to.have.lengthOf(1);
+        expect(docs[0].name).to.equal('Alice');
+      });
+
+      it('$size: 1 - should match single-element arrays', async function() {
+        const docs = await db.collection('test').find({ tags: { $size: 1 } }).toArray();
+        expect(docs).to.have.lengthOf(3);
+        const names = docs.map(d => d.name).sort();
+        expect(names).to.deep.equal([ 'Bob', 'Carol', 'Eve' ]);
+      });
+
+      it('$size: 0 - should match empty arrays', async function() {
+        const docs = await db.collection('test').find({ tags: { $size: 0 } }).toArray();
+        expect(docs).to.have.lengthOf(1);
+        expect(docs[0].name).to.equal('Dave');
+      });
+    });
+  });
+
+  // ============================================
+  // SECTION 3: Update Operators
+  // ============================================
+
+  describe('Update Operators', function() {
+    describe('$set', function() {
+      it('should set field value', async function() {
+        await db.collection('test').insertOne({
+          _id: 'set1',
+          a: 1,
+          b: 2
+        });
+        await db.collection('test').updateOne({ _id: 'set1' }, {
+          $set: {
+            a: 10,
+            c: 3
+          }
+        });
+        const doc = await db.collection('test').findOne({ _id: 'set1' });
+        expect(doc.a).to.equal(10);
+        expect(doc.b).to.equal(2);
+        expect(doc.c).to.equal(3);
+      });
+
+      it('should set nested field value', async function() {
+        await db.collection('test').insertOne({
+          _id: 'set2',
+          nested: { a: 1 }
+        });
+        await db.collection('test').updateOne({ _id: 'set2' }, { $set: { 'nested.b': 2 } });
+        const doc = await db.collection('test').findOne({ _id: 'set2' });
+        expect(doc.nested.a).to.equal(1);
+        expect(doc.nested.b).to.equal(2);
+      });
+    });
+
+    describe('$unset', function() {
+      it('should remove field', async function() {
+        await db.collection('test').insertOne({
+          _id: 'unset1',
+          a: 1,
+          b: 2,
+          c: 3
+        });
+        await db.collection('test').updateOne({ _id: 'unset1' }, { $unset: { b: '' } });
+        const doc = await db.collection('test').findOne({ _id: 'unset1' });
+        expect(doc.a).to.equal(1);
+        expect(doc.b).to.be.undefined;
+        expect(doc.c).to.equal(3);
+      });
+    });
+
+    describe('$inc', function() {
+      it('should increment numeric field', async function() {
+        await db.collection('test').insertOne({
+          _id: 'inc1',
+          count: 5
+        });
+        await db.collection('test').updateOne({ _id: 'inc1' }, { $inc: { count: 3 } });
+        const doc = await db.collection('test').findOne({ _id: 'inc1' });
+        expect(doc.count).to.equal(8);
+      });
+
+      it('should decrement with negative value', async function() {
+        await db.collection('test').insertOne({
+          _id: 'inc2',
+          count: 10
+        });
+        await db.collection('test').updateOne({ _id: 'inc2' }, { $inc: { count: -4 } });
+        const doc = await db.collection('test').findOne({ _id: 'inc2' });
+        expect(doc.count).to.equal(6);
+      });
+
+      it('should create field if it does not exist', async function() {
+        await db.collection('test').insertOne({ _id: 'inc3' });
+        await db.collection('test').updateOne({ _id: 'inc3' }, { $inc: { count: 1 } });
+        const doc = await db.collection('test').findOne({ _id: 'inc3' });
+        expect(doc.count).to.equal(1);
+      });
+    });
+
+    describe('single-statement update path', function() {
+      it('should apply both $inc and $set in a single update', async function() {
+        await db.collection('test').insertOne({
+          _id: 'combo1',
+          count: 5,
+          status: 'pending'
+        });
+        await db.collection('test').updateOne(
+          { _id: 'combo1' },
+          {
+            $inc: { count: 3 },
+            $set: { status: 'done' }
+          }
+        );
+        const doc = await db.collection('test').findOne({ _id: 'combo1' });
+        expect(doc.count).to.equal(8);
+        expect(doc.status).to.equal('done');
+      });
+
+      it('should fall back to read-modify-write for $set with upsert', async function() {
+        await db.collection('test').updateOne(
+          { _id: 'combo2' },
+          { $set: { name: 'upserted' } },
+          { upsert: true }
+        );
+        const doc = await db.collection('test').findOne({ _id: 'combo2' });
+        expect(doc.name).to.equal('upserted');
+      });
+
+      it('should fall back to read-modify-write when $set touches text-indexed fields', async function() {
+        const col = db.collection('test_text_atomic');
+        await col.insertOne({
+          _id: 'ta1',
+          title: 'Original',
+          highSearchText: 'original',
+          lowSearchText: 'original',
+          searchBoost: '',
+          body: 'test'
+        });
+        await col.createIndex({
+          highSearchText: 'text',
+          lowSearchText: 'text',
+          title: 'text',
+          searchBoost: 'text'
+        });
+        // This $set touches 'title' which is text-indexed, so it must
+        // go through the read-modify-write path to keep FTS in sync
+        await col.updateOne(
+          { _id: 'ta1' },
+          {
+            $set: {
+              title: 'Updated',
+              highSearchText: 'updated'
+            }
+          }
+        );
+        const doc = await col.findOne({ _id: 'ta1' });
+        expect(doc.title).to.equal('Updated');
+        // Verify text search finds the updated content
+        const found = await col.find({ $text: { $search: 'updated' } }).toArray();
+        expect(found).to.have.lengthOf(1);
+        expect(found[0]._id).to.equal('ta1');
+        // lowSearchText still contains 'original' so it should still match
+        // (FTS indexes all text fields, not just the ones we updated)
+        const stillFound = await col.find({ $text: { $search: 'original' } }).toArray();
+        expect(stillFound).to.have.lengthOf(1);
+      });
+
+      it('should use single-statement path when $set does not touch text-indexed fields', async function() {
+        const col = db.collection('test_text_atomic');
+        // 'body' is not text-indexed, so this should use the single-statement path
+        await col.updateOne(
+          { _id: 'ta1' },
+          {
+            $set: { body: 'changed' },
+            $inc: { views: 1 }
+          }
+        );
+        const doc = await col.findOne({ _id: 'ta1' });
+        expect(doc.body).to.equal('changed');
+        expect(doc.views).to.equal(1);
+        // Text search should still work (FTS not affected)
+        const found = await col.find({ $text: { $search: 'updated' } }).toArray();
+        expect(found).to.have.lengthOf(1);
+      });
+
+      it('should handle $unset via single-statement path', async function() {
+        await db.collection('test').insertOne({
+          _id: 'atomic_unset1',
+          a: 1,
+          b: 2,
+          c: 3
+        });
+        await db.collection('test').updateOne(
+          { _id: 'atomic_unset1' },
+          { $unset: { b: '' } }
+        );
+        const doc = await db.collection('test').findOne({ _id: 'atomic_unset1' });
+        expect(doc.a).to.equal(1);
+        expect(doc.b).to.be.undefined;
+        expect(doc.c).to.equal(3);
+      });
+
+      it('should handle $unset combined with $set and $inc in a single update', async function() {
+        await db.collection('test').insertOne({
+          _id: 'atomic_unset2',
+          keep: 'yes',
+          remove: 'gone',
+          count: 0
+        });
+        await db.collection('test').updateOne(
+          { _id: 'atomic_unset2' },
+          {
+            $set: { keep: 'updated' },
+            $unset: { remove: '' },
+            $inc: { count: 1 }
+          }
+        );
+        const doc = await db.collection('test').findOne({ _id: 'atomic_unset2' });
+        expect(doc.keep).to.equal('updated');
+        expect(doc.remove).to.be.undefined;
+        expect(doc.count).to.equal(1);
+      });
+
+      it('should handle $currentDate combined with $set in a single update', async function() {
+        await db.collection('test').insertOne({
+          _id: 'atomic_cd1',
+          status: 'pending'
+        });
+        const before = new Date();
+        await db.collection('test').updateOne(
+          { _id: 'atomic_cd1' },
+          {
+            $set: { status: 'done' },
+            $currentDate: { updatedAt: true }
+          }
+        );
+        const after = new Date();
+        const doc = await db.collection('test').findOne({ _id: 'atomic_cd1' });
+        expect(doc.status).to.equal('done');
+        expect(doc.updatedAt).to.be.an.instanceOf(Date);
+        expect(doc.updatedAt.getTime()).to.be.at.least(before.getTime());
+        expect(doc.updatedAt.getTime()).to.be.at.most(after.getTime());
+      });
+
+      it('should handle scalar $addToSet via single-statement path', async function() {
+        await db.collection('test').insertOne({
+          _id: 'atomic_addset1',
+          tags: [ 'a', 'b' ]
+        });
+        // Add new value
+        await db.collection('test').updateOne(
+          { _id: 'atomic_addset1' },
+          { $addToSet: { tags: 'c' } }
+        );
+        let doc = await db.collection('test').findOne({ _id: 'atomic_addset1' });
+        expect(doc.tags).to.include.members([ 'a', 'b', 'c' ]);
+        expect(doc.tags).to.have.lengthOf(3);
+        // Add duplicate (should be no-op)
+        await db.collection('test').updateOne(
+          { _id: 'atomic_addset1' },
+          { $addToSet: { tags: 'b' } }
+        );
+        doc = await db.collection('test').findOne({ _id: 'atomic_addset1' });
+        expect(doc.tags).to.have.lengthOf(3);
+      });
+
+      it('should handle scalar $pull via single-statement path', async function() {
+        await db.collection('test').insertOne({
+          _id: 'atomic_pull1',
+          tags: [ 'a', 'b', 'c' ]
+        });
+        await db.collection('test').updateOne(
+          { _id: 'atomic_pull1' },
+          { $pull: { tags: 'b' } }
+        );
+        const doc = await db.collection('test').findOne({ _id: 'atomic_pull1' });
+        expect(doc.tags).to.deep.equal([ 'a', 'c' ]);
+      });
+
+      it('should handle scalar $push via single-statement path', async function() {
+        await db.collection('test').insertOne({
+          _id: 'atomic_push1',
+          tags: [ 'a', 'b' ]
+        });
+        await db.collection('test').updateOne(
+          { _id: 'atomic_push1' },
+          { $push: { tags: 'c' } }
+        );
+        const doc = await db.collection('test').findOne({ _id: 'atomic_push1' });
+        expect(doc.tags).to.deep.equal([ 'a', 'b', 'c' ]);
+      });
+
+      it('should handle $push when field does not exist', async function() {
+        await db.collection('test').insertOne({
+          _id: 'atomic_push2',
+          name: 'test'
+        });
+        await db.collection('test').updateOne(
+          { _id: 'atomic_push2' },
+          { $push: { tags: 'first' } }
+        );
+        const doc = await db.collection('test').findOne({ _id: 'atomic_push2' });
+        expect(doc.tags).to.deep.equal([ 'first' ]);
+      });
+
+      it('should handle $push with $set and $inc combined', async function() {
+        await db.collection('test').insertOne({
+          _id: 'atomic_push3',
+          log: [ 'init' ],
+          count: 0,
+          status: 'new'
+        });
+        await db.collection('test').updateOne(
+          { _id: 'atomic_push3' },
+          {
+            $push: { log: 'step1' },
+            $inc: { count: 1 },
+            $set: { status: 'running' }
+          }
+        );
+        const doc = await db.collection('test').findOne({ _id: 'atomic_push3' });
+        expect(doc.log).to.deep.equal([ 'init', 'step1' ]);
+        expect(doc.count).to.equal(1);
+        expect(doc.status).to.equal('running');
+      });
+
+      it('should handle $pull and $addToSet on different fields', async function() {
+        await db.collection('test').insertOne({
+          _id: 'atomic_both1',
+          active: [ 'x', 'y' ],
+          archived: [ 'z' ]
+        });
+        await db.collection('test').updateOne(
+          { _id: 'atomic_both1' },
+          {
+            $pull: { active: 'x' },
+            $addToSet: { archived: 'x' }
+          }
+        );
+        const doc = await db.collection('test').findOne({ _id: 'atomic_both1' });
+        expect(doc.active).to.deep.equal([ 'y' ]);
+        expect(doc.archived).to.include.members([ 'z', 'x' ]);
+      });
+
+      it('should handle $addToSet when field does not exist', async function() {
+        await db.collection('test').insertOne({
+          _id: 'atomic_addset2',
+          name: 'test'
+        });
+        await db.collection('test').updateOne(
+          { _id: 'atomic_addset2' },
+          { $addToSet: { tags: 'first' } }
+        );
+        const doc = await db.collection('test').findOne({ _id: 'atomic_addset2' });
+        expect(doc.tags).to.deep.equal([ 'first' ]);
+      });
+
+      it('should handle $pull when field does not exist', async function() {
+        await db.collection('test').insertOne({
+          _id: 'atomic_pull2',
+          name: 'test'
+        });
+        await db.collection('test').updateOne(
+          { _id: 'atomic_pull2' },
+          { $pull: { tags: 'nope' } }
+        );
+        const doc = await db.collection('test').findOne({ _id: 'atomic_pull2' });
+        // MongoDB leaves the field absent, SQL adapters create an
+        // empty array. Both are acceptable — the field has no elements.
+        if (doc.tags !== undefined) {
+          expect(doc.tags).to.deep.equal([]);
+        }
+      });
+
+      it('should combine scalar $pull with $set and $inc', async function() {
+        await db.collection('test').insertOne({
+          _id: 'atomic_combo3',
+          ids: [ 'a', 'b' ],
+          count: 5,
+          status: 'active'
+        });
+        await db.collection('test').updateOne(
+          { _id: 'atomic_combo3' },
+          {
+            $pull: { ids: 'a' },
+            $inc: { count: -1 },
+            $set: { status: 'modified' }
+          }
+        );
+        const doc = await db.collection('test').findOne({ _id: 'atomic_combo3' });
+        expect(doc.ids).to.deep.equal([ 'b' ]);
+        expect(doc.count).to.equal(4);
+        expect(doc.status).to.equal('modified');
+      });
+
+      it('should fall back to read-modify-write for object $addToSet', async function() {
+        await db.collection('test').insertOne({
+          _id: 'atomic_objset1',
+          items: [ { id: 1 } ]
+        });
+        await db.collection('test').updateOne(
+          { _id: 'atomic_objset1' },
+          { $addToSet: { items: { id: 2 } } }
+        );
+        const doc = await db.collection('test').findOne({ _id: 'atomic_objset1' });
+        expect(doc.items).to.have.lengthOf(2);
+        expect(doc.items[1].id).to.equal(2);
+      });
+
+      it('should fall back to read-modify-write for object $pull', async function() {
+        await db.collection('test').insertOne({
+          _id: 'atomic_objpull1',
+          items: [
+            { id: 1 },
+            { id: 2 }
+          ]
+        });
+        await db.collection('test').updateOne(
+          { _id: 'atomic_objpull1' },
+          { $pull: { items: { id: 1 } } }
+        );
+        const doc = await db.collection('test').findOne({ _id: 'atomic_objpull1' });
+        expect(doc.items).to.have.lengthOf(1);
+        expect(doc.items[0].id).to.equal(2);
+      });
+    });
+
+    describe('$push', function() {
+      it('should add element to array', async function() {
+        await db.collection('test').insertOne({
+          _id: 'push1',
+          items: [ 'a', 'b' ]
+        });
+        await db.collection('test').updateOne({ _id: 'push1' }, { $push: { items: 'c' } });
+        const doc = await db.collection('test').findOne({ _id: 'push1' });
+        expect(doc.items).to.deep.equal([ 'a', 'b', 'c' ]);
+      });
+
+      it('should create array if it does not exist', async function() {
+        await db.collection('test').insertOne({ _id: 'push2' });
+        await db.collection('test').updateOne({ _id: 'push2' }, { $push: { items: 'a' } });
+        const doc = await db.collection('test').findOne({ _id: 'push2' });
+        expect(doc.items).to.deep.equal([ 'a' ]);
+      });
+    });
+
+    describe('$pull', function() {
+      it('should remove matching elements from array', async function() {
+        await db.collection('test').insertOne({
+          _id: 'pull1',
+          items: [ 'a', 'b', 'c', 'b' ]
+        });
+        await db.collection('test').updateOne({ _id: 'pull1' }, { $pull: { items: 'b' } });
+        const doc = await db.collection('test').findOne({ _id: 'pull1' });
+        expect(doc.items).to.deep.equal([ 'a', 'c' ]);
+      });
+    });
+
+    describe('$addToSet', function() {
+      it('should add element only if not present', async function() {
+        await db.collection('test').insertOne({
+          _id: 'add1',
+          tags: [ 'a', 'b' ]
+        });
+        await db.collection('test').updateOne({ _id: 'add1' }, { $addToSet: { tags: 'c' } });
+        const doc = await db.collection('test').findOne({ _id: 'add1' });
+        expect(doc.tags).to.deep.equal([ 'a', 'b', 'c' ]);
+      });
+
+      it('should not add duplicate element', async function() {
+        await db.collection('test').insertOne({
+          _id: 'add2',
+          tags: [ 'a', 'b' ]
+        });
+        await db.collection('test').updateOne({ _id: 'add2' }, { $addToSet: { tags: 'b' } });
+        const doc = await db.collection('test').findOne({ _id: 'add2' });
+        expect(doc.tags).to.deep.equal([ 'a', 'b' ]);
+      });
+    });
+
+    describe('$currentDate', function() {
+      it('should set field to current date', async function() {
+        await db.collection('test').insertOne({
+          _id: 'date1',
+          name: 'test'
+        });
+        const before = new Date();
+        await db.collection('test').updateOne({ _id: 'date1' }, { $currentDate: { updatedAt: true } });
+        const after = new Date();
+        const doc = await db.collection('test').findOne({ _id: 'date1' });
+        expect(doc.updatedAt).to.be.instanceOf(Date);
+        expect(doc.updatedAt.getTime()).to.be.at.least(before.getTime());
+        expect(doc.updatedAt.getTime()).to.be.at.most(after.getTime());
+      });
+    });
+  });
+
+  // ============================================
+  // SECTION 4: Counting and Distinct
+  // ============================================
+
+  describe('countDocuments', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'c1',
+          type: 'a',
+          value: 1
+        },
+        {
+          _id: 'c2',
+          type: 'a',
+          value: 2
+        },
+        {
+          _id: 'c3',
+          type: 'b',
+          value: 3
+        }
+      ]);
+    });
+
+    it('should count all documents', async function() {
+      const count = await db.collection('test').countDocuments({});
+      expect(count).to.equal(3);
+    });
+
+    it('should count matching documents', async function() {
+      const count = await db.collection('test').countDocuments({ type: 'a' });
+      expect(count).to.equal(2);
+    });
+  });
+
+  describe('distinct', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'd1',
+          category: 'food',
+          tag: 'healthy'
+        },
+        {
+          _id: 'd2',
+          category: 'food',
+          tag: 'junk'
+        },
+        {
+          _id: 'd3',
+          category: 'tech',
+          tag: 'healthy'
+        },
+        {
+          _id: 'd4',
+          category: 'tech',
+          tag: 'new'
+        }
+      ]);
+    });
+
+    it('should return distinct values for field', async function() {
+      const values = await db.collection('test').distinct('category');
+      expect(values.sort()).to.deep.equal([ 'food', 'tech' ]);
+    });
+
+    it('should return distinct values with filter', async function() {
+      const values = await db.collection('test').distinct('tag', { category: 'food' });
+      expect(values.sort()).to.deep.equal([ 'healthy', 'junk' ]);
+    });
+
+    it('should return distinct object values as parsed objects', async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'dobj1',
+          updatedBy: { _id: 'user1', title: 'Alice' }
+        },
+        {
+          _id: 'dobj2',
+          updatedBy: { _id: 'user2', title: 'Bob' }
+        },
+        {
+          _id: 'dobj3',
+          updatedBy: { _id: 'user1', title: 'Alice' }
+        }
+      ]);
+      const values = await db.collection('test').distinct('updatedBy');
+      // Should return parsed objects, not JSON strings
+      expect(values).to.be.an('array');
+      expect(values.length).to.be.at.least(2);
+      const hasUser1 = values.some(v => typeof v === 'object' && v._id === 'user1');
+      const hasUser2 = values.some(v => typeof v === 'object' && v._id === 'user2');
+      expect(hasUser1).to.equal(true);
+      expect(hasUser2).to.equal(true);
+    });
+  });
+
+  // ============================================
+  // SECTION 5: Aggregation (Limited)
+  // ============================================
+
+  describe('aggregate', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'agg1',
+          category: 'fruit',
+          name: 'apple',
+          qty: 10
+        },
+        {
+          _id: 'agg2',
+          category: 'fruit',
+          name: 'banana',
+          qty: 5
+        },
+        {
+          _id: 'agg3',
+          category: 'vegetable',
+          name: 'carrot',
+          qty: 8
+        },
+        {
+          _id: 'agg4',
+          category: 'vegetable',
+          name: 'broccoli',
+          qty: 3
+        }
+      ]);
+    });
+
+    it('$match - should filter documents', async function() {
+      const results = await db.collection('test').aggregate([
+        { $match: { category: 'fruit' } }
+      ]).toArray();
+      expect(results).to.have.lengthOf(2);
+    });
+
+    it('$group - should group and aggregate', async function() {
+      const results = await db.collection('test').aggregate([
+        {
+          $group: {
+            _id: '$category',
+            total: { $sum: '$qty' }
+          }
+        }
+      ]).toArray();
+      expect(results).to.have.lengthOf(2);
+      const fruit = results.find(r => r._id === 'fruit');
+      const vegetable = results.find(r => r._id === 'vegetable');
+      expect(fruit.total).to.equal(15);
+      expect(vegetable.total).to.equal(11);
+    });
+
+    it('$project - should project fields', async function() {
+      const results = await db.collection('test').aggregate([
+        { $match: { _id: 'agg1' } },
+        {
+          $project: {
+            name: 1,
+            qty: 1
+          }
+        }
+      ]).toArray();
+      expect(results).to.have.lengthOf(1);
+      expect(results[0].name).to.equal('apple');
+      expect(results[0].category).to.be.undefined;
+    });
+
+    it('$unwind - should unwind array field', async function() {
+      await db.collection('test').insertOne({
+        _id: 'agg5',
+        name: 'mixed',
+        items: [ 'x', 'y', 'z' ]
+      });
+      const results = await db.collection('test').aggregate([
+        { $match: { _id: 'agg5' } },
+        { $unwind: '$items' }
+      ]).toArray();
+      expect(results).to.have.lengthOf(3);
+      expect(results.map(r => r.items)).to.deep.equal([ 'x', 'y', 'z' ]);
+    });
+
+    it('$match - throws on unrecognized operator (parity with find())', async function() {
+      // The in-memory matcher backs any $match stage after the first,
+      // so unknown operators must throw instead of silently matching
+      // everything — matching the SQL find() path.
+      let err;
+      try {
+        await db.collection('test').aggregate([
+          { $match: { category: 'fruit' } },
+          { $match: { qty: { $madeUp: 5 } } }
+        ]).toArray();
+      } catch (e) {
+        err = e;
+      }
+      expect(err).to.exist;
+      expect(err.message).to.match(/\$madeUp|Unsupported operator/);
+    });
+
+    it('$match - supports $regex/$not/$all/$size in the in-memory matcher', async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'agg6',
+          name: 'match',
+          tags: [ 'a', 'b', 'c' ]
+        },
+        {
+          _id: 'agg7',
+          name: 'other',
+          tags: [ 'a' ]
+        }
+      ]);
+      const r1 = await db.collection('test').aggregate([
+        { $match: { name: { $exists: true } } },
+        { $match: { name: { $regex: '^mat' } } }
+      ]).toArray();
+      expect(r1.map(d => d._id)).to.deep.equal([ 'agg6' ]);
+
+      const r2 = await db.collection('test').aggregate([
+        { $match: { _id: { $in: [ 'agg6', 'agg7' ] } } },
+        { $match: { tags: { $size: 3 } } }
+      ]).toArray();
+      expect(r2.map(d => d._id)).to.deep.equal([ 'agg6' ]);
+
+      const r3 = await db.collection('test').aggregate([
+        { $match: { _id: { $in: [ 'agg6', 'agg7' ] } } },
+        { $match: { tags: { $all: [ 'a', 'b' ] } } }
+      ]).toArray();
+      expect(r3.map(d => d._id)).to.deep.equal([ 'agg6' ]);
+
+      const r4 = await db.collection('test').aggregate([
+        { $match: { _id: { $in: [ 'agg6', 'agg7' ] } } },
+        { $match: { name: { $not: { $regex: '^mat' } } } }
+      ]).toArray();
+      expect(r4.map(d => d._id)).to.deep.equal([ 'agg7' ]);
+    });
+  });
+
+  // ============================================
+  // SECTION 6: Index Operations
+  // ============================================
+
+  describe('Index Operations', function() {
+    it('createIndex - should create a single field index', async function() {
+      await db.collection('test').insertOne({
+        _id: 'idx1',
+        field: 'value'
+      });
+      const indexName = await db.collection('test').createIndex({ field: 1 });
+      expect(indexName).to.be.a('string');
+
+      const indexes = await db.collection('test').indexes();
+      const fieldIndex = indexes.find(i => i.key && i.key.field === 1);
+      expect(fieldIndex).to.exist;
+    });
+
+    it('createIndex - should create a compound index', async function() {
+      await db.collection('test').insertOne({
+        _id: 'idx2',
+        a: 1,
+        b: 2
+      });
+      const indexName = await db.collection('test').createIndex({
+        a: 1,
+        b: -1
+      });
+      expect(indexName).to.be.a('string');
+    });
+
+    it('createIndex - should create a unique index', async function() {
+      await db.collection('test').insertOne({
+        _id: 'idx3',
+        email: 'test@example.com'
+      });
+      await db.collection('test').createIndex({ email: 1 }, { unique: true });
+
+      // Should reject duplicate
+      try {
+        await db.collection('test').insertOne({
+          _id: 'idx4',
+          email: 'test@example.com'
+        });
+        expect.fail('Should have thrown duplicate key error');
+      } catch (e) {
+        expect(e.message).to.match(/duplicate|unique|already exists/i);
+      }
+    });
+
+    it('createIndex - should support text index', async function() {
+      await db.collection('test').insertOne({
+        _id: 'txt1',
+        content: 'hello world'
+      });
+      const indexName = await db.collection('test').createIndex({ content: 'text' });
+      expect(indexName).to.be.a('string');
+    });
+
+    it('dropIndex - should drop an index', async function() {
+      await db.collection('test').insertOne({
+        _id: 'drop1',
+        field: 'value'
+      });
+      const indexName = await db.collection('test').createIndex({ field: 1 });
+
+      await db.collection('test').dropIndex(indexName);
+
+      const indexes = await db.collection('test').indexes();
+      const fieldIndex = indexes.find(i => i.name === indexName);
+      expect(fieldIndex).to.not.exist;
+    });
+
+    it('indexes - should list all indexes', async function() {
+      await db.collection('test').insertOne({
+        _id: 'list1',
+        a: 1,
+        b: 2
+      });
+      await db.collection('test').createIndex({ a: 1 });
+      await db.collection('test').createIndex({ b: 1 });
+
+      const indexes = await db.collection('test').indexes();
+      expect(indexes.length).to.be.at.least(3); // _id index + a + b
+    });
+
+    it('createIndex - should create index on nested field', async function() {
+      await db.collection('test').insertOne({
+        _id: 'nested1',
+        user: { profile: { name: 'Alice' } }
+      });
+      const indexName = await db.collection('test').createIndex({ 'user.profile.name': 1 });
+      expect(indexName).to.be.a('string');
+
+      // Verify we can query using the indexed field
+      const doc = await db.collection('test').findOne({ 'user.profile.name': 'Alice' });
+      expect(doc).to.exist;
+      expect(doc._id).to.equal('nested1');
+    });
+
+    it('createIndex - should create sparse index', async function() {
+      // Insert docs with and without the indexed field
+      await db.collection('test').insertMany([
+        {
+          _id: 'sparse1',
+          optionalField: 'present'
+        },
+        { _id: 'sparse2' }, // no optionalField
+        {
+          _id: 'sparse3',
+          optionalField: 'also present'
+        }
+      ]);
+
+      const indexName = await db.collection('test').createIndex(
+        { optionalField: 1 },
+        { sparse: true }
+      );
+      expect(indexName).to.be.a('string');
+
+      // Both docs with the field should be findable
+      const docs = await db.collection('test').find({ optionalField: { $exists: true } }).toArray();
+      expect(docs).to.have.lengthOf(2);
+    });
+
+    it('createIndex - should create unique sparse index', async function() {
+      // Unique sparse index allows multiple docs without the field
+      await db.collection('test').insertMany([
+        {
+          _id: 'us1',
+          uniqueOptional: 'value1'
+        },
+        { _id: 'us2' }, // no uniqueOptional - allowed with sparse
+        { _id: 'us3' }  // no uniqueOptional - also allowed with sparse
+      ]);
+
+      await db.collection('test').createIndex(
+        { uniqueOptional: 1 },
+        {
+          unique: true,
+          sparse: true
+        }
+      );
+
+      // Should reject duplicate value
+      try {
+        await db.collection('test').insertOne({
+          _id: 'us4',
+          uniqueOptional: 'value1'
+        });
+        expect.fail('Should have thrown duplicate key error');
+      } catch (e) {
+        expect(e.message).to.match(/duplicate|unique|already exists/i);
+      }
+
+      // But allow another doc without the field
+      await db.collection('test').insertOne({ _id: 'us5' });
+      const count = await db.collection('test').countDocuments({ _id: { $in: [ 'us2', 'us3', 'us5' ] } });
+      expect(count).to.equal(3);
+    });
+
+    // Typed index tests - these are PostgreSQL-specific optimizations
+    // but should work (be ignored) for MongoDB as well
+    it('createIndex - should create numeric index for range queries', async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'num1',
+          price: 10
+        },
+        {
+          _id: 'num2',
+          price: 25
+        },
+        {
+          _id: 'num3',
+          price: 50
+        },
+        {
+          _id: 'num4',
+          price: 100
+        }
+      ]);
+
+      // Create numeric index for efficient range queries
+      const indexName = await db.collection('test').createIndex(
+        { price: 1 },
+        { type: 'number' }
+      );
+      expect(indexName).to.be.a('string');
+
+      // Range queries should work correctly
+      const cheap = await db.collection('test').find({ price: { $lt: 30 } }).toArray();
+      expect(cheap).to.have.lengthOf(2);
+      expect(cheap.map(d => d._id).sort()).to.deep.equal([ 'num1', 'num2' ]);
+
+      const expensive = await db.collection('test').find({ price: { $gte: 50 } }).toArray();
+      expect(expensive).to.have.lengthOf(2);
+      expect(expensive.map(d => d._id).sort()).to.deep.equal([ 'num3', 'num4' ]);
+
+      const midRange = await db.collection('test').find({
+        price: {
+          $gt: 10,
+          $lt: 100
+        }
+      }).toArray();
+      expect(midRange).to.have.lengthOf(2);
+      expect(midRange.map(d => d._id).sort()).to.deep.equal([ 'num2', 'num3' ]);
+    });
+
+    it('createIndex - should create date index for range queries', async function() {
+      const now = new Date();
+      const yesterday = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+      const lastWeek = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+      const lastMonth = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000);
+
+      await db.collection('test').insertMany([
+        {
+          _id: 'date1',
+          createdAt: lastMonth
+        },
+        {
+          _id: 'date2',
+          createdAt: lastWeek
+        },
+        {
+          _id: 'date3',
+          createdAt: yesterday
+        },
+        {
+          _id: 'date4',
+          createdAt: now
+        }
+      ]);
+
+      // Create date index for efficient range queries
+      const indexName = await db.collection('test').createIndex(
+        { createdAt: 1 },
+        { type: 'date' }
+      );
+      expect(indexName).to.be.a('string');
+
+      // Range queries should work correctly
+      const recent = await db.collection('test').find({
+        createdAt: { $gte: yesterday }
+      }).toArray();
+      expect(recent).to.have.lengthOf(2);
+      expect(recent.map(d => d._id).sort()).to.deep.equal([ 'date3', 'date4' ]);
+
+      const older = await db.collection('test').find({
+        createdAt: { $lt: lastWeek }
+      }).toArray();
+      expect(older).to.have.lengthOf(1);
+      expect(older[0]._id).to.equal('date1');
+
+      const midRange = await db.collection('test').find({
+        createdAt: {
+          $gt: lastMonth,
+          $lt: now
+        }
+      }).toArray();
+      expect(midRange).to.have.lengthOf(2);
+      expect(midRange.map(d => d._id).sort()).to.deep.equal([ 'date2', 'date3' ]);
+    });
+
+    it('createIndex - should create unique numeric index', async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'unum1',
+          rank: 1
+        },
+        {
+          _id: 'unum2',
+          rank: 2
+        }
+      ]);
+
+      await db.collection('test').createIndex(
+        { rank: 1 },
+        {
+          type: 'number',
+          unique: true
+        }
+      );
+
+      // Should reject duplicate
+      try {
+        await db.collection('test').insertOne({
+          _id: 'unum3',
+          rank: 1
+        });
+        expect.fail('Should have thrown duplicate key error');
+      } catch (e) {
+        expect(e.message).to.match(/duplicate|unique|already exists/i);
+      }
+
+      // Different value should work
+      await db.collection('test').insertOne({
+        _id: 'unum3',
+        rank: 3
+      });
+      const count = await db.collection('test').countDocuments({ _id: { $regex: '^unum' } });
+      expect(count).to.equal(3);
+    });
+
+    if (ADAPTER === 'postgres' || ADAPTER === 'multipostgres') {
+      // PostgreSQL-specific: verify indexes() reconstructs metadata from
+      // pg_indexes when the in-memory _indexes Map is not populated
+      // (e.g. after a reconnect)
+      it('indexes - should reconstruct index metadata from SQL definitions', async function() {
+        await db.collection('test').insertOne({
+          _id: 'parse1',
+          slug: 'hello',
+          price: 42,
+          createdAt: new Date('2024-06-01T00:00:00Z'),
+          user: { profile: { name: 'Alice' } },
+          content: 'some text here'
+        });
+
+        // Create various index types
+        await db.collection('test').createIndex({ slug: 1 });
+        await db.collection('test').createIndex({
+          a: 1,
+          b: -1
+        });
+        await db.collection('test').createIndex({ price: 1 }, { type: 'number' });
+        await db.collection('test').createIndex({ createdAt: 1 }, { type: 'date' });
+        await db.collection('test').createIndex({ 'user.profile.name': 1 });
+        await db.collection('test').createIndex({ content: 'text' });
+        await db.collection('test').createIndex({ slug: 1 }, {
+          unique: true,
+          name: 'slug_unique'
+        });
+        await db.collection('test').createIndex({ price: 1 }, {
+          sparse: true,
+          type: 'number',
+          name: 'price_sparse'
+        });
+
+        // Clear the in-memory index cache to force parsing from SQL
+        db.collection('test')._indexes.clear();
+
+        const indexes = await db.collection('test').indexes();
+
+        // Find the default text index
+        const textIdx = indexes.find(i => i.key && i.key.content === 'text');
+        expect(textIdx).to.exist;
+        expect(textIdx.key.content).to.equal('text');
+
+        // Find the single field index
+        const slugIdx = indexes.find(i =>
+          i.key && i.key.slug === 1 && !i.unique
+        );
+        expect(slugIdx).to.exist;
+
+        // Find the numeric typed index
+        const numIdx = indexes.find(i =>
+          i.key && i.key.price === 1 && i.type === 'number' && !i.sparse
+        );
+        expect(numIdx).to.exist;
+
+        // Find the date typed index
+        const dateIdx = indexes.find(i =>
+          i.key && i.key.createdAt === 1 && i.type === 'date'
+        );
+        expect(dateIdx).to.exist;
+
+        // Find the nested field index
+        const nestedIdx = indexes.find(i =>
+          i.key && i.key['user.profile.name'] === 1
+        );
+        expect(nestedIdx).to.exist;
+
+        // Find the compound index
+        const compoundIdx = indexes.find(i =>
+          i.key && i.key.a === 1 && i.key.b === -1
+        );
+        expect(compoundIdx).to.exist;
+
+        // Find the unique index
+        const uniqueIdx = indexes.find(i =>
+          i.key && i.key.slug === 1 && i.unique
+        );
+        expect(uniqueIdx).to.exist;
+
+        // Find the sparse numeric index
+        const sparseNumIdx = indexes.find(i =>
+          i.key && i.key.price === 1 && i.sparse && i.type === 'number'
+        );
+        expect(sparseNumIdx).to.exist;
+      });
+    }
+
+    // Verify that anchored-regex queries (e.g. ApostropheCMS matchDescendants)
+    // actually use a btree index on the matched field via the rewrite to a
+    // range predicate. This is the behavior we care about — without it, page
+    // tree queries degrade to O(n) sequential scans.
+    // Seed a collection with many non-matching _ids plus two targets
+    // whose _id matches /^\/tree\/parent\//. We assert index usage
+    // against the primary-key _id column rather than a JSONB field,
+    // because JSON-field regex queries carry a scalar-OR-array-element
+    // disjunction (MongoDB semantics for regex-matches-array-of-strings)
+    // that deliberately blocks bitmap index scans on the scalar branch.
+    // The primary-key path has no such fallback, so it is the right
+    // place to prove that the anchored-regex → range-predicate rewrite
+    // makes the adapter's real query index-eligible.
+    async function seedIdIndexCollection(coll) {
+      await coll.deleteMany({});
+      const docs = [];
+      for (let i = 0; i < 200; i++) {
+        docs.push({ _id: `/p${i}/child` });
+      }
+      docs.push({ _id: '/tree/parent/a' });
+      docs.push({ _id: '/tree/parent/b' });
+      await coll.insertMany(docs);
+    }
+
+    if (ADAPTER === 'postgres' || ADAPTER === 'multipostgres') {
+      it('anchored regex on an indexed field uses a btree index scan (postgres)', async function() {
+        const coll = db.collection('pathidx');
+        await seedIdIndexCollection(coll);
+
+        // End-to-end correctness first — proves the rewrite produces
+        // correct results.
+        const results = await coll.find({ _id: /^\/tree\/parent\// }).toArray();
+        const ids = results.map(d => d._id).sort();
+        expect(ids).to.deep.equal([ '/tree/parent/a', '/tree/parent/b' ]);
+
+        // Ask the cursor for the SQL it would actually run, then EXPLAIN
+        // THAT SQL. This keeps the test honest: future changes to
+        // buildWhereClause immediately show up here instead of drifting
+        // apart from a hand-written SQL string.
+        const cursor = coll.find({ _id: /^\/tree\/parent\// });
+        const { sql, params } = await cursor.explain();
+
+        const pool = db._pool;
+        const client = await pool.connect();
+        try {
+          await client.query('BEGIN');
+          // Make sure the planner has stats for the freshly seeded
+          // table — otherwise it may default to a seqscan based on a
+          // 0-row estimate.
+          await client.query(`ANALYZE ${coll._qualifiedName()}`);
+          // Force enable_seqscan = off so the planner must use the
+          // index if it is eligible at all. If it still falls back to
+          // a sequential scan under this setting, the rewrite is
+          // producing a predicate the planner cannot match to the
+          // index — i.e. the regression we are guarding against.
+          await client.query('SET LOCAL enable_seqscan = off');
+          const explain = await client.query(`EXPLAIN ${sql}`, params);
+          const planText = explain.rows.map(r => r['QUERY PLAN']).join('\n');
+          expect(planText).to.match(/Index (Only )?Scan|Bitmap Index Scan/);
+          await client.query('ROLLBACK');
+        } finally {
+          client.release();
+        }
+
+        await coll.deleteMany({});
+      });
+    }
+
+    if (ADAPTER === 'sqlite') {
+      it('anchored regex on an indexed field uses a btree index search (sqlite)', async function() {
+        const coll = db.collection('pathidx');
+        await seedIdIndexCollection(coll);
+
+        // End-to-end correctness first
+        const results = await coll.find({ _id: /^\/tree\/parent\// }).toArray();
+        const ids = results.map(d => d._id).sort();
+        expect(ids).to.deep.equal([ '/tree/parent/a', '/tree/parent/b' ]);
+
+        // Ask the cursor for the SQL it would actually run, then
+        // EXPLAIN QUERY PLAN on that same SQL. SQLite plan output:
+        //   "SEARCH table USING INDEX idx_name (...)"  -- uses index
+        //   "SCAN table"                                -- full scan
+        const cursor = coll.find({ _id: /^\/tree\/parent\// });
+        const { sql, params } = await cursor.explain();
+        const sqlite = db._sqlite;
+        const planRows = sqlite.prepare(`EXPLAIN QUERY PLAN ${sql}`).all(...params);
+        const planText = planRows.map(r => r.detail || '').join('\n');
+        expect(planText).to.match(/SEARCH.*USING (INDEX|ROWID|PRIMARY KEY)/);
+
+        await coll.deleteMany({});
+      });
+    }
+  });
+
+  // ============================================
+  // SECTION 7: Bulk Operations
+  // ============================================
+
+  describe('bulkWrite', function() {
+    it('should execute multiple operations', async function() {
+      await db.collection('test').insertOne({
+        _id: 'bulk1',
+        value: 1
+      });
+
+      const result = await db.collection('test').bulkWrite([
+        {
+          insertOne: {
+            document: {
+              _id: 'bulk2',
+              value: 2
+            }
+          }
+        },
+        {
+          updateOne: {
+            filter: { _id: 'bulk1' },
+            update: { $set: { value: 10 } }
+          }
+        },
+        {
+          insertOne: {
+            document: {
+              _id: 'bulk3',
+              value: 3
+            }
+          }
+        },
+        { deleteOne: { filter: { _id: 'bulk3' } } }
+      ]);
+
+      expect(result.insertedCount).to.equal(2);
+      expect(result.modifiedCount).to.equal(1);
+      expect(result.deletedCount).to.equal(1);
+
+      const docs = await db.collection('test').find({}).toArray();
+      expect(docs).to.have.lengthOf(2);
+      expect(docs.find(d => d._id === 'bulk1').value).to.equal(10);
+    });
+  });
+
+  // ============================================
+  // SECTION 8: findOneAndUpdate
+  // ============================================
+
+  describe('findOneAndUpdate', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertOne({
+        _id: 'fau1',
+        value: 1,
+        name: 'original'
+      });
+    });
+
+    it('should update and return the document', async function() {
+      const result = await db.collection('test').findOneAndUpdate(
+        { _id: 'fau1' },
+        { $set: { name: 'updated' } },
+        { returnDocument: 'after' }
+      );
+      expect(result._id).to.equal('fau1');
+      expect(result.name).to.equal('updated');
+    });
+
+    it('should return original by default', async function() {
+      const result = await db.collection('test').findOneAndUpdate(
+        { _id: 'fau1' },
+        { $set: { name: 'updated' } }
+      );
+      expect(result._id).to.equal('fau1');
+      expect(result.name).to.equal('original');
+    });
+
+    it('should support upsert', async function() {
+      const result = await db.collection('test').findOneAndUpdate(
+        { _id: 'fau2' },
+        { $set: { name: 'new' } },
+        {
+          upsert: true,
+          returnDocument: 'after'
+        }
+      );
+      expect(result._id).to.equal('fau2');
+      expect(result.name).to.equal('new');
+    });
+  });
+
+  // ============================================
+  // SECTION 9: Database Operations
+  // ============================================
+
+  describe('Database Operations', function() {
+    it('should get collection reference', function() {
+      const collection = db.collection('newcollection');
+      expect(collection).to.exist;
+      expect(collection.collectionName || collection.name).to.equal('newcollection');
+    });
+
+    it('should list collections', async function() {
+      await db.collection('listtest1').insertOne({ _id: '1' });
+      await db.collection('listtest2').insertOne({ _id: '2' });
+
+      const collections = await db.listCollections().toArray();
+      const names = collections.map(c => c.name);
+      expect(names).to.include('listtest1');
+      expect(names).to.include('listtest2');
+    });
+
+    it('should drop collection', async function() {
+      await db.collection('dropme').insertOne({ _id: '1' });
+
+      let collections = await db.listCollections().toArray();
+      expect(collections.map(c => c.name)).to.include('dropme');
+
+      await db.collection('dropme').drop();
+
+      collections = await db.listCollections().toArray();
+      expect(collections.map(c => c.name)).to.not.include('dropme');
+    });
+
+    it('should rename collection', async function() {
+      await db.collection('oldname').insertOne({
+        _id: 'rename1',
+        value: 42
+      });
+
+      await db.collection('oldname').rename('newname');
+
+      const doc = await db.collection('newname').findOne({ _id: 'rename1' });
+      expect(doc.value).to.equal(42);
+
+      const oldDoc = await db.collection('oldname').findOne({ _id: 'rename1' });
+      expect(oldDoc).to.be.null;
+    });
+  });
+
+  // ============================================
+  // SECTION 10: Nested Field Queries
+  // ============================================
+
+  describe('Nested Field Queries', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'n1',
+          user: {
+            name: 'Alice',
+            role: 'admin'
+          },
+          metadata: { views: 100 }
+        },
+        {
+          _id: 'n2',
+          user: {
+            name: 'Bob',
+            role: 'user'
+          },
+          metadata: { views: 50 }
+        },
+        {
+          _id: 'n3',
+          user: {
+            name: 'Carol',
+            role: 'admin'
+          },
+          metadata: { views: 200 }
+        }
+      ]);
+    });
+
+    it('should query nested fields with dot notation', async function() {
+      const docs = await db.collection('test').find({ 'user.role': 'admin' }).toArray();
+      expect(docs).to.have.lengthOf(2);
+    });
+
+    it('should update nested fields with dot notation', async function() {
+      await db.collection('test').updateOne(
+        { _id: 'n1' },
+        { $set: { 'user.name': 'Alicia' } }
+      );
+      const doc = await db.collection('test').findOne({ _id: 'n1' });
+      expect(doc.user.name).to.equal('Alicia');
+      expect(doc.user.role).to.equal('admin');
+    });
+
+    it('should project nested fields', async function() {
+      const doc = await db.collection('test').findOne(
+        { _id: 'n1' },
+        { projection: { 'user.name': 1 } }
+      );
+      expect(doc._id).to.equal('n1');
+      expect(doc.user.name).to.equal('Alice');
+      expect(doc.user.role).to.be.undefined;
+      expect(doc.metadata).to.be.undefined;
+    });
+  });
+
+  // ============================================
+  // SECTION 11: Sort on Multiple Fields
+  // ============================================
+
+  describe('Multi-field Sort', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 's1',
+          category: 'a',
+          priority: 2
+        },
+        {
+          _id: 's2',
+          category: 'b',
+          priority: 1
+        },
+        {
+          _id: 's3',
+          category: 'a',
+          priority: 1
+        },
+        {
+          _id: 's4',
+          category: 'b',
+          priority: 2
+        }
+      ]);
+    });
+
+    it('should sort by multiple fields', async function() {
+      const docs = await db.collection('test')
+        .find({})
+        .sort({
+          category: 1,
+          priority: -1
+        })
+        .toArray();
+
+      expect(docs[0]._id).to.equal('s1'); // a, 2
+      expect(docs[1]._id).to.equal('s3'); // a, 1
+      expect(docs[2]._id).to.equal('s4'); // b, 2
+      expect(docs[3]._id).to.equal('s2'); // b, 1
+    });
+  });
+
+  // ============================================
+  // SECTION 12: Database Switching
+  // ============================================
+
+  describe('Database Switching', function() {
+    if (ADAPTER === 'postgres') {
+      it('should return the same db for nullish or matching name', function() {
+        const db1 = client.db();
+        const db2 = client.db();
+        const db3 = client.db('dbtest_adapter');
+        expect(db1).to.equal(db2);
+        expect(db1).to.equal(db3);
+      });
+
+      it('should throw when requesting a different database name', function() {
+        expect(() => client.db('other_name')).to.throw(/multipostgres/);
+      });
+    } else if (ADAPTER === 'multipostgres') {
+      it('should switch to sibling schema', async function() {
+        const siblingDb = client.db('dbtest_adapter-siblingschema');
+
+        await siblingDb.collection('siblingcol').insertOne({
+          _id: 'sib1',
+          from: 'sibling'
+        });
+
+        // Verify it's not in original schema
+        const origDoc = await db.collection('siblingcol').findOne({ _id: 'sib1' });
+        expect(origDoc).to.be.null;
+
+        // Verify it's in sibling schema
+        const sibDoc = await siblingDb.collection('siblingcol').findOne({ _id: 'sib1' });
+        expect(sibDoc).to.exist;
+        expect(sibDoc.from).to.equal('sibling');
+
+        // Clean up sibling
+        await siblingDb.dropDatabase();
+      });
+    } else {
+      it('should switch to sibling database', async function() {
+        const siblingDb = client.db('dbtest-sibling');
+
+        await siblingDb.collection('siblingcol').insertOne({
+          _id: 'sib1',
+          from: 'sibling'
+        });
+
+        // Verify it's not in original
+        const origDoc = await db.collection('siblingcol').findOne({ _id: 'sib1' });
+        expect(origDoc).to.be.null;
+
+        // Verify it's in sibling
+        const sibDoc = await siblingDb.collection('siblingcol').findOne({ _id: 'sib1' });
+        expect(sibDoc).to.exist;
+        expect(sibDoc.from).to.equal('sibling');
+
+        // Clean up sibling
+        await siblingDb.collection('siblingcol').drop();
+      });
+    }
+  });
+
+  // ============================================
+  // SECTION 13: Empty Results
+  // ============================================
+
+  describe('Empty Results Handling', function() {
+    it('should return empty array for find with no matches', async function() {
+      const docs = await db.collection('test').find({ nonexistent: true }).toArray();
+      expect(docs).to.be.an('array').that.is.empty;
+    });
+
+    it('should return 0 for count with no matches', async function() {
+      const count = await db.collection('test').countDocuments({ nonexistent: true });
+      expect(count).to.equal(0);
+    });
+
+    it('should return empty array for distinct with no matches', async function() {
+      const values = await db.collection('test').distinct('field', { nonexistent: true });
+      expect(values).to.be.an('array').that.is.empty;
+    });
+  });
+
+  // ============================================
+  // SECTION 14: Date Handling
+  // ============================================
+
+  describe('Date Handling', function() {
+    it('should store and retrieve Date objects', async function() {
+      const now = new Date();
+      await db.collection('test').insertOne({
+        _id: 'date1',
+        createdAt: now
+      });
+
+      const doc = await db.collection('test').findOne({ _id: 'date1' });
+      expect(doc.createdAt).to.be.instanceOf(Date);
+      expect(doc.createdAt.getTime()).to.equal(now.getTime());
+    });
+
+    it('should query by date comparison', async function() {
+      const old = new Date('2020-01-01');
+      const recent = new Date('2024-01-01');
+      const cutoff = new Date('2022-01-01');
+
+      await db.collection('test').insertMany([
+        {
+          _id: 'old',
+          createdAt: old
+        },
+        {
+          _id: 'recent',
+          createdAt: recent
+        }
+      ]);
+
+      const docs = await db.collection('test').find({ createdAt: { $gte: cutoff } }).toArray();
+      expect(docs).to.have.lengthOf(1);
+      expect(docs[0]._id).to.equal('recent');
+    });
+  });
+
+  // ============================================
+  // SECTION 15: Null and Undefined Handling
+  // ============================================
+
+  describe('Null and Undefined Handling', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'null1',
+          value: null
+        },
+        {
+          _id: 'null2',
+          value: 'present'
+        },
+        { _id: 'null3' } // value field missing
+      ]);
+    });
+
+    it('should find documents with null value', async function() {
+      const docs = await db.collection('test').find({ value: null }).toArray();
+      // MongoDB matches both explicit null AND missing fields with
+      // { value: null }, so null1 (explicit null) and null3 (missing) match,
+      // but null2 (value: 'present') does not.
+      expect(docs).to.have.lengthOf(2);
+      expect(docs.map(d => d._id).sort()).to.deep.equal([ 'null1', 'null3' ]);
+    });
+
+    it('should distinguish null from missing with $exists', async function() {
+      const withField = await db.collection('test').find({ value: { $exists: true } }).toArray();
+      expect(withField).to.have.lengthOf(2);
+
+      const withoutField = await db.collection('test').find({ value: { $exists: false } }).toArray();
+      expect(withoutField).to.have.lengthOf(1);
+      expect(withoutField[0]._id).to.equal('null3');
+    });
+  });
+
+  // ============================================
+  // SECTION 16: Mixed Type Arrays
+  // ============================================
+
+  describe('Mixed Type Arrays', function() {
+    it('should handle arrays with mixed types', async function() {
+      await db.collection('test').insertOne({
+        _id: 'mixed1',
+        items: [ 1, 'two', { three: 3 }, [ 4, 5 ], null ]
+      });
+
+      const doc = await db.collection('test').findOne({ _id: 'mixed1' });
+      expect(doc.items).to.deep.equal([ 1, 'two', { three: 3 }, [ 4, 5 ], null ]);
+    });
+  });
+
+  // ============================================
+  // SECTION 17: Large Documents
+  // ============================================
+
+  describe('Large Documents', function() {
+    it('should handle documents with many fields', async function() {
+      const doc = { _id: 'large1' };
+      for (let i = 0; i < 100; i++) {
+        doc[`field${i}`] = `value${i}`;
+      }
+
+      await db.collection('test').insertOne(doc);
+      const retrieved = await db.collection('test').findOne({ _id: 'large1' });
+
+      expect(retrieved.field0).to.equal('value0');
+      expect(retrieved.field99).to.equal('value99');
+    });
+
+    it('should handle large string values', async function() {
+      const largeString = 'x'.repeat(100000);
+      await db.collection('test').insertOne({
+        _id: 'largestr',
+        content: largeString
+      });
+
+      const doc = await db.collection('test').findOne({ _id: 'largestr' });
+      expect(doc.content).to.equal(largeString);
+    });
+  });
+
+  // ============================================
+  // SECTION 18: Multiple Update Operators
+  // ============================================
+
+  describe('Multiple Update Operators Combined', function() {
+    it('should apply multiple update operators in single update', async function() {
+      await db.collection('test').insertOne({
+        _id: 'multi1',
+        count: 5,
+        name: 'original',
+        tags: [ 'a' ],
+        toRemove: 'value'
+      });
+
+      await db.collection('test').updateOne(
+        { _id: 'multi1' },
+        {
+          $set: { name: 'updated' },
+          $inc: { count: 3 },
+          $push: { tags: 'b' },
+          $unset: { toRemove: '' }
+        }
+      );
+
+      const doc = await db.collection('test').findOne({ _id: 'multi1' });
+      expect(doc.name).to.equal('updated');
+      expect(doc.count).to.equal(8);
+      expect(doc.tags).to.deep.equal([ 'a', 'b' ]);
+      expect(doc.toRemove).to.be.undefined;
+    });
+  });
+
+  // ============================================
+  // SECTION 19: Atomicity
+  // ============================================
+
+  describe('Atomicity', function() {
+    it('should ensure atomic _id uniqueness', async function() {
+      // Run multiple concurrent inserts with same _id
+      const promises = [];
+      for (let i = 0; i < 10; i++) {
+        promises.push(
+          db.collection('test').insertOne({
+            _id: 'atomic1',
+            value: i
+          })
+            .then(() => 'success')
+            .catch(() => 'duplicate')
+        );
+      }
+
+      const results = await Promise.all(promises);
+      const successes = results.filter(r => r === 'success');
+      const duplicates = results.filter(r => r === 'duplicate');
+
+      // Exactly one should succeed
+      expect(successes).to.have.lengthOf(1);
+      expect(duplicates).to.have.lengthOf(9);
+
+      // Verify only one document exists
+      const count = await db.collection('test').countDocuments({ _id: 'atomic1' });
+      expect(count).to.equal(1);
+    });
+  });
+
+  // ============================================
+  // SECTION 20: Type Preservation
+  // ============================================
+
+  describe('Type Preservation', function() {
+    it('should preserve JavaScript types', async function() {
+      const testDoc = {
+        _id: 'types1',
+        string: 'hello',
+        number: 42,
+        float: 3.14159,
+        boolean: true,
+        date: new Date('2024-01-15T12:00:00Z'),
+        array: [ 1, 2, 3 ],
+        nested: {
+          a: 1,
+          b: { c: 2 }
+        },
+        nullValue: null
+      };
+
+      await db.collection('test').insertOne(testDoc);
+      const doc = await db.collection('test').findOne({ _id: 'types1' });
+
+      expect(typeof doc.string).to.equal('string');
+      expect(typeof doc.number).to.equal('number');
+      expect(typeof doc.float).to.equal('number');
+      expect(typeof doc.boolean).to.equal('boolean');
+      expect(doc.date).to.be.instanceOf(Date);
+      expect(Array.isArray(doc.array)).to.be.true;
+      expect(typeof doc.nested).to.equal('object');
+      expect(doc.nullValue).to.be.null;
+    });
+  });
+
+  // ============================================
+  // SECTION 21: Multi-schema Mode (multipostgres only)
+  // ============================================
+
+  // ============================================
+  // SECTION 22: Batched Containment Queries
+  // ============================================
+
+  describe('Batched Containment Queries', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'bc1',
+          type: 'article',
+          slug: '/news',
+          status: 'published',
+          tags: [ 'featured', 'news' ]
+        },
+        {
+          _id: 'bc2',
+          type: 'article',
+          slug: '/blog',
+          status: 'draft',
+          tags: [ 'blog' ]
+        },
+        {
+          _id: 'bc3',
+          type: 'page',
+          slug: '/home',
+          status: 'published',
+          tags: [ 'featured' ]
+        },
+        {
+          _id: 'bc4',
+          type: 'page',
+          slug: '/about',
+          status: 'published',
+          tags: []
+        }
+      ]);
+    });
+
+    it('should match multi-field scalar equality', async function() {
+      const docs = await db.collection('test').find({
+        type: 'article',
+        status: 'published'
+      }).toArray();
+      expect(docs).to.have.lengthOf(1);
+      expect(docs[0]._id).to.equal('bc1');
+    });
+
+    it('should match three-field scalar equality', async function() {
+      const docs = await db.collection('test').find({
+        type: 'page',
+        status: 'published',
+        slug: '/home'
+      }).toArray();
+      expect(docs).to.have.lengthOf(1);
+      expect(docs[0]._id).to.equal('bc3');
+    });
+
+    it('should match scalar value in array field via containment', async function() {
+      // { tags: 'featured' } matches docs where
+      // tags contains 'featured'
+      const docs = await db.collection('test').find({
+        tags: 'featured',
+        type: 'article'
+      }).toArray();
+      expect(docs).to.have.lengthOf(1);
+      expect(docs[0]._id).to.equal('bc1');
+    });
+
+    it('should handle nested field equality in containment', async function() {
+      await db.collection('test').insertOne({
+        _id: 'bc5',
+        user: {
+          profile: {
+            name: 'Alice',
+            role: 'admin'
+          }
+        }
+      });
+      await db.collection('test').insertOne({
+        _id: 'bc6',
+        user: {
+          profile: {
+            name: 'Bob',
+            role: 'admin'
+          }
+        }
+      });
+      const docs = await db.collection('test').find({
+        'user.profile.role': 'admin',
+        'user.profile.name': 'Alice'
+      }).toArray();
+      expect(docs).to.have.lengthOf(1);
+      expect(docs[0]._id).to.equal('bc5');
+    });
+
+    it('should combine containment with operator conditions', async function() {
+      // Mix of scalar equality (batched) and operator conditions
+      const docs = await db.collection('test').find({
+        type: 'page',
+        status: { $ne: 'draft' }
+      }).toArray();
+      expect(docs).to.have.lengthOf(2);
+    });
+
+    it('should handle boolean values in containment', async function() {
+      await db.collection('test').insertOne({
+        _id: 'bc7',
+        active: true,
+        visible: false
+      });
+      const docs = await db.collection('test').find({
+        active: true,
+        visible: false
+      }).toArray();
+      expect(docs).to.have.lengthOf(1);
+      expect(docs[0]._id).to.equal('bc7');
+    });
+
+    it('should handle numeric values in containment', async function() {
+      await db.collection('test').insertOne({
+        _id: 'bc8',
+        level: 5,
+        score: 100
+      });
+      const docs = await db.collection('test').find({
+        level: 5,
+        score: 100
+      }).toArray();
+      expect(docs).to.have.lengthOf(1);
+      expect(docs[0]._id).to.equal('bc8');
+    });
+
+    it('should handle Date values in containment', async function() {
+      const date = new Date('2024-06-15T12:00:00Z');
+      await db.collection('test').insertOne({
+        _id: 'bc9',
+        createdAt: date,
+        type: 'event'
+      });
+      const docs = await db.collection('test').find({
+        type: 'event',
+        createdAt: date
+      }).toArray();
+      expect(docs).to.have.lengthOf(1);
+      expect(docs[0]._id).to.equal('bc9');
+      expect(docs[0].createdAt).to.be.instanceOf(Date);
+      expect(docs[0].createdAt.getTime()).to.equal(date.getTime());
+    });
+  });
+
+  // ============================================
+  // SECTION 23: $in on _id Field
+  // ============================================
+
+  describe('$in on _id field', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'in1',
+          value: 1
+        },
+        {
+          _id: 'in2',
+          value: 2
+        },
+        {
+          _id: 'in3',
+          value: 3
+        },
+        {
+          _id: 'in4',
+          value: 4
+        },
+        {
+          _id: 'in5',
+          value: 5
+        }
+      ]);
+    });
+
+    it('should find documents by _id $in', async function() {
+      const docs = await db.collection('test').find({
+        _id: { $in: [ 'in1', 'in3', 'in5' ] }
+      }).sort({ _id: 1 }).toArray();
+      expect(docs).to.have.lengthOf(3);
+      expect(docs[0]._id).to.equal('in1');
+      expect(docs[1]._id).to.equal('in3');
+      expect(docs[2]._id).to.equal('in5');
+    });
+
+    it('should handle _id $in with single value', async function() {
+      const docs = await db.collection('test').find({
+        _id: { $in: [ 'in2' ] }
+      }).toArray();
+      expect(docs).to.have.lengthOf(1);
+      expect(docs[0]._id).to.equal('in2');
+    });
+
+    it('should handle _id $in with empty array', async function() {
+      const docs = await db.collection('test').find({
+        _id: { $in: [] }
+      }).toArray();
+      expect(docs).to.have.lengthOf(0);
+    });
+
+    it('should handle _id $in with many values', async function() {
+      // Test with more IDs than exist — should only return matching ones
+      const ids = [];
+      for (let i = 1; i <= 20; i++) {
+        ids.push(`in${i}`);
+      }
+      const docs = await db.collection('test').find({
+        _id: { $in: ids }
+      }).toArray();
+      expect(docs).to.have.lengthOf(5);
+    });
+
+    it('should handle _id $in with non-matching values', async function() {
+      const docs = await db.collection('test').find({
+        _id: { $in: [ 'nonexistent1', 'nonexistent2' ] }
+      }).toArray();
+      expect(docs).to.have.lengthOf(0);
+    });
+
+    it('should combine _id $in with other conditions', async function() {
+      const docs = await db.collection('test').find({
+        _id: { $in: [ 'in1', 'in2', 'in3' ] },
+        value: { $gt: 1 }
+      }).toArray();
+      expect(docs).to.have.lengthOf(2);
+    });
+  });
+
+  // ============================================
+  // SECTION 24: $in on Array Fields
+  // ============================================
+
+  describe('$in on array fields', function() {
+    beforeEach(async function() {
+      await db.collection('test').insertMany([
+        {
+          _id: 'ia1',
+          name: 'Alice',
+          roles: [ 'admin', 'editor' ]
+        },
+        {
+          _id: 'ia2',
+          name: 'Bob',
+          roles: [ 'viewer' ]
+        },
+        {
+          _id: 'ia3',
+          name: 'Carol',
+          roles: [ 'editor', 'viewer' ]
+        },
+        {
+          _id: 'ia4',
+          name: 'Dave',
+          roles: [ 'admin' ]
+        }
+      ]);
+    });
+
+    it('$in should match array field containing any of the values', async function() {
+      const docs = await db.collection('test').find({
+        roles: { $in: [ 'admin', 'viewer' ] }
+      }).sort({ _id: 1 }).toArray();
+      // ia1 has admin, ia2 has viewer, ia3 has viewer, ia4 has admin
+      expect(docs).to.have.lengthOf(4);
+      expect(docs.map(d => d._id)).to.deep.equal([ 'ia1', 'ia2', 'ia3', 'ia4' ]);
+    });
+
+    it('$in should match scalar field normally', async function() {
+      const docs = await db.collection('test').find({
+        name: { $in: [ 'Alice', 'Carol' ] }
+      }).sort({ _id: 1 }).toArray();
+      expect(docs).to.have.lengthOf(2);
+      expect(docs.map(d => d._id)).to.deep.equal([ 'ia1', 'ia3' ]);
+    });
+
+    it('$in with null should match missing fields', async function() {
+      await db.collection('test').insertOne({
+        _id: 'ia5',
+        name: 'Eve'
+        // no roles field
+      });
+      const docs = await db.collection('test').find({
+        roles: { $in: [ 'admin', null ] }
+      }).sort({ _id: 1 }).toArray();
+      // Should match ia1 (has admin), ia4 (has admin), and ia5 (roles missing)
+      expect(docs).to.have.lengthOf(3);
+      expect(docs.map(d => d._id)).to.deep.equal([ 'ia1', 'ia4', 'ia5' ]);
+    });
+  });
+
+  // ============================================
+  // SECTION 25: Deserialization Optimization
+  // ============================================
+
+  describe('Deserialization Optimization', function() {
+    it('should correctly roundtrip documents with no dates', async function() {
+      const original = {
+        _id: 'deser1',
+        title: 'No Dates Here',
+        count: 42,
+        active: true,
+        tags: [ 'a', 'b', 'c' ],
+        nested: {
+          deep: {
+            value: 'hello',
+            list: [ 1, 2, 3 ]
+          }
+        }
+      };
+      await db.collection('test').insertOne(original);
+      const doc = await db.collection('test').findOne({ _id: 'deser1' });
+      expect(doc._id).to.equal('deser1');
+      expect(doc.title).to.equal('No Dates Here');
+      expect(doc.count).to.equal(42);
+      expect(doc.active).to.equal(true);
+      expect(doc.tags).to.deep.equal([ 'a', 'b', 'c' ]);
+      expect(doc.nested.deep.value).to.equal('hello');
+      expect(doc.nested.deep.list).to.deep.equal([ 1, 2, 3 ]);
+    });
+
+    it('should correctly roundtrip documents with deeply nested dates', async function() {
+      const date1 = new Date('2024-01-15T10:30:00Z');
+      const date2 = new Date('2024-06-01T00:00:00Z');
+      const original = {
+        _id: 'deser2',
+        title: 'Has Dates',
+        metadata: {
+          createdAt: date1,
+          nested: {
+            modifiedAt: date2,
+            plain: 'no date here'
+          }
+        },
+        tags: [ 'a', 'b' ]
+      };
+      await db.collection('test').insertOne(original);
+      const doc = await db.collection('test').findOne({ _id: 'deser2' });
+      expect(doc.metadata.createdAt).to.be.instanceOf(Date);
+      expect(doc.metadata.createdAt.getTime()).to.equal(date1.getTime());
+      expect(doc.metadata.nested.modifiedAt).to.be.instanceOf(Date);
+      expect(doc.metadata.nested.modifiedAt.getTime()).to.equal(date2.getTime());
+      expect(doc.metadata.nested.plain).to.equal('no date here');
+      expect(doc.tags).to.deep.equal([ 'a', 'b' ]);
+    });
+
+    it('should correctly roundtrip documents with dates in arrays', async function() {
+      const date1 = new Date('2024-03-01T00:00:00Z');
+      const date2 = new Date('2024-04-01T00:00:00Z');
+      const original = {
+        _id: 'deser3',
+        events: [
+          {
+            name: 'event1',
+            date: date1
+          },
+          {
+            name: 'event2',
+            date: date2
+          },
+          { name: 'event3' } // no date
+        ]
+      };
+      await db.collection('test').insertOne(original);
+      const doc = await db.collection('test').findOne({ _id: 'deser3' });
+      expect(doc.events[0].date).to.be.instanceOf(Date);
+      expect(doc.events[0].date.getTime()).to.equal(date1.getTime());
+      expect(doc.events[1].date).to.be.instanceOf(Date);
+      expect(doc.events[1].date.getTime()).to.equal(date2.getTime());
+      expect(doc.events[2].date).to.be.undefined;
+    });
+
+    it('should handle multiple documents efficiently via find', async function() {
+      // Insert mix of documents with and without dates
+      await db.collection('test').insertMany([
+        {
+          _id: 'deser4',
+          title: 'Plain',
+          value: 1
+        },
+        {
+          _id: 'deser5',
+          title: 'With Date',
+          createdAt: new Date('2024-01-01')
+        },
+        {
+          _id: 'deser6',
+          title: 'Also Plain',
+          value: 3
+        }
+      ]);
+      const docs = await db.collection('test').find({
+        _id: { $in: [ 'deser4', 'deser5', 'deser6' ] }
+      }).sort({ _id: 1 }).toArray();
+      expect(docs).to.have.lengthOf(3);
+      expect(docs[0].title).to.equal('Plain');
+      expect(docs[0].createdAt).to.be.undefined;
+      expect(docs[1].createdAt).to.be.instanceOf(Date);
+      expect(docs[2].title).to.equal('Also Plain');
+    });
+  });
+
+  // ============================================
+  // SECTION 26: Full-Text Search
+  // ============================================
+
+  describe('Full-Text Search', function() {
+    beforeEach(async function() {
+      const col = db.collection('search');
+      try {
+        await col.drop();
+      } catch (e) { /* ignore */ }
+      // Create a text index on title and body
+      await col.createIndex({
+        title: 'text',
+        body: 'text'
+      });
+      // Insert documents with varying relevance to "database migration"
+      await col.insertMany([
+        {
+          _id: 'full-match',
+          title: 'Database Migration Guide',
+          body: 'This guide covers database migration strategies for production systems. Database migration is critical.'
+        },
+        {
+          _id: 'title-only',
+          title: 'Database Basics',
+          body: 'An introduction to storing and retrieving information.'
+        },
+        {
+          _id: 'body-only',
+          title: 'System Administration',
+          body: 'Learn about database backup and migration procedures.'
+        },
+        {
+          _id: 'no-match',
+          title: 'Cooking Recipes',
+          body: 'How to make a perfect sourdough bread.'
+        }
+      ]);
+    });
+
+    afterEach(async function() {
+      try {
+        await db.collection('search').drop();
+      } catch (e) { /* ignore */ }
+    });
+
+    it('$text should match documents containing search terms', async function() {
+      const results = await db.collection('search')
+        .find({ $text: { $search: 'database' } })
+        .toArray();
+      const ids = results.map(d => d._id);
+      expect(ids).to.include('full-match');
+      expect(ids).to.include('title-only');
+      expect(ids).to.include('body-only');
+      expect(ids).to.not.include('no-match');
+    });
+
+    it('$text should combine with other query operators', async function() {
+      const results = await db.collection('search')
+        .find({
+          $text: { $search: 'database' },
+          _id: { $ne: 'title-only' }
+        })
+        .toArray();
+      const ids = results.map(d => d._id);
+      expect(ids).to.include('full-match');
+      expect(ids).to.include('body-only');
+      expect(ids).to.not.include('title-only');
+      expect(ids).to.not.include('no-match');
+    });
+
+    it('$text with empty search should match nothing', async function() {
+      const results = await db.collection('search')
+        .find({ $text: { $search: '   ' } })
+        .toArray();
+      expect(results).to.have.lengthOf(0);
+    });
+
+    it('$text should use fields from the text index, not hardcoded defaults', async function() {
+      // The text index is on title and body. A search for content
+      // in those fields should work. A value only present in an
+      // un-indexed field should not match.
+      const col = db.collection('search');
+      await col.insertOne({
+        _id: 'unindexed',
+        title: 'Nothing special',
+        body: 'Nothing special',
+        notes: 'database migration'
+      });
+      const results = await col
+        .find({ $text: { $search: 'sourdough' } })
+        .toArray();
+      // 'sourdough' appears only in no-match's body, which IS indexed
+      expect(results.map(d => d._id)).to.include('no-match');
+      // 'unindexed' has 'database migration' only in notes (not indexed)
+      // so a search that only matches notes should not find it
+      const results2 = await col
+        .find({
+          $text: { $search: 'database' },
+          _id: 'unindexed'
+        })
+        .toArray();
+      expect(results2).to.have.lengthOf(0);
+    });
+
+    it('should rank results by relevance when sorted by textScore', async function() {
+      const results = await db.collection('search')
+        .find({ $text: { $search: 'database migration' } })
+        .sort({ score: { $meta: 'textScore' } })
+        .project({ score: { $meta: 'textScore' } })
+        .toArray();
+        // full-match has "database" 2x and "migration" 2x — should rank first
+      expect(results.length).to.be.at.least(3);
+      expect(results[0]._id).to.equal('full-match');
+    });
+
+    it('should expose textScore via $meta projection', async function() {
+      const results = await db.collection('search')
+        .find({ $text: { $search: 'database migration' } })
+        .sort({ score: { $meta: 'textScore' } })
+        .project({
+          title: 1,
+          score: { $meta: 'textScore' }
+        })
+        .toArray();
+      expect(results.length).to.be.at.least(1);
+      // Each result should have a numeric score
+      for (const doc of results) {
+        expect(doc.score).to.be.a('number');
+        expect(doc.score).to.be.greaterThan(0);
+        // Projection should still include requested fields
+        expect(doc.title).to.be.a('string');
+      }
+      // Higher-relevance doc should have a higher score
+      const fullMatch = results.find(d => d._id === 'full-match');
+      const titleOnly = results.find(d => d._id === 'title-only');
+      if (fullMatch && titleOnly) {
+        expect(fullMatch.score).to.be.greaterThan(titleOnly.score);
+      }
+    });
+
+    it('should support sorting by $meta textScore', async function() {
+      const results = await db.collection('search')
+        .find({ $text: { $search: 'database migration' } })
+        .sort({ score: { $meta: 'textScore' } })
+        .project({ score: { $meta: 'textScore' } })
+        .toArray();
+      expect(results.length).to.be.at.least(2);
+      // Scores should be in descending order
+      for (let i = 1; i < results.length; i++) {
+        expect(results[i - 1].score).to.be.at.least(results[i].score);
+      }
+    });
+
+    it('should sort by relevance with textScore among other sort fields', async function() {
+      // Insert additional docs to make ranking clearer
+      const col = db.collection('search');
+      await col.insertOne({
+        _id: 'weak-match',
+        title: 'Random Notes',
+        body: 'Contains the word database once among other unrelated content about gardening and weather.'
+      });
+
+      const results = await col
+        .find({ $text: { $search: 'database migration' } })
+        .sort({ score: { $meta: 'textScore' } })
+        .project({ score: { $meta: 'textScore' } })
+        .toArray();
+
+      expect(results.length).to.be.at.least(2);
+      // Scores should be in descending order
+      for (let i = 1; i < results.length; i++) {
+        expect(results[i - 1].score).to.be.at.least(results[i].score);
+      }
+    });
+  }); // Full-Text Search
+
+  if (ADAPTER === 'multipostgres') {
+    describe('Multi-schema Mode', function() {
+      it('should store tables in the named schema, not public', async function() {
+        // Insert a doc to ensure the table exists in the schema
+        await db.collection('schematest').insertOne({
+          _id: 'st1',
+          value: 'hello'
+        });
+
+        // Check that the table exists in the named schema
+        const { Pool } = require('pg');
+        const pool = new Pool({ connectionString: 'postgres://localhost:5432/dbtest_adapter' });
+        try {
+          const inSchema = await pool.query(
+            'SELECT tablename FROM pg_tables WHERE schemaname = \'testschema\' AND tablename = \'schematest\''
+          );
+          expect(inSchema.rows).to.have.lengthOf(1);
+
+          const inPublic = await pool.query(
+            'SELECT tablename FROM pg_tables WHERE schemaname = \'public\' AND tablename = \'schematest\''
+          );
+          expect(inPublic.rows).to.have.lengthOf(0);
+        } finally {
+          await pool.end();
+        }
+
+        // Clean up
+        await db.collection('schematest').drop();
+      });
+
+      it('should list schemas as databases via admin().listDatabases()', async function() {
+        // Ensure at least one table exists so the schema is created
+        await db.collection('admintest').insertOne({
+          _id: 'at1',
+          value: 1
+        });
+
+        const result = await db.admin().listDatabases();
+        expect(result.databases).to.be.an('array');
+        const names = result.databases.map(d => d.name);
+        expect(names).to.include('dbtest_adapter-testschema');
+
+        await db.collection('admintest').drop();
+      });
+
+      it('should drop schema via dropDatabase()', async function() {
+        const tempDb = client.db('dbtest_adapter-dropschematest');
+        await tempDb.collection('tempcol').insertOne({
+          _id: 'tmp1',
+          value: 1
+        });
+
+        // Verify schema exists
+        const { Pool } = require('pg');
+        const pool = new Pool({ connectionString: 'postgres://localhost:5432/dbtest_adapter' });
+        try {
+          let schemas = await pool.query(
+            'SELECT schema_name FROM information_schema.schemata WHERE schema_name = \'dropschematest\''
+          );
+          expect(schemas.rows).to.have.lengthOf(1);
+
+          // Drop it
+          await tempDb.dropDatabase();
+
+          schemas = await pool.query(
+            'SELECT schema_name FROM information_schema.schemata WHERE schema_name = \'dropschematest\''
+          );
+          expect(schemas.rows).to.have.lengthOf(0);
+        } finally {
+          await pool.end();
+        }
+      });
+    });
+  }
+});
diff --git a/packages/db-connect/test/dump-restore.test.js b/packages/db-connect/test/dump-restore.test.js
new file mode 100644
index 0000000000..a0c0835b3c
--- /dev/null
+++ b/packages/db-connect/test/dump-restore.test.js
@@ -0,0 +1,180 @@
+/* global describe, it, before, after */
+const { expect } = require('chai');
+const dbConnect = require('..');
+
+const ADAPTER = process.env.ADAPTER || 'mongodb';
+
+function getUri(dbName) {
+  if (ADAPTER === 'mongodb') {
+    return `mongodb://localhost:27017/${dbName}`;
+  } else if (ADAPTER === 'postgres') {
+    const user = process.env.PGUSER || process.env.USER;
+    const password = process.env.PGPASSWORD || '';
+    const auth = password ? `${user}:${password}@` : `${user}@`;
+    return `postgres://${auth}localhost:5432/${dbName}`;
+  } else if (ADAPTER === 'multipostgres') {
+    const user = process.env.PGUSER || process.env.USER;
+    const password = process.env.PGPASSWORD || '';
+    const auth = password ? `${user}:${password}@` : `${user}@`;
+    return `multipostgres://${auth}localhost:5432/dbtest_dump-${dbName}`;
+  } else if (ADAPTER === 'sqlite') {
+    return `sqlite:///tmp/${dbName}.db`;
+  }
+  throw new Error(`Unknown adapter: ${ADAPTER}`);
+}
+
+describe(`dump/restore programmatic API (${ADAPTER})`, function () {
+  const sourceDbName = 'dbtest_dump_source';
+  const targetDbName = 'dbtest_dump_target';
+  let sourceClient;
+  let targetClient;
+
+  before(async function () {
+    // Clean up any previous runs
+    sourceClient = await dbConnect(getUri(sourceDbName));
+    targetClient = await dbConnect(getUri(targetDbName));
+    const sourceDb = sourceClient.db();
+    const targetDb = targetClient.db();
+    try {
+      await sourceDb.collection('items').drop();
+    } catch (e) { /* ignore */ }
+    try {
+      await sourceDb.collection('meta').drop();
+    } catch (e) { /* ignore */ }
+    try {
+      await targetDb.collection('items').drop();
+    } catch (e) { /* ignore */ }
+    try {
+      await targetDb.collection('meta').drop();
+    } catch (e) { /* ignore */ }
+    await sourceClient.close();
+    await targetClient.close();
+  });
+
+  after(async function () {
+    // Clean up
+    sourceClient = await dbConnect(getUri(sourceDbName));
+    targetClient = await dbConnect(getUri(targetDbName));
+    try {
+      await sourceClient.db().collection('items').drop();
+    } catch (e) { /* ignore */ }
+    try {
+      await sourceClient.db().collection('meta').drop();
+    } catch (e) { /* ignore */ }
+    try {
+      await targetClient.db().collection('items').drop();
+    } catch (e) { /* ignore */ }
+    try {
+      await targetClient.db().collection('meta').drop();
+    } catch (e) { /* ignore */ }
+    await sourceClient.close();
+    await targetClient.close();
+  });
+
+  it('dump yields an async iterable of NDJSON lines', async function () {
+    // Insert some data
+    const client = await dbConnect(getUri(sourceDbName));
+    const db = client.db();
+    await db.collection('items').insertMany([
+      {
+        _id: 'item1',
+        title: 'First',
+        value: 10
+      },
+      {
+        _id: 'item2',
+        title: 'Second',
+        value: 20
+      }
+    ]);
+    await db.collection('meta').insertOne({
+      _id: 'version',
+      v: 1
+    });
+    await client.close();
+
+    const iter = dbConnect.dump(getUri(sourceDbName));
+    // Must be an async iterable — NOT a string (API contract: dump is
+    // streamed so large databases never sit fully in memory).
+    expect(iter).to.not.be.a('string');
+    expect(typeof iter[Symbol.asyncIterator]).to.equal('function');
+
+    const lines = [];
+    for await (const line of iter) {
+      lines.push(line);
+    }
+    // Every emitted record must be a non-empty single JSON object —
+    // no embedded newlines, parseable as JSON.
+    for (const line of lines) {
+      expect(line).to.be.a('string');
+      expect(line).to.not.include('\n');
+      expect(() => JSON.parse(line)).to.not.throw();
+    }
+    const joined = lines.join('\n');
+    expect(joined).to.include('item1');
+    expect(joined).to.include('First');
+    expect(joined).to.include('item2');
+    expect(joined).to.include('version');
+  });
+
+  it('should restore a database from a dump stream', async function () {
+    await dbConnect.restore(getUri(targetDbName), dbConnect.dump(getUri(sourceDbName)));
+
+    const client = await dbConnect(getUri(targetDbName));
+    const db = client.db();
+    const items = await db.collection('items').find({}).sort({ _id: 1 }).toArray();
+    expect(items).to.have.length(2);
+    expect(items[0]._id).to.equal('item1');
+    expect(items[0].title).to.equal('First');
+    expect(items[1]._id).to.equal('item2');
+    expect(items[1].title).to.equal('Second');
+
+    const meta = await db.collection('meta').findOne({ _id: 'version' });
+    expect(meta.v).to.equal(1);
+    await client.close();
+  });
+
+  it('should copy a database via copyDatabase()', async function () {
+    // Modify source to prove we get fresh data
+    const client = await dbConnect(getUri(sourceDbName));
+    await client.db().collection('items').insertOne({
+      _id: 'item3',
+      title: 'Third',
+      value: 30
+    });
+    await client.close();
+
+    // Clean target first
+    const tgt = await dbConnect(getUri(targetDbName));
+    try {
+      await tgt.db().collection('items').drop();
+    } catch (e) { /* ignore */ }
+    try {
+      await tgt.db().collection('meta').drop();
+    } catch (e) { /* ignore */ }
+    await tgt.close();
+
+    await dbConnect.copyDatabase(getUri(sourceDbName), getUri(targetDbName));
+
+    const check = await dbConnect(getUri(targetDbName));
+    const items = await check.db().collection('items').find({}).sort({ _id: 1 }).toArray();
+    expect(items).to.have.length(3);
+    expect(items[2].title).to.equal('Third');
+    await check.close();
+  });
+
+  it('should produce independent databases after copy', async function () {
+    await dbConnect.copyDatabase(getUri(sourceDbName), getUri(targetDbName));
+
+    // Modify target
+    const tgt = await dbConnect(getUri(targetDbName));
+    await tgt.db().collection('items').updateOne({ _id: 'item1' }, { $set: { title: 'Modified' } });
+    await tgt.close();
+
+    // Source should be unchanged
+    const src = await dbConnect(getUri(sourceDbName));
+    const item = await src.db().collection('items').findOne({ _id: 'item1' });
+    expect(item.title).to.equal('First');
+    await src.close();
+  });
+});
diff --git a/packages/db-connect/test/security.test.js b/packages/db-connect/test/security.test.js
new file mode 100644
index 0000000000..399b16dbed
--- /dev/null
+++ b/packages/db-connect/test/security.test.js
@@ -0,0 +1,316 @@
+/* global describe, it, before, after, beforeEach */
+/* eslint-disable no-unused-expressions */
+const { expect } = require('chai');
+
+// Security tests for SQL injection prevention
+// These tests verify that inputs are properly escaped or rejected as appropriate
+
+const ADAPTER = process.env.ADAPTER || 'mongodb';
+
+describe(`Security Tests (${ADAPTER})`, function() {
+  let client;
+  let db;
+
+  before(async function() {
+    if (ADAPTER === 'mongodb') {
+      const mongodb = require('../adapters/mongodb');
+      client = await mongodb.connect('mongodb://localhost:27017/dbtest-security');
+      db = client.db();
+    } else if (ADAPTER === 'postgres') {
+      const postgres = require('../adapters/postgres');
+      const user = process.env.PGUSER || process.env.USER;
+      const password = process.env.PGPASSWORD || '';
+      const auth = password ? `${user}:${password}@` : `${user}@`;
+      client = await postgres.connect(`postgres://${auth}localhost:5432/dbtest_adapter`);
+      db = client.db('dbtest_adapter');
+    } else if (ADAPTER === 'multipostgres') {
+      const postgres = require('../adapters/postgres');
+      const user = process.env.PGUSER || process.env.USER;
+      const password = process.env.PGPASSWORD || '';
+      const auth = password ? `${user}:${password}@` : `${user}@`;
+      client = await postgres.connect(`multipostgres://${auth}localhost:5432/dbtest_adapter-securitytest`);
+      db = client.db();
+    } else if (ADAPTER === 'sqlite') {
+      const sqlite = require('../adapters/sqlite');
+      const os = require('os');
+      const pathModule = require('path');
+      const fs = require('fs');
+      const dbPath = pathModule.join(os.tmpdir(), 'dbtest-security.db');
+      try {
+        fs.unlinkSync(dbPath);
+      } catch (e) { /* ignore */ }
+      client = await sqlite.connect(`sqlite://${dbPath}`);
+      db = client.db();
+    }
+  });
+
+  after(async function() {
+    if (db) {
+      try {
+        await db.collection('sectest').drop();
+      } catch (e) {
+        // ignore
+      }
+    }
+    if (client) {
+      await client.close();
+    }
+  });
+
+  // These tests only apply to postgres adapter since MongoDB doesn't have SQL
+  if (ADAPTER === 'postgres' || ADAPTER === 'sqlite') {
+    describe('SQL Injection Prevention', function() {
+      describe('Field Names (escaping, not rejection)', function() {
+        it('should safely escape field names with single quotes', async function() {
+          // Field names with quotes should be escaped, not cause SQL injection
+          await db.collection('sectest').insertOne({
+            _id: 'esc1',
+            'field\'test': 'value'
+          });
+          const doc = await db.collection('sectest').findOne({ 'field\'test': 'value' });
+          expect(doc).to.exist;
+          expect(doc['field\'test']).to.equal('value');
+          await db.collection('sectest').deleteOne({ _id: 'esc1' });
+        });
+
+        it('should safely escape field names with SQL-like content', async function() {
+          // This should NOT execute SQL injection, just be a weird field name
+          await db.collection('sectest').insertOne({
+            _id: 'esc2',
+            'field; DROP TABLE users;': 'value'
+          });
+          const doc = await db.collection('sectest').findOne({ 'field; DROP TABLE users;': 'value' });
+          expect(doc).to.exist;
+          await db.collection('sectest').deleteOne({ _id: 'esc2' });
+        });
+
+        it('should safely handle field names with special characters', async function() {
+          await db.collection('sectest').insertOne({
+            _id: 'esc3',
+            'field()': 'value',
+            'field"quote': 'test'
+          });
+          const doc = await db.collection('sectest').findOne({ _id: 'esc3' });
+          expect(doc).to.exist;
+          expect(doc['field()']).to.equal('value');
+          expect(doc['field"quote']).to.equal('test');
+          await db.collection('sectest').deleteOne({ _id: 'esc3' });
+        });
+
+        it('should allow nested field names with dots', async function() {
+          await db.collection('sectest').insertOne({
+            _id: 'sec1',
+            user: { name: 'test' }
+          });
+          const doc = await db.collection('sectest').findOne({ 'user.name': 'test' });
+          expect(doc).to.exist;
+          await db.collection('sectest').deleteOne({ _id: 'sec1' });
+        });
+
+        it('should allow field names with hyphens', async function() {
+          await db.collection('sectest').insertOne({
+            _id: 'sec4',
+            'my-field-name': 'value'
+          });
+          const doc = await db.collection('sectest').findOne({ 'my-field-name': 'value' });
+          expect(doc).to.exist;
+          await db.collection('sectest').deleteOne({ _id: 'sec4' });
+        });
+      });
+
+      describe('Collection Names', function() {
+        it('should reject collection names with SQL injection', async function() {
+          try {
+            db.collection('test\'; DROP TABLE users;--');
+            expect.fail('Should have rejected malicious collection name');
+          } catch (e) {
+            expect(e.message).to.include('Invalid table name');
+          }
+        });
+
+        it('should reject collection names with double quotes', async function() {
+          try {
+            db.collection('test"injection');
+            expect.fail('Should have rejected malicious collection name');
+          } catch (e) {
+            expect(e.message).to.include('Invalid table name');
+          }
+        });
+
+        it('should allow collection names with hyphens (converted to underscores)', async function() {
+          const col = db.collection('test-collection');
+          expect(col.name).to.equal('test-collection');
+          // The internal table name should have underscores and be prefixed with db name
+          expect(col._tableName).to.include('test_collection');
+        });
+
+        it('should allow standard alphanumeric collection names', async function() {
+          const col = db.collection('MyCollection123');
+          expect(col.name).to.equal('MyCollection123');
+        });
+      });
+
+      describe('Index Names', function() {
+        beforeEach(async function() {
+          try {
+            await db.collection('sectest').drop();
+          } catch (e) {
+            // ignore
+          }
+          await db.collection('sectest').insertOne({
+            _id: 'idx1',
+            field: 'value'
+          });
+        });
+
+        it('should sanitize malicious index names', async function() {
+          // Index names arrive from cross-backend dumps (e.g. MongoDB defaults
+          // like "collection._id_1") so we sanitize rather than reject. The
+          // security property we care about is that no dangerous characters
+          // reach the SQL statement — quotes, semicolons, dashes must all be
+          // replaced before the name is interpolated into CREATE INDEX.
+          const returned = await db.collection('sectest').createIndex(
+            { field: 1 },
+            { name: 'idx\'; DROP TABLE users;--' }
+          );
+          expect(returned).to.not.match(/['";\- ]/);
+          // And the table must still exist — sanity check that no injection ran.
+          const doc = await db.collection('sectest').findOne({ _id: 'idx1' });
+          expect(doc).to.not.be.null;
+        });
+
+        it('should allow valid index names', async function() {
+          const indexName = await db.collection('sectest').createIndex({ field: 1 }, { name: 'my_custom_index' });
+          expect(indexName).to.equal('my_custom_index');
+        });
+      });
+
+      describe('Operator Values', function() {
+        beforeEach(async function() {
+          try {
+            await db.collection('sectest').drop();
+          } catch (e) {
+            // ignore
+          }
+          await db.collection('sectest').insertOne({
+            _id: 'op1',
+            name: 'test',
+            count: 5
+          });
+        });
+
+        it('should safely handle malicious string values (parameterized)', async function() {
+          // This should not cause SQL injection because values are parameterized
+          const doc = await db.collection('sectest').findOne({ name: '\'; DROP TABLE users;--' });
+          expect(doc).to.be.null; // No match, but no error either
+        });
+
+        it('should safely handle malicious _id values (parameterized)', async function() {
+          const doc = await db.collection('sectest').findOne({ _id: '\'; DROP TABLE users;--' });
+          expect(doc).to.be.null; // No match, but no error either
+        });
+
+        it('should safely handle malicious values in $in operator', async function() {
+          const docs = await db.collection('sectest').find({
+            name: { $in: [ '\'; DROP TABLE users;--', 'normal' ] }
+          }).toArray();
+          expect(docs).to.have.lengthOf(0);
+        });
+
+        it('should safely handle malicious regex patterns', async function() {
+          // Regex patterns are parameterized
+          const docs = await db.collection('sectest').find({
+            name: { $regex: '\'; DROP TABLE' }
+          }).toArray();
+          expect(docs).to.have.lengthOf(0);
+        });
+      });
+
+      describe('LIMIT and OFFSET Validation', function() {
+        beforeEach(async function() {
+          try {
+            await db.collection('sectest').drop();
+          } catch (e) {
+            // ignore
+          }
+          await db.collection('sectest').insertMany([
+            {
+              _id: 'lim1',
+              value: 1
+            },
+            {
+              _id: 'lim2',
+              value: 2
+            },
+            {
+              _id: 'lim3',
+              value: 3
+            }
+          ]);
+        });
+
+        it('should reject non-integer limit values', async function() {
+          try {
+            await db.collection('sectest').find({}).limit('1; DROP TABLE users;--').toArray();
+            expect.fail('Should have rejected non-integer limit');
+          } catch (e) {
+            expect(e.message).to.include('must be a non-negative integer');
+          }
+        });
+
+        it('should reject negative limit values', async function() {
+          try {
+            await db.collection('sectest').find({}).limit(-1).toArray();
+            expect.fail('Should have rejected negative limit');
+          } catch (e) {
+            expect(e.message).to.include('must be a non-negative integer');
+          }
+        });
+
+        it('should reject non-integer skip values', async function() {
+          try {
+            await db.collection('sectest').find({}).skip('1; DROP TABLE users;--').toArray();
+            expect.fail('Should have rejected non-integer skip');
+          } catch (e) {
+            expect(e.message).to.include('must be a non-negative integer');
+          }
+        });
+
+        it('should allow valid integer limit and skip', async function() {
+          const docs = await db.collection('sectest').find({}).skip(1).limit(1).toArray();
+          expect(docs).to.have.lengthOf(1);
+        });
+      });
+    });
+  }
+
+  // Basic tests that apply to both adapters
+  describe('Basic Security', function() {
+    it('should prevent duplicate _id atomically', async function() {
+      await db.collection('sectest').insertOne({
+        _id: 'atomic1',
+        value: 1
+      });
+
+      const promises = [];
+      for (let i = 0; i < 5; i++) {
+        promises.push(
+          db.collection('sectest').insertOne({
+            _id: 'atomic1',
+            value: i
+          })
+            .then(() => 'success')
+            .catch(() => 'duplicate')
+        );
+      }
+
+      const results = await Promise.all(promises);
+      const successes = results.filter(r => r === 'success');
+      expect(successes).to.have.lengthOf(0); // First insert already succeeded above
+
+      // Only one document should exist
+      const count = await db.collection('sectest').countDocuments({ _id: 'atomic1' });
+      expect(count).to.equal(1);
+    });
+  });
+});
diff --git a/packages/db-connect/test/shared.test.js b/packages/db-connect/test/shared.test.js
new file mode 100644
index 0000000000..e0fd78e962
--- /dev/null
+++ b/packages/db-connect/test/shared.test.js
@@ -0,0 +1,121 @@
+/* global describe, it */
+/* eslint-disable no-unused-expressions */
+const { expect } = require('chai');
+const {
+  extractAnchoredLiteralPrefix,
+  prefixUpperBound
+} = require('../lib/shared');
+
+describe('shared: extractAnchoredLiteralPrefix', function() {
+  it('extracts a plain anchored literal', function() {
+    const r = extractAnchoredLiteralPrefix(/^hello/);
+    expect(r).to.deep.equal({
+      prefix: 'hello',
+      anchored: true
+    });
+  });
+
+  it('handles escaped slashes and dots (the ApostropheCMS page path pattern)', function() {
+    const r = extractAnchoredLiteralPrefix(/^\/parent\/child\/./);
+    expect(r.prefix).to.equal('/parent/child/');
+    expect(r.anchored).to.equal(true);
+  });
+
+  it('stops at the first unescaped metacharacter', function() {
+    expect(extractAnchoredLiteralPrefix(/^foo.*bar/).prefix).to.equal('foo');
+    expect(extractAnchoredLiteralPrefix(/^foo(bar|baz)/).prefix).to.equal('foo');
+    expect(extractAnchoredLiteralPrefix(/^foo\d+/).prefix).to.equal('foo');
+    expect(extractAnchoredLiteralPrefix(/^foo[abc]/).prefix).to.equal('foo');
+    expect(extractAnchoredLiteralPrefix(/^foo?/).prefix).to.equal('fo');
+  });
+
+  it('keeps the preceding char before + (one-or-more, guaranteed once)', function() {
+    expect(extractAnchoredLiteralPrefix(/^foo+/).prefix).to.equal('foo');
+  });
+
+  it('drops the preceding char before * (zero-or-more)', function() {
+    expect(extractAnchoredLiteralPrefix(/^foo*/).prefix).to.equal('fo');
+  });
+
+  it('drops the preceding char before {0,...} quantifier', function() {
+    expect(extractAnchoredLiteralPrefix(/^foo{2,3}/).prefix).to.equal('fo');
+  });
+
+  it('treats escaped metacharacters as literals', function() {
+    expect(extractAnchoredLiteralPrefix(/^a\.b\+c\*d/).prefix).to.equal('a.b+c*d');
+    expect(extractAnchoredLiteralPrefix(/^a\(b\)c/).prefix).to.equal('a(b)c');
+  });
+
+  it('returns empty prefix when not anchored', function() {
+    expect(extractAnchoredLiteralPrefix(/hello/)).to.deep.equal({
+      prefix: '',
+      anchored: false
+    });
+  });
+
+  it('returns empty prefix for case-insensitive regex', function() {
+    expect(extractAnchoredLiteralPrefix(/^hello/i)).to.deep.equal({
+      prefix: '',
+      anchored: false
+    });
+  });
+
+  it('returns empty prefix when the regex starts with a metacharacter', function() {
+    expect(extractAnchoredLiteralPrefix(/^.foo/).prefix).to.equal('');
+    expect(extractAnchoredLiteralPrefix(/^(foo|bar)/).prefix).to.equal('');
+  });
+
+  it('returns empty prefix for non-RegExp input', function() {
+    expect(extractAnchoredLiteralPrefix('hello').prefix).to.equal('');
+    expect(extractAnchoredLiteralPrefix(null).prefix).to.equal('');
+  });
+
+  it('stops at character-class escapes like \\d, \\w, \\s', function() {
+    expect(extractAnchoredLiteralPrefix(/^abc\d/).prefix).to.equal('abc');
+    expect(extractAnchoredLiteralPrefix(/^abc\w/).prefix).to.equal('abc');
+    expect(extractAnchoredLiteralPrefix(/^abc\s/).prefix).to.equal('abc');
+  });
+
+  it('returns empty prefix for top-level alternation', function() {
+    // Top-level alternation means the other branch may match a completely
+    // different string, so no prefix is safe for range predicates.
+    expect(extractAnchoredLiteralPrefix(/^en:|^fr:/).prefix).to.equal('');
+    expect(extractAnchoredLiteralPrefix(/^foo|^bar|^baz/).prefix).to.equal('');
+    expect(extractAnchoredLiteralPrefix(/^abc|xyz/).prefix).to.equal('');
+  });
+
+  it('returns empty prefix for just ^', function() {
+    expect(extractAnchoredLiteralPrefix(/^/).prefix).to.equal('');
+  });
+});
+
+describe('shared: prefixUpperBound', function() {
+  it('increments the last character code point', function() {
+    expect(prefixUpperBound('foo')).to.equal('fop');
+    expect(prefixUpperBound('/parent/')).to.equal('/parent0'); // '/' (0x2F) -> '0' (0x30)
+    expect(prefixUpperBound('a')).to.equal('b');
+  });
+
+  it('orders such that all P-prefixed strings fall in [P, upper)', function() {
+    const P = '/parent/';
+    const U = prefixUpperBound(P);
+    // A few descendants
+    for (const s of [ '/parent/', '/parent/a', '/parent/child/foo', '/parent/~~~', '/parent/' + '\uFFFE' ]) {
+      expect(s >= P).to.equal(true);
+      expect(s < U).to.equal(true);
+    }
+    // Non-descendants must fall outside
+    for (const s of [ '/parent', '/parentx', '/parenu', '0', '/' ]) {
+      const inRange = s >= P && s < U;
+      expect(inRange).to.equal(false);
+    }
+  });
+
+  it('returns null for empty prefix', function() {
+    expect(prefixUpperBound('')).to.equal(null);
+  });
+
+  it('returns null when the last character is the max BMP code point', function() {
+    expect(prefixUpperBound('foo\uFFFF')).to.equal(null);
+  });
+});
diff --git a/packages/emulate-mongo-3-driver/package.json b/packages/emulate-mongo-3-driver/package.json
index e367316a30..f9ce250fc9 100644
--- a/packages/emulate-mongo-3-driver/package.json
+++ b/packages/emulate-mongo-3-driver/package.json
@@ -28,6 +28,9 @@
     "mongodb": "^6.8.0",
     "mongodb-legacy": "^6.0.1"
   },
+  "apostropheTestConfig": {
+    "mongodbOnly": true
+  },
   "devDependencies": {
     "eslint": "^9.39.1",
     "eslint-config-apostrophe": "workspace:^",
diff --git a/packages/express-cache-on-demand/package.json b/packages/express-cache-on-demand/package.json
index 9e845fd2d9..3810a1bae9 100644
--- a/packages/express-cache-on-demand/package.json
+++ b/packages/express-cache-on-demand/package.json
@@ -30,6 +30,9 @@
     "cache-on-demand": "workspace:^",
     "lodash": "^4.18.1"
   },
+  "apostropheTestConfig": {
+    "requiresMongo": false
+  },
   "devDependencies": {
     "eslint": "^9.39.1",
     "eslint-config-apostrophe": "workspace:^",
diff --git a/packages/form/test/test.js b/packages/form/test/test.js
index 2be39e3193..7fc619df35 100644
--- a/packages/form/test/test.js
+++ b/packages/form/test/test.js
@@ -746,10 +746,12 @@ describe('Forms module', function () {
 
   it('should accept multiple files for a single file field when allowMultiple is true', async function () {
     // Update the existing form's file field to allow multiple
+    const formDoc = await apos.doc.db.findOne({ _id: savedForm1._id });
+    const item = formDoc.contents.items.find(i => i._id === 'dogPhotoId');
+    item.allowMultiple = true;
     await apos.doc.db.updateOne(
       { _id: savedForm1._id },
-      { $set: { 'contents.items.$[w].allowMultiple': true } },
-      { arrayFilters: [ { 'w._id': 'dogPhotoId' } ] }
+      { $set: { contents: formDoc.contents } }
     );
 
     const formData = new FormData();
diff --git a/packages/import-export/test/importDraftsOnly.js b/packages/import-export/test/importDraftsOnly.js
index 9248eed1ec..5ee09336da 100644
--- a/packages/import-export/test/importDraftsOnly.js
+++ b/packages/import-export/test/importDraftsOnly.js
@@ -69,6 +69,7 @@ describe('#import - when `importDraftsOnly` option is set to `true`', function (
 
       const topics = await apos.doc.db
         .find({ type: 'topic' })
+        .sort({ _id: 1 })
         .toArray();
 
       const actual = topics;
@@ -127,6 +128,7 @@ describe('#import - when `importDraftsOnly` option is set to `true`', function (
 
         const topics = await apos.doc.db
           .find({ type: 'topic' })
+          .sort({ _id: 1 })
           .toArray();
 
         const actual = topics.map(topic => ({
@@ -169,6 +171,7 @@ describe('#import - when `importDraftsOnly` option is set to `true`', function (
 
         const topics = await apos.doc.db
           .find({ type: 'topic' })
+          .sort({ _id: 1 })
           .toArray();
 
         const actual = topics.map(topic => ({
@@ -220,6 +223,7 @@ describe('#import - when `importDraftsOnly` option is set to `true`', function (
 
           const topics = await apos.doc.db
             .find({ type: 'topic' })
+            .sort({ _id: 1 })
             .toArray();
 
           const actual = topics.map(topic => ({
@@ -263,6 +267,7 @@ describe('#import - when `importDraftsOnly` option is set to `true`', function (
 
           const topics = await apos.doc.db
             .find({ type: 'topic' })
+            .sort({ _id: 1 })
             .toArray();
 
           const actual = topics.map(topic => ({
@@ -305,6 +310,7 @@ describe('#import - when `importDraftsOnly` option is set to `true`', function (
 
           const pages = await apos.doc.db
             .find({ type: 'default-page' })
+            .sort({ _id: 1 })
             .toArray();
 
           const actual = pages.map(page => ({
@@ -384,6 +390,7 @@ describe('#import - when `importDraftsOnly` option is set to `true`', function (
 
         const topics = await apos.doc.db
           .find({ type: 'topic' })
+          .sort({ _id: 1 })
           .toArray();
 
         const actual = topics;
@@ -466,6 +473,7 @@ describe('#import - when `importDraftsOnly` option is set to `true`', function (
 
         const topics = await apos.doc.db
           .find({ type: 'topic' })
+          .sort({ _id: 1 })
           .toArray();
 
         const actual = topics;
@@ -528,6 +536,7 @@ describe('#import - when `importDraftsOnly` option is set to `true`', function (
 
           const topics = await apos.doc.db
             .find({ type: 'topic' })
+            .sort({ _id: 1 })
             .toArray();
 
           const actual = topics;
@@ -589,6 +598,7 @@ describe('#import - when `importDraftsOnly` option is set to `true`', function (
 
           const topics = await apos.doc.db
             .find({ type: 'topic' })
+            .sort({ _id: 1 })
             .toArray();
 
           const actual = topics;
@@ -644,6 +654,7 @@ describe('#import - when `importDraftsOnly` option is set to `true`', function (
 
           const pages = await apos.doc.db
             .find({ type: 'default-page' })
+            .sort({ _id: 1 })
             .toArray();
 
           const actual = pages;
@@ -705,6 +716,7 @@ describe('#import - when `importDraftsOnly` option is set to `true`', function (
 
           const pages = await apos.doc.db
             .find({ type: 'default-page' })
+            .sort({ _id: 1 })
             .toArray();
 
           const actual = pages;
diff --git a/packages/import-export/test/index.js b/packages/import-export/test/index.js
index c3f53a1da4..d4fe8bd213 100644
--- a/packages/import-export/test/index.js
+++ b/packages/import-export/test/index.js
@@ -409,10 +409,12 @@ describe('@apostrophecms/import-export', function() {
 
     const importedDocs = await apos.doc.db
       .find({ type: /article|topic|@apostrophecms\/image/ })
+      .sort({ _id: 1 })
       .toArray();
 
     const importedAttachments = await apos.attachment.db
       .find()
+      .sort({ _id: 1 })
       .toArray();
 
     const articlesWithRelatedImages = importedDocs
@@ -428,7 +430,7 @@ describe('@apostrophecms/import-export', function() {
     const actual = {
       articlesWithRelatedImages,
       docsLength: importedDocs.length,
-      docsTitles: importedDocs.map(({ title }) => title),
+      docsTitles: importedDocs.map(({ title }) => title).sort(),
       attachmentsNames: importedAttachments.map(({ name }) => name),
       attachmentFileNames: attachmentFiles.map((fullName) => {
         const regex = /-([\w\d-]+)\./;
@@ -451,10 +453,11 @@ describe('@apostrophecms/import-export', function() {
         } ],
       docsLength: 10,
       docsTitles: [
-        'article2', 'article1',
-        'article2', 'article1',
-        'topic1', 'topic3', 'topic2',
-        'topic3', 'topic1', 'topic2'
+        'article1', 'article1',
+        'article2', 'article2',
+        'topic1', 'topic1',
+        'topic2', 'topic2',
+        'topic3', 'topic3'
       ],
       attachmentsNames: [ 'test-image' ],
       attachmentFileNames: new Array(apos.attachment.imageSizes.length + 1)
@@ -535,13 +538,14 @@ describe('@apostrophecms/import-export', function() {
         type: /article|topic|@apostrophecms\/image/,
         aposMode: { $ne: 'previous' }
       })
+      .sort({ _id: 1 })
       .toArray();
-    const updatedAttachments = await apos.attachment.db.find().toArray();
+    const updatedAttachments = await apos.attachment.db.find().sort({ _id: 1 }).toArray();
     const attachmentFiles = await fs.readdir(attachmentPath);
     const job = await apos.modules['@apostrophecms/job'].db.findOne({ _id: jobId });
 
     const actual = {
-      docTitles: updatedDocs.map(({ title }) => title),
+      docTitles: updatedDocs.map(({ title }) => title).sort(),
       attachmentNames: updatedAttachments.map(({ name }) => name),
       attachmentFileNames: extractFileNames(attachmentFiles),
       job: {
@@ -552,18 +556,12 @@ describe('@apostrophecms/import-export', function() {
 
     const expected = {
       docTitles: [
-        'image1',
-        'image1',
-        'article1',
-        'article2',
-        'article1',
-        'article2',
-        'new title',
-        'topic2',
-        'topic1',
-        'new title',
-        'topic2',
-        'topic1'
+        'article1', 'article1',
+        'article2', 'article2',
+        'image1', 'image1',
+        'new title', 'new title',
+        'topic1', 'topic1',
+        'topic2', 'topic2'
       ],
       attachmentNames: [ 'new-name' ],
       attachmentFileNames: new Array(apos.attachment.imageSizes.length + 1)
@@ -609,20 +607,21 @@ describe('@apostrophecms/import-export', function() {
 
     const importedDocs = await apos.doc.db
       .find({ type: /default-page|article|topic|@apostrophecms\/image/ })
+      .sort({ _id: 1 })
       .toArray();
     const importedAttachments = await apos.attachment.db.find(
       { aposMode: { $ne: 'previous' } }
-    ).toArray();
+    ).sort({ _id: 1 }).toArray();
     const attachmentFiles = await fs.readdir(attachmentPath);
 
     const actual = {
-      docTitles: importedDocs.map(({ title }) => title),
+      docTitles: importedDocs.map(({ title }) => title).sort(),
       attachmentNames: importedAttachments.map(({ name }) => name),
       attachmentFileNames: extractFileNames(attachmentFiles)
     };
 
     const expected = {
-      docTitles: [ 'image1', 'image1', 'article2', 'article2', 'page1', 'page1' ],
+      docTitles: [ 'article2', 'article2', 'image1', 'image1', 'page1', 'page1' ],
       attachmentNames: [ 'test-image' ],
       attachmentFileNames: new Array(apos.attachment.imageSizes.length + 1)
         .fill('test-image')
@@ -699,13 +698,14 @@ describe('@apostrophecms/import-export', function() {
         type: /default-page|article|@apostrophecms\/image/,
         aposMode: { $ne: 'previous' }
       })
+      .sort({ _id: 1 })
       .toArray();
-    const updatedAttachments = await apos.attachment.db.find().toArray();
+    const updatedAttachments = await apos.attachment.db.find().sort({ _id: 1 }).toArray();
     const attachmentFiles = await fs.readdir(attachmentPath);
     const job = await apos.modules['@apostrophecms/job'].db.findOne({ _id: jobId });
 
     const actual = {
-      docTitles: updatedDocs.map(({ title }) => title),
+      docTitles: updatedDocs.map(({ title }) => title).sort(),
       attachmentNames: updatedAttachments.map(({ name }) => name),
       attachmentFileNames: extractFileNames(attachmentFiles),
       job: {
@@ -716,14 +716,10 @@ describe('@apostrophecms/import-export', function() {
 
     const expected = {
       docTitles: [
-        'image1',
-        'image1',
-        'new title',
-        'article2',
-        'new title',
-        'article2',
-        'page1',
-        'page1'
+        'article2', 'article2',
+        'image1', 'image1',
+        'new title', 'new title',
+        'page1', 'page1'
       ],
       attachmentNames: [ 'new-name' ],
       attachmentFileNames: new Array(apos.attachment.imageSizes.length + 1)
@@ -807,13 +803,14 @@ describe('@apostrophecms/import-export', function() {
         type: /default-page|article|@apostrophecms\/image/,
         aposMode: { $ne: 'previous' }
       })
+      .sort({ _id: 1 })
       .toArray();
-    const updatedAttachments = await apos.attachment.db.find().toArray();
+    const updatedAttachments = await apos.attachment.db.find().sort({ _id: 1 }).toArray();
     const attachmentFiles = await fs.readdir(attachmentPath);
     const job = await apos.modules['@apostrophecms/job'].db.findOne({ _id: jobId });
 
     const actual = {
-      docTitles: docs.map(({ title }) => title),
+      docTitles: docs.map(({ title }) => title).sort(),
       attachmentNames: updatedAttachments.map(({ name }) => name),
       attachmentFileNames: extractFileNames(attachmentFiles),
       job: {
@@ -825,14 +822,10 @@ describe('@apostrophecms/import-export', function() {
 
     const expected = {
       docTitles: [
-        'new title',
-        'new title',
-        'new title',
-        'article2',
-        'new title',
-        'article2',
-        'page1',
-        'page1'
+        'article2', 'article2',
+        'new title', 'new title',
+        'new title', 'new title',
+        'page1', 'page1'
       ],
       attachmentNames: [ 'new-name' ],
       attachmentFileNames: new Array(apos.attachment.imageSizes.length + 1)
@@ -918,6 +911,7 @@ describe('@apostrophecms/import-export', function() {
 
     const updatedPage = await apos.doc.db
       .find({ title: 'page2' })
+      .sort({ _id: 1 })
       .toArray();
 
     assert.deepEqual(updatedPage.every((doc) => {
@@ -1091,6 +1085,7 @@ describe('@apostrophecms/import-export', function() {
 
       const topics = await apos.doc.db
         .find({ type: 'topic' })
+        .sort({ _id: 1 })
         .toArray();
 
       assert.equal(topics.length, 1);
@@ -1107,6 +1102,7 @@ describe('@apostrophecms/import-export', function() {
 
       const topics = await apos.doc.db
         .find({ type: 'topic' })
+        .sort({ _id: 1 })
         .toArray();
 
       assert.equal(topics.length, 1);
@@ -1122,6 +1118,7 @@ describe('@apostrophecms/import-export', function() {
 
       const pages = await apos.doc.db
         .find({ type: 'default-page' })
+        .sort({ _id: 1 })
         .toArray();
 
       assert.equal(pages.length, 1);
@@ -1136,6 +1133,7 @@ describe('@apostrophecms/import-export', function() {
 
       const topics = await apos.doc.db
         .find({ type: 'topic' })
+        .sort({ _id: 1 })
         .toArray();
 
       assert.equal(topics.length, 2);
@@ -1158,6 +1156,7 @@ describe('@apostrophecms/import-export', function() {
 
       const pages = await apos.doc.db
         .find({ type: 'default-page' })
+        .sort({ _id: 1 })
         .toArray();
 
       assert.equal(pages.length, 2);
@@ -1178,6 +1177,7 @@ describe('@apostrophecms/import-export', function() {
 
       const topics = await apos.doc.db
         .find({ type: 'topic' })
+        .sort({ _id: 1 })
         .toArray();
 
       assert.equal(topics.length, 2);
@@ -1200,6 +1200,7 @@ describe('@apostrophecms/import-export', function() {
 
       const pages = await apos.doc.db
         .find({ type: 'default-page' })
+        .sort({ _id: 1 })
         .toArray();
 
       assert.equal(pages.length, 2);
@@ -1227,6 +1228,7 @@ describe('@apostrophecms/import-export', function() {
 
       const topics = await apos.doc.db
         .find({ type: 'topic' })
+        .sort({ _id: 1 })
         .toArray();
 
       assert.equal(topics.length, 2);
@@ -1258,6 +1260,7 @@ describe('@apostrophecms/import-export', function() {
 
       const pages = await apos.doc.db
         .find({ type: 'default-page' })
+        .sort({ _id: 1 })
         .toArray();
 
       assert.equal(pages.length, 2);
@@ -1301,6 +1304,7 @@ describe('@apostrophecms/import-export', function() {
 
       const topics = await apos.doc.db
         .find({ type: 'topic' })
+        .sort({ _id: 1 })
         .toArray();
 
       assert.equal(topics.length, 2);
@@ -1345,6 +1349,7 @@ describe('@apostrophecms/import-export', function() {
 
       const pages = await apos.doc.db
         .find({ type: 'default-page' })
+        .sort({ _id: 1 })
         .toArray();
 
       assert.equal(pages.length, 2);
@@ -1388,6 +1393,7 @@ describe('@apostrophecms/import-export', function() {
 
       const topics = await apos.doc.db
         .find({ type: 'topic' })
+        .sort({ _id: 1 })
         .toArray();
 
       assert.equal(topics.length, 2);
@@ -1432,6 +1438,7 @@ describe('@apostrophecms/import-export', function() {
 
       const pages = await apos.doc.db
         .find({ type: 'default-page' })
+        .sort({ _id: 1 })
         .toArray();
 
       assert.equal(pages.length, 2);
@@ -1709,6 +1716,7 @@ describe('@apostrophecms/import-export', function() {
               ]
             }
           })
+          .sort({ _id: 1 })
           .toArray();
 
         const actual = importedDocs.map(doc => {
@@ -2029,6 +2037,7 @@ describe('@apostrophecms/import-export', function() {
               ]
             }
           })
+          .sort({ _id: 1 })
           .toArray();
 
         const actual = importedDocs.map(doc => {
diff --git a/packages/import-export/test/overrideDuplicates.js b/packages/import-export/test/overrideDuplicates.js
index d813cedda4..e7785e49b6 100644
--- a/packages/import-export/test/overrideDuplicates.js
+++ b/packages/import-export/test/overrideDuplicates.js
@@ -277,7 +277,7 @@ describe('#overrideDuplicates - overriding locales integration tests', function(
         locale: 'fr',
         mode: 'draft'
       });
-      const [ nonLocalized ] = await apos.doc.db.find({ title: 'nonLocalized1' }).toArray();
+      const [ nonLocalized ] = await apos.doc.db.find({ title: 'nonLocalized1' }).sort({ _id: 1 }).toArray();
       const enArticles = await apos.article.find(req).toArray();
       const parkedPages = await apos.page
         .find(req, { parkedId: { $exists: true } })
diff --git a/packages/import-export/test/overrideLocales.js b/packages/import-export/test/overrideLocales.js
index ad89a7e054..d60547dcd5 100644
--- a/packages/import-export/test/overrideLocales.js
+++ b/packages/import-export/test/overrideLocales.js
@@ -68,6 +68,7 @@ describe('#import - overriding locales integration tests', function() {
         .findOne({ _id: notificationId });
       const topics = await apos.doc.db
         .find({ type: 'topic' })
+        .sort({ _id: 1 })
         .toArray();
 
       const actual = {
@@ -123,6 +124,7 @@ describe('#import - overriding locales integration tests', function() {
         .findOne({ _id: notificationId });
       const topics = await apos.doc.db
         .find({ type: 'topic' })
+        .sort({ _id: 1 })
         .toArray();
 
       const actual = {
@@ -267,6 +269,7 @@ describe('#import - overriding locales integration tests', function() {
         .findOne({ _id: notificationId });
       const topics = await apos.doc.db
         .find({ type: 'topic' })
+        .sort({ _id: 1 })
         .toArray();
 
       const actual = {
@@ -327,6 +330,7 @@ describe('#import - overriding locales integration tests', function() {
         .findOne({ _id: notificationId });
       const topics = await apos.doc.db
         .find({ type: 'topic' })
+        .sort({ _id: 1 })
         .toArray();
 
       const actual = {
@@ -390,6 +394,7 @@ describe('#import - overriding locales integration tests', function() {
         .findOne({ _id: notificationId2 });
       const topics = await apos.doc.db
         .find({ type: 'topic' })
+        .sort({ _id: 1 })
         .toArray();
 
       const actual = {
diff --git a/packages/mongodb-snapshot/package.json b/packages/mongodb-snapshot/package.json
index b8617f32dd..7a0f058c21 100644
--- a/packages/mongodb-snapshot/package.json
+++ b/packages/mongodb-snapshot/package.json
@@ -22,6 +22,9 @@
     "bson": "^6.10.1",
     "mongodb": "^6.12.0"
   },
+  "apostropheTestConfig": {
+    "mongodbOnly": true
+  },
   "devDependencies": {
     "mocha": "^11.7.5"
   },
diff --git a/packages/uploadfs/webp-test.js b/packages/uploadfs/webp-test.js
old mode 100755
new mode 100644

From dfd25cf35c1371801971b323875ace51098c250e Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Fri, 24 Apr 2026 09:31:23 -0400
Subject: [PATCH 08/56] forgot to include a changeset (#5390)

---
 .changeset/curvy-bobcats-peel.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/curvy-bobcats-peel.md

diff --git a/.changeset/curvy-bobcats-peel.md b/.changeset/curvy-bobcats-peel.md
new file mode 100644
index 0000000000..0849faf743
--- /dev/null
+++ b/.changeset/curvy-bobcats-peel.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": minor
+---
+
+Introduced support for postgres://, sqlite://, and multipostgres:// database URIs in addition to mongodb://. The new db-connect API supports all of the database operations currently used in our own core, pro and multisite modules. For more information see the documentation.

From b360b05e8d4e479a36fcae45a5a6dbf820b8fba3 Mon Sep 17 00:00:00 2001
From: Stuart Romanek <stuart@apostrophecms.com>
Date: Wed, 29 Apr 2026 14:00:17 -0400
Subject: [PATCH 09/56] ignore inline table array as draggable ui for windows
 (#5392)

---
 .changeset/stale-shirts-read.md                              | 5 +++++
 .../@apostrophecms/modal/ui/apos/components/AposModal.vue    | 3 ++-
 2 files changed, 7 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/stale-shirts-read.md

diff --git a/.changeset/stale-shirts-read.md b/.changeset/stale-shirts-read.md
new file mode 100644
index 0000000000..271cd86872
--- /dev/null
+++ b/.changeset/stale-shirts-read.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": patch
+---
+
+fixes issue where orderable table array items drag the entire floating window
diff --git a/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue b/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue
index 6402d79c49..a83770ff35 100644
--- a/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue
+++ b/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue
@@ -212,7 +212,8 @@ const nonDraggableElements = [
   '.apos-field--inline-array-field',
   '.apos-field--inline-array-table-with-remove-button-field',
   '.apos-field--inline-array-table-field',
-  '.apos-input-color__sample-picker'
+  '.apos-input-color__sample-picker',
+  '.apos-input-array-inline-table'
 ];
 
 const resizeSides = [

From 77a2968206b0208883ff45de37feb43ba0b5d5b1 Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Mon, 4 May 2026 13:26:48 +0300
Subject: [PATCH 10/56] Layout focus orchestration (#5393)

---
 .changeset/quick-guests-join.md                             | 5 +++++
 .../area/ui/apos/components/AposAreaWidget.vue              | 2 ++
 .../ui/apos/components/AposAreaLayoutEditor.vue             | 6 ++++++
 3 files changed, 13 insertions(+)
 create mode 100644 .changeset/quick-guests-join.md

diff --git a/.changeset/quick-guests-join.md b/.changeset/quick-guests-join.md
new file mode 100644
index 0000000000..8bab7b0384
--- /dev/null
+++ b/.changeset/quick-guests-join.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": minor
+---
+
+Fix layout widget not regaining full focus on switching back to Edit content mode.
diff --git a/packages/apostrophe/modules/@apostrophecms/area/ui/apos/components/AposAreaWidget.vue b/packages/apostrophe/modules/@apostrophecms/area/ui/apos/components/AposAreaWidget.vue
index a8ac47dde0..7b83852860 100644
--- a/packages/apostrophe/modules/@apostrophecms/area/ui/apos/components/AposAreaWidget.vue
+++ b/packages/apostrophe/modules/@apostrophecms/area/ui/apos/components/AposAreaWidget.vue
@@ -536,6 +536,7 @@ export default {
     apos.bus.$on('widget-focus-parent', this.focusParent);
     apos.bus.$on('context-menu-toggled', this.getFocusForMenu);
     apos.bus.$on('suppress-focused-widget-controls', this.doSuppressWidgetControls);
+    apos.bus.$on('clear-focused-widget-control-suppression', this.clearSuppressionFlags);
 
     this.breadcrumbs.$lastEl = this.$el;
 
@@ -573,6 +574,7 @@ export default {
     // Remove the focus parent listener when unmounted
     apos.bus.$off('widget-focus-parent', this.focusParent);
     apos.bus.$off('suppress-focused-widget-controls', this.doSuppressWidgetControls);
+    apos.bus.$off('clear-focused-widget-control-suppression', this.clearSuppressionFlags);
     window.removeEventListener('scroll', this.stickyControlsScroll);
     window.removeEventListener('resize', this.stickyControlsResize);
     this.unregisterFromGraph();
diff --git a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposAreaLayoutEditor.vue b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposAreaLayoutEditor.vue
index 17a32f0202..9f4f2387d4 100644
--- a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposAreaLayoutEditor.vue
+++ b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposAreaLayoutEditor.vue
@@ -259,6 +259,12 @@ export default {
         this.emphasizeGrid();
       } else {
         this.deEmphasizeGrid();
+        // Leaving layout mode: clear the control-suppression flag that was
+        // set on the focused widget when we entered layout mode. Without
+        // this the layout widget keeps `isSuppressingWidgetControls=true`
+        // and its side operation bar stays hidden even though it is the
+        // focused widget.
+        apos.bus.$emit('clear-focused-widget-control-suppression');
       }
     }
   },

From 82ff1104c635d187420f29a6dfef748e7a8609ab Mon Sep 17 00:00:00 2001
From: Robert Means <robert@apostrophecms.com>
Date: Mon, 4 May 2026 11:34:44 -0400
Subject: [PATCH 11/56] Pro 9405 remove hreflang (#5395)

* Remove hreflang generation and update README

* Add changeset

* Changeset update
---
 .changeset/common-beans-lie.md |  5 +++
 packages/seo/README.md         |  2 ++
 packages/seo/lib/nodes.js      | 63 +---------------------------------
 3 files changed, 8 insertions(+), 62 deletions(-)
 create mode 100644 .changeset/common-beans-lie.md

diff --git a/.changeset/common-beans-lie.md b/.changeset/common-beans-lie.md
new file mode 100644
index 0000000000..42fd0945d7
--- /dev/null
+++ b/.changeset/common-beans-lie.md
@@ -0,0 +1,5 @@
+---
+"@apostrophecms/seo": minor
+---
+
+Removes unimplemented hreflang output; use @apostrophecms/sitemap for hreflang support
diff --git a/packages/seo/README.md b/packages/seo/README.md
index 17dd7f5a27..ecc080959d 100644
--- a/packages/seo/README.md
+++ b/packages/seo/README.md
@@ -297,6 +297,8 @@ The module automatically provides an `/llms.txt` route to communicate your AI us
 
 Works seamlessly with `@apostrophecms/sitemap` to generate XML sitemaps that help search engines discover and index your content. The sitemap is automatically referenced in the `/llms.txt` file for AI crawlers.
 
+**Hreflang:** This module does not output `<link rel="alternate" hreflang="...">` tags. Generating them at render time requires fetching each locale's true URL, which is expensive. Google accepts hreflang via XML sitemap as an equivalent signal, and [`@apostrophecms/sitemap`](https://apostrophecms.com/extensions/sitemap) handles this without the per-request overhead.
+
 ### Performance Optimization
 
 **Critical Font Preloading** - Automatically preload critical fonts to improve Core Web Vitals scores and SEO performance:
diff --git a/packages/seo/lib/nodes.js b/packages/seo/lib/nodes.js
index 5a9c8461c6..01731cfcae 100644
--- a/packages/seo/lib/nodes.js
+++ b/packages/seo/lib/nodes.js
@@ -262,66 +262,6 @@ function getMetaHead(data, options) {
     }
   }
 
-  // Add hreflang tags
-  const hreflangTags = getHreflangTags(data);
-  nodes.push(...hreflangTags);
-
-  return nodes;
-}
-
-function getHreflangTags(data) {
-  const nodes = [];
-  const {
-    piece, page, req
-  } = data;
-  const document = piece || page;
-
-  // Only add hreflang if the site has i18n enabled
-  if (!req?.locale || !document?._url) {
-    return nodes;
-  }
-
-  // Get all locale versions of this document if they exist
-  // This assumes ApostropheCMS i18n structure
-  if (document.aposLocale && data.alternateLocales) {
-    // Add current page
-    nodes.push({
-      name: 'link',
-      attrs: {
-        rel: 'alternate',
-        hreflang: req.locale,
-        href: document._url
-      }
-    });
-
-    // Add alternate locales
-    data.alternateLocales.forEach(alt => {
-      if (alt.locale && alt.url) {
-        nodes.push({
-          name: 'link',
-          attrs: {
-            rel: 'alternate',
-            hreflang: alt.locale,
-            href: alt.url
-          }
-        });
-      }
-    });
-
-    // Add x-default for the primary locale
-    const defaultLocale = data.alternateLocales.find(alt => alt.isDefault);
-    if (defaultLocale) {
-      nodes.push({
-        name: 'link',
-        attrs: {
-          rel: 'alternate',
-          hreflang: 'x-default',
-          href: defaultLocale.url
-        }
-      });
-    }
-  }
-
   return nodes;
 }
 
@@ -407,6 +347,5 @@ function getTagManagerBody(data) {
 module.exports = {
   getMetaHead,
   getTagManagerHead,
-  getTagManagerBody,
-  getHreflangTags
+  getTagManagerBody
 };

From d65c5d61032f59b76189ecd18005436b2c3326d9 Mon Sep 17 00:00:00 2001
From: Robert Means <robert@apostrophecms.com>
Date: Mon, 4 May 2026 11:36:22 -0400
Subject: [PATCH 12/56] Pro 9406 base url (#5396)

* Removes `seoSiteCanonicalUrl`

* Update tests and remove missed log

* Change semver level
---
 .changeset/shaky-regions-spend.md             |  5 +++++
 packages/seo/i18n/de.json                     |  2 --
 packages/seo/i18n/en.json                     |  2 --
 packages/seo/i18n/es.json                     |  2 --
 packages/seo/i18n/fr.json                     |  2 --
 packages/seo/i18n/it.json                     |  2 --
 packages/seo/i18n/pt-BR.json                  |  2 --
 packages/seo/i18n/sk.json                     |  2 --
 packages/seo/lib/jsonld-schemas.js            |  8 --------
 .../@apostrophecms/seo-fields-global/index.js | 20 +++++++++++--------
 packages/seo/test/functional-tests.js         | 10 +++-------
 packages/seo/test/unit-tests.js               |  2 --
 12 files changed, 20 insertions(+), 39 deletions(-)
 create mode 100644 .changeset/shaky-regions-spend.md

diff --git a/.changeset/shaky-regions-spend.md b/.changeset/shaky-regions-spend.md
new file mode 100644
index 0000000000..a21e913af0
--- /dev/null
+++ b/.changeset/shaky-regions-spend.md
@@ -0,0 +1,5 @@
+---
+"@apostrophecms/seo": minor
+---
+
+Removes the `seoSiteCanonicalUrl` field from global settings. The base URL is now derived automatically from `APOS_BASE_URL` or the `baseUrl` option. The value remains available at `req.data.global.seoSiteCanonicalUrl` for backwards compatibility.
diff --git a/packages/seo/i18n/de.json b/packages/seo/i18n/de.json
index aa74b5dd98..1a1c35e8e0 100644
--- a/packages/seo/i18n/de.json
+++ b/packages/seo/i18n/de.json
@@ -30,8 +30,6 @@
   "siteNameHelp": "Der Name Ihrer Website (verwendet in strukturierten Daten und beim Teilen in sozialen Netzwerken).",
   "siteDescription": "Website-Beschreibung",
   "siteDescriptionHelp": "Eine kurze Beschreibung Ihrer Website.",
-  "siteCanonicalUrl": "Basis-URL der Website",
-  "siteCanonicalUrlHelp": "Die Basis-URL Ihrer Website (z. B. https://example.com). Erforderlich für korrekte kanonische Links und strukturierte Daten.",
 
   "themeColor": "Mobile Themenfarbe",
   "themeColorHelp": "Legen Sie die Farbe der Browser-Oberfläche für Mobilgeräte und PWAs fest.",
diff --git a/packages/seo/i18n/en.json b/packages/seo/i18n/en.json
index b5eaffcf59..d5205dbe89 100644
--- a/packages/seo/i18n/en.json
+++ b/packages/seo/i18n/en.json
@@ -30,8 +30,6 @@
   "siteNameHelp": "The name of your website (used in structured data and social sharing).",
   "siteDescription": "Site Description",
   "siteDescriptionHelp": "A brief description of your website.",
-  "siteCanonicalUrl": "Site Base URL",
-  "siteCanonicalUrlHelp": "The base URL of your site (e.g., https://example.com). Required for proper canonical links and structured data.",
 
   "themeColor": "Mobile Theme Color",
   "themeColorHelp": "Set the browser chrome color for mobile devices and PWAs.",
diff --git a/packages/seo/i18n/es.json b/packages/seo/i18n/es.json
index cd59918887..72ae861be9 100644
--- a/packages/seo/i18n/es.json
+++ b/packages/seo/i18n/es.json
@@ -30,8 +30,6 @@
   "siteNameHelp": "El nombre de su sitio web (usado en datos estructurados y en redes sociales).",
   "siteDescription": "Descripción del sitio",
   "siteDescriptionHelp": "Una breve descripción de su sitio web.",
-  "siteCanonicalUrl": "URL base del sitio",
-  "siteCanonicalUrlHelp": "La URL base de su sitio (ej. https://example.com). Requerida para enlaces canónicos y datos estructurados correctos.",
 
   "themeColor": "Color del tema móvil",
   "themeColorHelp": "Establezca el color de la interfaz del navegador en dispositivos móviles y PWAs.",
diff --git a/packages/seo/i18n/fr.json b/packages/seo/i18n/fr.json
index 793ba8e7e5..84887ed702 100644
--- a/packages/seo/i18n/fr.json
+++ b/packages/seo/i18n/fr.json
@@ -30,8 +30,6 @@
   "siteNameHelp": "Le nom de votre site web (utilisé dans les données structurées et le partage sur les réseaux sociaux).",
   "siteDescription": "Description du site",
   "siteDescriptionHelp": "Brève description de votre site web.",
-  "siteCanonicalUrl": "URL de base du site",
-  "siteCanonicalUrlHelp": "L’URL de base de votre site (ex. https://example.com). Nécessaire pour des liens canoniques et des données structurées corrects.",
 
   "themeColor": "Couleur du thème mobile",
   "themeColorHelp": "Définissez la couleur de l’interface du navigateur sur les appareils mobiles et les PWA.",
diff --git a/packages/seo/i18n/it.json b/packages/seo/i18n/it.json
index e4f66b05ea..042871d5f3 100644
--- a/packages/seo/i18n/it.json
+++ b/packages/seo/i18n/it.json
@@ -30,8 +30,6 @@
   "siteNameHelp": "Il nome del tuo sito web (usato nei dati strutturati e nella condivisione sui social).",
   "siteDescription": "Descrizione del sito",
   "siteDescriptionHelp": "Breve descrizione del tuo sito web.",
-  "siteCanonicalUrl": "URL base del sito",
-  "siteCanonicalUrlHelp": "L’URL base del tuo sito (es. https://example.com). Necessario per i link canonici e i dati strutturati corretti.",
 
   "themeColor": "Colore tema mobile",
   "themeColorHelp": "Imposta il colore dell’interfaccia del browser per dispositivi mobili e PWA.",
diff --git a/packages/seo/i18n/pt-BR.json b/packages/seo/i18n/pt-BR.json
index 2de412cf89..0e2b96321f 100644
--- a/packages/seo/i18n/pt-BR.json
+++ b/packages/seo/i18n/pt-BR.json
@@ -29,8 +29,6 @@
   "siteNameHelp": "O nome do seu site (usado em dados estruturados e compartilhamento em redes sociais).",
   "siteDescription": "Descrição do site",
   "siteDescriptionHelp": "Uma breve descrição do seu site.",
-  "siteCanonicalUrl": "URL base do site",
-  "siteCanonicalUrlHelp": "A URL base do seu site (ex.: https://example.com). Necessária para links canônicos e dados estruturados corretos.",
 
   "themeColor": "Cor do tema móvel",
   "themeColorHelp": "Defina a cor da interface do navegador para dispositivos móveis e PWAs.",
diff --git a/packages/seo/i18n/sk.json b/packages/seo/i18n/sk.json
index 9794e9ad7b..c639e2b234 100644
--- a/packages/seo/i18n/sk.json
+++ b/packages/seo/i18n/sk.json
@@ -30,8 +30,6 @@
   "siteNameHelp": "Názov vašej webovej stránky (používa sa v štruktúrovaných dátach a pri zdieľaní na sociálnych sieťach).",
   "siteDescription": "Popis stránky",
   "siteDescriptionHelp": "Stručný popis vašej webovej stránky.",
-  "siteCanonicalUrl": "Základná URL stránky",
-  "siteCanonicalUrlHelp": "Základná URL vašej stránky (napr. https://example.com). Potrebné pre správne kanonické odkazy a štruktúrované dáta.",
 
   "themeColor": "Farba témy pre mobil",
   "themeColorHelp": "Nastavte farbu rozhrania prehliadača pre mobilné zariadenia a PWA.",
diff --git a/packages/seo/lib/jsonld-schemas.js b/packages/seo/lib/jsonld-schemas.js
index ae4c08d02b..2ea026cbda 100644
--- a/packages/seo/lib/jsonld-schemas.js
+++ b/packages/seo/lib/jsonld-schemas.js
@@ -983,14 +983,6 @@ class JsonLdSchemaHandler {
     if (fromGlobal) {
       return fromGlobal.replace(/\/$/, '');
     }
-    const abs = data.req?.absoluteUrl;
-
-    if (abs) {
-      try {
-        return new URL(abs).origin;
-      } catch (e) { }
-    }
-
     return null;
   }
 
diff --git a/packages/seo/modules/@apostrophecms/seo-fields-global/index.js b/packages/seo/modules/@apostrophecms/seo-fields-global/index.js
index 93b2ada0ca..457793c60d 100644
--- a/packages/seo/modules/@apostrophecms/seo-fields-global/index.js
+++ b/packages/seo/modules/@apostrophecms/seo-fields-global/index.js
@@ -141,12 +141,6 @@ module.exports = {
         textarea: true,
         help: 'aposSeo:siteDescriptionHelp'
       },
-      seoSiteCanonicalUrl: {
-        label: 'aposSeo:siteCanonicalUrl',
-        type: 'url',
-        required: true,
-        help: 'aposSeo:siteCanonicalUrlHelp'
-      },
       seoJsonLdOrganization: {
         label: 'aposSeo:organizationInfo',
         type: 'object',
@@ -333,7 +327,6 @@ module.exports = {
           'llmsCustomText',
           'seoSiteName',
           'seoSiteDescription',
-          'seoSiteCanonicalUrl',
           'seoJsonLdOrganization',
           'seoSocialProfiles',
           'seoSearchQueryParam'
@@ -375,6 +368,17 @@ module.exports = {
       : null;
   },
 
+  extendMethods(self) {
+    return {
+      async addGlobalToData(_super, req) {
+        await _super(req);
+        // For bc. Prefer self.apos.url.getBaseUrl(req) or the ._url
+        // property of the document in question.
+        req.data.global.seoSiteCanonicalUrl = self.apos.url.getBaseUrl(req);
+      }
+    };
+  },
+
   handlers(self) {
     return {
       '@apostrophecms/url:getAllUrlMetadata': {
@@ -533,7 +537,7 @@ Allow: /
               return global.llmsCustomText;
             }
 
-            const baseUrl = global?.seoSiteCanonicalUrl || req.absoluteUrl.split('/').slice(0, 3).join('/');
+            const baseUrl = self.apos.url.getBaseUrl(req);
 
             // Build the LLMS.txt content
             let content = `# ${global.seoSiteName || global.title || 'Website'}\n\n`;
diff --git a/packages/seo/test/functional-tests.js b/packages/seo/test/functional-tests.js
index 8c85f2a25b..e893f59fab 100644
--- a/packages/seo/test/functional-tests.js
+++ b/packages/seo/test/functional-tests.js
@@ -14,6 +14,7 @@ describe('@apostrophecms/seo - Integration Tests (Actual Page Output)', function
     apos = await t.create({
       root: module,
       testModule: true,
+      baseUrl: 'http://localhost:3000',
       modules: getAppConfig()
     });
   });
@@ -37,7 +38,6 @@ describe('@apostrophecms/seo - Integration Tests (Actual Page Output)', function
         { _id: global._id },
         {
           $set: {
-            seoSiteCanonicalUrl: 'https://example.com',
             seoSiteName: 'Example Tech Corp',
             seoSiteDescription: 'Leading provider of tech solutions',
             seoJsonLdOrganization: {
@@ -92,7 +92,7 @@ describe('@apostrophecms/seo - Integration Tests (Actual Page Output)', function
       const websiteSchema = jsonLd['@graph'].find(s => s['@type'] === 'WebSite');
       assert(websiteSchema, 'Homepage should include WebSite schema');
       assert.strictEqual(websiteSchema.name, 'Example Tech Corp');
-      assert.strictEqual(websiteSchema.url, 'https://example.com');
+      assert.strictEqual(websiteSchema.url, 'http://localhost:3000');
       assert(websiteSchema.potentialAction, 'WebSite should have search action');
       assert.strictEqual(websiteSchema.potentialAction['@type'], 'SearchAction');
 
@@ -158,7 +158,6 @@ describe('@apostrophecms/seo - Integration Tests (Actual Page Output)', function
         { _id: global._id },
         {
           $set: {
-            seoSiteCanonicalUrl: 'https://example.com',
             seoSiteName: 'Test Site',
             seoJsonLdOrganization: {
               name: 'Test Organization',
@@ -264,7 +263,6 @@ describe('@apostrophecms/seo - Integration Tests (Actual Page Output)', function
         { _id: global._id },
         {
           $set: {
-            seoSiteCanonicalUrl: 'https://example.com',
             seoSiteName: 'Test Site'
           }
         }
@@ -315,7 +313,6 @@ describe('@apostrophecms/seo - Integration Tests (Actual Page Output)', function
         { _id: global._id },
         {
           $set: {
-            seoSiteCanonicalUrl: 'https://example.com',
             seoSiteName: 'Test Site'
           }
         }
@@ -443,7 +440,6 @@ describe('@apostrophecms/seo - Integration Tests (Actual Page Output)', function
         { _id: global._id },
         {
           $set: {
-            seoSiteCanonicalUrl: 'https://example.com',
             seoSiteName: 'Test Site for LLMs',
             seoSiteDescription: 'A test site demonstrating llms.txt',
             llmsTxtSelection: 'allow'
@@ -460,7 +456,7 @@ describe('@apostrophecms/seo - Integration Tests (Actual Page Output)', function
         llmsTxt.includes('A test site demonstrating llms.txt'),
         'Should include site description'
       );
-      assert(llmsTxt.includes('https://example.com'), 'Should include base URL');
+      assert(llmsTxt.includes('http://localhost:3000'), 'Should include base URL');
       assert(
         llmsTxt.includes('## AI Training Policy') ||
         llmsTxt.includes('AI Training'),
diff --git a/packages/seo/test/unit-tests.js b/packages/seo/test/unit-tests.js
index 241660ee63..095d82077f 100644
--- a/packages/seo/test/unit-tests.js
+++ b/packages/seo/test/unit-tests.js
@@ -78,8 +78,6 @@ describe('@apostrophecms/seo', function () {
 
       const schemas = handler.generateSchemas(data);
       const articleSchema = schemas.find(s => s['@type'] === 'Article');
-      console.log(articleSchema);// eslint-disable-line no-console
-
       assert(articleSchema.author, 'author should exist');
       assert.strictEqual(articleSchema.author.name, 'John Doe');
     });

From 008417fa9814dba4899b53b9394778dbd46ccf3c Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Tue, 5 May 2026 18:02:03 +0300
Subject: [PATCH 13/56] Bump dependencies (#5398)

* Bump dependencies
* Fix missing test await resulting in random failures
---
 packages/cli/lib/commands/create.js | 12 ++++++------
 packages/cli/package.json           |  2 +-
 packages/login-totp/test/test.js    |  2 +-
 packages/oembetter/package.json     |  2 +-
 4 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/packages/cli/lib/commands/create.js b/packages/cli/lib/commands/create.js
index 9837cf9a1f..8596c3c8bb 100644
--- a/packages/cli/lib/commands/create.js
+++ b/packages/cli/lib/commands/create.js
@@ -86,7 +86,7 @@ module.exports = function (program) {
       const expressIndexPath = resolvePath('lib/modules/apostrophe-express/index.js');
       if (fs.existsSync(expressIndexPath)) {
         util.replaceInFiles(
-          [expressIndexPath],
+          [ expressIndexPath ],
           /secret: undefined/,
           `secret: '${secret}'`
         );
@@ -96,7 +96,7 @@ module.exports = function (program) {
       secret = util.secret();
 
       util.replaceInFiles(
-        [resolvePath('app.js')],
+        [ resolvePath('app.js') ],
         /disabledFileKey: undefined/,
         `disabledFileKey: '${secret}'`
       );
@@ -124,7 +124,7 @@ module.exports = function (program) {
           });
         } catch (error) {
           await util.error('create', 'Error installing backend packages');
-          /* eslint-disable-next-line no-console */
+
           console.error(error);
         }
 
@@ -136,7 +136,7 @@ module.exports = function (program) {
           });
         } catch (error) {
           await util.error('create', 'Error installing frontend packages');
-          /* eslint-disable-next-line no-console */
+
           console.error(error);
         }
       } else {
@@ -147,7 +147,7 @@ module.exports = function (program) {
           });
         } catch (error) {
           await util.error('create', 'Error installing packages');
-          /* eslint-disable-next-line no-console */
+
           console.error(error);
         }
       }
@@ -192,6 +192,6 @@ module.exports = function (program) {
 };
 
 function replaceInConfig(regex, replacement, resolvePath) {
-  const files = [resolvePath('app.js'), resolvePath('package.json')];
+  const files = [ resolvePath('app.js'), resolvePath('package.json') ];
   util.replaceInFiles(files, regex, replacement);
 }
diff --git a/packages/cli/package.json b/packages/cli/package.json
index ff9c72b249..20ff3c1395 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -29,7 +29,7 @@
     "shell-quote": "^1.8.1",
     "shelljs": "^0.10.0",
     "sync-request": "^6.0.0",
-    "uuid": "^8.0.0"
+    "uuid": "^11.1.0"
   },
   "devDependencies": {
     "eslint": "^9.39.1",
diff --git a/packages/login-totp/test/test.js b/packages/login-totp/test/test.js
index 0a298c2a9a..75e536c8e3 100644
--- a/packages/login-totp/test/test.js
+++ b/packages/login-totp/test/test.js
@@ -67,7 +67,7 @@ describe('totp module', function () {
     user.role = 'editor';
 
     const doc = await apos.user.insert(apos.task.getReq(), user);
-    apos.user.safe.updateOne({
+    await apos.user.safe.updateOne({
       _id: doc._id
     }, {
       $set: {
diff --git a/packages/oembetter/package.json b/packages/oembetter/package.json
index 3b01690fec..63ee9c08c2 100644
--- a/packages/oembetter/package.json
+++ b/packages/oembetter/package.json
@@ -29,7 +29,7 @@
   "dependencies": {
     "async": "^0.9.0",
     "cheerio": "^1.1.0",
-    "fast-xml-parser": "^4.5.6",
+    "fast-xml-parser": "^5.7.0",
     "node-fetch": "^2.6.7",
     "urls": "0.0.4"
   },

From 7ab9961a5f368f140e014a8099b4ca2f8fdfd284 Mon Sep 17 00:00:00 2001
From: Robert Means <robert@apostrophecms.com>
Date: Wed, 6 May 2026 08:01:32 -0400
Subject: [PATCH 14/56] Pro 9405 remove hreflang (#5395)

* Remove hreflang generation and update README

* Add changeset

* Changeset update

From e9b3bac692315414da47fe05202e8854dd31d7ee Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 6 May 2026 14:13:29 -0400
Subject: [PATCH 15/56] PRO-9467: remove defunct and nonpublic oembed providers
 and improve developer control to ensure security in the future (no risk
 exists today) (#5400)

* PRO-9467: remove defunct and nonpublic oembed providers and improve developer control to ensure security in the future (no risk exists today)

* allow newer twitter domain

* infogr.am still around

* facebook no longer does oembed
---
 .changeset/wild-forks-fetch.md                | 15 ++++++++
 .../modules/@apostrophecms/oembed/index.js    | 31 +++++++++-------
 packages/oembetter/index.js                   | 36 +++++--------------
 3 files changed, 42 insertions(+), 40 deletions(-)
 create mode 100644 .changeset/wild-forks-fetch.md

diff --git a/.changeset/wild-forks-fetch.md b/.changeset/wild-forks-fetch.md
new file mode 100644
index 0000000000..f5f944c79e
--- /dev/null
+++ b/.changeset/wild-forks-fetch.md
@@ -0,0 +1,15 @@
+---
+"apostrophe": minor
+---
+
+apostrophe and oembetter have been updated to eliminate a number of services that formerly supported
+oembed for the general public, but no longer do so. While there is no security risk today, removing
+these ensures that if these domains are ever allowed to lapse, they do not become an XSS
+attack vector in the future.
+
+Because oembed responses are not always iframes, it is important that this list be maintained
+over time. In addition, developers always have the option to prune it on their own by setting
+the new minimumAllowlist and minimumEndpoints options of the @apostrophecms/oembed module.
+
+Thanks to [Sainithin0309](https://github.com/Sainithin0309) for pointing out the potential
+long-term security concern.
diff --git a/packages/apostrophe/modules/@apostrophecms/oembed/index.js b/packages/apostrophe/modules/@apostrophecms/oembed/index.js
index 9e4e83ad8a..d21e458da7 100644
--- a/packages/apostrophe/modules/@apostrophecms/oembed/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/oembed/index.js
@@ -16,10 +16,13 @@ const cheerio = require('cheerio');
 // widely trusted sites are already allowlisted.
 //
 // Your `allowlist` option is concatenated with `oembetter`'s standard
-// allowlist, plus wufoo.com, infogr.am, and slideshare.net.
+// allowlist, plus wufoo.com, infogr.am and slideshare.net.
 //
 // Your `endpoints` option is concatenated with `oembetter`'s standard
 // endpoints list.
+//
+// If you wish to completely override the behavior, set
+// `minimumAllowlist` and `minimumEndpoints` instead.
 
 module.exports = {
   options: {
@@ -42,28 +45,30 @@ module.exports = {
         // Don't permit oembed of untrusted sites, which could
         // lead to XSS attacks
 
-        self.oembetter.allowlist(self.oembetter.suggestedAllowlist.concat(
-          self.options.allowlist || [],
-          [
-            'wufoo.com',
-            'infogr.am',
-            'slideshare.net'
-          ])
-        );
+        const minimumAllowlist = self.options.minimumAllowlist || [
+          ...self.oembetter.suggestedAllowlist,
+          'wufoo.com',
+          'infogr.am',
+          'slideshare.net'
+        ];
+
+        self.oembetter.allowlist(minimumAllowlist.concat(self.options.allowlist || []));
+
+        const minimumEndpoints = self.options.minimumEndpoints || self.oembetter.suggestedEndpoints;
         self.oembetter.endpoints(
-          self.oembetter.suggestedEndpoints.concat(self.options.endpoints || [])
+          minimumEndpoints.concat(self.options.endpoints || [])
         );
       },
 
       // Enhances oembetter to support services better or to support services
-      // that have no oembed support by default. Called by `afterConstruct`.
-      // Extend this method to add additional `oembetter` filters.
+      // that have no oembed support by default.
+      //
+      // Extend or override this method to change or add oembetter filters.
 
       enhanceOembetter() {
         require('./lib/youtube.js')(self, self.oembetter);
         require('./lib/vimeo.js')(self, self.oembetter);
         require('./lib/wufoo.js')(self, self.oembetter);
-        require('./lib/infogram.js')(self, self.oembetter);
       },
 
       // This method fetches the specified URL, determines its best embedded
diff --git a/packages/oembetter/index.js b/packages/oembetter/index.js
index 6f33de895f..4c3d168def 100644
--- a/packages/oembetter/index.js
+++ b/packages/oembetter/index.js
@@ -187,41 +187,15 @@ module.exports = function(options) {
   self.suggestedAllowlist = [
     'youtube.com',
     'youtu.be',
-    'blip.tv',
     'dailymotion.com',
     'flickr.com',
-    'hulu.com',
-    'nfb.ca',
-    'qik.com',
-    'revision3.com',
-    'scribd.com',
-    'viddler.com',
     'vimeo.com',
-    'youtube.com',
-    'dotsub.com',
-    'yfrog.com',
-    'photobucket.com',
     'soundcloud.com',
-    'instagram.com',
     'twitter.com',
-    'facebook.com'
+    'x.com'
   ];
 
   self.suggestedEndpoints = [
-    {
-      domain: 'instagram.com',
-      endpoint: 'http://api.instagram.com/oembed'
-    },
-    {
-      domain: 'facebook.com',
-      path: /\/videos\//,
-      endpoint: 'https://www.facebook.com/plugins/video/oembed.json/'
-    },
-    {
-      domain: 'facebook.com',
-      path: /\/posts\//,
-      endpoint: 'https://www.facebook.com/plugins/post/oembed.json/'
-    },
     {
       domain: 'vimeo.com',
       endpoint: 'https://vimeo.com/api/oembed.json'
@@ -233,6 +207,14 @@ module.exports = function(options) {
     {
       domain: 'youtu.be',
       endpoint: 'https://www.youtube.com/oembed'
+    },
+    {
+      domain: 'twitter.com',
+      endpoint: 'https://publish.twitter.com/oembed'
+    },
+    {
+      domain: 'x.com',
+      endpoint: 'https://publish.twitter.com/oembed'
     }
   ];
 

From bc8f7bed381d4462a082976dd92b8d7f28180a95 Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Thu, 7 May 2026 18:21:28 +0300
Subject: [PATCH 16/56] Layout editable gap (#5397)

---
 .changeset/seven-emus-vanish.md               |   6 +
 .../widgets/LayoutWidget.astro                |  32 +-
 .../modules/@apostrophecms/i18n/i18n/en.json  |   2 +
 .../@apostrophecms/layout-widget/index.js     | 126 ++++-
 .../apos/components/AposAreaLayoutEditor.vue  |  89 ++-
 .../ui/apos/components/AposGridLayout.vue     |   4 +-
 .../ui/apos/components/AposGridManager.vue    |   4 +-
 .../layout-widget/ui/apos/layout.css          |   8 +
 .../layout-widget/ui/src/layout.css           |   2 +-
 .../layout-widget/views/widget.html           |   6 +-
 .../modules/@apostrophecms/styles/index.js    |  16 +
 .../@apostrophecms/styles/lib/handlers.js     |   6 +
 .../@apostrophecms/styles/lib/methods.js      |  93 +++
 .../@apostrophecms/styles/lib/presets.js      |  17 +
 .../styles/ui/apos/universal/render.mjs       |  11 +-
 .../modules/@apostrophecms/util/index.js      |   4 +
 .../@apostrophecms/widget-type/index.js       |   6 +
 .../ui/apos/components/AposWidgetEditor.vue   |  32 ++
 packages/apostrophe/test/layout-widget-gap.js | 530 ++++++++++++++++++
 packages/apostrophe/test/styles.js            |  50 ++
 20 files changed, 1022 insertions(+), 22 deletions(-)
 create mode 100644 .changeset/seven-emus-vanish.md
 create mode 100644 packages/apostrophe/test/layout-widget-gap.js

diff --git a/.changeset/seven-emus-vanish.md b/.changeset/seven-emus-vanish.md
new file mode 100644
index 0000000000..564a10e231
--- /dev/null
+++ b/.changeset/seven-emus-vanish.md
@@ -0,0 +1,6 @@
+---
+"@apostrophecms/apostrophe-astro": minor
+"apostrophe": minor
+---
+
+Editors can now control the layout-widget gap through the styles system, both site-wide via a global `layoutGap` preset and per widget via a `gap` styles field. New Layout widget option `className` allows for additional CSS class names to be added to the widget Grid container.
diff --git a/packages/apostrophe-astro/widgets/LayoutWidget.astro b/packages/apostrophe-astro/widgets/LayoutWidget.astro
index ec25dfaa5b..596cbecffa 100644
--- a/packages/apostrophe-astro/widgets/LayoutWidget.astro
+++ b/packages/apostrophe-astro/widgets/LayoutWidget.astro
@@ -2,6 +2,31 @@
 const { widget, options } = Astro.props;
 import AposArea from "../components/AposArea.astro";
 import LayoutColumn from "./LayoutColumn.astro";
+
+const gapMeta = widget._options || {};
+const resolvedGap = options._gap ?? gapMeta._gap ?? null;
+const gapHasGlobal = options._gapHasGlobal ?? gapMeta._gapHasGlobal ?? false;
+
+// Resolve the inline `--grid-gap` value
+const hasWidgetGap = resolvedGap != null;
+const omitGridGap = !hasWidgetGap && gapHasGlobal;
+const gridGap = hasWidgetGap
+  ? resolvedGap
+  : omitGridGap
+    ? undefined
+    : options.gap || "0";
+
+// Mirror the Nunjucks `parentOptionsForArea` helper so the in-place
+// layout editor (AposAreaLayoutEditor) sees the same `gap` signal in
+// its `data-parent-options` JSON as it would on the Nunjucks side:
+// - widget value present → carries through (string with unit).
+// - widget value absent + global enabled → `gap: null` (signal omit).
+// - otherwise → no `gap` key (use the static module default / BC).
+const parentOptions = {
+  ...options,
+  widgetId: widget._id,
+  ...(hasWidgetGap ? { gap: resolvedGap } : omitGridGap ? { gap: null } : {}),
+};
 ---
 
 <AposArea
@@ -9,7 +34,7 @@ import LayoutColumn from "./LayoutColumn.astro";
   aposClassName="layout-widget"
   aposStyle={{
     "--grid-columns": options.columns,
-    "--grid-gap": options.gap || "0",
+    ...(gridGap !== undefined ? { "--grid-gap": gridGap } : {}),
     "--grid-rows": "auto",
     "--mobile-grid-rows": "auto",
     "--tablet-grid-rows": "auto",
@@ -20,9 +45,6 @@ import LayoutColumn from "./LayoutColumn.astro";
     "data-tablet-auto": true,
     "data-mobile-auto": true,
   }}
-  aposParentOptions={{
-    ...options,
-    widgetId: widget._id,
-  }}
+  aposParentOptions={parentOptions}
   widgetComponent={LayoutColumn}
 />
diff --git a/packages/apostrophe/modules/@apostrophecms/i18n/i18n/en.json b/packages/apostrophe/modules/@apostrophecms/i18n/i18n/en.json
index d2ae0d8af6..e6b5ed913d 100644
--- a/packages/apostrophe/modules/@apostrophecms/i18n/i18n/en.json
+++ b/packages/apostrophe/modules/@apostrophecms/i18n/i18n/en.json
@@ -643,6 +643,8 @@
   "styleGradientAngle": "Angle",
   "styleGradientEnd": "End Color",
   "styleGradientStart": "Start Color",
+  "styleLayoutGap": "Layout Gap",
+  "styleLayoutGapHelp": "Sets the spacing between columns inside layout sections across the site.",
   "styleLeft": "Left",
   "styleMargin": "Margin",
   "styleOverlayColor": "Overlay Color",
diff --git a/packages/apostrophe/modules/@apostrophecms/layout-widget/index.js b/packages/apostrophe/modules/@apostrophecms/layout-widget/index.js
index 71377222d0..b6d2060bd7 100644
--- a/packages/apostrophe/modules/@apostrophecms/layout-widget/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/layout-widget/index.js
@@ -19,6 +19,10 @@ module.exports = {
     gap: '1.5rem',
     defaultCellHorizontalAlignment: null,
     defaultCellVerticalAlignment: null,
+    // Extra class name(s) to append to the rendered layout-widget area
+    // wrapper, in addition to the built-in `layout-widget` class. Accepts
+    // a string of space-separated class names.
+    className: '',
     injectStyles: true,
     minifyStyles: true
   },
@@ -98,6 +102,25 @@ module.exports = {
         validateAndIdentifyTypes() {
           const { column } = self.validateAndIdentifyTypes();
           self.columnWidgetName = column;
+        },
+        // Detect the widget-style "gap" field (any styles field whose
+        // CSS `property` resolves to `gap`). Only the first match is used.
+        // Also detect whether the @apostrophecms/styles module has a
+        // site-wide layout gap field configured (via the `layoutGap`
+        // preset / `layoutGapDefault: true` marker).
+        detectGapFields() {
+          const widgetGapFields = self.apos.styles
+            .fieldsWithProperty(self.schema, 'gap');
+          if (widgetGapFields.length > 1) {
+            self.apos.util.warn(
+              `[${self.__meta.name}] Multiple style fields produce the ` +
+              `CSS \`gap\` property (${widgetGapFields.join(', ')}). ` +
+              'Only the first one will be honoured as the widget-scope gap.'
+            );
+          }
+          self.widgetGapFieldName = widgetGapFields[0] || null;
+          self.globalGapEnabled = !!self.apos.modules['@apostrophecms/styles']
+            ?.layoutGapFieldName;
         }
       }
     };
@@ -118,6 +141,17 @@ module.exports = {
             defaultCellHorizontalAlignment: self.options.defaultCellHorizontalAlignment,
             defaultCellVerticalAlignment: self.options.defaultCellVerticalAlignment
           },
+          widgetGapFieldName: self.widgetGapFieldName || null,
+          widgetGapFieldUnit: self.widgetGapFieldName
+            ? (self.apos.styles
+              .getFieldByPath(self.schema, self.widgetGapFieldName)
+              ?.unit || '')
+            : '',
+          globalGapEnabled: !!self.globalGapEnabled,
+          // Opt-in flag read by the generic widget editor: when true,
+          // it broadcasts `apos-widget-live-preview` events on the apos bus
+          // during the style-only fast path.
+          subscribesToLivePreview: !!self.widgetGapFieldName,
           columnWidgetName: self.columnWidgetName
         };
       },
@@ -132,6 +166,7 @@ module.exports = {
           defaultCellHorizontalAlignment,
           defaultCellVerticalAlignment
         } = self.options;
+        const widgetGap = self.resolveWidgetGap(widget);
         return {
           ..._super(widget, { scene }),
           columns,
@@ -141,13 +176,53 @@ module.exports = {
           tablet,
           gap,
           defaultCellHorizontalAlignment,
-          defaultCellVerticalAlignment
+          defaultCellVerticalAlignment,
+          _gap: widgetGap,
+          _gapHasGlobal: !!self.globalGapEnabled
         };
       }
     };
   },
   methods(self) {
     return {
+      // Resolve the widget-scope gap for a widget instance, if this
+      // module declares a styles field with `property: 'gap'`. Returns
+      // the resolved value (with unit, when applicable). When the
+      // widget has no explicit value, falls back to the field's `def`.
+      // Returns `null` only when no widget gap field is
+      // configured, no widget value is set, and no `def` is declared
+      // on the field.
+      resolveWidgetGap(widget) {
+        if (!self.widgetGapFieldName || !widget) {
+          return null;
+        }
+        const field = self.apos.styles.getFieldByPath(
+          self.schema, self.widgetGapFieldName
+        );
+        let value = self.apos.util.get(widget, self.widgetGapFieldName);
+        if (value === null || value === undefined || value === '') {
+          if (field?.def === null || field?.def === undefined || field?.def === '') {
+            return null;
+          }
+          value = field.def;
+        }
+        if (field?.unit && typeof value !== 'string') {
+          return `${value}${field.unit}`;
+        }
+        return value;
+      },
+      // Determine whether the inline `--grid-gap` CSS variable should
+      // be omitted on the grid container so the global cascade
+      // (`var(--apos-layout-gap, …)`) can take effect. The inline var
+      // is omitted whenever:
+      //   - no widget-scope gap value is set, AND
+      //   - the global layout-gap field is configured.
+      shouldOmitInlineGap(widget, global) {
+        if (!self.globalGapEnabled) {
+          return false;
+        }
+        return self.resolveWidgetGap(widget) === null;
+      },
       publicCssNodes(req) {
         return [
           {
@@ -277,11 +352,13 @@ module.exports = {
         const mobileBreakpointPlus = mobileBreakpoint + 1;
         const tabletBreakpoint = self.options.tablet?.breakpoint || 1024;
         const tabletBreakpointPlus = tabletBreakpoint + 1;
+        const gapDefault = self.options.gap || '0';
         cssContent = cssContent
           .replace(/\{\$mobile\}/g, mobileBreakpoint)
           .replace(/\{\$mobile-plus\}/g, mobileBreakpointPlus)
           .replace(/\{\$tablet\}/g, tabletBreakpoint)
-          .replace(/\{\$tablet-plus\}/g, tabletBreakpointPlus);
+          .replace(/\{\$tablet-plus\}/g, tabletBreakpointPlus)
+          .replace(/\{\$gap-default\}/g, gapDefault);
 
         return self.processCss(cssContent, scene);
       },
@@ -371,6 +448,51 @@ module.exports = {
           (a.order ?? 0) - (b.order ?? 0)
         );
         return items[items.length - 1]._id;
+      },
+      // Compute the `--grid-gap: <value>;` declaration to inline on the
+      // grid container, or an empty string when the cascade should
+      // resolve gap via `var(--apos-layout-gap, …)` instead.
+      // Honours the priority order:
+      //   1. Widget-style gap (when set on this widget instance).
+      //   2. Static module option (BC) — when no global gap field is
+      //      configured, or it has no value.
+      //   3. Otherwise, omit the inline var so the global cascade wins.
+      // Must be invoked via the widget's own module namespace —
+      // `apos.modules[data.manager.__meta.name].gapInlineCss(...)` —
+      // so that `self` resolves to the actual subclass and picks up
+      // its `widgetGapFieldName` / `globalGapEnabled`.
+      gapInlineCss(widget, options, global) {
+        const widgetGap = self.resolveWidgetGap(widget);
+        if (widgetGap !== null) {
+          return ` --grid-gap: ${widgetGap};`;
+        }
+        if (self.shouldOmitInlineGap(widget, global)) {
+          return '';
+        }
+        const fallback = (options && options.gap) || self.options.gap || '0';
+        return ` --grid-gap: ${fallback};`;
+      },
+      // Build the `aposParentOptions` payload passed by the rendered
+      // layout-widget area to the in-place editor (AposAreaLayoutEditor).
+      // Includes the widget's resolved gap (from its `gap` styles field,
+      // when present) so the live editor's grid container reflects the
+      // saved per-widget value rather than only the static module
+      // option. Sets `gap: null` to signal the editor to omit
+      // `--grid-gap` so the global cascade resolves it through
+      // `:root { --apos-layout-gap }`. Must be invoked via the widget's
+      // own module namespace, like `gapInlineCss`.
+      parentOptionsForArea(widget, options, global) {
+        const opts = {
+          ...(options || {}),
+          widgetId: widget._id
+        };
+        const widgetGap = self.resolveWidgetGap(widget);
+        if (widgetGap !== null) {
+          opts.gap = widgetGap;
+        } else if (self.shouldOmitInlineGap(widget, global)) {
+          opts.gap = null;
+        }
+        return opts;
       }
     };
   }
diff --git a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposAreaLayoutEditor.vue b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposAreaLayoutEditor.vue
index 9f4f2387d4..9e6d4bd4d8 100644
--- a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposAreaLayoutEditor.vue
+++ b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposAreaLayoutEditor.vue
@@ -122,6 +122,7 @@
 
 <script>
 import { mapActions } from 'pinia';
+import get from 'lodash/get';
 import AposAreaEditorLogic from 'Modules/@apostrophecms/area/logic/AposAreaEditor.js';
 import walkWidgets from 'Modules/@apostrophecms/area/lib/walk-widgets.js';
 import { useWidgetStore } from 'Modules/@apostrophecms/ui/stores/widget.js';
@@ -144,7 +145,11 @@ export default {
     return {
       // 'layout' | 'focus' | 'content'
       layoutMode: 'content',
-      layoutDeviceMode: 'desktop'
+      layoutDeviceMode: 'desktop',
+      // Live snapshot of the parent layout-widget's in-modal style
+      // values, fed by `apos-widget-live-preview` bus events from
+      // AposWidgetEditor while the user drags style sliders.
+      liveWidgetData: null
     };
   },
   computed: {
@@ -152,11 +157,48 @@ export default {
       return window.apos.modules[this.moduleName] || {};
     },
     gridModuleOptions() {
-      return Object.assign(
-        {},
-        this.layoutModuleOptions.grid ?? {},
-        this.parentOptions
-      );
+      const baseGrid = this.layoutModuleOptions.grid ?? {};
+      const parent = this.parentOptions || {};
+      const opts = Object.assign({}, baseGrid, parent);
+      // Resolve `gap` priority for the live editor:
+      const liveGap = this.liveGapValue;
+      if (liveGap != null) {
+        opts.gap = liveGap;
+      } else if (parent.gap != null) {
+        opts.gap = parent.gap;
+      } else if (
+        parent.gap === null ||
+        this.layoutModuleOptions.globalGapEnabled
+      ) {
+        // Parent signalled "use the cascade" (omit `--grid-gap` and let
+        // `var(--apos-layout-gap, …)` resolve it on `:root`).
+        // The snapshot is recomputed whenever `layoutMode`
+        // changes, which is the only cadence the editor needs.
+        if (this.layoutMode !== 'content') {
+          opts.gap = this.resolvedCascadeGap();
+        } else {
+          opts.gap = undefined;
+        }
+      } else {
+        opts.gap = baseGrid.gap;
+      }
+      return opts;
+    },
+    // Reactive bridge to the parent layout-widget's styles modal.
+    liveGapValue() {
+      if (this.layoutMode !== 'content') {
+        return null;
+      }
+      const fieldName = this.layoutModuleOptions.widgetGapFieldName;
+      if (!fieldName || !this.liveWidgetData) {
+        return null;
+      }
+      const value = get(this.liveWidgetData, fieldName);
+      if (value === null || value === undefined || value === '') {
+        return null;
+      }
+      const unit = this.layoutModuleOptions.widgetGapFieldUnit || '';
+      return typeof value === 'string' ? value : `${value}${unit}`;
     },
     // Meta storage is not yet implemented, return a default meta object
     layoutMeta() {
@@ -272,6 +314,8 @@ export default {
     apos.bus.$on('apos-switch-layout-mode', this.switchLayoutMode);
     apos.bus.$on('apos-layout-col-delete', this.onRemoveLayoutColumn);
     apos.bus.$on('apos-edit-styles', this.editStyles);
+    apos.bus.$on('apos-widget-live-preview', this.onWidgetLivePreview);
+    apos.bus.$on('apos-widget-live-preview-end', this.onWidgetLivePreviewEnd);
     if (!this.hasLayoutColumnWidgets) {
       this.onCreateProvision();
     }
@@ -281,6 +325,8 @@ export default {
     apos.bus.$off('apos-switch-layout-mode', this.switchLayoutMode);
     apos.bus.$off('apos-layout-col-delete', this.onRemoveLayoutColumn);
     apos.bus.$off('apos-edit-styles', this.editStyles);
+    apos.bus.$off('apos-widget-live-preview', this.onWidgetLivePreview);
+    apos.bus.$off('apos-widget-live-preview-end', this.onWidgetLivePreviewEnd);
   },
   methods: {
     ...mapActions(useWidgetStore, [
@@ -290,6 +336,37 @@ export default {
       'removeEmphasizedWidget',
       'setFocusedWidget'
     ]),
+    // Read the current resolved value of the global cascade variable
+    // `--apos-layout-gap` from `:root`. Used by `gridModuleOptions` to
+    // hand layout/focus modes a real gap value.
+    resolvedCascadeGap() {
+      if (!document?.documentElement) {
+        return undefined;
+      }
+      const value = window.getComputedStyle(document.documentElement)
+        .getPropertyValue('--apos-layout-gap')
+        .trim();
+      return value || undefined;
+    },
+    onWidgetLivePreview({ widgetId, data }) {
+      if (!widgetId || widgetId !== this.parentOptions?.widgetId) {
+        return;
+      }
+      this.liveWidgetData = data;
+    },
+    onWidgetLivePreviewEnd({ widgetId, reason }) {
+      if (!widgetId || widgetId !== this.parentOptions?.widgetId) {
+        return;
+      }
+      // On `save` keep the live snapshot in place: clearing
+      // here would expose the old `parent.gap` value for one frame.
+      // On `cancel` / `unmount` drop the live value immediately so the
+      // editor falls back to the SSR-rendered parent options.
+      if (reason === 'save') {
+        return;
+      }
+      this.liveWidgetData = null;
+    },
     clickOnGrid() {
       if (this.parentOptions.widgetId) {
         this.setFocusedWidget(this.parentOptions.widgetId, this.areaId);
diff --git a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridLayout.vue b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridLayout.vue
index 513b052e5a..94ed25c8f8 100644
--- a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridLayout.vue
+++ b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridLayout.vue
@@ -16,7 +16,7 @@
       data-mobile-auto="true"
       :style="{
         '--grid-columns': gridState.columns,
-        '--grid-gap': gridState.options.gap || '0',
+        '--grid-gap': gridState.options.gap ?? null,
         '--grid-rows': 'auto',
         '--mobile-grid-rows': 'auto',
         '--tablet-grid-rows': 'auto',
@@ -310,7 +310,7 @@ export default {
   display: grid;
   grid-template-columns: repeat(var(--grid-columns, 12), 1fr);
   grid-template-rows: repeat(var(--grid-rows), auto);
-  grid-gap: var(--grid-gap, 0);
+  gap: var(--grid-gap, var(--apos-layout-gap, 0));
   justify-items: var(--justify-items);
   /* stylelint-disable-next-line declaration-block-no-redundant-longhand-properties */
   align-items: var(--align-items);
diff --git a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridManager.vue b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridManager.vue
index bbe6c23824..e776b9aab8 100644
--- a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridManager.vue
+++ b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridManager.vue
@@ -5,7 +5,7 @@
     data-apos-test="aposLayoutContainerClone"
     :style="{
       '--grid-columns': gridState.columns,
-      '--grid-gap': gridState.options.gap,
+      '--grid-gap': gridState.options.gap ?? null,
     }"
     @mousemove="onMouseMove($event)"
   >
@@ -938,7 +938,7 @@ $resize-ui-z-index: 2;
     inset: 0;
     grid-template-columns: repeat(var(--grid-columns, 12), 1fr);
     grid-template-rows: repeat(var(--grid-rows), auto);
-    grid-gap: var(--grid-gap, 0);
+    gap: var(--grid-gap, var(--apos-layout-gap, 0));
 
     &.is-moving,
     &.is-resizing {
diff --git a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/layout.css b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/layout.css
index 3861e290a4..905d2bd649 100644
--- a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/layout.css
+++ b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/layout.css
@@ -1,3 +1,11 @@
+/*
+  Reserve the same vertical footprint for the SSR markup. 
+  This stylesheet is only injected on the apos scene in edit mode.
+*/
+.layout-widget > div {
+  min-height: 150px;
+}
+
 /* Tablet rules for admin interface */
 /* stylelint-disable-next-line media-feature-name-allowed-list */
 @media screen and (min-width: {$mobile-plus}px) and (max-width: {$tablet}px) {
diff --git a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/src/layout.css b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/src/layout.css
index 1eaa71057b..a4ca78aa52 100644
--- a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/src/layout.css
+++ b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/src/layout.css
@@ -2,7 +2,7 @@
   display: grid;
   grid-template-columns: repeat(var(--grid-columns, 12), 1fr);
   grid-template-rows: repeat(var(--grid-rows), auto);
-  grid-gap: var(--grid-gap, 0);
+  gap: var(--grid-gap, var(--apos-layout-gap, {$gap-default}));
   justify-items: var(--justify-items);
   /* stylelint-disable-next-line declaration-block-no-redundant-longhand-properties */
   align-items: var(--align-items);
diff --git a/packages/apostrophe/modules/@apostrophecms/layout-widget/views/widget.html b/packages/apostrophe/modules/@apostrophecms/layout-widget/views/widget.html
index 13a1ddac62..13dcd00337 100644
--- a/packages/apostrophe/modules/@apostrophecms/layout-widget/views/widget.html
+++ b/packages/apostrophe/modules/@apostrophecms/layout-widget/views/widget.html
@@ -1,13 +1,13 @@
 {% area data.widget, 'columns' with { 
   aposStyle: '--grid-columns: ' + (data.options.columns or data.manager.options.columns) + ';' + 
-    ' --grid-gap: ' + (data.options.gap or data.manager.options.gap or '0') + ';' + 
+    apos.modules[data.manager.__meta.name].gapInlineCss(data.widget, data.options, data.global) + 
     ' --grid-rows: auto;' + 
     ' --mobile-grid-rows: auto;' +
     ' --tablet-grid-rows: auto;' + 
     ' --justify-items: ' + (data.options.defaultCellHorizontalAlignment or data.manager.options.defaultCellHorizontalAlignment or 'stretch') + ';' +
     ' --align-items: ' + (data.options.defaultCellVerticalAlignment or data.manager.options.defaultCellVerticalAlignment or 'stretch') + ';', 
-  aposClassName: 'layout-widget',
-  aposParentOptions: data.options | merge({ widgetId: data.widget._id }),
+  aposClassName: ('layout-widget' + ((' ' + (data.options.className or data.manager.options.className)) if (data.options.className or data.manager.options.className))),
+  aposParentOptions: apos.modules[data.manager.__meta.name].parentOptionsForArea(data.widget, data.options, data.global),
   aposAttrs: {
     'tablet-auto': true,
     'mobile-auto': true
diff --git a/packages/apostrophe/modules/@apostrophecms/styles/index.js b/packages/apostrophe/modules/@apostrophecms/styles/index.js
index 6b77689e3c..800d6058f2 100644
--- a/packages/apostrophe/modules/@apostrophecms/styles/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/styles/index.js
@@ -87,6 +87,22 @@ module.exports = {
     self.prependNodes('body', 'stylesheet');
     self.prependNodes('body', 'ui');
 
+    // Detect the layout gap field (carries `layoutGapDefault: true`,
+    // see the `layoutGap` preset). If present, layout-widget will use its
+    // value as the site-wide layout gap. Only one such field is allowed —
+    // the first match wins; subsequent ones are ignored with a warning.
+    const layoutGapFieldNames = self.fieldsWithMarker(
+      self.schema, 'layoutGapDefault'
+    );
+    if (layoutGapFieldNames.length > 1) {
+      self.apos.util.warn(
+        '[@apostrophecms/styles] Multiple fields are marked with ' +
+        `\`layoutGapDefault: true\` (${layoutGapFieldNames.join(', ')}). ` +
+        'Only the first one will be used.'
+      );
+    }
+    self.layoutGapFieldName = layoutGapFieldNames[0] || null;
+
     // Detect if any top-level style field uses a background preset
     // (which includes image relationships requiring attachment annotation).
     // A hack until we analyze the relationship/attachment racing
diff --git a/packages/apostrophe/modules/@apostrophecms/styles/lib/handlers.js b/packages/apostrophe/modules/@apostrophecms/styles/lib/handlers.js
index 3007d433d5..046c1a7ad2 100644
--- a/packages/apostrophe/modules/@apostrophecms/styles/lib/handlers.js
+++ b/packages/apostrophe/modules/@apostrophecms/styles/lib/handlers.js
@@ -34,6 +34,12 @@ node app @apostrophecms-pro/palette:migrate-to-styles
           stylesClasses: classes,
           stylesStylesheetVersion: createId()
         };
+        if (self.layoutGapFieldName) {
+          const value = self.apos.util.get(doc, self.layoutGapFieldName);
+          $set.aposLayoutGap = (value === null || value === undefined || value === '')
+            ? null
+            : value;
+        }
         return self.apos.doc.db.updateOne({
           type: '@apostrophecms/global',
           aposLocale: doc.aposLocale
diff --git a/packages/apostrophe/modules/@apostrophecms/styles/lib/methods.js b/packages/apostrophe/modules/@apostrophecms/styles/lib/methods.js
index d641c39f08..c04140ef8e 100644
--- a/packages/apostrophe/modules/@apostrophecms/styles/lib/methods.js
+++ b/packages/apostrophe/modules/@apostrophecms/styles/lib/methods.js
@@ -353,6 +353,99 @@ module.exports = (self, options) => {
         throw new Error('Preset must be an object with a "type" property.');
       }
     },
+    // Walk an expanded styles schema (array of fields) and return the
+    // names of fields that emit the given CSS `property`. Recurses into
+    // object fields. Returns [] when no schema is provided.
+    // The field names are dot notation paths.
+    fieldsWithProperty(schema, property) {
+      if (!Array.isArray(schema) || !property) {
+        return [];
+      }
+      const matches = [];
+      for (const field of schema) {
+        const props = Array.isArray(field.property)
+          ? field.property
+          : (field.property ? [ field.property ] : []);
+        if (props.includes(property)) {
+          matches.push(field.name);
+        }
+        if (Array.isArray(field.schema) && field.schema.length) {
+          for (const sub of field.schema) {
+            const subProps = Array.isArray(sub.property)
+              ? sub.property
+              : (sub.property ? [ sub.property ] : []);
+            if (subProps.includes(property)) {
+              matches.push(`${field.name}.${sub.name}`);
+            }
+          }
+        }
+      }
+      return matches;
+    },
+    // Resolve a (possibly dotted) field path against an expanded styles
+    // schema and return the corresponding field definition, or null if
+    // not found. Supports one level of nesting through `object` fields,
+    // matching what `fieldsWithProperty` enumerates.
+    getFieldByPath(schema, path) {
+      if (!Array.isArray(schema) || !path) {
+        return null;
+      }
+      const segments = String(path).split('.');
+      let current = schema;
+      let field = null;
+      for (const segment of segments) {
+        if (!Array.isArray(current)) {
+          return null;
+        }
+        field = current.find(f => f.name === segment) || null;
+        if (!field) {
+          return null;
+        }
+        current = field.schema || [];
+      }
+      return field;
+    },
+    // Walk an expanded styles schema (array of fields) and return the
+    // names of fields carrying a given marker property set to `true`.
+    // Recurses into object fields (returns dotted paths for nested
+    // matches), matching the recursion shape of `fieldsWithProperty`.
+    fieldsWithMarker(schema, markerName) {
+      if (!Array.isArray(schema) || !markerName) {
+        return [];
+      }
+      const matches = [];
+      for (const field of schema) {
+        if (field[markerName] === true) {
+          matches.push(field.name);
+        }
+        if (Array.isArray(field.schema) && field.schema.length) {
+          for (const sub of field.schema) {
+            if (sub[markerName] === true) {
+              matches.push(`${field.name}.${sub.name}`);
+            }
+          }
+        }
+      }
+      return matches;
+    },
+    // Throw if any field in the given expanded schema is marked with
+    // `layoutGapDefault: true`. The `layoutGap` preset is reserved for
+    // @apostrophecms/styles schema.
+    rejectLayoutGapPresetOnSchema(schema, contextLabel) {
+      if (!Array.isArray(schema)) {
+        return;
+      }
+      const offenders = self.fieldsWithMarker(schema, 'layoutGapDefault');
+      if (offenders.length) {
+        throw new Error(
+          `${contextLabel}: the "layoutGap" preset (or a field carrying ` +
+          '`layoutGapDefault: true`) is reserved for the @apostrophecms/styles ' +
+          'module and cannot be used as a widget styles field. ' +
+          'Use a field with `property: "gap"` instead. ' +
+          `Offending field(s): ${offenders.join(', ')}.`
+        );
+      }
+    },
     addToAdminBar() {
       if (Object.keys(self.styles).length === 0) {
         return;
diff --git a/packages/apostrophe/modules/@apostrophecms/styles/lib/presets.js b/packages/apostrophe/modules/@apostrophecms/styles/lib/presets.js
index 558ba0bbb5..7dcd5f3799 100644
--- a/packages/apostrophe/modules/@apostrophecms/styles/lib/presets.js
+++ b/packages/apostrophe/modules/@apostrophecms/styles/lib/presets.js
@@ -298,6 +298,23 @@ module.exports = (moduleOptions) => {
           }
         }
       }
+    },
+    // Site-wide layout gap for @apostrophecms/layout-widget instances.
+    // Writes a CSS custom property at :root; meant to be added to the
+    // @apostrophecms/styles module only.
+    // Use on widget styles is rejected at boot.
+    layoutGap: {
+      label: 'apostrophe:styleLayoutGap',
+      help: 'apostrophe:styleLayoutGapHelp',
+      type: 'range',
+      min: 0,
+      max: 64,
+      def: 24,
+      unit: 'px',
+      property: '--apos-layout-gap',
+      selector: ':root',
+      // Marker used to identify the site-wide layout gap field.
+      layoutGapDefault: true
     }
   };
 };
diff --git a/packages/apostrophe/modules/@apostrophecms/styles/ui/apos/universal/render.mjs b/packages/apostrophe/modules/@apostrophecms/styles/ui/apos/universal/render.mjs
index 8439f6134a..ca42467ef5 100644
--- a/packages/apostrophe/modules/@apostrophecms/styles/ui/apos/universal/render.mjs
+++ b/packages/apostrophe/modules/@apostrophecms/styles/ui/apos/universal/render.mjs
@@ -369,7 +369,11 @@ function filter(field, doc) {
     return true;
   }
   if (!doc[field.name] && doc[field.name] !== 0) {
-    return false;
+    // Allow the field through when it declares a `def` so the
+    // normalizer can substitute the default.
+    if (field.def === null || field.def === undefined || field.def === '') {
+      return false;
+    }
   }
   if (field.customType) {
     return true;
@@ -437,6 +441,11 @@ function normalize(field, doc, {
   let selectors = [];
   let properties = [];
   let fieldValue = doc[field.name];
+  // Fall back to the field's declared `def` when the doc carries no
+  // value.
+  if (fieldValue === null || fieldValue === undefined) {
+    fieldValue = field.def;
+  }
   let canBeInline = true;
   const fieldUnit = field.unit || '';
   const fieldMediaQuery = field.mediaQuery || rootMediaQuery;
diff --git a/packages/apostrophe/modules/@apostrophecms/util/index.js b/packages/apostrophe/modules/@apostrophecms/util/index.js
index de5fbcb9ba..ab47fd0137 100644
--- a/packages/apostrophe/modules/@apostrophecms/util/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/util/index.js
@@ -743,6 +743,7 @@ module.exports = {
       // in addition if the first component begins with `@xyz` the
       // sub-object within `o` with an `_id` property equal to `xyz`.
       // is found and returned, no matter how deeply nested it is.
+      // Returns `undefined` if any intermediate segment is null or undefined.
       get(o, path) {
         let i;
         path = path.split('.');
@@ -751,6 +752,9 @@ module.exports = {
           if ((i === 0) && (p.charAt(0) === '@')) {
             o = self.apos.util.findNestedObjectById(o, p.substring(1));
           } else {
+            if (o == null) {
+              return undefined;
+            }
             o = o[p];
           }
         }
diff --git a/packages/apostrophe/modules/@apostrophecms/widget-type/index.js b/packages/apostrophe/modules/@apostrophecms/widget-type/index.js
index 3f05448a4e..53c1c1cd5b 100644
--- a/packages/apostrophe/modules/@apostrophecms/widget-type/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/widget-type/index.js
@@ -355,6 +355,12 @@ module.exports = {
           addFields: self.apos.schema.fieldsToArray(`Module ${self.__meta.name}`, self.fields),
           arrangeFields: self.apos.schema.groupsToArray(self.fieldsGroups)
         }, self);
+        // The `layoutGap` preset (and any field carrying
+        // `layoutGapDefault: true`) is reserved for global styles.
+        self.apos.styles.rejectLayoutGapPresetOnSchema(
+          self.schema,
+          `Widget "${self.name}"`
+        );
         const forbiddenFields = [
           '_id',
           'type'
diff --git a/packages/apostrophe/modules/@apostrophecms/widget-type/ui/apos/components/AposWidgetEditor.vue b/packages/apostrophe/modules/@apostrophecms/widget-type/ui/apos/components/AposWidgetEditor.vue
index 40827d3d62..076f001b8f 100644
--- a/packages/apostrophe/modules/@apostrophecms/widget-type/ui/apos/components/AposWidgetEditor.vue
+++ b/packages/apostrophe/modules/@apostrophecms/widget-type/ui/apos/components/AposWidgetEditor.vue
@@ -371,6 +371,9 @@ export default {
     this.areaDebounceUpdate.cancel?.();
     apos.area.widgetOptions = apos.area.widgetOptions.slice(1);
     this.stopWatchingWindowSize();
+    // Publish-side cleanup: tell live-preview consumers we're gone.
+    // Safe broadcast — consumers self-gate on widget id.
+    this.emitLivePreviewEnd('unmount');
   },
   created() {
     const defaults = this.getDefault();
@@ -561,6 +564,17 @@ export default {
           subset: this.moduleOptions.stylesFields
         });
         this.applyPreviewStyles(styles);
+        // Publish the live snapshot on the apos bus so consumers
+        // can react in real time.
+        // Gated by the widget module's `subscribesToLivePreview` browser-data
+        // flag so the bus stays quiet for widgets that don't subscribe.
+        if (this.moduleOptions.subscribesToLivePreview) {
+          apos.bus.$emit('apos-widget-live-preview', {
+            widgetId: this.getPreviewWidgetId(),
+            type: this.type,
+            data: value.data
+          });
+        }
 
         return;
       }
@@ -574,6 +588,7 @@ export default {
       }
     },
     removePreview() {
+      this.emitLivePreviewEnd(this.saving ? 'save' : 'cancel');
       if (!this.preview) {
         return;
       }
@@ -589,6 +604,20 @@ export default {
         });
       }
     },
+    emitLivePreviewEnd(reason) {
+      if (!this.moduleOptions.subscribesToLivePreview) {
+        return;
+      }
+      const widgetId = this.getPreviewWidgetId();
+      if (!widgetId) {
+        return;
+      }
+      apos.bus.$emit('apos-widget-live-preview-end', {
+        widgetId,
+        type: this.type,
+        reason
+      });
+    },
     applyPreviewStyles({
       inline = '', css = '', classes = []
     }) {
@@ -715,6 +744,9 @@ export default {
       };
     },
     getPreviewWidgetId() {
+      if (!this.preview) {
+        return null;
+      }
       if (!this.previewWidgetId) {
         if (this.preview.create) {
           // Deliberately different from the final widget's id, which will
diff --git a/packages/apostrophe/test/layout-widget-gap.js b/packages/apostrophe/test/layout-widget-gap.js
new file mode 100644
index 0000000000..590fcf1db7
--- /dev/null
+++ b/packages/apostrophe/test/layout-widget-gap.js
@@ -0,0 +1,530 @@
+const t = require('../test-lib/test.js');
+const assert = require('node:assert/strict');
+
+describe('Layout Widget — gap via styles', function () {
+  this.timeout(t.timeout);
+
+  describe('Styles helpers (server)', function () {
+    let apos;
+
+    before(async function () {
+      apos = await t.create({
+        root: module,
+        modules: {
+          '@apostrophecms/styles': {}
+        }
+      });
+    });
+
+    after(async function () {
+      return t.destroy(apos);
+    });
+
+    it('exposes the layoutGap preset with the layoutGapDefault marker', function () {
+      const preset = apos.styles.getPreset('layoutGap');
+      assert.ok(preset, 'layoutGap preset should be registered');
+      assert.equal(preset.type, 'range');
+      assert.equal(preset.min, 0);
+      assert.equal(preset.max, 64);
+      assert.equal(preset.def, 24);
+      assert.equal(preset.unit, 'px');
+      assert.equal(preset.property, '--apos-layout-gap');
+      assert.equal(preset.selector, ':root');
+      assert.equal(preset.layoutGapDefault, true);
+    });
+
+    it('fieldsWithProperty enumerates fields by CSS property (incl. nested)', function () {
+      const schema = [
+        {
+          name: 'gap',
+          type: 'range',
+          property: 'gap'
+        },
+        {
+          name: 'wrap',
+          type: 'object',
+          schema: [
+            {
+              name: 'innerGap',
+              type: 'range',
+              property: 'gap'
+            },
+            {
+              name: 'color',
+              type: 'color',
+              property: 'background-color'
+            }
+          ]
+        }
+      ];
+      assert.deepEqual(
+        apos.styles.fieldsWithProperty(schema, 'gap'),
+        [ 'gap', 'wrap.innerGap' ]
+      );
+      assert.deepEqual(
+        apos.styles.fieldsWithProperty(schema, 'background-color'),
+        [ 'wrap.color' ]
+      );
+      assert.deepEqual(apos.styles.fieldsWithProperty([], 'gap'), []);
+      assert.deepEqual(apos.styles.fieldsWithProperty(null, 'gap'), []);
+    });
+
+    it('getFieldByPath resolves top-level and nested (dotted) paths', function () {
+      const innerGap = {
+        name: 'innerGap',
+        type: 'range',
+        property: 'gap',
+        unit: 'px'
+      };
+      const wrap = {
+        name: 'wrap',
+        type: 'object',
+        schema: [ innerGap ]
+      };
+      const gap = {
+        name: 'gap',
+        type: 'range',
+        property: 'gap'
+      };
+      const schema = [ gap, wrap ];
+
+      assert.equal(apos.styles.getFieldByPath(schema, 'gap'), gap);
+      assert.equal(apos.styles.getFieldByPath(schema, 'wrap'), wrap);
+      assert.equal(apos.styles.getFieldByPath(schema, 'wrap.innerGap'), innerGap);
+      // Missing segments
+      assert.equal(apos.styles.getFieldByPath(schema, 'nope'), null);
+      assert.equal(apos.styles.getFieldByPath(schema, 'wrap.nope'), null);
+      // Walking into a leaf (no `.schema`) must not throw
+      assert.equal(apos.styles.getFieldByPath(schema, 'gap.foo'), null);
+      // Invalid inputs
+      assert.equal(apos.styles.getFieldByPath(null, 'gap'), null);
+      assert.equal(apos.styles.getFieldByPath(schema, ''), null);
+    });
+
+    it('fieldsWithMarker returns names of fields carrying a true marker', function () {
+      const schema = [
+        {
+          name: 'a',
+          layoutGapDefault: true
+        },
+        { name: 'b' },
+        {
+          name: 'c',
+          layoutGapDefault: false
+        },
+        {
+          name: 'wrap',
+          type: 'object',
+          schema: [
+            {
+              name: 'inner',
+              layoutGapDefault: true
+            },
+            {
+              name: 'other',
+              layoutGapDefault: false
+            }
+          ]
+        }
+      ];
+      assert.deepEqual(
+        apos.styles.fieldsWithMarker(schema, 'layoutGapDefault'),
+        [ 'a', 'wrap.inner' ]
+      );
+      assert.deepEqual(apos.styles.fieldsWithMarker([], 'x'), []);
+    });
+
+    it('rejectLayoutGapPresetOnSchema throws on offending fields', function () {
+      assert.throws(
+        () => apos.styles.rejectLayoutGapPresetOnSchema(
+          [ {
+            name: 'siteGap',
+            layoutGapDefault: true
+          } ],
+          'test-widget'
+        ),
+        /layoutGap/
+      );
+      // Throws when the marker lives on a nested object subfield
+      assert.throws(
+        () => apos.styles.rejectLayoutGapPresetOnSchema(
+          [ {
+            name: 'wrap',
+            type: 'object',
+            schema: [ {
+              name: 'siteGap',
+              layoutGapDefault: true
+            } ]
+          } ],
+          'test-widget'
+        ),
+        /layoutGap/
+      );
+      // Must not throw on a clean schema
+      apos.styles.rejectLayoutGapPresetOnSchema(
+        [ {
+          name: 'gap',
+          property: 'gap'
+        } ],
+        'test-widget'
+      );
+    });
+  });
+
+  describe('Widget schema validation', function () {
+    let apos;
+
+    before(async function () {
+      apos = await t.create({
+        root: module,
+        modules: {
+          '@apostrophecms/styles': {}
+        }
+      });
+    });
+
+    after(async function () {
+      return t.destroy(apos);
+    });
+
+    it('expandStyles + rejectLayoutGapPresetOnSchema blocks the layoutGap preset on widget configs', function () {
+      const expanded = apos.styles.expandStyles({ siteGap: 'layoutGap' });
+      const schema = Object.entries(expanded).map(([ name, field ]) => ({
+        name,
+        ...field
+      }));
+      assert.throws(
+        () => apos.styles.rejectLayoutGapPresetOnSchema(schema, 'Widget "x"'),
+        /layoutGap/
+      );
+    });
+  });
+
+  describe('Layout-widget detection & resolution', function () {
+    let apos;
+
+    before(async function () {
+      apos = await t.create({
+        root: module,
+        modules: {
+          '@apostrophecms/styles': {
+            styles: {
+              add: {
+                siteGap: 'layoutGap'
+              }
+            }
+          },
+          '@apostrophecms/layout-widget': {
+            styles: {
+              add: {
+                gap: {
+                  label: 'Gap',
+                  type: 'range',
+                  min: 0,
+                  max: 64,
+                  unit: 'px',
+                  property: 'gap'
+                }
+              }
+            }
+          }
+        }
+      });
+    });
+
+    after(async function () {
+      return t.destroy(apos);
+    });
+
+    it('detects the styles layoutGap field name', function () {
+      assert.equal(apos.styles.layoutGapFieldName, 'siteGap');
+    });
+
+    it('detects the widget gap field name and global enabled flag', function () {
+      const lw = apos.modules['@apostrophecms/layout-widget'];
+      assert.equal(lw.widgetGapFieldName, 'gap');
+      assert.equal(lw.globalGapEnabled, true);
+    });
+
+    it('resolveWidgetGap returns null when widget value is absent', function () {
+      const lw = apos.modules['@apostrophecms/layout-widget'];
+      assert.equal(lw.resolveWidgetGap({}), null);
+      assert.equal(lw.resolveWidgetGap({ gap: null }), null);
+      assert.equal(lw.resolveWidgetGap({ gap: '' }), null);
+    });
+
+    it('resolveWidgetGap appends the field unit to numeric values', function () {
+      const lw = apos.modules['@apostrophecms/layout-widget'];
+      assert.equal(lw.resolveWidgetGap({ gap: 16 }), '16px');
+    });
+
+    it('shouldOmitInlineGap decision matrix', function () {
+      const lw = apos.modules['@apostrophecms/layout-widget'];
+      // Widget has its own gap → never omit
+      assert.equal(
+        lw.shouldOmitInlineGap({ gap: 8 }, { aposLayoutGap: 24 }),
+        false
+      );
+      // No widget gap, global enabled → omit (cascade resolves via
+      // :root --apos-layout-gap, falling through to the static
+      // options.gap default when no saved value).
+      assert.equal(
+        lw.shouldOmitInlineGap({}, { aposLayoutGap: 24 }),
+        true
+      );
+      assert.equal(
+        lw.shouldOmitInlineGap({}, { aposLayoutGap: null }),
+        true
+      );
+      assert.equal(lw.shouldOmitInlineGap({}, {}), true);
+      assert.equal(lw.shouldOmitInlineGap({}, null), true);
+    });
+
+    it('gapInlineCss prefers widget value, then omits when global enabled', function () {
+      const lw = apos.modules['@apostrophecms/layout-widget'];
+      const gapInlineCss = lw.__helpers.gapInlineCss;
+      // Widget value wins
+      assert.equal(
+        gapInlineCss({ gap: 12 }, { gap: '1rem' }, { aposLayoutGap: 24 }),
+        ' --grid-gap: 12px;'
+      );
+      // No widget value, global enabled → empty (cascade resolves
+      // through :root --apos-layout-gap or static options.gap default)
+      assert.equal(
+        gapInlineCss({}, { gap: '1rem' }, { aposLayoutGap: 24 }),
+        ''
+      );
+      assert.equal(
+        gapInlineCss({}, { gap: '1rem' }, { aposLayoutGap: null }),
+        ''
+      );
+      assert.equal(
+        gapInlineCss({}, {}, { aposLayoutGap: null }),
+        ''
+      );
+    });
+
+    it('annotateWidgetForExternalFront adds _gap and _gapHasGlobal', function () {
+      const lw = apos.modules['@apostrophecms/layout-widget'];
+      const out = lw.annotateWidgetForExternalFront(
+        {
+          _id: 'w1',
+          type: '@apostrophecms/layout',
+          gap: 18
+        },
+        {}
+      );
+      assert.equal(out._gap, '18px');
+      assert.equal(out._gapHasGlobal, true);
+    });
+
+    it('parentOptionsForArea passes resolved widget gap to the editor', function () {
+      const lw = apos.modules['@apostrophecms/layout-widget'];
+      const parentOptionsForArea = lw.__helpers.parentOptionsForArea;
+      // Widget value present → carries through as a string with unit
+      assert.deepEqual(
+        parentOptionsForArea(
+          {
+            _id: 'w1',
+            gap: 18
+          },
+          { columns: 12 },
+          { aposLayoutGap: 24 }
+        ),
+        {
+          columns: 12,
+          widgetId: 'w1',
+          gap: '18px'
+        }
+      );
+      // Widget value absent + global has value → gap: null (signal omit)
+      assert.deepEqual(
+        parentOptionsForArea(
+          { _id: 'w2' },
+          { columns: 12 },
+          { aposLayoutGap: 24 }
+        ),
+        {
+          columns: 12,
+          widgetId: 'w2',
+          gap: null
+        }
+      );
+      // Widget value absent + global enabled → gap: null (signal omit)
+      // regardless of whether the global has a saved value.
+      assert.deepEqual(
+        parentOptionsForArea(
+          { _id: 'w3' },
+          { columns: 12 },
+          { aposLayoutGap: null }
+        ),
+        {
+          columns: 12,
+          widgetId: 'w3',
+          gap: null
+        }
+      );
+    });
+  });
+
+  describe('Layout-widget without global gap configured', function () {
+    let apos;
+
+    before(async function () {
+      apos = await t.create({
+        root: module,
+        modules: {
+          '@apostrophecms/styles': {},
+          '@apostrophecms/layout-widget': {}
+        }
+      });
+    });
+
+    after(async function () {
+      return t.destroy(apos);
+    });
+
+    it('globalGapEnabled is false when no layoutGap field configured', function () {
+      const lw = apos.modules['@apostrophecms/layout-widget'];
+      assert.equal(lw.globalGapEnabled, false);
+      assert.equal(lw.widgetGapFieldName, null);
+    });
+
+    it('gapInlineCss falls back to BC value', function () {
+      const lw = apos.modules['@apostrophecms/layout-widget'];
+      assert.equal(
+        lw.__helpers.gapInlineCss({}, { gap: '1.5rem' }, {}),
+        ' --grid-gap: 1.5rem;'
+      );
+    });
+  });
+
+  describe('Layout-widget with nested (dotted) gap field', function () {
+    let apos;
+
+    before(async function () {
+      apos = await t.create({
+        root: module,
+        modules: {
+          '@apostrophecms/styles': {},
+          '@apostrophecms/layout-widget': {
+            styles: {
+              add: {
+                gap: {
+                  label: 'Gap',
+                  type: 'range',
+                  min: 0,
+                  max: 64,
+                  unit: 'px',
+                  property: 'gap'
+                }
+              }
+            }
+          }
+        }
+      });
+    });
+
+    after(async function () {
+      return t.destroy(apos);
+    });
+
+    it('resolveWidgetGap reads from a dotted widgetGapFieldName via apos.util.get', function () {
+      const lw = apos.modules['@apostrophecms/layout-widget'];
+      const original = lw.widgetGapFieldName;
+      const originalSchema = lw.schema;
+      // Simulate detection of a nested gap field at `spacing.inner`.
+      lw.widgetGapFieldName = 'spacing.inner';
+      lw.schema = [ {
+        name: 'spacing',
+        type: 'object',
+        schema: [ {
+          name: 'inner',
+          type: 'range',
+          property: 'gap',
+          unit: 'rem'
+        } ]
+      } ];
+      try {
+        assert.equal(
+          lw.resolveWidgetGap({ spacing: { inner: 2 } }),
+          '2rem'
+        );
+        assert.equal(
+          lw.resolveWidgetGap({ spacing: { inner: '3rem' } }),
+          '3rem'
+        );
+        assert.equal(lw.resolveWidgetGap({ spacing: {} }), null);
+        assert.equal(lw.resolveWidgetGap({}), null);
+      } finally {
+        lw.widgetGapFieldName = original;
+        lw.schema = originalSchema;
+      }
+    });
+  });
+
+  describe('Layout-widget with widget gap field declaring `def`', function () {
+    let apos;
+
+    before(async function () {
+      apos = await t.create({
+        root: module,
+        modules: {
+          '@apostrophecms/styles': {},
+          '@apostrophecms/layout-widget': {
+            styles: {
+              add: {
+                gap: {
+                  label: 'Gap',
+                  type: 'range',
+                  min: 0,
+                  max: 64,
+                  def: 24,
+                  unit: 'px',
+                  property: 'gap'
+                }
+              }
+            }
+          }
+        }
+      });
+    });
+
+    after(async function () {
+      return t.destroy(apos);
+    });
+
+    it('resolveWidgetGap falls back to field.def when widget value is absent', function () {
+      const lw = apos.modules['@apostrophecms/layout-widget'];
+      assert.equal(lw.resolveWidgetGap({}), '24px');
+      assert.equal(lw.resolveWidgetGap({ gap: null }), '24px');
+      assert.equal(lw.resolveWidgetGap({ gap: '' }), '24px');
+      // Explicit value still wins.
+      assert.equal(lw.resolveWidgetGap({ gap: 8 }), '8px');
+    });
+
+    it('gapInlineCss emits the def value (no global cascade in play)', function () {
+      const lw = apos.modules['@apostrophecms/layout-widget'];
+      assert.equal(
+        lw.__helpers.gapInlineCss({}, { gap: '1.5rem' }, {}),
+        ' --grid-gap: 24px;'
+      );
+    });
+
+    it('parentOptionsForArea passes the def value to the editor', function () {
+      const lw = apos.modules['@apostrophecms/layout-widget'];
+      assert.deepEqual(
+        lw.__helpers.parentOptionsForArea(
+          { _id: 'w1' },
+          { columns: 12 },
+          {}
+        ),
+        {
+          columns: 12,
+          widgetId: 'w1',
+          gap: '24px'
+        }
+      );
+    });
+  });
+});
diff --git a/packages/apostrophe/test/styles.js b/packages/apostrophe/test/styles.js
index 2121b4a468..15b87856cb 100644
--- a/packages/apostrophe/test/styles.js
+++ b/packages/apostrophe/test/styles.js
@@ -1102,6 +1102,56 @@ describe('Styles', function () {
       );
     });
 
+    it('should fall back to field.def when the doc has no value', async function () {
+      const { renderGlobalStyles, renderScopedStyles } = await universal;
+
+      const schema = [
+        {
+          name: 'gap',
+          type: 'range',
+          selector: ':root',
+          property: '--apos-layout-gap',
+          unit: 'px',
+          def: 24
+        },
+        {
+          name: 'noDef',
+          type: 'range',
+          selector: ':root',
+          property: '--no-def',
+          unit: 'px'
+        }
+      ];
+
+      // Doc carries no `gap` value (e.g. field added after doc was
+      // created). The field's `def` is used.
+      const fromDef = renderGlobalStyles(schema, {});
+      assert.ok(
+        fromDef.css.includes('--apos-layout-gap: 24px'),
+        'renderGlobalStyles should emit field.def when doc value is absent'
+      );
+      assert.ok(
+        !fromDef.css.includes('--no-def'),
+        'fields without def should still be skipped'
+      );
+
+      // Saved value overrides def.
+      const fromDoc = renderGlobalStyles(schema, { gap: 12 });
+      assert.ok(
+        fromDoc.css.includes('--apos-layout-gap: 12px'),
+        'doc value should override field.def'
+      );
+
+      // Scoped renderer behaves the same way.
+      const scoped = renderScopedStyles(schema, {}, {
+        rootSelector: '#id'
+      });
+      assert.ok(
+        scoped.css.includes('--apos-layout-gap: 24px'),
+        'renderScopedStyles should emit field.def when doc value is absent'
+      );
+    });
+
     it('should include imageSizes in attachment getBrowserData', function () {
       const browserData = apos.attachment.getBrowserData(apos.task.getReq());
       assert.ok(

From 2e2f3b4b46301fc81c46200f837e794b247a9aef Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Thu, 7 May 2026 23:50:21 +0300
Subject: [PATCH 17/56] a11y fixes (#5401)

---
 .changeset/a11y-admin-nav.md                  |  5 +++
 .changeset/a11y-context-title.md              |  5 +++
 .changeset/a11y-locale-switcher.md            |  5 +++
 .changeset/a11y-recently-edited-icon.md       |  5 +++
 .changeset/a11y-sr-only.md                    |  5 +++
 .changeset/a11y-tray-aria.md                  |  5 +++
 .../ui/apos/components/TheAposAdminBar.vue    |  1 -
 .../apos/components/TheAposAdminBarMenu.vue   | 33 +++++++++++++-----
 .../TheAposContextBreakpointPreviewMode.vue   |  9 +++++
 .../apos/components/TheAposContextTitle.vue   |  9 +++++
 .../modules/@apostrophecms/i18n/i18n/en.json  |  6 ++++
 .../components/AposRecentlyEditedIcon.vue     |  2 ++
 .../components/AposSubmittedDraftIcon.vue     |  1 +
 .../ui/ui/apos/components/AposButton.vue      | 16 +++++++--
 .../ui/ui/apos/components/AposContextMenu.vue | 34 ++++++++++++++++---
 .../apos/components/AposContextMenuDialog.vue |  8 +++++
 .../apos/components/AposContextMenuItem.vue   |  7 ++--
 .../ui/apos/components/AposLocalePicker.vue   | 15 +++++++-
 .../ui/ui/apos/scss/global/_utilities.scss    | 14 +++++++-
 19 files changed, 165 insertions(+), 20 deletions(-)
 create mode 100644 .changeset/a11y-admin-nav.md
 create mode 100644 .changeset/a11y-context-title.md
 create mode 100644 .changeset/a11y-locale-switcher.md
 create mode 100644 .changeset/a11y-recently-edited-icon.md
 create mode 100644 .changeset/a11y-sr-only.md
 create mode 100644 .changeset/a11y-tray-aria.md

diff --git a/.changeset/a11y-admin-nav.md b/.changeset/a11y-admin-nav.md
new file mode 100644
index 0000000000..e6025193a8
--- /dev/null
+++ b/.changeset/a11y-admin-nav.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": patch
+---
+
+Accessibility: corrected ARIA semantics on the top admin navigation bar. 
diff --git a/.changeset/a11y-context-title.md b/.changeset/a11y-context-title.md
new file mode 100644
index 0000000000..344cf6fa7b
--- /dev/null
+++ b/.changeset/a11y-context-title.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": patch
+---
+
+Accessibility: improvements to the document context title (admin bar middle group) and the underlying `AposContextMenu` machinery.
diff --git a/.changeset/a11y-locale-switcher.md b/.changeset/a11y-locale-switcher.md
new file mode 100644
index 0000000000..ec687d8c7d
--- /dev/null
+++ b/.changeset/a11y-locale-switcher.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": patch
+---
+
+Accessibility: improve the locale switcher (`AposLocalePicker`).
diff --git a/.changeset/a11y-recently-edited-icon.md b/.changeset/a11y-recently-edited-icon.md
new file mode 100644
index 0000000000..8c6a04567c
--- /dev/null
+++ b/.changeset/a11y-recently-edited-icon.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": patch
+---
+
+Accessibility: the Recently Edited Documents tray icon (admin bar) now exposes its action through `aria-label`.
diff --git a/.changeset/a11y-sr-only.md b/.changeset/a11y-sr-only.md
new file mode 100644
index 0000000000..193a4cf5ec
--- /dev/null
+++ b/.changeset/a11y-sr-only.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": patch
+---
+
+Accessibility: fix `.apos-sr-only` so screen-reader-only content is exposed to the accessibility tree.
diff --git a/.changeset/a11y-tray-aria.md b/.changeset/a11y-tray-aria.md
new file mode 100644
index 0000000000..4f39003b28
--- /dev/null
+++ b/.changeset/a11y-tray-aria.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": patch
+---
+
+Accessibility: icon-only context-utility buttons in the admin bar tray (e.g. the global settings cog) now expose their action through `aria-label`.
diff --git a/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposAdminBar.vue b/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposAdminBar.vue
index c5b81e01de..a70a0b2484 100644
--- a/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposAdminBar.vue
+++ b/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposAdminBar.vue
@@ -11,7 +11,6 @@
     <nav
       ref="adminBar"
       :class="classes"
-      role="menubar"
       aria-label="Apostrophe Admin Bar"
     >
       <div class="apos-admin-bar__row">
diff --git a/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposAdminBarMenu.vue b/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposAdminBarMenu.vue
index df69d168ad..6eb17ab954 100644
--- a/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposAdminBarMenu.vue
+++ b/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposAdminBarMenu.vue
@@ -1,8 +1,5 @@
 <template>
-  <ol
-    class="apos-admin-bar__items"
-    role="menu"
-  >
+  <ol class="apos-admin-bar__items">
     <li
       v-if="pageTree"
       class="apos-admin-bar__item"
@@ -12,7 +9,6 @@
         label="apostrophe:pages"
         class="apos-admin-bar__btn"
         :modifiers="['no-motion']"
-        role="menuitem"
         action-test-label="page-manager-button"
         @click="emitEvent({ action: '@apostrophecms/page:manager' })"
       />
@@ -33,7 +29,6 @@
           class: 'apos-admin-bar__btn',
           type: 'subtle'
         }"
-        role="menuitem"
         @item-clicked="emitEvent"
       />
       <Component
@@ -44,7 +39,6 @@
         :modifiers="['no-motion']"
         class="apos-admin-bar__btn"
         :action-test-label="`${item.name}-manager-button`"
-        role="menuitem"
         @click="emitEvent(item)"
       />
     </li>
@@ -62,7 +56,6 @@
           type: 'primary',
           modifiers: ['round', 'no-motion']
         }"
-        role="menuitem"
         @item-clicked="emitEvent"
       />
     </li>
@@ -89,6 +82,7 @@
           :label="item.label"
           :action="item.action"
           :state="trayItemState[item.name] ? [ 'active' ] : []"
+          :attrs="trayItemAttrs(item)"
           @click="emitEvent(item)"
         />
       </template>
@@ -185,6 +179,29 @@ export default {
       } else {
         return item.options.tooltip;
       }
+    },
+    // Tray utility buttons render icon-only, so the visible label
+    // (e.g. "Global Content") is sr-only and doesn't describe what the
+    // button does. Make them accessible by providing an aria-label based on
+    // the tooltip content.
+    trayItemAttrs(item) {
+      const tooltip = item.options?.tooltip;
+      let key = null;
+      if (item.options?.toggle) {
+        if (this.trayItemState[item.name] && tooltip?.deactivate) {
+          key = tooltip.deactivate;
+        } else if (tooltip?.activate) {
+          key = tooltip.activate;
+        }
+      } else if (typeof tooltip === 'string') {
+        key = tooltip;
+      } else if (tooltip && typeof tooltip.content === 'string') {
+        key = tooltip.content;
+      }
+      if (!key) {
+        return {};
+      }
+      return { 'aria-label': this.$t(key) };
     }
   }
 };
diff --git a/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposContextBreakpointPreviewMode.vue b/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposContextBreakpointPreviewMode.vue
index 2087d12719..66c6baea79 100644
--- a/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposContextBreakpointPreviewMode.vue
+++ b/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposContextBreakpointPreviewMode.vue
@@ -14,6 +14,7 @@
         :label="screen.label"
         :tooltip="$t(screen.label)"
         :title="$t(screen.label)"
+        :attrs="shortcutAttrs(screen)"
         :icon="screen.icon"
         :icon-only="true"
         type="subtle"
@@ -36,6 +37,7 @@
       :active-item="mode"
       :center-on-icon="true"
       menu-placement="bottom-end"
+      :dialog-label="'apostrophe:breakpointPreviewSelectMenu'"
       @item-clicked="selectBreakpoint"
     />
     <Transition>
@@ -320,6 +322,13 @@ export default {
     },
     setShowDropdown() {
       this.showDropdown = Object.values(this.screens).some(({ shortcut }) => !shortcut);
+    },
+    shortcutAttrs(screen) {
+      return {
+        'aria-label': this.$t('apostrophe:breakpointPreviewShortcut', {
+          breakpoint: this.$t(screen.label)
+        })
+      };
     }
   }
 };
diff --git a/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposContextTitle.vue b/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposContextTitle.vue
index 5d96775758..d020d02705 100644
--- a/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposContextTitle.vue
+++ b/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposContextTitle.vue
@@ -33,6 +33,8 @@
           :disabled="hasCustomUi || isUnpublished"
           :center-on-icon="true"
           menu-placement="bottom-end"
+          :dialog-label="'apostrophe:publicationStatusMenu'"
+          :trigger-aria-label="draftTriggerAriaLabel"
           @item-clicked="switchDraftMode"
         />
         <AposLabel
@@ -91,6 +93,13 @@ export default {
         type: 'quiet'
       };
     },
+    draftTriggerAriaLabel() {
+      return this.$t('apostrophe:publicationStatusTrigger', {
+        status: this.$t(
+          this.draftMode === 'draft' ? 'apostrophe:draft' : 'apostrophe:published'
+        )
+      });
+    },
     isUnpublished() {
       return !this.context.lastPublishedAt;
     },
diff --git a/packages/apostrophe/modules/@apostrophecms/i18n/i18n/en.json b/packages/apostrophe/modules/@apostrophecms/i18n/i18n/en.json
index e6b5ed913d..0adcf393d2 100644
--- a/packages/apostrophe/modules/@apostrophecms/i18n/i18n/en.json
+++ b/packages/apostrophe/modules/@apostrophecms/i18n/i18n/en.json
@@ -89,6 +89,8 @@
   "breakpointPreviewExit": "Exit",
   "breakpointPreviewMobile": "Mobile",
   "breakpointPreviewSelect": "Select Breakpoint",
+  "breakpointPreviewSelectMenu": "Breakpoint preview menu",
+  "breakpointPreviewShortcut": "Preview at {{ breakpoint }} breakpoint",
   "breakpointPreviewTablet": "Tablet",
   "browse": "Browse",
   "browseDocType": "Browse {{ type }}",
@@ -387,6 +389,7 @@
   "mediaUploadViaDrop": "Drop ’em when you’re ready",
   "mediaUploadViaExplorer": "Or click to open the file explorer",
   "mergeCells": "Merge Cells",
+  "menu": "Menu",
   "minLabel": "Min:",
   "minSize": "Min size of {{ width }}x{{ height }}",
   "minimumSize": "Minimum size of {{ width }} x {{ height }} px",
@@ -475,6 +478,8 @@
   "publishBeforeUsingTooltip": "Publish this content before using it in a relationship",
   "publishType": "Publish {{ type }}",
   "published": "Published",
+  "publicationStatusMenu": "Publication status",
+  "publicationStatusTrigger": "Publication status: {{ status }}. Change publication status.",
   "publishingBatchConfirmation": "Are you sure you want to publish {{ count }} {{ type }}?",
   "publishingBatchConfirmationButton": "Yes, publish content.",
   "rawCssAndJs": "Raw CSS and JS",
@@ -490,6 +495,7 @@
   "recentlyEditedActionSubmitted": "Submitted",
   "recentlyEditedCurrentUser": "Me ({{ user }})",
   "recentlyEditedDocuments": "Recently edited documents",
+  "recentlyEditedManagerOpen": "Open recently edited documents manager",
   "recentlyEditedEditedBy": "Edited by",
   "recentlyEditedClearAllFilters": "Clear all filters",
   "recentlyEditedClearSearch": "Clear search",
diff --git a/packages/apostrophe/modules/@apostrophecms/recently-edited/ui/apos/components/AposRecentlyEditedIcon.vue b/packages/apostrophe/modules/@apostrophecms/recently-edited/ui/apos/components/AposRecentlyEditedIcon.vue
index 5d1f78f97b..0852868d37 100644
--- a/packages/apostrophe/modules/@apostrophecms/recently-edited/ui/apos/components/AposRecentlyEditedIcon.vue
+++ b/packages/apostrophe/modules/@apostrophecms/recently-edited/ui/apos/components/AposRecentlyEditedIcon.vue
@@ -6,6 +6,8 @@
     :modifiers="['small', 'no-motion']"
     :tooltip="$t('apostrophe:recentlyEditedDocuments')"
     :icon-only="true"
+    :label="'apostrophe:recentlyEditedManagerOpen'"
+    :attrs="{ 'aria-label': $t('apostrophe:recentlyEditedManagerOpen') }"
     @click="open"
   />
 </template>
diff --git a/packages/apostrophe/modules/@apostrophecms/submitted-draft/ui/apos/components/AposSubmittedDraftIcon.vue b/packages/apostrophe/modules/@apostrophecms/submitted-draft/ui/apos/components/AposSubmittedDraftIcon.vue
index 5a30436f29..b9bde48b45 100644
--- a/packages/apostrophe/modules/@apostrophecms/submitted-draft/ui/apos/components/AposSubmittedDraftIcon.vue
+++ b/packages/apostrophe/modules/@apostrophecms/submitted-draft/ui/apos/components/AposSubmittedDraftIcon.vue
@@ -7,6 +7,7 @@
     :tooltip="tooltip"
     :icon-only="true"
     :action="action"
+    :attrs="{ 'aria-label': $t(tooltip) }"
     @click="open"
   >
     <template #label>
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposButton.vue b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposButton.vue
index 7a729903f8..70bb580d67 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposButton.vue
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposButton.vue
@@ -459,6 +459,15 @@ export default {
     }
   }
 
+  // Keyboard-focus indicator for the `quiet` modifier
+  .apos-button--quiet {
+    &:focus-visible {
+      box-shadow: 0 0 0 2px var(--a-primary-light-40);
+      outline: none;
+      border-radius: var(--a-border-radius);
+    }
+  }
+
   .apos-button--subtle {
     padding: 11px 10px; // extra pixel keeps them aligned with border'd buttons
     color: var(--a-text-primary);
@@ -757,11 +766,14 @@ export default {
   }
 
   .apos-button--no-motion {
-    &:hover:not([disabled]),
-    &:focus:not([disabled]) {
+    &:hover:not([disabled]) {
       transform: none;
       box-shadow: none;
     }
+
+    &:focus:not([disabled]) {
+      transform: none;
+    }
   }
 
   .apos-button__wrapper {
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposContextMenu.vue b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposContextMenu.vue
index feb963eed9..4577a32ada 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposContextMenu.vue
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposContextMenu.vue
@@ -19,15 +19,11 @@
         v-bind="button"
         ref="dropdownButton"
         class="apos-context-menu__btn"
-        role="button"
         :data-apos-test="identifier"
         :state="buttonState"
         :disabled="disabled"
         :tooltip="btnTooltip"
-        :attrs="{
-          'aria-haspopup': 'menu',
-          'aria-expanded': isOpen ? true : false
-        }"
+        :attrs="triggerAttrs"
         @icon="setIconToCenterTo"
         @click.stop="buttonClicked($event)"
       />
@@ -52,6 +48,7 @@
           :active-item="activeItem"
           :is-open="isOpen"
           :has-tip="hasTip"
+          :dialog-label="dialogLabel"
           @item-clicked="menuItemClicked"
           @set-arrow="setArrow"
         >
@@ -87,6 +84,7 @@
             :is-open="isOpen"
             :has-tip="hasTip"
             :ignore-unfocus="ignoreUnfocus"
+            :dialog-label="dialogLabel"
             @item-clicked="menuItemClicked"
             @set-arrow="setArrow"
           >
@@ -215,6 +213,21 @@ const props = defineProps({
   ignoreUnfocus: {
     type: Boolean,
     default: false
+  },
+  // Accessible name for the popover dialog. Pass an i18n key describing
+  // the menu's purpose. Defaults to a generic "Menu" label.
+  dialogLabel: {
+    type: String,
+    default: 'apostrophe:menu'
+  },
+  // Optional accessible name for the trigger button. When provided, it
+  // overrides the visible button label as the button's accessible name
+  // (useful when the visible label alone does not convey the trigger's
+  // purpose, e.g. when the label only shows the current value of a
+  // setting the menu changes). Pass an already-translated string.
+  triggerAriaLabel: {
+    type: String,
+    default: null
   }
 });
 
@@ -320,6 +333,17 @@ const menuAttrs = computed(() => {
   };
 });
 
+const triggerAttrs = computed(() => {
+  const attrs = {
+    'aria-haspopup': 'menu',
+    'aria-expanded': isOpen.value
+  };
+  if (props.triggerAriaLabel) {
+    attrs['aria-label'] = props.triggerAriaLabel;
+  }
+  return attrs;
+});
+
 const teleportedStyle = computed(() => {
   // For teleported content, we need to ensure positioning is always fresh
   // The positioning is already calculated correctly by setDropdownPosition
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposContextMenuDialog.vue b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposContextMenuDialog.vue
index f9ea0ba4d0..33d4dea1c6 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposContextMenuDialog.vue
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposContextMenuDialog.vue
@@ -3,6 +3,7 @@
     class="apos-primary-scrollbar apos-context-menu__dialog"
     :class="classes"
     role="dialog"
+    :aria-label="$t(props.dialogLabel)"
     :data-apos-ignore-unfocus="props.ignoreUnfocus"
   >
     <AposContextMenuTip
@@ -71,6 +72,13 @@ const props = defineProps({
   activeItem: {
     type: String,
     default: null
+  },
+  // Accessible name for the dialog wrapper (role="dialog"). Pass an i18n
+  // key describing the menu's purpose for the most useful screen-reader
+  // announcement. Defaults to a generic "Menu" label.
+  dialogLabel: {
+    type: String,
+    default: 'apostrophe:menu'
   }
 });
 
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposContextMenuItem.vue b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposContextMenuItem.vue
index f2a3f71ee0..602c7f6ef9 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposContextMenuItem.vue
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposContextMenuItem.vue
@@ -2,6 +2,7 @@
   <li
     class="apos-context-menu__item"
     :class="menuItem.separator ? 'apos-context-menu__item--separator' : null"
+    role="presentation"
   >
     <hr
       v-if="menuItem.separator"
@@ -178,7 +179,9 @@ export default {
   }
 
   &--disabled {
-    color: var(--a-base-3);
+    // Use --a-base-2 (#6f6f6f) so the disabled label still meets WCAG AA
+    // contrast against the menu background (--a-background-primary, #fff).
+    color: var(--a-base-2);
 
     &:focus,
     &:active {
@@ -189,7 +192,7 @@ export default {
     &:focus,
     &:active {
       cursor: not-allowed;
-      color: var(--a-base-5);
+      color: var(--a-base-2);
       background-color: var(--a-base-9);
     }
   }
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposLocalePicker.vue b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposLocalePicker.vue
index 78cb80276c..c0e2f2878a 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposLocalePicker.vue
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposLocalePicker.vue
@@ -9,9 +9,14 @@
         type="text"
         class="apos-locales-picker__filter"
         :placeholder="$t('apostrophe:searchLocalesPlaceholder')"
+        :aria-label="$t('apostrophe:searchLocales')"
       >
     </div>
-    <ul class="apos-locales-picker__list">
+    <ul
+      class="apos-locales-picker__list"
+      role="menu"
+      :aria-label="$t('apostrophe:locale')"
+    >
       <li
         v-for="locale in filteredLocales"
         :key="locale.name"
@@ -19,11 +24,15 @@
         :class="localeClasses(locale)"
         class="apos-locale-picker__item"
         data-apos-test="localeItem"
+        role="presentation"
         @click="switchLocale(locale)"
       >
         <button
           :tabindex="isOpen ? '0' : '-1'"
           class="apos-locale-picker__locale-display"
+          role="menuitemradio"
+          :aria-checked="isActive(locale)"
+          :aria-disabled="isForbidden(locale) ? 'true' : null"
         >
           <AposIndicator
             v-if="isForbidden(locale)"
@@ -49,6 +58,10 @@
             v-if="showLocalized"
             class="apos-locale-picker__localized"
             :class="{ 'apos-state-is-localized': isLocalized(locale) }"
+            role="img"
+            :aria-label="isLocalized(locale)
+              ? $t('apostrophe:localizeLocalized')
+              : $t('apostrophe:localizeNotYetLocalized')"
           />
         </button>
       </li>
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/scss/global/_utilities.scss b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/scss/global/_utilities.scss
index b20aa9063f..785d0ea304 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/scss/global/_utilities.scss
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/scss/global/_utilities.scss
@@ -1,6 +1,18 @@
+// Visually hidden but exposed to assistive technology and the
+// accessibility tree (unlike `visibility: hidden` or `display: none`,
+// which both remove the element from the a11y tree). Used to provide
+// accessible names for icon-only buttons, hidden labels, and visually
+// hidden form inputs that should remain focusable.
 .apos-sr-only {
-  visibility: hidden;
   position: absolute;
+  overflow: hidden;
+  width: 1px;
+  height: 1px; 
+  margin: -1px;
+  padding: 0;
+  border: 0;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
 }
 
 .apos-ltr {

From 13f2c69f219a47f82972d8fa9036deddd84223dc Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Fri, 8 May 2026 11:10:31 -0400
Subject: [PATCH 18/56] clarifications (#5403)

---
 .changeset/cozy-wombats-burn.md    | 2 +-
 .changeset/fifty-hornets-follow.md | 6 +++---
 .changeset/wild-forks-fetch.md     | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.changeset/cozy-wombats-burn.md b/.changeset/cozy-wombats-burn.md
index e04a363fcd..a484ecded0 100644
--- a/.changeset/cozy-wombats-burn.md
+++ b/.changeset/cozy-wombats-burn.md
@@ -2,4 +2,4 @@
 "@apostrophecms/cli": patch
 ---
 
-Bump and clean up depdendencies.
+Security: bump and clean up dependencies. This closes vulnerabilities in `uuid` and `fast-xml-parser` although they were not used in a sensitive or vulnerable way within ApostropheCMS. This also closes a vulnerability in `shelljs` which ould only be exploited if the developer could be convinced to enter malicious commands as part of their CLI input.
diff --git a/.changeset/fifty-hornets-follow.md b/.changeset/fifty-hornets-follow.md
index 52da86bff8..d698950dad 100644
--- a/.changeset/fifty-hornets-follow.md
+++ b/.changeset/fifty-hornets-follow.md
@@ -1,7 +1,7 @@
 ---
-"apostrophe": minor
+"apostrophe": patch
 ---
 
 - Removed duplicate <meta charset> tag from `outerLayoutBase.html`
-- Standardized charset to utf-8 (removed legacy configuration option)
-- Altered unused/legacy i18n template helper to return `utf-8` (BC)
+- Standardized charset to utf-8 (the legacy configuration option is now ignored). Per the spec this is the only legal setting, so we classify this as a bug fix
+- Altered unused/legacy i18n template helper to return `utf-8`, ensuring backwards compatibility
diff --git a/.changeset/wild-forks-fetch.md b/.changeset/wild-forks-fetch.md
index f5f944c79e..a175167488 100644
--- a/.changeset/wild-forks-fetch.md
+++ b/.changeset/wild-forks-fetch.md
@@ -1,5 +1,5 @@
 ---
-"apostrophe": minor
+"apostrophe": patch
 ---
 
 apostrophe and oembetter have been updated to eliminate a number of services that formerly supported

From 08dfcacd4345005fd58a211022360842bb999ec1 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 13 May 2026 08:56:11 -0400
Subject: [PATCH 19/56] Merge commit from fork

* Security: a malicious full name containing HTML was executed as HTML in the tooltip displayed with an "i" icon next to the title of the current page, creating an
XSS attack risk versus other users. Since most projects permit users to change their full name (the "title" property), All projects with multiple users should be updated promptly
to close this vulnerability.

* changeset
---
 .changeset/open-garlics-smile.md                    |  7 +++++++
 .../ui/apos/components/TheAposContextTitle.vue      | 13 +++++++++++--
 2 files changed, 18 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/open-garlics-smile.md

diff --git a/.changeset/open-garlics-smile.md b/.changeset/open-garlics-smile.md
new file mode 100644
index 0000000000..610ece378e
--- /dev/null
+++ b/.changeset/open-garlics-smile.md
@@ -0,0 +1,7 @@
+---
+"apostrophe": patch
+---
+
+Security: a malicious full name containing HTML was executed as HTML in the tooltip displayed with an "i" icon next to the title of the current page, creating an
+XSS attack risk versus other users. Since most projects permit users to change their full name (the "title" property), All projects with multiple users should be
+updated promptly to close this vulnerability. Thanks to [Muhammad Uwais](https://github.com/MuhammadUwais) for reporting the issue.
diff --git a/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposContextTitle.vue b/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposContextTitle.vue
index d020d02705..4289b627e1 100644
--- a/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposContextTitle.vue
+++ b/packages/apostrophe/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposContextTitle.vue
@@ -58,6 +58,15 @@
 <script>
 import dayjs from 'dayjs';
 
+function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
 export default {
   name: 'TheAposContextTitle',
   props: {
@@ -80,8 +89,8 @@ export default {
       if (this.context.updatedBy) {
         const editor = this.context.updatedBy;
         editorLabel = '';
-        editorLabel += editor.title ? `${editor.title} ` : '';
-        editorLabel += editor.username ? `(${editor.username})` : '';
+        editorLabel += editor.title ? `${escapeHtml(editor.title)} ` : '';
+        editorLabel += editor.username ? `(${escapeHtml(editor.username)})` : '';
       }
       return editorLabel;
     },

From 8d4c882b4ed3a7ce802cd87f89f0c1cb7482b8c2 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 13 May 2026 08:56:35 -0400
Subject: [PATCH 20/56] Merge commit from fork

* fix xmp tag vulnerability

* thanks
---
 .changeset/upset-ties-cough.md      | 5 +++++
 packages/sanitize-html/README.md    | 4 ++--
 packages/sanitize-html/index.js     | 7 ++++++-
 packages/sanitize-html/test/test.js | 9 +++++++++
 4 files changed, 22 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/upset-ties-cough.md

diff --git a/.changeset/upset-ties-cough.md b/.changeset/upset-ties-cough.md
new file mode 100644
index 0000000000..6795e47545
--- /dev/null
+++ b/.changeset/upset-ties-cough.md
@@ -0,0 +1,5 @@
+---
+"sanitize-html": patch
+---
+
+Security vulnerability: the xmp tag could be used to pass forbidden markup through sanitize-html, even when xmp itself is not explicitly allowed All users of sanitize-html should update immediately. Thanks to [Vincenzo Turturro](https://github.com/sushi-gif) for reporting the vulnerability.
diff --git a/packages/sanitize-html/README.md b/packages/sanitize-html/README.md
index 6600332a29..fca839f93d 100644
--- a/packages/sanitize-html/README.md
+++ b/packages/sanitize-html/README.md
@@ -695,13 +695,13 @@ Normally, with a few exceptions, if a tag is not allowed, all of the text within
 
 The exceptions are:
 
-`style`, `script`, `textarea`, `option`
+`style`, `script`, `textarea`, `option`, `xmp`
 
 If you wish to replace this list, for instance to discard whatever is found
 inside a `noscript` tag, use the `nonTextTags` option:
 
 ```js
-nonTextTags: [ 'style', 'script', 'textarea', 'option', 'noscript' ]
+nonTextTags: [ 'style', 'script', 'textarea', 'option', 'xmp', 'noscript' ]
 ```
 
 Note that if you use this option you are responsible for stating the entire list. This gives you the power to retain the content of `textarea`, if you want to.
diff --git a/packages/sanitize-html/index.js b/packages/sanitize-html/index.js
index 58db0bef4a..eec6ca628c 100644
--- a/packages/sanitize-html/index.js
+++ b/packages/sanitize-html/index.js
@@ -135,11 +135,16 @@ function sanitizeHtml(html, options, _recursing) {
   // the text when the tag is disallowed makes sense for other reasons.
   // If we are not allowing these tags, we should drop their content too.
   // For other tags you would drop the tag but keep its content.
+  // `xmp` is included because htmlparser2 treats it as a raw-text element,
+  // so markup inside is parsed as text on input but would otherwise be
+  // re-emitted unescaped via the `ontext` branch below, allowing XSS bypass
+  // when `xmp` is disallowed (which is the default).
   const nonTextTagsArray = options.nonTextTags || [
     'script',
     'style',
     'textarea',
-    'option'
+    'option',
+    'xmp'
   ];
   let allowedAttributesMap;
   let allowedAttributesGlobMap;
diff --git a/packages/sanitize-html/test/test.js b/packages/sanitize-html/test/test.js
index f013c5e41e..5bd342e530 100644
--- a/packages/sanitize-html/test/test.js
+++ b/packages/sanitize-html/test/test.js
@@ -123,6 +123,15 @@ describe('sanitizeHtml', function() {
   it('should drop the content of textarea elements but keep the closing parent tag, when nested', function() {
     assert.equal(sanitizeHtml('<p>Paragraph<textarea>Nifty</textarea></p>'), '<p>Paragraph</p>');
   });
+  it('should drop the content of disallowed xmp elements rather than re-emit it as live markup', function() {
+    // Regression test for GHSA-rpr9-rxv7-x643: htmlparser2 parses the contents
+    // of <xmp> as raw text, so without xmp in nonTextTags the inner markup
+    // would be re-emitted unescaped and become live HTML.
+    assert.equal(sanitizeHtml('<xmp><script>alert(1)</script></xmp>'), '');
+    assert.equal(sanitizeHtml('<xmp><img src=x onerror=alert(1)></xmp>'), '');
+    assert.equal(sanitizeHtml('<xmp><svg><script>alert(1)</script></svg></xmp>'), '');
+    assert.equal(sanitizeHtml('before<xmp><script>alert(1)</script></xmp>after'), 'beforeafter');
+  });
   it('should retain the content of fibble elements by default', function() {
     assert.equal(sanitizeHtml('<fibble>Nifty</fibble><p>Paragraph</p>'), 'Nifty<p>Paragraph</p>');
   });

From 5d1a02876b9305afd585e7020f8aa4eba1c6ddd0 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 13 May 2026 08:56:52 -0400
Subject: [PATCH 21/56] Merge commit from fork

* secure the link URL field of image widgets

* credit
---
 .changeset/pink-buckets-write.md              |   7 ++
 .../@apostrophecms/image-widget/index.js      |  30 ++++-
 packages/apostrophe/package.json              |   2 +-
 packages/launder/index.js                     | 113 ++++++++++++------
 packages/launder/test/test.js                 |  70 +++++++++++
 packages/sanitize-html/index.js               |  49 ++------
 packages/sanitize-html/package.json           |   1 +
 7 files changed, 194 insertions(+), 78 deletions(-)
 create mode 100644 .changeset/pink-buckets-write.md

diff --git a/.changeset/pink-buckets-write.md b/.changeset/pink-buckets-write.md
new file mode 100644
index 0000000000..9333df426d
--- /dev/null
+++ b/.changeset/pink-buckets-write.md
@@ -0,0 +1,7 @@
+---
+"sanitize-html": patch
+"apostrophe": patch
+"launder": patch
+---
+
+Security: launder now uses and exports the best available naughtyHref function for detecting malicious URLs. sanitize-html now depends on it, and apostrophe now uses type: 'url' for the link URL field of image widgets, which leverages it. Prior to this fix, it was possible for any user with editing privileges, including a contributor, to trigger arbitrary JavaScript via a javascript: URL in the link URL field of an image widget. A migration has been included to strip any such malicious URLs already present in the database. All users of apostrophe are encouraged to upgrade to get this security fix. Thanks to [Muhammad Uwais](https://github.com/MuhammadUwais) for reporting the issue.
diff --git a/packages/apostrophe/modules/@apostrophecms/image-widget/index.js b/packages/apostrophe/modules/@apostrophecms/image-widget/index.js
index 43fe175055..ebe2175625 100644
--- a/packages/apostrophe/modules/@apostrophecms/image-widget/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/image-widget/index.js
@@ -102,7 +102,7 @@ module.exports = {
         linkHref: {
           label: 'apostrophe:url',
           help: 'apostrophe:linkHrefHelp',
-          type: 'string',
+          type: 'url',
           required: true,
           if: {
             linkTo: '_url'
@@ -147,6 +147,7 @@ module.exports = {
     self.showPlaceholder = self.options.placeholder !== false;
     self.options.placeholder = true;
     self.determineBestAssetUrl('placeholder');
+    self.addCleanLinkHrefMigration();
   },
   handlers(self) {
     return {
@@ -159,6 +160,33 @@ module.exports = {
   },
   methods(self) {
     return {
+      // Clear link hrefs that use dangerous URL schemes (e.g.
+      // `javascript:`) and may have been stored before the linkHref
+      // schema field was changed to `type: 'url'`. Registered per
+      // module instance so subclasses of this widget are migrated
+      // under their own widget type and migration name.
+      addCleanLinkHrefMigration() {
+        self.apos.migration.add(
+          `${self.__meta.name}:clean-naughty-link-href`,
+          async () => {
+            await self.apos.migration.eachWidget({}, async (doc, widget, dotPath) => {
+              if (widget.type !== self.name) {
+                return;
+              }
+              if (!widget.linkHref) {
+                return;
+              }
+              if (!self.apos.launder.naughtyHref(widget.linkHref)) {
+                return;
+              }
+              await self.apos.doc.db.updateOne(
+                { _id: doc._id },
+                { $set: { [`${dotPath}.linkHref`]: '' } }
+              );
+            });
+          }
+        );
+      },
       validateAndAddSchemaLabels() {
         const linkWithType = self.options.linkWithType;
 
diff --git a/packages/apostrophe/package.json b/packages/apostrophe/package.json
index a01079b6d2..f33c12137c 100644
--- a/packages/apostrophe/package.json
+++ b/packages/apostrophe/package.json
@@ -93,7 +93,7 @@
     "is-wsl": "^2.2.0",
     "jsdom": "^24.1.0",
     "klona": "^2.0.4",
-    "launder": "^1.4.0",
+    "launder": "workspace:^",
     "lodash": "^4.18.1",
     "mini-css-extract-plugin": "^1.6.0",
     "minimatch": "^3.1.4",
diff --git a/packages/launder/index.js b/packages/launder/index.js
index 3393ce17a1..0cb59390c5 100644
--- a/packages/launder/index.js
+++ b/packages/launder/index.js
@@ -1,5 +1,64 @@
 const dayjs = require('dayjs');
 
+// Strip characters browsers ignore inside URLs (control chars and
+// embedded HTML comments) that are commonly used to sneak XSS
+// payloads past simple scheme checks.
+function cleanHref(href) {
+  // Browsers ignore character codes of 32 (space) and below in a surprising
+  // number of situations. Start reading here:
+  // https://www.owasp.org/index.php/XSS_Filter_Evasion_Cheat_Sheet#Embedded_tab
+  // eslint-disable-next-line no-control-regex
+  href = href.replace(/[\x00-\x20]+/g, '');
+  // Clobber any comments in URLs, which the browser might
+  // interpret inside an XML data island, allowing
+  // a javascript: URL to be snuck through
+  while (true) {
+    const firstIndex = href.indexOf('<!--');
+    if (firstIndex === -1) {
+      break;
+    }
+    const lastIndex = href.indexOf('-->', firstIndex + 4);
+    if (lastIndex === -1) {
+      break;
+    }
+    href = href.substring(0, firstIndex) + href.substring(lastIndex + 3);
+  }
+  return href;
+}
+
+// Returns true if `href` should be rejected as unsafe. Used to block
+// `javascript:`, `data:` and other dangerous schemes both when
+// validating URL fields and when sanitizing HTML attribute values.
+//
+// `options.allowedSchemes` is an array of permitted URL schemes
+// (defaults to the schemes long permitted by `launder().url`).
+// `options.allowProtocolRelative` controls whether protocol-relative
+// URLs (e.g. `//example.com`) are permitted. Defaults to true.
+function naughtyHref(href, options) {
+  options = options || {};
+  const allowedSchemes = options.allowedSchemes ||
+    [ 'http', 'https', 'ftp', 'mailto', 'tel', 'sms' ];
+  const allowProtocolRelative = (options.allowProtocolRelative !== false);
+  if (typeof href !== 'string') {
+    return false;
+  }
+  href = cleanHref(href);
+  // Case insensitive so we don't get faked out by JAVASCRIPT #1
+  // Allow more characters after the first so we don't get faked
+  // out by certain schemes browsers accept
+  const matches = href.match(/^([a-zA-Z][a-zA-Z0-9.\-+]*):/);
+  if (!matches) {
+    // Protocol-relative URL starting with any combination of '/' and '\'
+    if (href.match(/^[/\\]{2}/)) {
+      return !allowProtocolRelative;
+    }
+    // No scheme
+    return false;
+  }
+  const scheme = matches[1].toLowerCase();
+  return allowedSchemes.indexOf(scheme) === -1;
+}
+
 module.exports = function(options) {
   const self = {};
   self.options = options || {};
@@ -91,18 +150,27 @@ module.exports = function(options) {
     return i;
   };
 
+  self.naughtyHref = naughtyHref;
+
   self.url = function(s, def, httpsFix) {
     s = self.string(s, def);
     // Allow the default to be undefined, null, false, etc.
     if (s === def) {
       return s;
     }
-    s = fixUrl(s);
-    if (s === null) {
+    // Strip characters browsers ignore that are commonly used to
+    // smuggle dangerous schemes past validation.
+    s = cleanHref(s);
+    // Reject naughty URLs (e.g. `javascript:`, `data:`) before fixUrl
+    // runs. Otherwise fixUrl could mask such schemes by prepending
+    // `https://` to anything containing a `.`, turning
+    // `javascript:alert(document.domain)` into a syntactically odd
+    // but accepted `https://...` URL.
+    if (naughtyHref(s)) {
       return def;
     }
-    s = naughtyHref(s);
-    if (s === true) {
+    s = fixUrl(s);
+    if (s === null) {
       return def;
     }
     return s;
@@ -119,39 +187,6 @@ module.exports = function(options) {
         return null;
       }
     };
-
-    function naughtyHref(href) {
-      // Browsers ignore character codes of 32 (space) and below in a surprising
-      // number of situations. Start reading here:
-      // https://www.owasp.org/index.php/XSS_Filter_Evasion_Cheat_Sheet#Embedded_tab
-      // eslint-disable-next-line no-control-regex
-      href = href.replace(/[\x00-\x20]+/g, '');
-      // Clobber any comments in URLs, which the browser might
-      // interpret inside an XML data island, allowing
-      // a javascript: URL to be snuck through
-      while (true) {
-        const firstIndex = href.indexOf('<!--');
-        if (firstIndex === -1) {
-          break;
-        }
-        const lastIndex = href.indexOf('-->', firstIndex + 4);
-        if (lastIndex === -1) {
-          break;
-        }
-        href = href.substring(0, firstIndex) + href.substring(lastIndex + 3);
-      }
-      // Case insensitive so we don't get faked out by JAVASCRIPT #1
-      // Allow more characters after the first so we don't get faked
-      // out by certain schemes browsers accept
-      const matches = href.match(/^([a-zA-Z]+):/);
-      if (!matches) {
-        // No scheme = no way to inject js (right?)
-        return href;
-      }
-      const scheme = matches[1].toLowerCase();
-
-      return (![ 'http', 'https', 'ftp', 'mailto', 'tel', 'sms' ].includes(scheme)) ? true : href;
-    }
   };
 
   self.select = function(s, choices, def) {
@@ -497,3 +532,7 @@ module.exports = function(options) {
   };
   return self;
 };
+
+// Expose `naughtyHref` statically so callers (notably sanitize-html)
+// can use it without instantiating a launder.
+module.exports.naughtyHref = naughtyHref;
diff --git a/packages/launder/test/test.js b/packages/launder/test/test.js
index 75c7542e23..e491b6c9c2 100644
--- a/packages/launder/test/test.js
+++ b/packages/launder/test/test.js
@@ -250,6 +250,76 @@ describe('launder', function() {
     it('should add https:// when missing if httpsFix is true', function() {
       assert(launder.url('www.apostrophenow.org', null, true) === 'https://www.apostrophenow.org');
     });
+    it('should reject javascript: even when the URL contains a dot', function() {
+      // Without rejecting before fixUrl, the dot in `document.domain`
+      // causes fixUrl to prepend `https://`, masking the dangerous
+      // scheme rather than discarding it.
+      assert(launder.url('javascript:alert(document.domain)', 'http://www.apostrophenow.org') === 'http://www.apostrophenow.org');
+    });
+    it('should reject javascript: with mixed case', function() {
+      assert(launder.url('JaVaScRiPt:alert(1)', 'http://www.apostrophenow.org') === 'http://www.apostrophenow.org');
+    });
+    it('should reject javascript: smuggled past simple checks with control characters', function() {
+      assert(launder.url('java\tscript:alert(1)', 'http://www.apostrophenow.org') === 'http://www.apostrophenow.org');
+    });
+    it('should reject javascript: smuggled past simple checks with HTML comments', function() {
+      assert(launder.url('java<!---->script:alert(1)', 'http://www.apostrophenow.org') === 'http://www.apostrophenow.org');
+    });
+    it('should reject data: urls', function() {
+      assert(launder.url('data:text/html,<script>alert(1)</script>', 'http://www.apostrophenow.org') === 'http://www.apostrophenow.org');
+    });
+    it('should preserve relative urls beginning with /', function() {
+      assert(launder.url('/about') === '/about');
+    });
+    it('should preserve protocol-relative urls', function() {
+      assert(launder.url('//www.apostrophenow.org') === '//www.apostrophenow.org');
+    });
+  });
+
+  describe('naughtyHref', function() {
+    it('should report javascript: as naughty', function() {
+      assert(launder.naughtyHref('javascript:alert(1)') === true);
+    });
+    it('should report data: as naughty', function() {
+      assert(launder.naughtyHref('data:text/html,<script>alert(1)</script>') === true);
+    });
+    it('should report mixed-case javascript: as naughty', function() {
+      assert(launder.naughtyHref('JaVaScRiPt:alert(1)') === true);
+    });
+    it('should report control-character-smuggled javascript: as naughty', function() {
+      assert(launder.naughtyHref('java\tscript:alert(1)') === true);
+    });
+    it('should report HTML-comment-smuggled javascript: as naughty', function() {
+      assert(launder.naughtyHref('java<!---->script:alert(1)') === true);
+    });
+    it('should accept allowed schemes', function() {
+      assert(launder.naughtyHref('https://example.com') === false);
+      assert(launder.naughtyHref('http://example.com') === false);
+      assert(launder.naughtyHref('ftp://example.com') === false);
+      assert(launder.naughtyHref('mailto:foo@example.com') === false);
+      assert(launder.naughtyHref('tel:1234') === false);
+      assert(launder.naughtyHref('sms:1234') === false);
+    });
+    it('should accept relative URLs', function() {
+      assert(launder.naughtyHref('/about') === false);
+      assert(launder.naughtyHref('about') === false);
+      assert(launder.naughtyHref('#fragment') === false);
+    });
+    it('should accept protocol-relative URLs by default', function() {
+      assert(launder.naughtyHref('//example.com') === false);
+    });
+    it('should reject protocol-relative URLs when allowProtocolRelative is false', function() {
+      assert(launder.naughtyHref('//example.com', { allowProtocolRelative: false }) === true);
+    });
+    it('should respect a custom allowedSchemes list', function() {
+      assert(launder.naughtyHref('https://example.com', { allowedSchemes: [ 'http' ] }) === true);
+      assert(launder.naughtyHref('http://example.com', { allowedSchemes: [ 'http' ] }) === false);
+    });
+    it('should return false for non-string input', function() {
+      assert(launder.naughtyHref(undefined) === false);
+      assert(launder.naughtyHref(null) === false);
+      assert(launder.naughtyHref(42) === false);
+    });
   });
 
   describe('select', function() {
diff --git a/packages/sanitize-html/index.js b/packages/sanitize-html/index.js
index eec6ca628c..6a67683868 100644
--- a/packages/sanitize-html/index.js
+++ b/packages/sanitize-html/index.js
@@ -4,6 +4,7 @@ const { isPlainObject } = require('is-plain-object');
 const deepmerge = require('deepmerge');
 const parseSrcset = require('parse-srcset');
 const { parse: postcssParse } = require('postcss');
+const { naughtyHref: launderNaughtyHref } = require('launder');
 // Tags that can conceivably represent stand-alone media.
 const mediaTags = [
   'img', 'audio', 'video', 'picture', 'svg',
@@ -731,45 +732,15 @@ function sanitizeHtml(html, options, _recursing) {
   }
 
   function naughtyHref(name, href) {
-    // Browsers ignore character codes of 32 (space) and below in a surprising
-    // number of situations. Start reading here:
-    // https://www.owasp.org/index.php/XSS_Filter_Evasion_Cheat_Sheet#Embedded_tab
-    // eslint-disable-next-line no-control-regex
-    href = href.replace(/[\x00-\x20]+/g, '');
-    // Clobber any comments in URLs, which the browser might
-    // interpret inside an XML data island, allowing
-    // a javascript: URL to be snuck through
-    while (true) {
-      const firstIndex = href.indexOf('<!--');
-      if (firstIndex === -1) {
-        break;
-      }
-      const lastIndex = href.indexOf('-->', firstIndex + 4);
-      if (lastIndex === -1) {
-        break;
-      }
-      href = href.substring(0, firstIndex) + href.substring(lastIndex + 3);
-    }
-    // Case insensitive so we don't get faked out by JAVASCRIPT #1
-    // Allow more characters after the first so we don't get faked
-    // out by certain schemes browsers accept
-    const matches = href.match(/^([a-zA-Z][a-zA-Z0-9.\-+]*):/);
-    if (!matches) {
-      // Protocol-relative URL starting with any combination of '/' and '\'
-      if (href.match(/^[/\\]{2}/)) {
-        return !options.allowProtocolRelative;
-      }
-
-      // No scheme
-      return false;
-    }
-    const scheme = matches[1].toLowerCase();
-
-    if (has(options.allowedSchemesByTag, name)) {
-      return options.allowedSchemesByTag[name].indexOf(scheme) === -1;
-    }
-
-    return !options.allowedSchemes || options.allowedSchemes.indexOf(scheme) === -1;
+    // Resolve the per-tag scheme allowlist if one is configured for
+    // this tag, otherwise fall back to the global allowedSchemes.
+    const allowedSchemes = has(options.allowedSchemesByTag, name)
+      ? options.allowedSchemesByTag[name]
+      : (options.allowedSchemes || []);
+    return launderNaughtyHref(href, {
+      allowedSchemes,
+      allowProtocolRelative: options.allowProtocolRelative
+    });
   }
 
   function parseUrl(value) {
diff --git a/packages/sanitize-html/package.json b/packages/sanitize-html/package.json
index d6ffe4fdc1..fe401c0764 100644
--- a/packages/sanitize-html/package.json
+++ b/packages/sanitize-html/package.json
@@ -30,6 +30,7 @@
     "escape-string-regexp": "^4.0.0",
     "htmlparser2": "^10.1.0",
     "is-plain-object": "^5.0.0",
+    "launder": "workspace:^",
     "parse-srcset": "^1.0.2",
     "postcss": "^8.3.11"
   },

From 41670a39e681449758ca82a071e9bb84c265048a Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 13 May 2026 08:57:42 -0400
Subject: [PATCH 22/56] Merge commit from fork

---
 .changeset/busy-spies-enter.md                |   5 +
 .../modules/@apostrophecms/login/index.js     |  28 ++--
 packages/apostrophe/test/login.js             | 123 +++++++++++++++++-
 3 files changed, 140 insertions(+), 16 deletions(-)
 create mode 100644 .changeset/busy-spies-enter.md

diff --git a/.changeset/busy-spies-enter.md b/.changeset/busy-spies-enter.md
new file mode 100644
index 0000000000..cc922b7b1c
--- /dev/null
+++ b/.changeset/busy-spies-enter.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": patch
+---
+
+Security fix: the password reset request feature will refuse to operate unless the baseUrl option or the APOS_BASE_URL environment variable has been set (note that this is automatic in multisite projects). This fix is necessary to prevent a vulnerability that can be used to convince ApostropheCMS to send emails containing links to other sites. It is only a vulnerability if you have enabled the passwordReset: true option for the login module. Thanks to [SPIDY](https://github.com/Mujahidkhan525) for reporting the issue.
diff --git a/packages/apostrophe/modules/@apostrophecms/login/index.js b/packages/apostrophe/modules/@apostrophecms/login/index.js
index 224e22d0fb..bdcf934859 100644
--- a/packages/apostrophe/modules/@apostrophecms/login/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/login/index.js
@@ -295,7 +295,17 @@ module.exports = {
           async resetRequest(req) {
             const MIN_RESPONSE_TIME = 2000;
             const startTime = Date.now();
-            const site = (req.headers.host || '').replace(/:\d+$/, '');
+            // Refuse to construct reset URLs from the request's Host header,
+            // which is attacker-controlled. Operators must configure the
+            // baseUrl option (or the APOS_BASE_URL environment variable) so
+            // the link in the reset email points to the real site rather than
+            // wherever the attacker aimed their crafted request.
+            if (!self.apos.baseUrl) {
+              throw self.apos.error(
+                'invalid',
+                'The baseUrl option (or APOS_BASE_URL environment variable) must be configured to enable password reset'
+              );
+            }
             const email = self.apos.launder.string(req.body.email);
             if (!email.length) {
               throw self.apos.error('invalid', req.t('apostrophe:loginResetEmailRequired'));
@@ -319,22 +329,10 @@ module.exports = {
               user.passwordReset = reset;
               user.passwordResetAt = new Date();
               await self.apos.user.update(req, user, { permissions: false });
-              let port = (req.headers.host || '').split(':')[1];
-              if (!port || [ '80', '443' ].includes(port)) {
-                port = '';
-              } else {
-                port = `:${port}`;
-              }
-              const parsed = new URL(
-                req.absoluteUrl,
-                self.apos.baseUrl
-                  ? undefined
-                  : `${req.protocol}://${req.hostname}${port}`
-              );
-              parsed.pathname = self.login();
-              parsed.search = '?';
+              const parsed = new URL(self.login(), self.apos.baseUrl);
               parsed.searchParams.append('reset', reset);
               parsed.searchParams.append('email', user.email);
+              const site = parsed.hostname;
               try {
                 await self.email(req, 'passwordResetEmail', {
                   user,
diff --git a/packages/apostrophe/test/login.js b/packages/apostrophe/test/login.js
index 82ec345ec6..877c2207dc 100644
--- a/packages/apostrophe/test/login.js
+++ b/packages/apostrophe/test/login.js
@@ -11,6 +11,7 @@ describe('Login', function () {
   before(async function () {
     apos = await t.create({
       root: module,
+      baseUrl: 'http://localhost:3000',
       modules: {
         '@apostrophecms/express': {
           options: {
@@ -602,8 +603,14 @@ describe('Login', function () {
       assert.equal(opts.to, user.email);
       assert(opts.subject);
 
-      // Safe the token for the reset tests
+      // The reset URL must be derived from apos.baseUrl, not from the
+      // request's Host header, to prevent host header injection attacks
+      // that could leak the reset token to an attacker-controlled domain.
       const url = new URL(data.url);
+      assert.equal(`${url.protocol}//${url.host}`, apos.baseUrl);
+      assert.equal(data.site, new URL(apos.baseUrl).hostname);
+
+      // Safe the token for the reset tests
       resetToken = url.searchParams.get('reset');
     }
 
@@ -798,6 +805,56 @@ describe('Login', function () {
     assert(page.match(/logged in/));
   });
 
+  it('should ignore a spoofed Host header on POST /login/reset-request', async function () {
+    let args;
+    const orig = apos.login.email;
+    apos.login.email = (req, ...a) => {
+      args = a;
+    };
+
+    let user = apos.user.newInstance();
+    user.title = 'spoofUser';
+    user.email = 'spoofUser@example.com';
+    user.username = 'spoofUser';
+    user.password = 'secret';
+    user.role = 'guest';
+    user = await apos.user.insert(apos.task.getReq(), user);
+
+    const jar = apos.http.jar();
+    await apos.http.get(
+      '/',
+      {
+        jar
+      }
+    );
+
+    await apos.http.post(
+      '/api/v1/@apostrophecms/login/reset-request',
+      {
+        body: {
+          email: 'spoofUser',
+          session: true
+        },
+        headers: {
+          Host: 'evil.attacker.example'
+        },
+        jar
+      }
+    );
+
+    assert(Array.isArray(args));
+    const [ , data ] = args;
+    const url = new URL(data.url);
+    // The reset URL must reflect the configured apos.baseUrl, not the
+    // attacker-supplied Host header.
+    assert.equal(`${url.protocol}//${url.host}`, apos.baseUrl);
+    assert.notEqual(url.hostname, 'evil.attacker.example');
+    assert.equal(data.site, new URL(apos.baseUrl).hostname);
+    assert.notEqual(data.site, 'evil.attacker.example');
+
+    apos.login.email = orig;
+  });
+
   it('should find user by reset data', async function () {
     let user = apos.user.newInstance();
     user.title = 'getResetUser';
@@ -1053,6 +1110,70 @@ describe('Login', function () {
       assert.deepEqual(actual, expected);
     });
   });
+
+  describe('passwordReset without apos.baseUrl', function () {
+    let apos3;
+
+    this.timeout(20000);
+
+    before(async function () {
+      apos3 = await t.create({
+        root: module,
+        modules: {
+          '@apostrophecms/login': {
+            options: {
+              passwordReset: true,
+              environmentLabel: 'test'
+            }
+          }
+        }
+      });
+    });
+
+    after(function () {
+      return t.destroy(apos3);
+    });
+
+    it('should reject reset-request when apos.baseUrl is not configured', async function () {
+      assert(!apos3.baseUrl);
+
+      const user = apos3.user.newInstance();
+      user.title = 'noBaseUrlUser';
+      user.username = 'noBaseUrlUser';
+      user.email = 'noBaseUrlUser@example.com';
+      user.password = 'secret';
+      user.role = 'guest';
+      await apos3.user.insert(apos3.task.getReq(), user);
+
+      const jar = apos3.http.jar();
+      await apos3.http.get('/', { jar });
+
+      let emailed = false;
+      const orig = apos3.login.email;
+      apos3.login.email = () => {
+        emailed = true;
+      };
+
+      await assert.rejects(() => apos3.http.post(
+        '/api/v1/@apostrophecms/login/reset-request',
+        {
+          body: {
+            email: 'noBaseUrlUser',
+            session: true
+          },
+          jar
+        }
+      ), {
+        status: 400
+      });
+
+      // Confirm no reset email was sent — the request must be refused
+      // before any token is generated or message dispatched.
+      assert.equal(emailed, false);
+
+      apos3.login.email = orig;
+    });
+  });
 });
 
 describe('Case Sensitivity', function() {

From 01bacd24ad40d973cad7962e50f1d32ba05130f8 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 13 May 2026 08:57:52 -0400
Subject: [PATCH 23/56] Merge commit from fork

---
 .changeset/fiery-lights-fetch.md    |  5 +++++
 packages/cli/lib/commands/create.js | 23 ++++++++++++++---------
 packages/cli/lib/util.js            | 24 ++++++++++++++++++++++++
 packages/cli/package.json           |  1 -
 4 files changed, 43 insertions(+), 10 deletions(-)
 create mode 100644 .changeset/fiery-lights-fetch.md

diff --git a/.changeset/fiery-lights-fetch.md b/.changeset/fiery-lights-fetch.md
new file mode 100644
index 0000000000..3bcf8c1da7
--- /dev/null
+++ b/.changeset/fiery-lights-fetch.md
@@ -0,0 +1,5 @@
+---
+"@apostrophecms/cli": patch
+---
+
+Security: passwords and starter kit URLs containing intentionally malicious punctuation cannot be used to run arbitrary shell commands. Because the CLI is only used by developers, this would always have been an "own goal" situation, however this does make the CLI more robust for scripted use. Thanks to [Nitro13urn](https://github.com/VadlaReddySai) for reporting the issue.
diff --git a/packages/cli/lib/commands/create.js b/packages/cli/lib/commands/create.js
index 8596c3c8bb..c7120ab7c0 100644
--- a/packages/cli/lib/commands/create.js
+++ b/packages/cli/lib/commands/create.js
@@ -1,13 +1,12 @@
 require('shelljs/global');
 // Utilities from shelljs
-/* globals exec cd rm */
+/* globals cd rm */
 const prompts = require('prompts');
 const path = require('path');
 const util = require('../util');
 const config = require('../../config');
 const fs = require('fs');
 const { stripIndent } = require('common-tags');
-const quote = require('shell-quote').quote;
 
 module.exports = function (program) {
   program
@@ -52,7 +51,7 @@ module.exports = function (program) {
       );
 
       // Clone the boilerplate project
-      if (exec(`git clone ${boilerplateUrl} ${shortName}`).code !== 0) {
+      if ((await util.spawnSafe('git', [ 'clone', boilerplateUrl, shortName ])).code !== 0) {
         await util.error('create', 'Error cloning starter code.');
         return false;
       }
@@ -175,15 +174,21 @@ module.exports = function (program) {
 
       const userTask = '@apostrophecms/user:add';
       const appJsPath = resolvePath('app.js');
-      let createUserCommand = `node ${appJsPath} ${userTask} admin admin`;
+      const createUserArgs = [ appJsPath, userTask, 'admin', 'admin' ];
 
-      // Prepend MongoDB URI if provided
+      const createUserEnv = { ...process.env };
       if (options.mongodbUri) {
-        // Ensure the URI is properly quoted to handle special characters
-        createUserCommand = `APOS_MONGODB_URI=${quote([ options.mongodbUri ])} ` + createUserCommand;
+        createUserEnv.APOS_MONGODB_URI = options.mongodbUri;
+      }
+      util.log('create', `Creating admin user: node ${createUserArgs.join(' ')}`);
+      const createUserResult = await util.spawnSafe('node', createUserArgs, {
+        env: createUserEnv,
+        input: `${response.pw ?? ''}\n`
+      });
+      if (createUserResult.code !== 0) {
+        await util.error('create', `Admin user creation exited with code ${createUserResult.code}.`);
+        return false;
       }
-      util.log('create', `Creating admin user with command: ${createUserCommand}`);
-      exec(`echo "${response.pw}" | ${createUserCommand}`);
       util.log('create', 'All done! 🎉 Login as "admin" at the /login URL.');
 
       await util.success('create');
diff --git a/packages/cli/lib/util.js b/packages/cli/lib/util.js
index 566b3e75fc..a6bdf9f415 100644
--- a/packages/cli/lib/util.js
+++ b/packages/cli/lib/util.js
@@ -167,6 +167,30 @@ util.secret = function() {
   return string;
 };
 
+// Spawn a child process without invoking a shell, so caller-supplied URLs,
+// passwords, etc. cannot be parsed as shell metacharacters. Returns a promise
+// resolving to `{ code }`, mirroring the `.code` property on shelljs's `exec`
+// result so call sites can use the same shape. Pass `input` to write a string
+// to the child's stdin (e.g. an interactive password prompt response); when
+// omitted, stdin is inherited from the parent.
+util.spawnSafe = function (command, args, {
+  env, input, cwd
+} = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      env: env ?? process.env,
+      cwd,
+      stdio: [ input != null ? 'pipe' : 'inherit', 'inherit', 'inherit' ]
+    });
+    child.on('error', reject);
+    child.on('exit', (code) => resolve({ code }));
+    if (input != null) {
+      child.stdin.on('error', reject);
+      child.stdin.end(input);
+    }
+  });
+};
+
 util.spawnWithSpinner = async function (command, options = {
   spinnerMessage: 'Processing...',
   codeMessage: 'Spawn process error code:'
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 20ff3c1395..c4f9221650 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -26,7 +26,6 @@
     "pkginfo": "^0.4.1",
     "prompts": "^2.3.2",
     "semver": "^7.3.2",
-    "shell-quote": "^1.8.1",
     "shelljs": "^0.10.0",
     "sync-request": "^6.0.0",
     "uuid": "^11.1.0"

From 8098017bb3f0ed55e8f231011c2924084eb9045d Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 13 May 2026 08:58:02 -0400
Subject: [PATCH 24/56] Merge commit from fork

* Fixed arbitrary image URL import vulnerability in rich text impport API

* additional reporter
---
 .changeset/solid-boats-send.md                |  10 +
 .../@apostrophecms/rich-text-widget/index.js  |  36 ++++
 packages/apostrophe/test/rich-text-widget.js  | 200 ++++++++++++++++++
 3 files changed, 246 insertions(+)
 create mode 100644 .changeset/solid-boats-send.md

diff --git a/.changeset/solid-boats-send.md b/.changeset/solid-boats-send.md
new file mode 100644
index 0000000000..d0f848873f
--- /dev/null
+++ b/.changeset/solid-boats-send.md
@@ -0,0 +1,10 @@
+---
+"apostrophe": patch
+---
+
+Security: the HTML import feature of the rich text widget no longer permits images to be fetched
+from arbitrary hosts. This could be used to probe internal networks, and to exfiltrate images from
+internal hosts if their URLs were known. Instead, the `imageImportAllowedHostnames` option of the
+`@apostrophecms/rich-text-widget` must be configured to opt into that feature.
+
+Thanks to [Yiğit Şengezer](https://github.com/yigitsengezer) and [Sainithin0309](https://github.com/Sainithin0309) for reporting this issue.
diff --git a/packages/apostrophe/modules/@apostrophecms/rich-text-widget/index.js b/packages/apostrophe/modules/@apostrophecms/rich-text-widget/index.js
index f394d06479..98ca65ef30 100644
--- a/packages/apostrophe/modules/@apostrophecms/rich-text-widget/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/rich-text-widget/index.js
@@ -128,6 +128,10 @@ module.exports = {
     defaultData: { content: '' },
     className: false,
     linkWithType: [ '@apostrophecms/any-page-type' ],
+    // Hostnames from which `<img>` tags in `import.html` may be fetched.
+    // The list is empty by default, which disables image fetching during
+    // rich text HTML import. Add hostnames here to opt in.
+    imageImportAllowedHostnames: [],
     tableOptions: {
       resizable: true,
       handleWidth: 10,
@@ -472,6 +476,31 @@ module.exports = {
         return widget.content;
       },
 
+      // Return the configured allowlist of hostnames from which images may
+      // be fetched during a rich text widget HTML import, normalized to
+      // lowercase. Returns an empty array if the option is unset, in which
+      // case any image fetch attempted during import is rejected.
+      getImageImportAllowedHostnames() {
+        const list = self.options.imageImportAllowedHostnames;
+        if (!Array.isArray(list)) {
+          return [];
+        }
+        return list
+          .filter(entry => typeof entry === 'string' && entry.length > 0)
+          .map(entry => entry.toLowerCase());
+      },
+
+      // Determine whether the given URL's hostname is permitted by the
+      // import allowlist. The protocol is also restricted to http/https
+      // to prevent fetches via file:, data:, or other schemes.
+      isImageImportHostnameAllowed(url, allowedHostnames) {
+        if (!url || (url.protocol !== 'http:' && url.protocol !== 'https:')) {
+          return false;
+        }
+        const hostname = (url.hostname || '').toLowerCase();
+        return allowedHostnames.includes(hostname);
+      },
+
       // Handle relationships to permalinks and inline images
       async load(req, widgets) {
         try {
@@ -1057,6 +1086,7 @@ module.exports = {
             if (input.import.baseUrl && ((typeof input.import.html) !== 'string')) {
               throw self.apos.error('invalid', 'If present, import.baseUrl must be a string');
             }
+            const allowedHostnames = self.getImageImportAllowedHostnames();
             const $ = cheerio.load(input.import.html);
             const $images = $('img');
             // Build an array of cheerio objects because
@@ -1071,6 +1101,12 @@ module.exports = {
               const src = $image.attr('src');
               const alt = $image.attr('alt') && self.apos.util.escapeHtml($image.attr('alt'));
               const url = new URL(src, input.import.baseUrl || self.apos.baseUrl);
+              if (!self.isImageImportHostnameAllowed(url, allowedHostnames)) {
+                throw self.apos.error(
+                  'forbidden',
+                  `Refusing to import image from disallowed hostname "${url.hostname}". Add it to the \`imageImportAllowedHostnames\` option of the \`@apostrophecms/rich-text-widget\` module to allow it.`
+                );
+              }
               const res = await fetch(url);
               if (res.status >= 400) {
                 self.apos.util.warn(`Error ${res.status} while importing ${src}, ignoring image`);
diff --git a/packages/apostrophe/test/rich-text-widget.js b/packages/apostrophe/test/rich-text-widget.js
index 05581e76ac..5a82caa7c2 100644
--- a/packages/apostrophe/test/rich-text-widget.js
+++ b/packages/apostrophe/test/rich-text-widget.js
@@ -293,4 +293,204 @@ describe('Rich Text Widget', function () {
     assert(text2.includes('src="/uploads/attachments/attachment-1-attachment-1.max.jpg" alt="Updated Test Image 1"'));
     assert(text2.includes('src="/uploads/attachments/attachment-2-attachment-2.max.jpg" alt="Updated Test Image 2"'));
   });
+
+  describe('image import allowlist (SSRF mitigation)', function () {
+    let originalConsoleError;
+
+    before(function () {
+      // The sanitize method intentionally console.errors thrown errors to
+      // surface stack traces during development; silence that noise during
+      // these negative tests.
+      // eslint-disable-next-line no-console
+      originalConsoleError = console.error;
+      // eslint-disable-next-line no-console
+      console.error = () => {};
+    });
+
+    after(function () {
+      // eslint-disable-next-line no-console
+      console.error = originalConsoleError;
+    });
+
+    it('allows rich text HTML import without `<img>` tags even with no allowlist configured', async function () {
+      apos = await t.create({
+        root: module,
+        modules: {}
+      });
+
+      const manager = apos.modules['@apostrophecms/rich-text-widget'];
+      const req = apos.task.getReq();
+
+      const output = await manager.sanitize(req, {
+        type: '@apostrophecms/rich-text',
+        content: '<p>seed</p>',
+        import: {
+          html: '<p>Hello <strong>world</strong></p>'
+        }
+      }, {});
+
+      assert.match(output.content, /Hello/);
+    });
+
+    it('rejects an image fetch for a hostname not in the allowlist and never calls fetch', async function () {
+      apos = await t.create({
+        root: module,
+        modules: {
+          '@apostrophecms/rich-text-widget': {
+            options: {
+              imageImportAllowedHostnames: [ 'images.example.com' ]
+            }
+          }
+        }
+      });
+
+      const manager = apos.modules['@apostrophecms/rich-text-widget'];
+      const req = apos.task.getReq();
+
+      const originalFetch = global.fetch;
+      let fetchCalled = false;
+      global.fetch = async () => {
+        fetchCalled = true;
+        throw new Error('fetch should not be called');
+      };
+
+      try {
+        await assert.rejects(
+          () => manager.sanitize(req, {
+            type: '@apostrophecms/rich-text',
+            content: '<p>seed</p>',
+            import: {
+              html: '<img src="http://127.0.0.1:7777/secret.png">',
+              baseUrl: 'http://127.0.0.1:7777'
+            }
+          }, {}),
+          (err) => {
+            assert.equal(err.name, 'forbidden');
+            assert.match(err.message, /127\.0\.0\.1/);
+            assert.match(err.message, /imageImportAllowedHostnames/);
+            return true;
+          }
+        );
+      } finally {
+        global.fetch = originalFetch;
+      }
+
+      assert.equal(fetchCalled, false);
+    });
+
+    it('rejects rich text HTML import for non-http(s) protocols even if hostname matches', async function () {
+      apos = await t.create({
+        root: module,
+        modules: {
+          '@apostrophecms/rich-text-widget': {
+            options: {
+              imageImportAllowedHostnames: [ 'localhost' ]
+            }
+          }
+        }
+      });
+
+      const manager = apos.modules['@apostrophecms/rich-text-widget'];
+      const req = apos.task.getReq();
+
+      await assert.rejects(
+        () => manager.sanitize(req, {
+          type: '@apostrophecms/rich-text',
+          content: '<p>seed</p>',
+          import: {
+            html: '<img src="file:///etc/passwd">',
+            baseUrl: 'file://localhost'
+          }
+        }, {}),
+        (err) => {
+          assert.equal(err.name, 'forbidden');
+          return true;
+        }
+      );
+    });
+
+    it('proceeds to fetch when import URL hostname is on the allowlist', async function () {
+      apos = await t.create({
+        root: module,
+        modules: {
+          '@apostrophecms/rich-text-widget': {
+            options: {
+              imageImportAllowedHostnames: [ 'images.example.com' ]
+            }
+          }
+        }
+      });
+
+      const manager = apos.modules['@apostrophecms/rich-text-widget'];
+      const req = apos.task.getReq();
+
+      const originalFetch = global.fetch;
+      const fetchedUrls = [];
+      // Throw a unique marker error from inside fetch. If the allowlist
+      // passes, the marker error propagates; if the allowlist rejects, we
+      // would see a `forbidden` error instead.
+      const marker = new Error('FETCH_REACHED');
+      marker.name = 'FetchReached';
+      global.fetch = async (url) => {
+        fetchedUrls.push(url.toString());
+        throw marker;
+      };
+
+      try {
+        await assert.rejects(
+          () => manager.sanitize(req, {
+            type: '@apostrophecms/rich-text',
+            content: '<p>seed</p>',
+            import: {
+              html: '<img src="https://images.example.com/foo.png">',
+              baseUrl: 'https://images.example.com'
+            }
+          }, {}),
+          (err) => err.name === 'FetchReached'
+        );
+      } finally {
+        global.fetch = originalFetch;
+      }
+
+      assert.deepEqual(fetchedUrls, [ 'https://images.example.com/foo.png' ]);
+    });
+
+    it('helper methods reflect option configuration', async function () {
+      apos = await t.create({
+        root: module,
+        modules: {
+          '@apostrophecms/rich-text-widget': {
+            options: {
+              imageImportAllowedHostnames: [ 'Images.Example.com', '', null, 'cdn.example.com' ]
+            }
+          }
+        }
+      });
+
+      const manager = apos.modules['@apostrophecms/rich-text-widget'];
+
+      assert.deepEqual(
+        manager.getImageImportAllowedHostnames(),
+        [ 'images.example.com', 'cdn.example.com' ]
+      );
+
+      const allowed = manager.getImageImportAllowedHostnames();
+      assert.equal(
+        manager.isImageImportHostnameAllowed(new URL('https://images.example.com/foo.png'), allowed),
+        true
+      );
+      assert.equal(
+        manager.isImageImportHostnameAllowed(new URL('https://IMAGES.example.com/foo.png'), allowed),
+        true
+      );
+      assert.equal(
+        manager.isImageImportHostnameAllowed(new URL('https://attacker.example.com/foo.png'), allowed),
+        false
+      );
+      assert.equal(
+        manager.isImageImportHostnameAllowed(new URL('file:///etc/passwd'), allowed),
+        false
+      );
+    });
+  });
 });

From ffa58b3d607c544649cb3a260869253ddb31afde Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 13 May 2026 10:22:41 -0400
Subject: [PATCH 25/56] mergeback (#5409)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Latest merge prerelease 2026 05 (#5404)

* Fix choices IDs (#5379)

* Fix choices IDs

* Cleanup dots from ID values

* Update changelog

Co-authored-by: Robert Means <robert@apostrophecms.com>

---------

Co-authored-by: Robert Means <robert@apostrophecms.com>
(cherry picked from commit 9f458b5d9544d33239a0971b0050fff8bffe028a)

* Bump CLI dependencies (#5383)

(cherry picked from commit a5e1a4a35d01e09cbfd2c503370c95a8c2490867)

* Native browser shortcuts work again (#5384)

(cherry picked from commit b9b32bdd446add927c75d85e44d0a26814ba62b0)

* Pro 8838 charset (#5385)

* Removes encoding option and comments hardcoded encoding meta

* add changeset

* Response to first comments

(cherry picked from commit 08845c5f23d95ead552ab9743a878daf997793a1)

* Log aposResponse errors (#5386)

* log aposResponse errors

* add changeset

---------

Co-authored-by: Harouna Traoré <haroun@users.noreply.github.com>
(cherry picked from commit d45e27f6d66cd25fde0cf9c7199ee9d014fa1518)

* merge back the thanks (#5388)

(cherry picked from commit f3501f4de0448d4d0f8a01a1db4dc2fcf52c6218)

* ignore inline table array as draggable ui for windows (#5392)

(cherry picked from commit b360b05e8d4e479a36fcae45a5a6dbf820b8fba3)

* Layout focus orchestration (#5393)

(cherry picked from commit 77a2968206b0208883ff45de37feb43ba0b5d5b1)

* Bump dependencies (#5398)

* Bump dependencies
* Fix missing test await resulting in random failures

(cherry picked from commit 008417fa9814dba4899b53b9394778dbd46ccf3c)

* PRO-9467: remove defunct and nonpublic oembed providers and improve developer control to ensure security in the future (no risk exists today) (#5400)

* PRO-9467: remove defunct and nonpublic oembed providers and improve developer control to ensure security in the future (no risk exists today)

* allow newer twitter domain

* infogr.am still around

* facebook no longer does oembed

(cherry picked from commit e9b3bac692315414da47fe05202e8854dd31d7ee)

* Layout editable gap (#5397)

(cherry picked from commit bc8f7bed381d4462a082976dd92b8d7f28180a95)

* a11y fixes (#5401)

(cherry picked from commit 2e2f3b4b46301fc81c46200f837e794b247a9aef)

* clarifications (#5403)

(cherry picked from commit 13f2c69f219a47f82972d8fa9036deddd84223dc)

---------

Co-authored-by: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Co-authored-by: Robert Means <robert@apostrophecms.com>
Co-authored-by: haroun <1765606+haroun@users.noreply.github.com>
Co-authored-by: Harouna Traoré <haroun@users.noreply.github.com>
Co-authored-by: Stuart Romanek <stuart@apostrophecms.com>

* Latest security merge (#5407)

* Merge commit from fork

* Fixed arbitrary image URL import vulnerability in rich text impport API

* additional reporter

* Merge commit from fork

* Merge commit from fork

* Merge commit from fork

* secure the link URL field of image widgets

* credit

* Merge commit from fork

* fix xmp tag vulnerability

* thanks

* Merge commit from fork

* Security: a malicious full name containing HTML was executed as HTML in the tooltip displayed with an "i" icon next to the title of the current page, creating an
XSS attack risk versus other users. Since most projects permit users to change their full name (the "title" property), All projects with multiple users should be updated promptly
to close this vulnerability.

* changeset

* release only (changelogs formatted) (#5408)

---------

Co-authored-by: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Co-authored-by: Robert Means <robert@apostrophecms.com>
Co-authored-by: haroun <1765606+haroun@users.noreply.github.com>
Co-authored-by: Harouna Traoré <haroun@users.noreply.github.com>
Co-authored-by: Stuart Romanek <stuart@apostrophecms.com>
---
 packages/apostrophe-astro/CHANGELOG.md |  7 +++++
 packages/apostrophe-astro/package.json |  2 +-
 packages/apostrophe/CHANGELOG.md       | 34 +++++++++++++++++++++++
 packages/apostrophe/package.json       |  2 +-
 packages/cli/CHANGELOG.md              |  8 ++++++
 packages/cli/package.json              |  2 +-
 packages/launder/CHANGELOG.md          | 38 +++++++++++++++-----------
 packages/launder/package.json          |  2 +-
 packages/sanitize-html/CHANGELOG.md    | 10 +++++++
 packages/sanitize-html/package.json    |  2 +-
 10 files changed, 86 insertions(+), 21 deletions(-)

diff --git a/packages/apostrophe-astro/CHANGELOG.md b/packages/apostrophe-astro/CHANGELOG.md
index fbac106e56..95757b3190 100644
--- a/packages/apostrophe-astro/CHANGELOG.md
+++ b/packages/apostrophe-astro/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.12.0
+
+### Adds
+
+- Editors can now control the layout-widget gap through the styles system, both site-wide via a global `layoutGap` preset and per widget via a `gap` styles field. New Layout widget option `className` allows for additional CSS class names to be added to the widget Grid container.
+- Log aposResponse errors server side in the Astro process. Thanks to [Harouna Traore](https://github.com/haroun).
+
 ## 1.11.0 (2026-04-15)
 
 ### Adds
diff --git a/packages/apostrophe-astro/package.json b/packages/apostrophe-astro/package.json
index 1018711f74..eb8545a881 100644
--- a/packages/apostrophe-astro/package.json
+++ b/packages/apostrophe-astro/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@apostrophecms/apostrophe-astro",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "type": "module",
   "description": "Apostrophe integration for Astro",
   "repository": {
diff --git a/packages/apostrophe/CHANGELOG.md b/packages/apostrophe/CHANGELOG.md
index 6443d761f2..982e6952c0 100644
--- a/packages/apostrophe/CHANGELOG.md
+++ b/packages/apostrophe/CHANGELOG.md
@@ -1,5 +1,39 @@
 # Changelog
 
+## 4.30.0
+
+### Adds
+
+- Layout widget gap is now controllable through the styles system, both site-wide via a global `layoutGap` preset and per widget via a `gap` styles field. A new `className` option allows additional CSS classes to be added to the widget grid container.
+
+### Fixes
+
+- Fixed layout widget not regaining full focus when switching back to Edit content mode.
+- Fixed illegal HTML `id` attribute values generated by the admin UI.
+- Fixed orderable table array items dragging the entire floating window.
+- Fixed keyboard shortcuts for widget operations (copy, cut, paste, duplicate, remove) blocking the browser's native clipboard behavior when no widget was focused. Previously, selecting and copying text while logged in was intercepted unconditionally by the admin UI.
+- Removed duplicate `<meta charset>` tag from `outerLayoutBase.html` and standardized charset to `utf-8`.
+- Updated `apostrophe` and `oembetter` to remove oembed services that no longer support public access, eliminating them as a potential future XSS vector. New `minimumAllowlist` and `minimumEndpoints` options on `@apostrophecms/oembed` allow developers to prune the list further.
+
+### Security
+
+- **Password reset base URL requirement:** The password reset feature now refuses to operate unless `baseUrl` or `APOS_BASE_URL` is set, preventing a vulnerability where ApostropheCMS could be convinced to send emails with links to attacker-controlled sites. Only affects projects with `passwordReset: true` on the login module. Thanks to [SPIDY](https://github.com/Mujahidkhan525) for reporting.
+- **XSS via full name field:** A malicious full name containing HTML was executed in the page title tooltip in the admin bar, posing an XSS risk to other users. All multi-user projects should update promptly. Thanks to [Muhammad Uwais](https://github.com/MuhammadUwais) for reporting.
+- **XSS via image widget link URL:** Users with editing privileges could trigger arbitrary JavaScript via a `javascript:` URL in the image widget's link URL field. A migration is included to strip any such URLs already in the database. Thanks to [Muhammad Uwais](https://github.com/MuhammadUwais) for reporting.
+- **SSRF via rich text HTML import:** The rich text widget's HTML import feature no longer fetches images from arbitrary hosts, which could be used to probe internal networks or exfiltrate internal images. Configure `imageImportAllowedHostnames` on `@apostrophecms/rich-text-widget` to opt in. Thanks to [Yiğit Şengezer](https://github.com/yigitsengezer) and [Sainithin0309](https://github.com/Sainithin0309) for reporting.
+-  **the xmp tag could be used to pass forbidden markup through sanitize-html**, even when xmp itself. This was fixed in `sanitize-html` and the dependency was bumped. Thanks to [Vincenzo Turturro](https://github.com/sushi-gif) for reporting the vulnerability.
+- **the `linkHref` field of image widgets was an XSS vulnerability** because it did not use the `url` field type. This means that a user with editing privileges could potentially carry out XSS. In addition, we have updated the `launder` module to sanitize URLs more robustly for the `url` field type, and bumped that dependency. Also, a database migration is included to clean any XSS attacks that could be present in existing links. Thanks to [Muhammad Uwais](https://github.com/MuhammadUwais) for reporting the issue.
+
+### Accessibility
+
+- Corrected ARIA semantics on the top admin navigation bar.
+- Improved the document context title (admin bar middle group) and the underlying `AposContextMenu` machinery.
+- Improved the locale switcher (`AposLocalePicker`).
+- The Recently Edited Documents tray icon now exposes its action via `aria-label`.
+- Fixed `.apos-sr-only` so screen-reader-only content is correctly exposed to the accessibility tree.
+- Icon-only context-utility buttons in the admin bar tray (e.g. the global settings cog) now expose their action via `aria-label`.
+
+
 ## 4.29.0 (2026-04-15)
 
 ### Adds
diff --git a/packages/apostrophe/package.json b/packages/apostrophe/package.json
index f33c12137c..850b2c9d12 100644
--- a/packages/apostrophe/package.json
+++ b/packages/apostrophe/package.json
@@ -1,6 +1,6 @@
 {
   "name": "apostrophe",
-  "version": "4.29.0",
+  "version": "4.30.0",
   "description": "The Apostrophe Content Management System.",
   "main": "index.js",
   "scripts": {
diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md
index e6b0c80964..517d506fb7 100644
--- a/packages/cli/CHANGELOG.md
+++ b/packages/cli/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## 3.6.1
+
+### Security
+
+- Bump and clean up dependencies. This closes vulnerabilities in `uuid` and `fast-xml-parser` although they were not used in a sensitive or vulnerable way within ApostropheCMS. This also closes a vulnerability in `shelljs` which ould only be exploited if the developer could be convinced to enter malicious commands as part of their CLI input.
+- Passwords and starter kit URLs containing intentionally malicious punctuation cannot be used to run arbitrary shell commands. Because the CLI is only used by developers, this would always have been an "own goal" situation, however this does make the CLI more robust for scripted use. Thanks to [Nitro13urn](https://github.com/VadlaReddySai) for reporting the issue.
+
 ## 3.6.0 (2026-02-18)
 
 ### Adds
@@ -11,6 +18,7 @@
   - The `add` command now displays an error when run inside a hybrid Astro project, as it is not currently supported in that context.
 
   - The default starter kit is now `public-demo`
+
 - Validates the `shortName` argument in the `create` command to only allow letters, numbers, hyphens, and underscores, preventing potential command injection.
 
 ## 3.5.0 (2025-01-07)
diff --git a/packages/cli/package.json b/packages/cli/package.json
index c4f9221650..fbad8f1f39 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@apostrophecms/cli",
-  "version": "3.6.0",
+  "version": "3.6.1",
   "description": "Commandline generator and configurator for Apostrophe CMS",
   "main": "bin/apostrophe",
   "scripts": {
diff --git a/packages/launder/CHANGELOG.md b/packages/launder/CHANGELOG.md
index 02c1338be2..05384c6951 100644
--- a/packages/launder/CHANGELOG.md
+++ b/packages/launder/CHANGELOG.md
@@ -1,67 +1,73 @@
 # Changelog
 
+## 1.7.1
+
+### Security
+
+- `launder` now uses and exports the best available naughtyHref function for detecting malicious URLs. sanitize-html now depends on it, and apostrophe now uses type: 'url' for the link URL field of image widgets, which leverages it. Prior to this fix, it was possible for any user with editing privileges, including a contributor, to trigger arbitrary JavaScript via a javascript: URL in the link URL field of an image widget. A migration has been included to strip any such malicious URLs already present in the database. All users of apostrophe are encouraged to upgrade to get this security fix. Thanks to [Muhammad Uwais](https://github.com/MuhammadUwais) for reporting the issue.
+
 ## 1.7.0 - 2023-05-03
 
-* Modernize dependencies to correct installation warnings, and eliminate use of `var`.
+- Modernize dependencies to correct installation warnings, and eliminate use of `var`.
 
 ## 1.6.0 - 2023-03-06
 
-* `sms:` urls are now accepted. Thanks to [Ruben](https://github.com/reubendsouza) for this change.
+- `sms:` urls are now accepted. Thanks to [Ruben](https://github.com/reubendsouza) for this change.
 
 ## 1.5.1 - 2021-10-28
 
-* The `date` method now correctly returns `null` if the date argument is unparseable and the `def` parameter is explicitly `null`. As was always documented, a default of `undefined` still returns the current date.
+- The `date` method now correctly returns `null` if the date argument is unparseable and the `def` parameter is explicitly `null`. As was always documented, a default of `undefined` still returns the current date.
 
 ## 1.5.0
 
-* The `url` method now accepts a third argument, `httpsFix`. If it is `true` and the URL passed in has no protocol, the URL will be prepended with `https://` rather than `http://`.
+- The `url` method now accepts a third argument, `httpsFix`. If it is `true` and the URL passed in has no protocol, the URL will be prepended with `https://` rather than `http://`.
 
 ## 1.4.0
 
-* `tel:` urls are now accepted.
+- `tel:` urls are now accepted.
 
 ## 1.3.0
 
-* `booleanOrNull` accepts the string `'null'` as a synonym for `null`. Note that `'any'` was already accepted. `'null'` can be an attractive choice when the user will not see it in the query string and conflict with other uses of `'any'` is a concern.
+- `booleanOrNull` accepts the string `'null'` as a synonym for `null`. Note that `'any'` was already accepted. `'null'` can be an attractive choice when the user will not see it in the query string and conflict with other uses of `'any'` is a concern.
 
 ## 1.2.0
 
-* `idRegExp` option may be passed to change the rules for `launder.id`.
+- `idRegExp` option may be passed to change the rules for `launder.id`.
 
 ## 1.1.2
 
-* linting.
+- linting.
 
 ## 1.1.1
 
-* for improved bc, `launder.select` does not crash if some of the choices given to `select` are null or undefined. Although this is a developer error rather than a sanitization issue, versions prior to 1.1.0 did tolerate this situation, so 1.1.1 does so as well. Thanks to Anthony Tarlao for his code contributions, and to Michelin for making this fix possible via [Apostrophe Enterprise Support](https://apostrophecms.com/support/enterprise-support).
+- for improved bc, `launder.select` does not crash if some of the choices given to `select` are null or undefined. Although this is a developer error rather than a sanitization issue, versions prior to 1.1.0 did tolerate this situation, so 1.1.1 does so as well. Thanks to Anthony Tarlao for his code contributions, and to Michelin for making this fix possible via [Apostrophe Enterprise Support](https://apostrophecms.com/support/enterprise-support).
 
 ## 1.1.0
 
-* `launder.select` now handles numeric values for choices gracefully. Specifically, if the value passed in is a string, it will be validated as a match for a choice that is a number, as long as they have the same string representation, and the number (not the string) will be returned. Previously there was no match in this situation.
+- `launder.select` now handles numeric values for choices gracefully. Specifically, if the value passed in is a string, it will be validated as a match for a choice that is a number, as long as they have the same string representation, and the number (not the string) will be returned. Previously there was no match in this situation.
 
 Thanks to Michelin for making this possible via [Apostrophe Enterprise Support](https://apostrophecms.com/support/enterprise-support).
 
 ## 1.0.1
 
-* `launder.time` will now also accept a `.` (dot) as the separator (until now only `:` colon was recognized). Thanks to Lars Houmark.
+- `launder.time` will now also accept a `.` (dot) as the separator (until now only `:` colon was recognized). Thanks to Lars Houmark.
 
 ## 1.0.0
 
-* switched to a maintained, secure fork of lodash 3, declared 1.0.0 as this has been a stable part of Apostrophe for years.
+- switched to a maintained, secure fork of lodash 3, declared 1.0.0 as this has been a stable part of Apostrophe for years.
 
 ## 0.1.3
 
-* `launder.booleanOrNull` broken out from `launder.addBooleanFilterCriteria` so that you can get the tri-state value without modifying a criteria object.
+- `launder.booleanOrNull` broken out from `launder.addBooleanFilterCriteria` so that you can get the tri-state value without modifying a criteria object.
 
 ## 0.1.2
 
-* `launder.tags` also accepts a comma-separated string.
+- `launder.tags` also accepts a comma-separated string.
 
 ## 0.1.1
 
-* removed never-used and undocumented `parseTime` method.
+- removed never-used and undocumented `parseTime` method.
 
 ## 0.1.0
 
-* initial release. Based on stable code recently refactored from Apostrophe 0.5.x.
+- initial release. Based on stable code recently refactored from Apostrophe 0.5.x.
diff --git a/packages/launder/package.json b/packages/launder/package.json
index aa01b14a36..de42a61358 100644
--- a/packages/launder/package.json
+++ b/packages/launder/package.json
@@ -1,6 +1,6 @@
 {
   "name": "launder",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "A sanitize module for the people. Built for ApostropheCMS.",
   "main": "index.js",
   "scripts": {
diff --git a/packages/sanitize-html/CHANGELOG.md b/packages/sanitize-html/CHANGELOG.md
index 9661f24184..b5663fa2b9 100644
--- a/packages/sanitize-html/CHANGELOG.md
+++ b/packages/sanitize-html/CHANGELOG.md
@@ -1,5 +1,15 @@
 # Changelog
 
+## 2.17.4
+
+### Changes
+
+- `sanitize-html` and `launder` now share a single implementation of `naughtyHref`, based on that which previously existed in `sanitize-html`.
+
+### Security
+
+- Security vulnerability: the xmp tag could be used to pass forbidden markup through sanitize-html, even when xmp itself is not explicitly allowed All users of sanitize-html should update immediately. Thanks to [Vincenzo Turturro](https://github.com/sushi-gif) for reporting the vulnerability.
+
 ## 2.17.3 (2026-04-15)
 
 ### Security
diff --git a/packages/sanitize-html/package.json b/packages/sanitize-html/package.json
index fe401c0764..a73117759d 100644
--- a/packages/sanitize-html/package.json
+++ b/packages/sanitize-html/package.json
@@ -1,6 +1,6 @@
 {
   "name": "sanitize-html",
-  "version": "2.17.3",
+  "version": "2.17.4",
   "description": "Clean up user-submitted HTML, preserving allowlisted elements and allowlisted attributes on a per-element basis",
   "sideEffects": false,
   "main": "index.js",

From e52e1df071f5e1fc83bdbe169e63ff6241717b85 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 13 May 2026 15:16:29 -0400
Subject: [PATCH 26/56] mergeback (#5414)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Latest merge prerelease 2026 05 (#5404)

* Fix choices IDs (#5379)

* Fix choices IDs

* Cleanup dots from ID values

* Update changelog

Co-authored-by: Robert Means <robert@apostrophecms.com>

---------

Co-authored-by: Robert Means <robert@apostrophecms.com>
(cherry picked from commit 9f458b5d9544d33239a0971b0050fff8bffe028a)

* Bump CLI dependencies (#5383)

(cherry picked from commit a5e1a4a35d01e09cbfd2c503370c95a8c2490867)

* Native browser shortcuts work again (#5384)

(cherry picked from commit b9b32bdd446add927c75d85e44d0a26814ba62b0)

* Pro 8838 charset (#5385)

* Removes encoding option and comments hardcoded encoding meta

* add changeset

* Response to first comments

(cherry picked from commit 08845c5f23d95ead552ab9743a878daf997793a1)

* Log aposResponse errors (#5386)

* log aposResponse errors

* add changeset

---------

Co-authored-by: Harouna Traoré <haroun@users.noreply.github.com>
(cherry picked from commit d45e27f6d66cd25fde0cf9c7199ee9d014fa1518)

* merge back the thanks (#5388)

(cherry picked from commit f3501f4de0448d4d0f8a01a1db4dc2fcf52c6218)

* ignore inline table array as draggable ui for windows (#5392)

(cherry picked from commit b360b05e8d4e479a36fcae45a5a6dbf820b8fba3)

* Layout focus orchestration (#5393)

(cherry picked from commit 77a2968206b0208883ff45de37feb43ba0b5d5b1)

* Bump dependencies (#5398)

* Bump dependencies
* Fix missing test await resulting in random failures

(cherry picked from commit 008417fa9814dba4899b53b9394778dbd46ccf3c)

* PRO-9467: remove defunct and nonpublic oembed providers and improve developer control to ensure security in the future (no risk exists today) (#5400)

* PRO-9467: remove defunct and nonpublic oembed providers and improve developer control to ensure security in the future (no risk exists today)

* allow newer twitter domain

* infogr.am still around

* facebook no longer does oembed

(cherry picked from commit e9b3bac692315414da47fe05202e8854dd31d7ee)

* Layout editable gap (#5397)

(cherry picked from commit bc8f7bed381d4462a082976dd92b8d7f28180a95)

* a11y fixes (#5401)

(cherry picked from commit 2e2f3b4b46301fc81c46200f837e794b247a9aef)

* clarifications (#5403)

(cherry picked from commit 13f2c69f219a47f82972d8fa9036deddd84223dc)

---------

Co-authored-by: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Co-authored-by: Robert Means <robert@apostrophecms.com>
Co-authored-by: haroun <1765606+haroun@users.noreply.github.com>
Co-authored-by: Harouna Traoré <haroun@users.noreply.github.com>
Co-authored-by: Stuart Romanek <stuart@apostrophecms.com>

* Latest security merge (#5407)

* Merge commit from fork

* Fixed arbitrary image URL import vulnerability in rich text impport API

* additional reporter

* Merge commit from fork

* Merge commit from fork

* Merge commit from fork

* secure the link URL field of image widgets

* credit

* Merge commit from fork

* fix xmp tag vulnerability

* thanks

* Merge commit from fork

* Security: a malicious full name containing HTML was executed as HTML in the tooltip displayed with an "i" icon next to the title of the current page, creating an
XSS attack risk versus other users. Since most projects permit users to change their full name (the "title" property), All projects with multiple users should be updated promptly
to close this vulnerability.

* changeset

* release only (changelogs formatted) (#5408)

* allow oembetter to be released (#5412)

* release oembetter 1.2.0 (#5413)

* release oembetter 1.2.0

* left commit

---------

Co-authored-by: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Co-authored-by: Robert Means <robert@apostrophecms.com>
Co-authored-by: haroun <1765606+haroun@users.noreply.github.com>
Co-authored-by: Harouna Traoré <haroun@users.noreply.github.com>
Co-authored-by: Stuart Romanek <stuart@apostrophecms.com>
---
 packages/oembetter/CHANGELOG.md | 32 ++++++++++++++++++++++++++++++++
 packages/oembetter/package.json |  2 +-
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/packages/oembetter/CHANGELOG.md b/packages/oembetter/CHANGELOG.md
index 10c9aca99a..652f3ffec9 100644
--- a/packages/oembetter/CHANGELOG.md
+++ b/packages/oembetter/CHANGELOG.md
@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.2.0
+
+### Changes
+
+- remove obsolete services and those which no longer support anonymous oembed from the suggestedAllowlist and suggestedEndpoints, to ensure they do not become a security risk in the future
+- update the fast-xml-parser dependency
+
+### Adds
+
+- add x.com endpoint
+
 ## 1.1.4 (2024-08-07)
 
 - Followup to 1.1.3: also hardcode the YouTube oembed endpoint for sharing URLs (`youtu.be`).
@@ -33,67 +44,88 @@
 - Updates `cheerio` to the 1.0.0-rc version series to address a security vulnerability.
 
 ## 1.0.0
+
 renamed the `whitelist` and `suggestedWhitelist` properties to `allowlist` and `suggestedAllowlist`, respectively. Also introduced support for `options.headers`.
 
 ## 0.1.23
+
 workaround for YouTube bug in which video pages contain `http:` recommendations for oembed URLs, but an `http:` request is rejected with a 403 error. Force `https:` for YouTube.
 
 ## 0.1.22
+
 fixed URL parsing bugs impacting use of preconfigured endpoints that already contain some query string parameters.
 
 ## 0.1.21
+
 Updated links and information in the README.
 
 ## 0.1.20
+
 fixed a nuisance error that was appearing when Facebook was present but `window` was not the default object.
 
 ## 0.1.19
+
 unnecessary Facebook API logic was running on non-Facebook embeds due to a syntax mistake in 0.1.17.
 
 ## 0.1.18
+
 report HTTP errors properly rather than attempting to parse a nonexistent JSON body. Also, always try/catch when parsing JSON and report the exception as the callback error if necessary.
 
 ## 0.1.17
+
 Facebook oembed filter works regardless of whether Facebook's API has been initialized yet or not.
 
 ## 0.1.16
+
 Built in filter that handles Facebook oembed responses.
 
 ## 0.1.15
+
 allowlisted `facebook.com`, which has extensive oembed these days.
 
 ## 0.1.14
+
 bumped `cheerio` dependency to fix deprecation warnings. No behavior changes.
 
 ## 0.1.13
+
 relative URLs work with discovery. Thanks to Alejandro Torrado.
 
 ## 0.1.12
+
 (unchanged, npm publishing issue)
 
 ## 0.1.11
+
 don't crash when evaluating allowlists if `parsed.hostname` somehow manages not to be set.
 
 ## 0.1.10
+
 user agent string to please Facebook. Thanks to `equinox7`.
 
 ## 0.1.9
+
 the new `endpoints` option allows you to configure custom oembed API endpoints for services that don't advertise an endpoint or advertise it incorrectly.
 
 ## 0.1.7-0.1.8
+
 support SoundCloud. Added it to the suggested allowlist and added tolerance for their incorrect JSON content type.
 
 ## 0.1.6
+
 security improvement:
 reject all URLs that are not `http:` or `https:` completely, right up front. This means you don't have to protect against these obvious hacks in your `before` and `after` handlers.
 
 ## 0.1.5
+
 packaging issues, no changes.
 
 ## 0.1.4
+
 if the URL leads to a page with no oembed metadata, look for a `link rel="canonical"` tag and try that URL instead. Don't pursue this more than one step.
 
 Also, specify a user agent so that certain hosts don't give us watered-down HTML.
 
 ## 0.1.3
+
 added `youtu.be` to the suggested allowlist.
diff --git a/packages/oembetter/package.json b/packages/oembetter/package.json
index 63ee9c08c2..a92b916db9 100644
--- a/packages/oembetter/package.json
+++ b/packages/oembetter/package.json
@@ -1,6 +1,6 @@
 {
   "name": "oembetter",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "A modern oembed client. Allows you to register filters to improve or supply oembed support for sites that don't normally have it. You can also supply a allowlist of services you trust to prevent XSS attacks.",
   "main": "index.js",
   "scripts": {

From cf1a63984acd76437608969e82e1b4e095dca0e6 Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Tue, 19 May 2026 11:14:01 +0300
Subject: [PATCH 27/56] Fix focus trap on the last element in a modal (#5406)

* Fix focus trap on the last element in a modal

* Fix trap escaping edge cases
---
 .changeset/moody-poems-speak.md               |  7 ++
 .../modal/ui/apos/components/AposModal.vue    | 72 +++++++++++++------
 2 files changed, 56 insertions(+), 23 deletions(-)
 create mode 100644 .changeset/moody-poems-speak.md

diff --git a/.changeset/moody-poems-speak.md b/.changeset/moody-poems-speak.md
new file mode 100644
index 0000000000..8582885ec2
--- /dev/null
+++ b/.changeset/moody-poems-speak.md
@@ -0,0 +1,7 @@
+---
+"apostrophe": minor
+---
+
+Fixed an issue where using the Tab key to navigate within modals could incorrectly jump focus to a wrong element instead of the next input field.
+
+Fixed Tab navigation escaping out of modals when the form contained hidden sections or elements that became disabled after editing.
diff --git a/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue b/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue
index a83770ff35..055434d48e 100644
--- a/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue
+++ b/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue
@@ -16,7 +16,7 @@
       :data-apos-graph-key="props.graphKey || undefined"
       tabindex="0"
       @focus.capture="captureFocus"
-      @keyup.tab="onKeyup"
+      @keydown.tab="onKeydownTab"
       @keyup.esc="onKeyup"
     >
       <transition :name="transitionType">
@@ -216,6 +216,22 @@ const nonDraggableElements = [
   '.apos-input-array-inline-table'
 ];
 
+// Selector for focusable elements inside the modal. Used both at trap setup
+// and on every Tab keydown to refresh the cycle list, so that elements that
+// became disabled/hidden (e.g. Save when validation fails) or newly visible
+// are reflected.
+const focusableSelector = [
+  '[tabindex]',
+  '[href]',
+  'input',
+  'select',
+  'textarea',
+  'button',
+  '[data-apos-focus-priority]'
+]
+  .map(s => `${s}:not([tabindex="-1"]):not([disabled]):not([type="hidden"]):not([aria-hidden]):not(.apos-sr-only)`)
+  .join(', ');
+
 const resizeSides = [
   {
     edge: 'top',
@@ -476,13 +492,30 @@ onUnmounted(() => {
   }
 });
 
-function onKeyup(event) {
+// Handle Tab on keydown — before the browser moves focus.
+// Handling Tab on keyup is too late: the browser has already moved focus,
+// so the cycling logic sees the wrong activeElement.
+//
+// We also recompute the focusable list here on every Tab, scoped to
+// modalEl, instead of relying on the snapshot taken at trapFocus() time.
+function onKeydownTab(event) {
+  if (!shouldTrapFocus.value) {
+    return;
+  }
   if (!store.isOnTop(modalEl.value)) {
     return;
   }
+  if (event.target?.nodeName?.toLowerCase() === 'textarea') {
+    return;
+  }
+  const elements = getFocusableElements(modalEl.value);
+  // Keep the store snapshot consistent for other consumers.
+  store.updateModalData(props.modalData.id, { elementsToFocus: elements });
+  cycleElementsToFocus(event, elements);
+}
 
-  if (event.key === 'Tab') {
-    cycleElementsToFocus(event, props.modalData.elementsToFocus);
+function onKeyup(event) {
+  if (!store.isOnTop(modalEl.value)) {
     return;
   }
 
@@ -517,23 +550,20 @@ function captureFocus(e) {
   store.updateModalData(props.modalData.id, { focusedElement: e.target });
 }
 
+function getFocusableElements(rootEl) {
+  if (!rootEl) {
+    return [];
+  }
+  return [ ...rootEl.querySelectorAll(focusableSelector) ]
+    // a cheap "visible and in the DOM" condition,
+    // false positive expected for position: fixed and
+    // visually hidden elements (visible: hidden, opacity: 0, etc.)
+    .filter(el => el.offsetParent !== null);
+}
+
 async function trapFocus() {
   if (modalEl?.value) {
-    const elementSelectors = [
-      '[tabindex]',
-      '[href]',
-      'input',
-      'select',
-      'textarea',
-      'button',
-      '[data-apos-focus-priority]'
-    ];
-
-    const selector = elementSelectors
-      .map(addExcludingAttributes)
-      .join(', ');
-
-    const elementsToFocus = [ ...modalEl.value.querySelectorAll(selector) ];
+    const elementsToFocus = getFocusableElements(modalEl.value);
 
     store.updateModalData(props.modalData.id, { elementsToFocus });
 
@@ -556,10 +586,6 @@ async function trapFocus() {
     await nextTick();
     focusElement(props.modalData.focusedElement, firstElementToFocus);
   }
-
-  function addExcludingAttributes(element) {
-    return `${element}:not([tabindex="-1"]):not([disabled]):not([type="hidden"]):not([aria-hidden]):not(.apos-sr-only)`;
-  }
 }
 
 function close() {

From 167c2b5c1d63ba4b01726a2295b92e3f8dd94a31 Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Tue, 19 May 2026 11:31:58 +0300
Subject: [PATCH 28/56] Fix import-export noise (#5399)

* remove noise, switch to utils debug

* Fix tests

* Introduce debug option

* changelog

* Fix test sorting issue
---
 .changeset/shy-cougars-switch.md             |  5 +++++
 packages/import-export/index.js              |  5 ++++-
 packages/import-export/lib/formats/csv.js    |  2 --
 packages/import-export/lib/formats/gzip.js   | 10 ----------
 packages/import-export/lib/handlers.js       |  4 ++--
 packages/import-export/lib/methods/export.js |  8 ++++----
 packages/import-export/lib/methods/import.js |  2 +-
 packages/import-export/lib/methods/index.js  | 15 ++++++++++++++-
 packages/import-export/package.json          |  2 +-
 packages/import-export/test/import-page.js   | 16 ++++++++++++++++
 packages/import-export/test/index.js         | 14 ++++++++++++--
 11 files changed, 59 insertions(+), 24 deletions(-)
 create mode 100644 .changeset/shy-cougars-switch.md

diff --git a/.changeset/shy-cougars-switch.md b/.changeset/shy-cougars-switch.md
new file mode 100644
index 0000000000..498dfa5775
--- /dev/null
+++ b/.changeset/shy-cougars-switch.md
@@ -0,0 +1,5 @@
+---
+"@apostrophecms/import-export": patch
+---
+
+Debug logging is now disabled by default and can be enabled by setting the `debug: true` option on the `@apostrophecms/import-export` module, or by setting the `APOS_DEBUG_IMPORT_EXPORT=1` environment variable.
diff --git a/packages/import-export/index.js b/packages/import-export/index.js
index 8418461470..e58d0baca3 100644
--- a/packages/import-export/index.js
+++ b/packages/import-export/index.js
@@ -20,7 +20,10 @@ module.exports = {
       browser: true
     },
     preventUpdateAssets: false,
-    importDraftsOnlyDefault: false
+    importDraftsOnlyDefault: false,
+    // When true (or when the `APOS_DEBUG_IMPORT_EXPORT='1'` env var is set),
+    // verbose internal progress is logged.
+    debug: false
   },
   init(self) {
     self.formats = {
diff --git a/packages/import-export/lib/formats/csv.js b/packages/import-export/lib/formats/csv.js
index caa6779739..9b776df946 100644
--- a/packages/import-export/lib/formats/csv.js
+++ b/packages/import-export/lib/formats/csv.js
@@ -41,7 +41,6 @@ module.exports = {
       reader.on('error', reject);
       parser.on('error', reject);
       parser.on('end', () => {
-        console.info(`[csv] docs read from ${filepath}`);
         resolve({ docs });
       });
     });
@@ -74,7 +73,6 @@ module.exports = {
       stringifier.on('error', reject);
       writer.on('error', reject);
       writer.on('finish', () => {
-        console.info(`[csv] export file written to ${filepath}`);
         resolve();
       });
     });
diff --git a/packages/import-export/lib/formats/gzip.js b/packages/import-export/lib/formats/gzip.js
index 763874fb36..a70e53c337 100644
--- a/packages/import-export/lib/formats/gzip.js
+++ b/packages/import-export/lib/formats/gzip.js
@@ -24,10 +24,8 @@ module.exports = {
     if (filepath.endsWith(this.allowedExtension)) {
       exportPath = filepath.replace(this.allowedExtension, '');
 
-      console.info(`[gzip] extracting ${filepath} into ${exportPath}`);
       await extract(filepath, exportPath);
 
-      console.info(`[gzip] removing ${filepath}`);
       await remove(filepath);
     }
 
@@ -35,10 +33,6 @@ module.exports = {
     const attachmentsPath = path.join(exportPath, 'aposAttachments.json');
     const attachmentFilesPath = path.join(exportPath, 'attachments');
 
-    console.info(`[gzip] reading docs from ${docsPath}`);
-    console.info(`[gzip] reading attachments from ${attachmentsPath}`);
-    console.info(`[gzip] reading attachment files from ${attachmentFilesPath}`);
-
     const docs = await fsp.readFile(docsPath);
     const attachments = await fsp.readFile(attachmentsPath);
 
@@ -92,12 +86,10 @@ module.exports = {
       pack.on('error', reject);
 
       writeStream.on('finish', () => {
-        console.info(`[gzip] export file written to ${filepath}`);
         resolve(result);
       });
 
       for (const [ filename, content ] of Object.entries(data.json || {})) {
-        console.info(`[gzip] adding ${filename} to the tarball`);
         addTarEntry(pack, { name: filename }, content).catch(reject);
       }
 
@@ -107,8 +99,6 @@ module.exports = {
       })
         .then(() => {
           processAttachments(data.attachments, async (attachmentPath, name, size) => {
-            console.info(`[gzip] adding attachments/${name} to the tarball`);
-
             const readStream = fs.createReadStream(attachmentPath);
             const entryStream = pack.entry({
               name: `attachments/${name}`,
diff --git a/packages/import-export/lib/handlers.js b/packages/import-export/lib/handlers.js
index b262ae48ed..2083c31bad 100644
--- a/packages/import-export/lib/handlers.js
+++ b/packages/import-export/lib/handlers.js
@@ -73,7 +73,7 @@ module.exports = self => {
         if (!ids.length) {
           return;
         }
-        self.apos.util.debug(`Clearing ${ids.length} timer(s)`);
+        self.debug(`Clearing ${ids.length} timer(s)`);
         for (const key of ids) {
           const entry = self.timeoutIds[key];
           delete self.timeoutIds[key];
@@ -85,7 +85,7 @@ module.exports = self => {
             await entry.handler();
           }
         }
-        self.apos.util.debug('Timer(s) cleared');
+        self.debug('Timer(s) cleared');
       }
     }
   };
diff --git a/packages/import-export/lib/methods/export.js b/packages/import-export/lib/methods/export.js
index ae22d3fe7e..ac107ca6e7 100644
--- a/packages/import-export/lib/methods/export.js
+++ b/packages/import-export/lib/methods/export.js
@@ -510,7 +510,7 @@ module.exports = self => {
       const downloadPath = path.join('/exports', filename);
       const downloadUrl = `${self.apos.attachment.uploadfs.getUrl()}${downloadPath}`;
       const copyIn = util.promisify(self.apos.attachment.uploadfs.copyIn);
-      console.info(`[export] copying ${filepath} to ${self.apos.rootDir}/public/uploads${downloadPath}`);
+      self.debug(`[export] copying ${filepath} to ${self.apos.rootDir}/public/uploads${downloadPath}`);
       try {
         await copyIn(filepath, downloadPath);
       } catch (error) {
@@ -565,7 +565,7 @@ module.exports = self => {
 
       async function processAttachment([ name, url ]) {
         const temp = self.apos.attachment.uploadfs.getTempPath() + '/' + self.apos.util.generateId();
-        console.info(`[export] processing attachment ${name} temporarily stored in ${temp}`);
+        self.debug(`[export] processing attachment ${name} temporarily stored in ${temp}`);
         try {
           await copyOut(url, temp);
           const { size } = await fsp.stat(temp);
@@ -593,9 +593,9 @@ module.exports = self => {
     removeFromUploadFs(downloadPath, expiration) {
       const ms = expiration || 1000 * 60 * 10;
       const id = uniqueId();
-      console.info(`[export] removing ${self.apos.rootDir}/public/uploads${downloadPath} from uploadfs in ${ms / 1000 / 60} minutes`);
+      self.debug(`[export] removing ${self.apos.rootDir}/public/uploads${downloadPath} from uploadfs in ${ms / 1000 / 60} minutes`);
       const handler = () => {
-        console.info(`[export] removing ${self.apos.rootDir}/public/uploads${downloadPath} from uploadfs`);
+        self.debug(`[export] removing ${self.apos.rootDir}/public/uploads${downloadPath} from uploadfs`);
         delete self.timeoutIds[id];
         return new Promise((resolve, _reject) => {
           self.apos.attachment.uploadfs.remove(downloadPath, error => {
diff --git a/packages/import-export/lib/methods/import.js b/packages/import-export/lib/methods/import.js
index 4d8226226e..747f20001a 100644
--- a/packages/import-export/lib/methods/import.js
+++ b/packages/import-export/lib/methods/import.js
@@ -1272,7 +1272,7 @@ module.exports = self => {
     },
 
     async cleanExport(req) {
-      console.info('[import] cleaning export...');
+      self.debug('[import] cleaning export...');
       const exportPath = await self.getExportPath(
         self.apos.launder.string(req.body.exportId)
       );
diff --git a/packages/import-export/lib/methods/index.js b/packages/import-export/lib/methods/index.js
index 42cf98ce9b..1d1613270d 100644
--- a/packages/import-export/lib/methods/index.js
+++ b/packages/import-export/lib/methods/index.js
@@ -2,8 +2,21 @@ const fsp = require('node:fs/promises');
 const importMethods = require('./import.js');
 const exportMethods = require('./export.js');
 
+const noop = () => {};
+
 module.exports = self => {
+  const debugEnabled = self.options.debug === true ||
+    process.env.APOS_DEBUG_IMPORT_EXPORT === '1';
+  // Bind once at startup so each call site pays no per-call cost.
+  // No-op unless the module's `debug` option is `true` or the
+  // `APOS_DEBUG_IMPORT_EXPORT` env var is set.
+  const debug = debugEnabled
+    ? (...args) => self.apos.util.debug(...args)
+    : noop;
+
   return {
+    debug,
+
     registerFormats(formats = {}) {
       verifyFormats(formats);
 
@@ -56,7 +69,7 @@ module.exports = self => {
         } else {
           await fsp.unlink(filepath);
         }
-        console.info(`removed: ${filepath}`);
+        self.debug(`removed: ${filepath}`);
       } catch (err) {
         console.trace(err);
         self.apos.util.error(
diff --git a/packages/import-export/package.json b/packages/import-export/package.json
index 6cce8ddd00..ab3b56118c 100644
--- a/packages/import-export/package.json
+++ b/packages/import-export/package.json
@@ -8,7 +8,7 @@
     "stylelint": "stylelint ui/**/*.{scss,vue}",
     "lint": "npm run eslint && npm run stylelint",
     "mocha": "mocha",
-    "test": "(../../scripts/pro-if-needed && npm run lint && mocha --ignore=test/import-page.js && mocha test/import-page.js) ; ../../scripts/undo-pro-if-needed"
+    "test": "../../scripts/pro-if-needed && (npm run lint && mocha --ignore=test/import-page.js && mocha test/import-page.js); err=$?; ../../scripts/undo-pro-if-needed; exit $err"
   },
   "repository": {
     "type": "git",
diff --git a/packages/import-export/test/import-page.js b/packages/import-export/test/import-page.js
index 889ba357e8..0792d338b1 100644
--- a/packages/import-export/test/import-page.js
+++ b/packages/import-export/test/import-page.js
@@ -365,6 +365,7 @@ describe('@apostrophecms/import-export:import-page', function () {
           titleSortified: 'level 2 page 1',
           type: 'test-page',
           updatedAt: importedDocs.at(0).updatedAt,
+          importedAt: importedDocs.at(0).importedAt,
           updatedBy: {
             _id: null, // TODO: should be my user id
             title: 'System Task',
@@ -404,6 +405,7 @@ describe('@apostrophecms/import-export:import-page', function () {
           titleSortified: 'level 2 page 1',
           type: 'test-page',
           updatedAt: importedDocs.at(1).updatedAt,
+          importedAt: importedDocs.at(1).importedAt,
           updatedBy: {
             _id: null, // TODO: should be my user id
             title: 'System Task',
@@ -443,6 +445,7 @@ describe('@apostrophecms/import-export:import-page', function () {
           titleSortified: 'level 4 page 1',
           type: 'test-page',
           updatedAt: importedDocs.at(2).updatedAt,
+          importedAt: importedDocs.at(2).importedAt,
           updatedBy: {
             _id: null, // TODO: should be my user id
             title: 'System Task',
@@ -484,6 +487,7 @@ describe('@apostrophecms/import-export:import-page', function () {
           titleSortified: 'level 4 page 1',
           type: 'test-page',
           updatedAt: importedDocs.at(3).updatedAt,
+          importedAt: importedDocs.at(3).importedAt,
           updatedBy: {
             _id: null, // TODO: should be my user id
             title: 'System Task',
@@ -614,6 +618,7 @@ describe('@apostrophecms/import-export:import-page', function () {
           titleSortified: 'level 2 page 1',
           type: 'test-page',
           updatedAt: importedDocs.at(0).updatedAt,
+          importedAt: importedDocs.at(0).importedAt,
           updatedBy: {
             _id: null, // TODO: should be my user id
             title: 'System Task',
@@ -653,6 +658,7 @@ describe('@apostrophecms/import-export:import-page', function () {
           titleSortified: 'level 2 page 1',
           type: 'test-page',
           updatedAt: importedDocs.at(1).updatedAt,
+          importedAt: importedDocs.at(1).importedAt,
           updatedBy: {
             _id: null, // TODO: should be my user id
             title: 'System Task',
@@ -692,6 +698,7 @@ describe('@apostrophecms/import-export:import-page', function () {
           titleSortified: 'level 4 page 1',
           type: 'test-page',
           updatedAt: importedDocs.at(2).updatedAt,
+          importedAt: importedDocs.at(2).importedAt,
           updatedBy: {
             _id: null, // TODO: should be my user id
             title: 'System Task',
@@ -733,6 +740,7 @@ describe('@apostrophecms/import-export:import-page', function () {
           titleSortified: 'level 4 page 1',
           type: 'test-page',
           updatedAt: importedDocs.at(3).updatedAt,
+          importedAt: importedDocs.at(3).importedAt,
           updatedBy: {
             _id: null, // TODO: should be my user id
             title: 'System Task',
@@ -985,6 +993,7 @@ describe('@apostrophecms/import-export:import-page', function () {
           titleSortified: 'custom',
           type: 'custom-page',
           updatedAt: importedDocs.at(0).updatedAt,
+          importedAt: importedDocs.at(0).importedAt,
           updatedBy: {
             _id: null, // TODO: should be my user id
             title: 'System Task',
@@ -1024,6 +1033,10 @@ describe('@apostrophecms/import-export:import-page', function () {
           titleSortified: 'custom',
           type: 'custom-page',
           updatedAt: importedDocs.at(1).updatedAt,
+          // No `importedAt`: this is a `:previous` mode revision (a snapshot
+          // of the prior published state demoted by re-publishing). The
+          // import flow only stamps the documents it actually inserts or
+          // updates (draft and published), not the audit copy.
           updatedBy: {
             _id: null, // TODO: should be my user id
             title: 'System Task',
@@ -1063,6 +1076,7 @@ describe('@apostrophecms/import-export:import-page', function () {
           titleSortified: 'custom',
           type: 'custom-page',
           updatedAt: importedDocs.at(2).updatedAt,
+          importedAt: importedDocs.at(2).importedAt,
           updatedBy: {
             _id: null, // TODO: should be my user id
             title: 'System Task',
@@ -1102,6 +1116,7 @@ describe('@apostrophecms/import-export:import-page', function () {
           titleSortified: 'custom level 3 page 1',
           type: 'test-page',
           updatedAt: importedDocs.at(3).updatedAt,
+          importedAt: importedDocs.at(3).importedAt,
           updatedBy: {
             _id: null, // TODO: should be my user id
             title: 'System Task',
@@ -1143,6 +1158,7 @@ describe('@apostrophecms/import-export:import-page', function () {
           titleSortified: 'custom level 3 page 1',
           type: 'test-page',
           updatedAt: importedDocs.at(4).updatedAt,
+          importedAt: importedDocs.at(4).importedAt,
           updatedBy: {
             _id: null, // TODO: should be my user id
             title: 'System Task',
diff --git a/packages/import-export/test/index.js b/packages/import-export/test/index.js
index d4fe8bd213..a8941a93b3 100644
--- a/packages/import-export/test/index.js
+++ b/packages/import-export/test/index.js
@@ -1791,7 +1791,7 @@ describe('@apostrophecms/import-export', function() {
           }
         ];
 
-        assert.deepEqual(actual, expected);
+        assert.deepEqual(sortDocs(actual), sortDocs(expected));
       });
 
       it('should import and translate duplicated docs', async function () {
@@ -2112,8 +2112,18 @@ describe('@apostrophecms/import-export', function() {
           }
         ];
 
-        assert.deepEqual(actual, expected);
+        assert.deepEqual(sortDocs(actual), sortDocs(expected));
       });
     });
   }
 });
+
+// Sort an array of `{ type, aposLocale, title, modified }` projections by
+// a deterministic composite key so assertions don't depend on insert order.
+function sortDocs(docs) {
+  return [ ...docs ].sort((a, b) => {
+    const keyA = `${a.type}|${a.aposLocale}|${a.title}`;
+    const keyB = `${b.type}|${b.aposLocale}|${b.title}`;
+    return keyA < keyB ? -1 : keyA > keyB ? 1 : 0;
+  });
+}

From 2191c8a6f31633418bafa67ed0ea156ed5605ba0 Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Tue, 19 May 2026 12:51:08 +0300
Subject: [PATCH 29/56] A11y fixes part 3 (#5416)

* Fix editor modal a11y issues

* Fix manager a11y problems

* Fix page manager a11y problems

* fix media manager a11y issues

* fix a11y issues in style editor and user settings

* Fix login a11y issues

* eliminate a modal issue

* Remove bad aria in rich text

* Fix wrong aria in layout

* changelog

* Fix totp a11y issues, doc context state safety

* Fix uncaught error - popup blockers/tests
---
 .changeset/itchy-zoos-kick.md                 |  5 ++++
 .../components/AposBreadcrumbOperations.vue   |  1 -
 .../ui/apos/components/AposWidgetControls.vue |  1 -
 .../ui/apos/logic/AposDocContextMenu.js       |  8 +++---
 .../modules/@apostrophecms/i18n/i18n/en.json  |  3 +++
 .../components/AposMediaManagerEditor.vue     |  4 +--
 .../ui/apos/components/AposGridColumn.vue     |  1 -
 .../ui/apos/components/AposGridManager.vue    |  1 -
 .../login/ui/apos/components/TheAposLogin.vue | 12 +++++++--
 .../ui/apos/components/TheAposLoginHeader.vue |  6 ++---
 .../modal/ui/apos/components/AposModal.vue    |  2 ++
 .../ui/apos/components/AposModalTabs.vue      |  7 +++++-
 .../@apostrophecms/piece-type/index.js        |  3 ++-
 .../components/AposDocsManagerDisplay.vue     |  9 +++++--
 .../ui/apos/components/AposCellTitle.vue      |  1 +
 .../components/AposRichTextWidgetEditor.vue   | 25 ++++++++++++++++---
 .../apos/components/AposInputDateAndTime.vue  |  9 +++++--
 .../ui/apos/components/AposInputSelect.vue    |  1 +
 .../ui/apos/components/AposInputWrapper.vue   |  2 +-
 .../schema/ui/apos/components/AposSubform.vue |  1 +
 .../schema/ui/apos/logic/AposSubform.js       | 10 ++++++++
 .../ui/apos/components/TheAposStyles.vue      |  1 +
 .../ui/ui/apos/components/AposButtonGroup.vue |  2 +-
 .../ui/apos/components/AposCellLastEdited.vue |  2 +-
 .../ui/ui/apos/components/AposSelect.vue      |  1 +
 .../ui/ui/apos/components/AposSlat.vue        |  2 +-
 .../ui/apos/components/AposSubformPreview.vue |  2 +-
 .../ui/ui/apos/components/AposTreeHeader.vue  |  2 +-
 .../ui/ui/apos/scss/global/_theme.scss        |  1 +
 .../ui/apos/components/AposTotp.scss          |  2 +-
 .../ui/apos/components/AposTotp.vue           |  4 +--
 31 files changed, 98 insertions(+), 33 deletions(-)
 create mode 100644 .changeset/itchy-zoos-kick.md

diff --git a/.changeset/itchy-zoos-kick.md b/.changeset/itchy-zoos-kick.md
new file mode 100644
index 0000000000..2d0bf3e421
--- /dev/null
+++ b/.changeset/itchy-zoos-kick.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": patch
+---
+
+Fix more admin UI a11y issues
diff --git a/packages/apostrophe/modules/@apostrophecms/area/ui/apos/components/AposBreadcrumbOperations.vue b/packages/apostrophe/modules/@apostrophecms/area/ui/apos/components/AposBreadcrumbOperations.vue
index 46f6c7851e..2ecb0e1b0e 100644
--- a/packages/apostrophe/modules/@apostrophecms/area/ui/apos/components/AposBreadcrumbOperations.vue
+++ b/packages/apostrophe/modules/@apostrophecms/area/ui/apos/components/AposBreadcrumbOperations.vue
@@ -119,7 +119,6 @@ export default {
         icon: 'plus-icon',
         type: 'group',
         modifiers: [ 'small', 'inline' ],
-        role: 'menuitem',
         class: 'apos-area-modify-controls__button',
         iconSize: 16,
         disableFocus: !this.isFocused
diff --git a/packages/apostrophe/modules/@apostrophecms/area/ui/apos/components/AposWidgetControls.vue b/packages/apostrophe/modules/@apostrophecms/area/ui/apos/components/AposWidgetControls.vue
index 8745ae5d2c..9c282b691b 100644
--- a/packages/apostrophe/modules/@apostrophecms/area/ui/apos/components/AposWidgetControls.vue
+++ b/packages/apostrophe/modules/@apostrophecms/area/ui/apos/components/AposWidgetControls.vue
@@ -90,7 +90,6 @@ export default {
         icon: 'plus-icon',
         type: 'group',
         modifiers: [ 'small', 'inline' ],
-        role: 'menuitem',
         class: 'apos-area-modify-controls__button',
         iconSize: 16,
         disableFocus: !this.tabbable
diff --git a/packages/apostrophe/modules/@apostrophecms/doc-type/ui/apos/logic/AposDocContextMenu.js b/packages/apostrophe/modules/@apostrophecms/doc-type/ui/apos/logic/AposDocContextMenu.js
index 12e5ddfe86..e766ba75cb 100644
--- a/packages/apostrophe/modules/@apostrophecms/doc-type/ui/apos/logic/AposDocContextMenu.js
+++ b/packages/apostrophe/modules/@apostrophecms/doc-type/ui/apos/logic/AposDocContextMenu.js
@@ -273,13 +273,13 @@ export default {
       });
     },
     moduleName() {
-      if (apos.modules[this.context.type].action === apos.modules['@apostrophecms/page'].action) {
+      if (apos.modules[this.context.type]?.action === apos.modules['@apostrophecms/page'].action) {
         return '@apostrophecms/page';
       }
       return this.context.type;
     },
     moduleOptions() {
-      return apos.modules[this.moduleName];
+      return apos.modules[this.moduleName] || {};
     },
     isUpdateOperation() {
       return !!this.context._id;
@@ -482,7 +482,9 @@ export default {
       );
     },
     preview(doc) {
-      window.open(doc._url, '_blank').focus();
+      // window.open() returns null when a popup blocker intercepts it,
+      // so guard before calling focus().
+      window.open(doc._url, '_blank')?.focus();
     },
     async copy(doc) {
       // If there are changes warn the user before discarding them before
diff --git a/packages/apostrophe/modules/@apostrophecms/i18n/i18n/en.json b/packages/apostrophe/modules/@apostrophecms/i18n/i18n/en.json
index 0adcf393d2..e93b9a68f8 100644
--- a/packages/apostrophe/modules/@apostrophecms/i18n/i18n/en.json
+++ b/packages/apostrophe/modules/@apostrophecms/i18n/i18n/en.json
@@ -205,6 +205,7 @@
   "editImageRelationshipTitle": "Adjust Image",
   "editRelationship": "Edit Relationship",
   "editRelationshipFor": "Edit Relationship for {{ title }}",
+  "editSubform": "Edit {{ label }}",
   "editType": "Edit {{ type }}",
   "editWidget": "Edit Widget",
   "editWidgetForeignTooltip": "Click to edit this content in its natural context",
@@ -569,6 +570,7 @@
   "richTextHighlight": "Mark",
   "richTextHorizontalRule": "Horizontal Rule",
   "richTextHorizontalRuleDescription": "Add a horizontal separator",
+  "richTextEditor": "Rich text editor",
   "richTextInsertMenuHeading": "Insert element...",
   "richTextItalic": "Italic",
   "richTextLink": "Link",
@@ -632,6 +634,7 @@
   "slugInUse": "Slug already in use",
   "someoneElseTookControl": "{{ who }} took control of this document in another tab or window. A document can only be edited in one place at a time.",
   "splitCell": "Split Cell",
+  "status": "Status",
   "style": "Style",
   "styleAlignment": "Alignment",
   "styleBackground": "Background",
diff --git a/packages/apostrophe/modules/@apostrophecms/image/ui/apos/components/AposMediaManagerEditor.vue b/packages/apostrophe/modules/@apostrophecms/image/ui/apos/components/AposMediaManagerEditor.vue
index b6598bcaa1..46eba052d1 100644
--- a/packages/apostrophe/modules/@apostrophecms/image/ui/apos/components/AposMediaManagerEditor.vue
+++ b/packages/apostrophe/modules/@apostrophecms/image/ui/apos/components/AposMediaManagerEditor.vue
@@ -14,7 +14,7 @@
           v-if="activeMedia.attachment && activeMedia.attachment._urls"
           class="apos-media-editor__thumb"
           :src="activeMedia.attachment._urls[restoreOnly ? 'one-sixth' : 'one-third']"
-          :alt="activeMedia.description"
+          :alt="activeMedia.description || ''"
         >
       </div>
       <ul class="apos-media-editor__details">
@@ -484,7 +484,7 @@ export default {
 
     & {
       line-height: var(--a-line-tallest);
-      color: var(--a-base-4);
+      color: var(--a-base-2);
     }
   }
 
diff --git a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridColumn.vue b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridColumn.vue
index 87ff04278a..8b13324d76 100644
--- a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridColumn.vue
+++ b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridColumn.vue
@@ -6,7 +6,6 @@
     :style="itemStyles"
     :class="widgetStyles.classes"
     class="apos-layout__item"
-    role="gridcell"
     data-apos-test="aposLayoutItem"
     :data-id="item._id"
     :data-tablet-full="props.tabletFullItems[item._id] || false"
diff --git a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridManager.vue b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridManager.vue
index e776b9aab8..f7dc396f71 100644
--- a/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridManager.vue
+++ b/packages/apostrophe/modules/@apostrophecms/layout-widget/ui/apos/components/AposGridManager.vue
@@ -14,7 +14,6 @@
       :key="item._id"
       ref="items"
       class="apos-layout__item"
-      role="gridcell"
       data-apos-test="aposManageLayoutItem"
       :data-id="item._id"
       :style="{
diff --git a/packages/apostrophe/modules/@apostrophecms/login/ui/apos/components/TheAposLogin.vue b/packages/apostrophe/modules/@apostrophecms/login/ui/apos/components/TheAposLogin.vue
index 1bb2223ff3..a22a2a86bf 100644
--- a/packages/apostrophe/modules/@apostrophecms/login/ui/apos/components/TheAposLogin.vue
+++ b/packages/apostrophe/modules/@apostrophecms/login/ui/apos/components/TheAposLogin.vue
@@ -10,6 +10,7 @@
         <div
           v-if="showNav"
           class="apos-login__nav"
+          role="navigation"
         >
           <a
             href="#"
@@ -22,7 +23,13 @@
           >{{ $t('apostrophe:loginHome') }}</a>
         </div>
       </transition>
-      <div class="apos-login__wrapper">
+      <div
+        class="apos-login__wrapper"
+        role="main"
+      >
+        <h1 class="apos-sr-only">
+          {{ $t('apostrophe:login') }}
+        </h1>
         <transition
           name="fade-body"
           mode="out-in"
@@ -55,6 +62,7 @@
         <div
           v-show="loaded"
           class="apos-login__footer"
+          role="contentinfo"
         >
           <AposLogo class="apos-login__logo" />
           <label
@@ -234,7 +242,7 @@ export default {
       overflow: hidden;
       margin-right: 0;
       margin-left: auto;
-      color: var(--a-base-5);
+      color: var(--a-base-2);
       text-overflow: clip;
       white-space: nowrap;
     }
diff --git a/packages/apostrophe/modules/@apostrophecms/login/ui/apos/components/TheAposLoginHeader.vue b/packages/apostrophe/modules/@apostrophecms/login/ui/apos/components/TheAposLoginHeader.vue
index 6a78ab3f4a..1e1b18d679 100644
--- a/packages/apostrophe/modules/@apostrophecms/login/ui/apos/components/TheAposLoginHeader.vue
+++ b/packages/apostrophe/modules/@apostrophecms/login/ui/apos/components/TheAposLoginHeader.vue
@@ -112,16 +112,16 @@ export default {
       text-transform: capitalize;
       padding: 6px 12px;
       color: var(--a-white);
-      background: var(--a-success);
+      background: var(--a-success-dark);
       border-radius: 5px;
     }
 
     &--development {
-      background: var(--a-danger);
+      background: var(--a-danger-button-hover);
     }
 
     &--success, &--staging {
-      background: var(--a-warning);
+      background: var(--a-warning-dark);
     }
   }
 
diff --git a/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue b/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue
index 055434d48e..108bd194a3 100644
--- a/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue
+++ b/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue
@@ -67,6 +67,7 @@
             <header
               v-if="!modal.disableHeader"
               class="apos-modal__header"
+              role="none"
             >
               <div class="apos-modal__header__main">
                 <div
@@ -133,6 +134,7 @@
             <footer
               v-if="hasSlot('footer')"
               class="apos-modal__footer"
+              role="none"
             >
               <div class="apos-modal__footer__inner">
                 <slot name="footer" />
diff --git a/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModalTabs.vue b/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModalTabs.vue
index fb6b47f56c..fa5d67f5bb 100644
--- a/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModalTabs.vue
+++ b/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModalTabs.vue
@@ -1,15 +1,20 @@
 <template>
   <div class="apos-modal-tabs">
-    <ul class="apos-modal-tabs__tabs">
+    <ul
+      class="apos-modal-tabs__tabs"
+      role="tablist"
+    >
       <li
         v-for="tab in tabs"
         v-show="tab.isVisible !== false"
         :key="tab.name"
         class="apos-modal-tabs__tab"
+        role="presentation"
       >
         <button
           :id="tab.name"
           class="apos-modal-tabs__btn"
+          role="tab"
           :aria-selected="tab.name === current ? true : false"
           @click="selectTab"
         >
diff --git a/packages/apostrophe/modules/@apostrophecms/piece-type/index.js b/packages/apostrophe/modules/@apostrophecms/piece-type/index.js
index 43b0f05208..e4eb14cc8c 100644
--- a/packages/apostrophe/modules/@apostrophecms/piece-type/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/piece-type/index.js
@@ -73,7 +73,8 @@ module.exports = {
         },
         labels: {
           name: 'labels',
-          label: '',
+          label: 'apostrophe:status',
+          labelSrOnly: true,
           component: 'AposCellLabels'
         },
         updatedAt: {
diff --git a/packages/apostrophe/modules/@apostrophecms/piece-type/ui/apos/components/AposDocsManagerDisplay.vue b/packages/apostrophe/modules/@apostrophecms/piece-type/ui/apos/components/AposDocsManagerDisplay.vue
index a8c2645811..81df994620 100644
--- a/packages/apostrophe/modules/@apostrophecms/piece-type/ui/apos/components/AposDocsManagerDisplay.vue
+++ b/packages/apostrophe/modules/@apostrophecms/piece-type/ui/apos/components/AposDocsManagerDisplay.vue
@@ -4,8 +4,11 @@
       <tr>
         <th
           v-if="hasBatchOperations"
+          scope="col"
           class="apos-table__header"
-        />
+        >
+          <span class="apos-sr-only">{{ $t('apostrophe:selectAll') }}</span>
+        </th>
         <th
           v-for="header in headers"
           :key="header.label"
@@ -16,6 +19,7 @@
           <component
             :is="getEl(header)"
             class="apos-table__header-label"
+            :class="{ 'apos-sr-only': header.labelSrOnly }"
           >
             <component
               :is="icons[header.labelIcon]"
@@ -28,11 +32,12 @@
         </th>
         <th
           key="contextMenu"
+          scope="col"
           class="apos-table__header"
         >
           <component
             :is="getEl({})"
-            class="apos-table__header-label apos-is-hidden"
+            class="apos-table__header-label apos-sr-only"
           >
             {{ $t('apostrophe:moreOperations') }}
           </component>
diff --git a/packages/apostrophe/modules/@apostrophecms/recently-edited/ui/apos/components/AposCellTitle.vue b/packages/apostrophe/modules/@apostrophecms/recently-edited/ui/apos/components/AposCellTitle.vue
index f258d45650..af499ba285 100644
--- a/packages/apostrophe/modules/@apostrophecms/recently-edited/ui/apos/components/AposCellTitle.vue
+++ b/packages/apostrophe/modules/@apostrophecms/recently-edited/ui/apos/components/AposCellTitle.vue
@@ -15,6 +15,7 @@
       :href="item._url"
       class="apos-recently-edited__cell-link"
       data-apos-test="recently-edited-cell-link"
+      :aria-label="$t('apostrophe:preview')"
       @click.stop
     >
       <AposIndicator
diff --git a/packages/apostrophe/modules/@apostrophecms/rich-text-widget/ui/apos/components/AposRichTextWidgetEditor.vue b/packages/apostrophe/modules/@apostrophecms/rich-text-widget/ui/apos/components/AposRichTextWidgetEditor.vue
index 70aa682eb7..df58ce31c0 100644
--- a/packages/apostrophe/modules/@apostrophecms/rich-text-widget/ui/apos/components/AposRichTextWidgetEditor.vue
+++ b/packages/apostrophe/modules/@apostrophecms/rich-text-widget/ui/apos/components/AposRichTextWidgetEditor.vue
@@ -1,7 +1,6 @@
 <template>
   <div
     :id="widgetId"
-    :aria-controls="`insert-menu-${modelValue._id}`"
     :style="widgetStyles.inline"
     :class="widgetStyles.classes"
     @keyup="handleUIKeyup"
@@ -43,7 +42,12 @@
       ref="insertMenu"
       plugin-key="insertMenu"
       :class="insertMenuClasses"
-      :tippy-options="{ duration: 100, zIndex: 999, placement: 'bottom-start' }"
+      :tippy-options="{
+        duration: 100,
+        zIndex: 999,
+        placement: 'bottom-start',
+        aria: { content: null, expanded: false }
+      }"
       :should-show="showFloatingMenu"
       :editor="editor"
       role="listbox"
@@ -229,7 +233,11 @@ export default {
         inertia: true,
         placement: 'bottom',
         hideOnClick: false,
-        onHide: this.onBubbleHide
+        onHide: this.onBubbleHide,
+        aria: {
+          content: null,
+          expanded: false
+        }
       };
     },
     // Note that context menu class-list expects a string
@@ -264,7 +272,11 @@ export default {
         placement: 'top',
         offset: [ 0, 35 ],
         moveTransition: 'transform 0s ease-out',
-        appendTo: document.body
+        appendTo: document.body,
+        aria: {
+          content: null,
+          expanded: false
+        }
       };
     },
     moduleOptions() {
@@ -468,6 +480,11 @@ export default {
         autofocus: this.autofocus,
         onUpdate: this.editorUpdate,
         extensions,
+        editorProps: {
+          attributes: {
+            'aria-label': this.$t('apostrophe:richTextEditor')
+          }
+        },
 
         // The following events are triggered:
         //  - before the placeholder configuration function, when loading the page
diff --git a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposInputDateAndTime.vue b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposInputDateAndTime.vue
index fce0147520..44339fe433 100644
--- a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposInputDateAndTime.vue
+++ b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposInputDateAndTime.vue
@@ -15,13 +15,17 @@
           @toggle="toggle"
         />
         <input
+          :id="uid"
           v-model="date"
           class="apos-input apos-input--date"
           :class="classes"
           type="date"
           @change="setDateAndTime"
         >
-        <span class="apos-input--label">
+        <span
+          :id="`${uid}-at`"
+          class="apos-input--label"
+        >
           {{ $t('apostrophe:at') }}
         </span>
         <input
@@ -29,6 +33,7 @@
           class="apos-input apos-input--time"
           :class="classes"
           type="time"
+          :aria-labelledby="`${uid} ${uid}-at`"
           @change="setDateAndTime"
         >
       </div>
@@ -60,7 +65,7 @@ export default {
     &--disabled {
       background-color: var(--a-white);
       border-color: var(--a-base-8);
-      color: var(--a-base-4);
+      color: var(--a-base-2);
     }
 
     &--label {
diff --git a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposInputSelect.vue b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposInputSelect.vue
index 472566c453..d5f5568452 100644
--- a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposInputSelect.vue
+++ b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposInputSelect.vue
@@ -8,6 +8,7 @@
   >
     <template #body>
       <AposSelect
+        :uid="uid"
         :icon="icon"
         :choices="choices"
         :classes="classes"
diff --git a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposInputWrapper.vue b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposInputWrapper.vue
index a24e4d7573..0a809b6ae3 100644
--- a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposInputWrapper.vue
+++ b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposInputWrapper.vue
@@ -211,7 +211,7 @@ export default {
   & {
     margin: 0 0 $spacing-base;
     line-height: var(--a-line-tall);
-    color: var(--a-base-3);
+    color: var(--a-base-2);
   }
 }
 
diff --git a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposSubform.vue b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposSubform.vue
index d4ce0b010b..810cb28165 100644
--- a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposSubform.vue
+++ b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposSubform.vue
@@ -74,6 +74,7 @@
       </div>
       <button
         class="apos-subform__preview-trigger"
+        :aria-label="editSubformLabel"
         @click="toggleExpanded"
         @mouseenter="triggerHover = true"
         @mouseleave="triggerHover = false"
diff --git a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/logic/AposSubform.js b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/logic/AposSubform.js
index ee4e218f00..74e2d6731c 100644
--- a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/logic/AposSubform.js
+++ b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/logic/AposSubform.js
@@ -67,6 +67,16 @@ export default {
     },
     serverError() {
       return this.error || !!this.serverErrors;
+    },
+    subformLabel() {
+      return this.$t(
+        this.subform.label ||
+          this.subform.schema?.[0]?.label ||
+          'apostrophe:notAvailable'
+      );
+    },
+    editSubformLabel() {
+      return this.$t('apostrophe:editSubform', { label: this.subformLabel });
     }
   },
 
diff --git a/packages/apostrophe/modules/@apostrophecms/styles/ui/apos/components/TheAposStyles.vue b/packages/apostrophe/modules/@apostrophecms/styles/ui/apos/components/TheAposStyles.vue
index 5ff471d584..443a46cb22 100644
--- a/packages/apostrophe/modules/@apostrophecms/styles/ui/apos/components/TheAposStyles.vue
+++ b/packages/apostrophe/modules/@apostrophecms/styles/ui/apos/components/TheAposStyles.vue
@@ -19,6 +19,7 @@
                 v-if="currentPath.length"
                 key="btn"
                 class="apos-styles__header-navigate-btn"
+                :aria-label="$t('apostrophe:back')"
                 @mousedown.stop=""
                 @click="navigateLeft"
               >
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposButtonGroup.vue b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposButtonGroup.vue
index 8c9b99291c..c775f496ff 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposButtonGroup.vue
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposButtonGroup.vue
@@ -2,7 +2,7 @@
   <div
     class="apos-button-group"
     :class="modifierClass"
-    role="menubar"
+    role="toolbar"
   >
     <div class="apos-button-group__inner">
       <slot />
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposCellLastEdited.vue b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposCellLastEdited.vue
index cf79c94891..192a7d80c1 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposCellLastEdited.vue
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposCellLastEdited.vue
@@ -70,6 +70,6 @@ export default {
 
 <style lang="scss" scoped>
   .apos-table__cell-field--relative-time {
-    color: var(--a-base-4);
+    color: var(--a-base-2);
   }
 </style>
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSelect.vue b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSelect.vue
index 4e081c7406..e3b96a28b8 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSelect.vue
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSelect.vue
@@ -4,6 +4,7 @@
     :class="wrapperClasses"
   >
     <select
+      :id="uid"
       class="apos-input apos-input--select"
       :class="classes"
       :uid="uid"
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSlat.vue b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSlat.vue
index b17ecda436..7d5ca444ce 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSlat.vue
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSlat.vue
@@ -9,7 +9,7 @@
       'apos-is-selected': selected,
       'apos-is-disabled': disabled,
     }"
-    :aria-pressed="engaged"
+    :aria-current="engaged"
     role="listitem"
     :aria-labelledby="parent"
     @keydown.space="toggleEngage"
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSubformPreview.vue b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSubformPreview.vue
index 9b161c5c6e..816d763f01 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSubformPreview.vue
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSubformPreview.vue
@@ -140,7 +140,7 @@ function inferFieldValues(schema, values, $t) {
     & {
       display: inline-block;
       line-height: 1;
-      color: var(--a-base-3);
+      color: var(--a-base-2);
     }
   }
 }
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposTreeHeader.vue b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposTreeHeader.vue
index c9abd2d456..09e358e29b 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposTreeHeader.vue
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposTreeHeader.vue
@@ -120,7 +120,7 @@ export default {
 @import '../scss/shared/_table-rows';
 
 .apos-tree__header {
-  color: var(--a-base-3);
+  color: var(--a-base-2);
 }
 
 .apos-tree__header.apos-tree__header--hidden {
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/scss/global/_theme.scss b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/scss/global/_theme.scss
index 0a6b8f3142..87ec3085e8 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/scss/global/_theme.scss
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/scss/global/_theme.scss
@@ -3,6 +3,7 @@
   --a-danger: #eb443b;
   --a-danger-fade: #eb443b30;
   --a-success: #00bf9a;
+  --a-success-dark: #006650;
   --a-success-fade: #00bf9a30;
   --a-warning: #ffce00;
   --a-warning-dark: #a75c07;
diff --git a/packages/login-totp/ui/apos/components/AposTotp.scss b/packages/login-totp/ui/apos/components/AposTotp.scss
index d71596b733..dd76a91a01 100644
--- a/packages/login-totp/ui/apos/components/AposTotp.scss
+++ b/packages/login-totp/ui/apos/components/AposTotp.scss
@@ -47,7 +47,7 @@
 
     & {
       margin: 0;
-      color: var(--a-base-5);
+      color: var(--a-base-2);
     }
   }
 
diff --git a/packages/login-totp/ui/apos/components/AposTotp.vue b/packages/login-totp/ui/apos/components/AposTotp.vue
index c8c9cfadaa..1905237e0b 100644
--- a/packages/login-totp/ui/apos/components/AposTotp.vue
+++ b/packages/login-totp/ui/apos/components/AposTotp.vue
@@ -1,11 +1,11 @@
 <template>
   <div class="apos-totp">
-    <h3
+    <h2
       class="apos-totp__title"
       :class="{'apos-totp__title--success': token && success}"
     >
       {{ token ? $t('aposTotp:loginTitleSetup') : $t('aposTotp:loginTitle') }}
-    </h3>
+    </h2>
     <div
       v-if="token && !success"
       class="apos-totp__setup"

From b1c7c9bcf5bda0be5101abbff3ddd30cc7ed334a Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Wed, 20 May 2026 16:22:15 +0300
Subject: [PATCH 30/56] Fix initial focus trap issue, introduced with recent
 changes (#5426)

---
 .../modal/ui/apos/components/AposModal.vue          | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue b/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue
index 108bd194a3..ad23fc1be3 100644
--- a/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue
+++ b/packages/apostrophe/modules/@apostrophecms/modal/ui/apos/components/AposModal.vue
@@ -510,7 +510,12 @@ function onKeydownTab(event) {
   if (event.target?.nodeName?.toLowerCase() === 'textarea') {
     return;
   }
-  const elements = getFocusableElements(modalEl.value);
+  // Skip visually hidden elements when cycling — but only here, not in
+  // trapFocus. Initial focus runs while `renderingElements` is still true,
+  // which puts the content under display:none and makes every candidate's
+  // offsetParent null.
+  const elements = getFocusableElements(modalEl.value)
+    .filter(el => el.offsetParent !== null);
   // Keep the store snapshot consistent for other consumers.
   store.updateModalData(props.modalData.id, { elementsToFocus: elements });
   cycleElementsToFocus(event, elements);
@@ -556,11 +561,7 @@ function getFocusableElements(rootEl) {
   if (!rootEl) {
     return [];
   }
-  return [ ...rootEl.querySelectorAll(focusableSelector) ]
-    // a cheap "visible and in the DOM" condition,
-    // false positive expected for position: fixed and
-    // visually hidden elements (visible: hidden, opacity: 0, etc.)
-    .filter(el => el.offsetParent !== null);
+  return [ ...rootEl.querySelectorAll(focusableSelector) ];
 }
 
 async function trapFocus() {

From b7f9ad54b5696db0b71ab7f0f96e3da4d7abb1a0 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Tue, 26 May 2026 18:28:31 -0400
Subject: [PATCH 31/56] PRO-9542: fix the bug that breaks sitemaps for RA
 (#5433)

* PRO-9542: fix the bug that breaks sitemaps for RA

* see changeset
---
 .changeset/sparkly-experts-walk.md                         | 5 +++++
 .../modules/@apostrophecms/piece-page-type/index.js        | 7 +++++++
 2 files changed, 12 insertions(+)
 create mode 100644 .changeset/sparkly-experts-walk.md

diff --git a/.changeset/sparkly-experts-walk.md b/.changeset/sparkly-experts-walk.md
new file mode 100644
index 0000000000..b641817bfa
--- /dev/null
+++ b/.changeset/sparkly-experts-walk.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": patch
+---
+
+Sites with a custom filterByIndexPage method no longer experience failures in the sitemap module and potential creeping CPU performance penalties. A regression introduced with our static site support, but not specific to static sites.
diff --git a/packages/apostrophe/modules/@apostrophecms/piece-page-type/index.js b/packages/apostrophe/modules/@apostrophecms/piece-page-type/index.js
index 604e5753dd..b847966159 100644
--- a/packages/apostrophe/modules/@apostrophecms/piece-page-type/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/piece-page-type/index.js
@@ -427,7 +427,14 @@ module.exports = {
           return metadata;
         }
         const [ pm ] = metadata;
+        // indexQuery is designed to be called with the
+        // index page in question as req.data.page. To
+        // reuse it for URL metadata purposes we must
+        // meet that expectation
+        const pageWas = req.data.page;
+        req.data.page = doc;
         const query = self.indexQuery(req);
+        req.data.page = pageWas;
         const filters = await self.getFiltersWithChoices(query, { allCounts: true });
 
         // 1. Enumerate every filter + choice combination

From cef4f894272662dbd012813dabfe9f3bb01b3d9f Mon Sep 17 00:00:00 2001
From: haroun <1765606+haroun@users.noreply.github.com>
Date: Thu, 28 May 2026 15:25:36 +0200
Subject: [PATCH 32/56] Feature/prevent infinite redirects (#5429)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* log aposResponse errors

* add changeset

* prevent infinite redirects to external URLs

---------

Co-authored-by: Harouna Traoré <haroun@users.noreply.github.com>
---
 .changeset/twelve-paws-wink.md    |  5 ++
 packages/redirect/i18n/de.json    | 17 +++---
 packages/redirect/i18n/en.json    | 23 ++++----
 packages/redirect/i18n/es.json    | 23 ++++----
 packages/redirect/i18n/fr.json    | 17 +++---
 packages/redirect/i18n/it.json    | 17 +++---
 packages/redirect/i18n/pt-BR.json | 17 +++---
 packages/redirect/i18n/sk.json    | 23 ++++----
 packages/redirect/index.js        |  8 +++
 packages/redirect/test/index.js   | 98 +++++++++++++++++++++++++++++++
 10 files changed, 183 insertions(+), 65 deletions(-)
 create mode 100644 .changeset/twelve-paws-wink.md

diff --git a/.changeset/twelve-paws-wink.md b/.changeset/twelve-paws-wink.md
new file mode 100644
index 0000000000..3c523198ea
--- /dev/null
+++ b/.changeset/twelve-paws-wink.md
@@ -0,0 +1,5 @@
+---
+"@apostrophecms/redirect": minor
+---
+
+Prevent infinite redirects to external URLs
diff --git a/packages/redirect/i18n/de.json b/packages/redirect/i18n/de.json
index 507eddac69..0392104cc8 100644
--- a/packages/redirect/i18n/de.json
+++ b/packages/redirect/i18n/de.json
@@ -1,18 +1,19 @@
 {
   "301": "Permanent (Statuscode 301)",
   "302": "Vorübergehend (Statuscode 302)",
+  "errorInfiniteRedirect": "Endlosweiterleitung: {{ originalSlug }} darf nicht mit {{ external }} identisch sein.",
+  "external": "URL",
+  "forwardQuery": "Query-String weiterleiten",
+  "ignoreQuery": "Query-String bei der Übereinstimmung ignorieren",
   "label": "Weiterleitung",
-  "pluralLabel": "Weiterleitungen",
+  "newPage": "Seitentitel",
   "originalSlug": "Alte URL",
   "originalSlugHelp": "Format mit führendem Schrägstrich (z.B. /alte-url)",
+  "pluralLabel": "Weiterleitungen",
+  "statusCode": "Weiterleitungstyp",
+  "statusCodeHtmlHelp": "<ul><li>Verwenden Sie <strong>\"Vorübergehend\"</strong> für vorübergehende Weiterleitungen oder zu Testzwecken.</li><li>Verwenden Sie <strong>\"Permanent\"</strong> nach dem Testen, dies ist eine bewährte SEO-Praxis. ⚠️ Suchmaschinen werden diese zwischenspeichern, also überprüfen Sie dies sorgfältig.</li>",
   "title": "Beschreibung",
   "urlType": "Linktyp",
-  "urlTypeInternal": "Interne Seite",
   "urlTypeExternal": "URL",
-  "ignoreQuery": "Query-String bei der Übereinstimmung ignorieren",
-  "forwardQuery": "Query-String weiterleiten",
-  "newPage": "Seitentitel",
-  "external": "URL",
-  "statusCode": "Weiterleitungstyp",
-  "statusCodeHtmlHelp": "<ul><li>Verwenden Sie <strong>\"Vorübergehend\"</strong> für vorübergehende Weiterleitungen oder zu Testzwecken.</li><li>Verwenden Sie <strong>\"Permanent\"</strong> nach dem Testen, dies ist eine bewährte SEO-Praxis. ⚠️ Suchmaschinen werden diese zwischenspeichern, also überprüfen Sie dies sorgfältig.</li>"
+  "urlTypeInternal": "Interne Seite"
 }
diff --git a/packages/redirect/i18n/en.json b/packages/redirect/i18n/en.json
index 51d51af847..be5817fb10 100644
--- a/packages/redirect/i18n/en.json
+++ b/packages/redirect/i18n/en.json
@@ -1,18 +1,19 @@
 {
+  "301": "Permanent (status code 301)",
+  "302": "Temporary (status code 302)",
+  "errorInfiniteRedirect": "Infinite redirect: {{ originalSlug }} cannot be the same as {{ external }}",
+  "external": "URL",
+  "forwardQuery": "Forward query string",
+  "ignoreQuery": "Ignore query string when matching",
   "label": "Redirect",
-  "pluralLabel": "Redirects",
+  "newPage": "Page Title",
   "originalSlug": "Old URL",
   "originalSlugHelp": "Format with leading slash (e.g., /old-url)",
+  "pluralLabel": "Redirects",
+  "statusCode": "Redirect Type",
+  "statusCodeHtmlHelp": "<ul><li>Use <strong>\"Temporary\"</strong> for temporary redirects or for testing purposes.</li><li>Use <strong>\"Permanent\"</strong> after testing, this is an SEO best practice. ⚠️ Search engines will cache these, so check carefully.</li>",
   "title": "Description",
   "urlType": "Link Type",
-  "urlTypeInternal": "Internal Page",
   "urlTypeExternal": "URL",
-  "ignoreQuery": "Ignore query string when matching",
-  "forwardQuery": "Forward query string",
-  "newPage": "Page Title",
-  "external": "URL",
-  "statusCode": "Redirect Type",
-  "statusCodeHtmlHelp": "<ul><li>Use <strong>\"Temporary\"</strong> for temporary redirects or for testing purposes.</li><li>Use <strong>\"Permanent\"</strong> after testing, this is an SEO best practice. ⚠️ Search engines will cache these, so check carefully.</li>",
-  "302": "Temporary (status code 302)",
-  "301": "Permanent (status code 301)"
-}
\ No newline at end of file
+  "urlTypeInternal": "Internal Page"
+}
diff --git a/packages/redirect/i18n/es.json b/packages/redirect/i18n/es.json
index 6653696f12..7e2a83b442 100644
--- a/packages/redirect/i18n/es.json
+++ b/packages/redirect/i18n/es.json
@@ -1,18 +1,19 @@
 {
+    "301": "Permanentemente (Código de Estado 301)",
+    "302": "Temporalmente (Código de Estado 302)",
+    "errorInfiniteRedirect": "Redirección infinita: {{ originalSlug }} no puede ser igual que {{ external }}",
+    "external": "URL",
+    "forwardQuery":  "Reenviar la cadena de consulta.",
+    "ignoreQuery": "Ignorar la cadena de consulta al igualar el URL.",
     "label": "Redirección de URL",
-    "pluralLabel": "Redirecciones de URLs",
+    "newPage": "Título de la Página",
     "originalSlug": "URL Previo",
     "originalSlugHelp": "Formato con la barra (/) (ej., /url-previo)",
+    "pluralLabel": "Redirecciones de URLs",
+    "statusCode": "Tipo de Redirección",
+    "statusCodeHtmlHelp": "<ul><li>Use <strong>\"Temporalmente\"</strong> para redirecciones temporales o para propositos de evaluación y verificación.</li><li>Use <strong>\"Permanentemente\"</strong> despues de probar y evaluar, esta es considerada una buena práctica de SEO. ⚠️ Los buscadores guardan estos en su memoria, por lo cual es importante verficar detalladamente.</li>",
     "title": "Descripción",
     "urlType": "Tipo de Liga o Enlace",
-    "urlTypeInternal": "Página Interna",
     "urlTypeExternal": "URL",
-    "ignoreQuery": "Ignorar la cadena de consulta al igualar el URL.",
-    "forwardQuery":  "Reenviar la cadena de consulta.",
-    "newPage": "Título de la Página",
-    "external": "URL",
-    "statusCode": "Tipo de Redirección",
-    "statusCodeHtmlHelp": "<ul><li>Use <strong>\"Temporalmente\"</strong> para redirecciones temporales o para propositos de evaluación y verificación.</li><li>Use <strong>\"Permanentemente\"</strong> despues de probar y evaluar, esta es considerada una buena práctica de SEO. ⚠️ Los buscadores guardan estos en su memoria, por lo cual es importante verficar detalladamente.</li>",
-    "302": "Temporalmente (Código de Estado 302)",
-    "301": "Permanentemente (Código de Estado 301)"
-  }
\ No newline at end of file
+    "urlTypeInternal": "Página Interna"
+  }
diff --git a/packages/redirect/i18n/fr.json b/packages/redirect/i18n/fr.json
index 2c6fa6dc1d..8e55aafe2b 100644
--- a/packages/redirect/i18n/fr.json
+++ b/packages/redirect/i18n/fr.json
@@ -1,18 +1,19 @@
 {
   "301": "Permanent (code de statut 301)",
   "302": "Temporaire (code de statut 302)",
+  "errorInfiniteRedirect": "Redirection infinie : {{ originalSlug }} ne peut pas être identique à {{ external }}",
+  "external": "URL",
+  "forwardQuery": "Transférer la chaîne de requête",
+  "ignoreQuery": "Ignorer la chaîne de requête lors de la correspondance",
   "label": "Redirection",
-  "pluralLabel": "Redirections",
+  "newPage": "Titre de la page",
   "originalSlug": "Ancienne URL",
   "originalSlugHelp": "Format avec une barre oblique au début (par exemple, /ancienne-url)",
+  "pluralLabel": "Redirections",
+  "statusCode": "Type de redirection",
+  "statusCodeHtmlHelp": "<ul><li>Utilisez <strong>\"Temporaire\"</strong> pour les redirections temporaires ou à des fins de test.</li><li>Utilisez <strong>\"Permanent\"</strong> après test, c'est une meilleure pratique SEO. ⚠️ Les moteurs de recherche mettront cela en cache, vérifiez donc attentivement.</li>",
   "title": "Description",
   "urlType": "Type de lien",
-  "urlTypeInternal": "Page interne",
   "urlTypeExternal": "URL",
-  "ignoreQuery": "Ignorer la chaîne de requête lors de la correspondance",
-  "forwardQuery": "Transférer la chaîne de requête",
-  "newPage": "Titre de la page",
-  "external": "URL",
-  "statusCode": "Type de redirection",
-  "statusCodeHtmlHelp": "<ul><li>Utilisez <strong>\"Temporaire\"</strong> pour les redirections temporaires ou à des fins de test.</li><li>Utilisez <strong>\"Permanent\"</strong> après test, c'est une meilleure pratique SEO. ⚠️ Les moteurs de recherche mettront cela en cache, vérifiez donc attentivement.</li>"
+  "urlTypeInternal": "Page interne"
 }
diff --git a/packages/redirect/i18n/it.json b/packages/redirect/i18n/it.json
index fb574a5dbe..da7aeee711 100644
--- a/packages/redirect/i18n/it.json
+++ b/packages/redirect/i18n/it.json
@@ -1,18 +1,19 @@
 {
   "301": "Permanente (codice di stato 301)",
   "302": "Temporaneo (codice di stato 302)",
+  "errorInfiniteRedirect": "Reindirizzamento infinito: {{ originalSlug }} non può essere uguale a {{ external }}",
+  "external": "URL",
+  "forwardQuery": "Inoltra la stringa di query",
+  "ignoreQuery": "Ignora la stringa di query durante il matching",
   "label": "Reindirizza",
-  "pluralLabel": "Reindirizzamenti",
+  "newPage": "Titolo della pagina",
   "originalSlug": "URL vecchia",
   "originalSlugHelp": "Formato con barra iniziale (ad es., /vecchia-url)",
+  "pluralLabel": "Reindirizzamenti",
+  "statusCode": "Tipo di reindirizzamento",
+  "statusCodeHtmlHelp": "<ul><li>Utilizza <strong>\"Temporaneo\"</strong> per reindirizzamenti temporanei o per scopi di test.</li><li>Utilizza <strong>\"Permanente\"</strong> dopo aver effettuato dei test, questa è una buona pratica SEO. ⚠️ I motori di ricerca memorizzeranno questi, quindi controlla attentamente.</li>",
   "title": "Descrizione",
   "urlType": "Tipo di collegamento",
-  "urlTypeInternal": "Incolla un URL",
   "urlTypeExternal": "URL",
-  "ignoreQuery": "Ignora la stringa di query durante il matching",
-  "forwardQuery": "Inoltra la stringa di query",
-  "newPage": "Titolo della pagina",
-  "external": "URL",
-  "statusCode": "Tipo di reindirizzamento",
-  "statusCodeHtmlHelp": "<ul><li>Utilizza <strong>\"Temporaneo\"</strong> per reindirizzamenti temporanei o per scopi di test.</li><li>Utilizza <strong>\"Permanente\"</strong> dopo aver effettuato dei test, questa è una buona pratica SEO. ⚠️ I motori di ricerca memorizzeranno questi, quindi controlla attentamente.</li>"
+  "urlTypeInternal": "Incolla un URL"
 }
diff --git a/packages/redirect/i18n/pt-BR.json b/packages/redirect/i18n/pt-BR.json
index 8ccfbf49a2..cf32f48143 100644
--- a/packages/redirect/i18n/pt-BR.json
+++ b/packages/redirect/i18n/pt-BR.json
@@ -1,18 +1,19 @@
 {
   "301": "Permanente (código de status 301)",
   "302": "Temporário (código de status 302)",
+  "errorInfiniteRedirect": "Redirecionamento infinito: {{ originalSlug }} não pode ser o mesmo que {{ external }}",
+  "external": "URL",
+  "forwardQuery": "Encaminhar string de consulta",
+  "ignoreQuery": "Ignorar string de consulta ao combinar",
   "label": "Redirecionar",
-  "pluralLabel": "Redirecionamentos",
+  "newPage": "Título da Página",
   "originalSlug": "URL Antiga",
   "originalSlugHelp": "Formato com barra inicial (por exemplo, /antiga-url)",
+  "pluralLabel": "Redirecionamentos",
+  "statusCode": "Tipo de Redirecionamento",
+  "statusCodeHtmlHelp": "<ul><li>Use <strong>\"Temporário\"</strong> para redirecionamentos temporários ou para fins de teste.</li><li>Use <strong>\"Permanente\"</strong> após os testes, essa é uma boa prática de SEO. ⚠️ Os motores de busca vão armazenar em cache, então verifique com cuidado.</li>",
   "title": "Descrição",
   "urlType": "Tipo de Link",
-  "urlTypeInternal": "Página Interna",
   "urlTypeExternal": "URL",
-  "ignoreQuery": "Ignorar string de consulta ao combinar",
-  "forwardQuery": "Encaminhar string de consulta",
-  "newPage": "Título da Página",
-  "external": "URL",
-  "statusCode": "Tipo de Redirecionamento",
-  "statusCodeHtmlHelp": "<ul><li>Use <strong>\"Temporário\"</strong> para redirecionamentos temporários ou para fins de teste.</li><li>Use <strong>\"Permanente\"</strong> após os testes, essa é uma boa prática de SEO. ⚠️ Os motores de busca vão armazenar em cache, então verifique com cuidado.</li>"
+  "urlTypeInternal": "Página Interna"
 }
diff --git a/packages/redirect/i18n/sk.json b/packages/redirect/i18n/sk.json
index 3b5232bf58..42b99e6da6 100644
--- a/packages/redirect/i18n/sk.json
+++ b/packages/redirect/i18n/sk.json
@@ -1,18 +1,19 @@
 {
+    "301": "Trvalý (stavový kód 301)",
+    "302": "Dočasný (stavový kód 302)",
+    "errorInfiniteRedirect": "Nekonečné presmerovanie: {{ originalSlug }} nemôže byť to isté ako {{ external }}",
+    "external": "URL",
+    "forwardQuery": "Presmerovať reťazec dotazu.",
+    "ignoreQuery": "Ignorovať reťazec dotazu pri zhode.",
     "label": "Presmerovať",
-    "pluralLabel": "Presmerovania",
+    "newPage": "Názov stránky",
     "originalSlug": "Pôvodná URL",
     "originalSlugHelp": "Formát s lomítkom (napr., /povodna-url)",
+    "pluralLabel": "Presmerovania",
+    "statusCode": "Typ presmerovania",
+    "statusCodeHtmlHelp": "<ul><li>Použite <strong>\"Dočasný\"</strong> na dočasné presmerovanie alebo na testovacie účely.</li><li>Použite <strong>\"Trvalý\"</strong> až po testovaní - je to osvedčený postup SEO. ⚠️ Vyhľadávače ich zaznamenávajú, preto ich starostlivo skontrolujte.</li>",
     "title": "Popis",
     "urlType": "Typ odkazu",
-    "urlTypeInternal": "Interná URL stránka",
     "urlTypeExternal": "URL",
-    "ignoreQuery": "Ignorovať reťazec dotazu pri zhode.",
-    "forwardQuery": "Presmerovať reťazec dotazu.",
-    "newPage": "Názov stránky",
-    "external": "URL",
-    "statusCode": "Typ presmerovania",
-    "statusCodeHtmlHelp": "<ul><li>Použite <strong>\"Dočasný\"</strong> na dočasné presmerovanie alebo na testovacie účely.</li><li>Použite <strong>\"Trvalý\"</strong> až po testovaní - je to osvedčený postup SEO. ⚠️ Vyhľadávače ich zaznamenávajú, preto ich starostlivo skontrolujte.</li>",
-    "302": "Dočasný (stavový kód 302)",
-    "301": "Trvalý (stavový kód 301)"
-  }
\ No newline at end of file
+    "urlTypeInternal": "Interná URL stránka"
+  }
diff --git a/packages/redirect/index.js b/packages/redirect/index.js
index 301752962b..5560e070e4 100644
--- a/packages/redirect/index.js
+++ b/packages/redirect/index.js
@@ -28,6 +28,14 @@ module.exports = {
   handlers(self) {
     return {
       beforeSave: {
+        preventInfiniteRedirect(req, doc) {
+          if (doc.urlType === 'external' && doc.redirectSlug === doc.externalUrl) {
+            throw self.apos.error('invalid', req.t('aposRedirect:errorInfiniteRedirect', {
+              originalSlug: req.t('aposRedirect:originalSlug'),
+              external: req.t('aposRedirect:external')
+            }));
+          }
+        },
         slugPrefix(req, doc) {
           doc.slug = 'redirect-' + doc.redirectSlug;
 
diff --git a/packages/redirect/test/index.js b/packages/redirect/test/index.js
index 7ad6323150..c1371e232c 100644
--- a/packages/redirect/test/index.js
+++ b/packages/redirect/test/index.js
@@ -58,6 +58,104 @@ describe('@apostrophecms/redirect', function () {
     assert.equal(redirected, '<title>page 2</title>\n');
   });
 
+  it('should prevent insertion of infinite redirects to external URLs', async function() {
+    const req = apos.task.getReq();
+    const instance = redirectModule.newInstance();
+
+    const actual = async () => redirectModule.insert(req, {
+      ...instance,
+      title: 'infinite redirect',
+      urlType: 'external',
+      redirectSlug: '/page-1',
+      externalUrl: '/page-1'
+    });
+    const expected = {
+      name: 'invalid',
+      message: 'Infinite redirect: Old URL cannot be the same as URL'
+    };
+
+    await assert.rejects(actual, expected);
+  });
+
+  it('should prevent insertion of infinite redirects to external URLs including UTF8', async function() {
+    const req = apos.task.getReq();
+    const instance = redirectModule.newInstance();
+
+    const actual = async () => redirectModule.insert(req, {
+      ...instance,
+      title: 'infinite redirect',
+      urlType: 'external',
+      redirectSlug: '/page-✅',
+      externalUrl: '/page-✅'
+    });
+    const expected = {
+      name: 'invalid',
+      message: 'Infinite redirect: Old URL cannot be the same as URL'
+    };
+
+    await assert.rejects(actual, expected);
+  });
+
+  it('should prevent update if infinite redirect to external URLs is detected', async function() {
+    const req = apos.task.getReq();
+    const instance = redirectModule.newInstance();
+
+    const { _id } = await redirectModule.insert(req, {
+      ...instance,
+      title: 'infinite redirect',
+      urlType: 'external',
+      redirectSlug: '/page-1',
+      externalUrl: '/new-page-1'
+    });
+
+    const previousDraft = await redirectModule.findOneForEditing(
+      apos.task.getReq({ mode: 'draft' }),
+      { _id }
+    );
+
+    const actual = async () => redirectModule.update(req, {
+      ...previousDraft,
+      // redirectSlug: '/page-1',
+      externalUrl: '/page-1'
+    });
+    const expected = {
+      name: 'invalid',
+      message: 'Infinite redirect: Old URL cannot be the same as URL'
+    };
+
+    await assert.rejects(actual, expected);
+  });
+
+  it('should prevent insertion of infinite redirects to external URLs including UTF8', async function() {
+    const req = apos.task.getReq();
+    const instance = redirectModule.newInstance();
+
+    const { _id } = await redirectModule.insert(req, {
+      ...instance,
+      title: 'infinite redirect',
+      urlType: 'external',
+      redirectSlug: '/page-✅',
+      externalUrl: '/new-page-✅'
+    });
+
+    const previousDraft = await redirectModule.findOneForEditing(
+      apos.task.getReq({ mode: 'draft' }),
+      { _id }
+    );
+
+    const actual = async () => redirectModule.update(req, {
+      ...previousDraft,
+      // redirectSlug: '/page-✅',
+      externalUrl: '/page-✅'
+    });
+    const expected = {
+      name: 'invalid',
+      message: 'Infinite redirect: Old URL cannot be the same as URL'
+    };
+
+    await assert.rejects(actual, expected);
+  });
+
   it('query string matters by default', async function() {
     const req = apos.task.getReq();
     const instance = redirectModule.newInstance();

From 33bb4c0093c9edc0cd283994cfec108e8cc9c847 Mon Sep 17 00:00:00 2001
From: Robert Means <robert@apostrophecms.com>
Date: Tue, 2 Jun 2026 07:40:58 -0400
Subject: [PATCH 33/56] add draggable: false support to non-inline array field
 (#5435)

* add draggable: false support to non-inline array field

* Add changeset
---
 .changeset/array-draggable-false-non-inline.md       |  5 +++++
 .../schema/ui/apos/components/AposArrayEditor.vue    |  1 +
 .../ui/ui/apos/components/AposSlat.vue               | 12 +++++++++---
 .../ui/ui/apos/components/AposSlatList.vue           |  7 ++++++-
 4 files changed, 21 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/array-draggable-false-non-inline.md

diff --git a/.changeset/array-draggable-false-non-inline.md b/.changeset/array-draggable-false-non-inline.md
new file mode 100644
index 0000000000..8d3056d696
--- /dev/null
+++ b/.changeset/array-draggable-false-non-inline.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": minor
+---
+
+Added support for `draggable: false` on non-inline `array` schema fields. Previously this option was only respected when `inline: true`. When set on a standard (modal-based) array field, drag-and-drop reordering and keyboard reordering are now disabled in the array editor's slat list.
diff --git a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposArrayEditor.vue b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposArrayEditor.vue
index 52e67b9735..0fa812820a 100644
--- a/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposArrayEditor.vue
+++ b/packages/apostrophe/modules/@apostrophecms/schema/ui/apos/components/AposArrayEditor.vue
@@ -58,6 +58,7 @@
             class="apos-modal-array-items__items"
             :selected="currentId"
             :model-value="withLabels(next)"
+            :draggable="field.draggable !== false"
             @update:model-value="update"
             @select="select"
           />
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSlat.vue b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSlat.vue
index 7d5ca444ce..4068a51a01 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSlat.vue
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSlat.vue
@@ -8,6 +8,7 @@
       'apos-is-only-child': slatCount === 1,
       'apos-is-selected': selected,
       'apos-is-disabled': disabled,
+      'apos-is-not-draggable': !draggable,
     }"
     :aria-current="engaged"
     role="listitem"
@@ -22,7 +23,7 @@
   >
     <div class="apos-slat__main">
       <drag-icon
-        v-if="slatCount > 1"
+        v-if="slatCount > 1 && draggable"
         class="apos-slat__control apos-slat__control--drag"
         :size="13"
       />
@@ -158,6 +159,10 @@ export default {
     editorIcon: {
       type: String,
       default: null
+    },
+    draggable: {
+      type: Boolean,
+      default: true
     }
   },
   emits: [ 'engage', 'disengage', 'move', 'remove', 'item-clicked', 'select' ],
@@ -209,7 +214,7 @@ export default {
       return e.target.click();
     },
     toggleEngage() {
-      if (this.slatCount > 1) {
+      if (this.draggable && this.slatCount > 1) {
         if (this.engaged) {
           this.disengage();
         } else {
@@ -278,7 +283,8 @@ export default {
     }
 
     &.apos-slat-list__item--disabled,
-    &.apos-is-only-child {
+    &.apos-is-only-child,
+    &.apos-is-not-draggable {
       &:hover,
       &:active {
         cursor: default;
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSlatList.vue b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSlatList.vue
index 81a9c9e35d..8e4d0f09ba 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSlatList.vue
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/components/AposSlatList.vue
@@ -26,6 +26,7 @@
               'apos-input--error': duplicate
             }"
             :disabled="disabled"
+            :draggable="draggable"
             :engaged="engaged === item._id"
             :parent="listId"
             :slat-count="next.length"
@@ -87,6 +88,10 @@ export default {
     duplicate: {
       type: String,
       default: null
+    },
+    draggable: {
+      type: Boolean,
+      default: true
     }
   },
   emits: [ 'item-clicked', 'select', 'update:modelValue' ],
@@ -104,7 +109,7 @@ export default {
     dragOptions() {
       return {
         animation: 0,
-        disabled: this.disabled || this.next.length <= 1,
+        disabled: !this.draggable || this.disabled || this.next.length <= 1,
         ghostClass: 'apos-is-dragging'
       };
     }

From ddcdaa7ff6864cd55d6fef9dfdfca2eaf63a5969 Mon Sep 17 00:00:00 2001
From: RohithVangalla1 <reachrohithv@gmail.com>
Date: Tue, 2 Jun 2026 08:58:38 -0400
Subject: [PATCH 34/56] Make logged-in cookie name configurable via options
 (#5430)

The logged-in cookie name was hardcoded as 'loggedIn' with TODO comments
indicating it should be configurable. This is needed for deployments
where multiple Apostrophe instances share a domain (e.g., staging and
production on subpaths) and need distinct cookie names to avoid conflicts.

Changes:
- Added 'loggedInCookieName' option to the login module (defaults to
  'loggedIn' for backward compatibility)
- Replaced all hardcoded references with self.loggedInCookieName
- Removed the TODO comments

Usage:
  modules: {
    '@apostrophecms/login': {
      options: {
        loggedInCookieName: 'myAppLoggedIn'
      }
    }
  }

Addresses the TODO comments:
  'get cookie name from config'

Co-authored-by: Vangalla, Rohith <rohith.vangalla@optum.com>
---
 .../apostrophe/modules/@apostrophecms/login/index.js  | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/packages/apostrophe/modules/@apostrophecms/login/index.js b/packages/apostrophe/modules/@apostrophecms/login/index.js
index bdcf934859..e7ce55fb7c 100644
--- a/packages/apostrophe/modules/@apostrophecms/login/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/login/index.js
@@ -47,7 +47,7 @@ const { createId } = require('@paralleldrive/cuid2');
 const expressSession = require('express-session');
 
 const loginAttemptsNamespace = '@apostrophecms/loginAttempt';
-const loggedInCookieName = 'loggedIn';
+const DEFAULT_LOGGED_IN_COOKIE_NAME = 'loggedIn';
 
 module.exports = {
   cascades: [ 'requirements' ],
@@ -77,6 +77,7 @@ module.exports = {
     whoamiFields: []
   },
   async init(self) {
+    self.loggedInCookieName = self.options.loggedInCookieName || DEFAULT_LOGGED_IN_COOKIE_NAME;
     self.passport = new Passport();
     self.enableSerializeUsers();
     self.enableDeserializeUsers();
@@ -164,8 +165,7 @@ module.exports = {
             const name = self.apos.modules['@apostrophecms/express'].sessionOptions.name;
             req.res.header('set-cookie', expireCookie.serialize(name, 'deleted'));
 
-            // TODO: get cookie name from config
-            req.res.cookie(`${self.apos.shortName}.${loggedInCookieName}`, 'false');
+            req.res.cookie(`${self.apos.shortName}.${self.loggedInCookieName}`, 'false');
           }
         },
         async whoami(req) {
@@ -934,7 +934,7 @@ module.exports = {
       // Awaitable wrapper for req.login. An implementation detail of the login
       // route
       async passportLogin(req, user) {
-        const cookieName = `${self.apos.shortName}.${loggedInCookieName}`;
+        const cookieName = `${self.apos.shortName}.${self.loggedInCookieName}`;
         if (req.cookies[cookieName] !== 'true') {
           req.res.cookie(cookieName, 'true');
         }
@@ -1201,8 +1201,7 @@ module.exports = {
       addLoggedInCookie: {
         before: '@apostrophecms/i18n',
         middleware(req, res, next) {
-          // TODO: get cookie name from config
-          const cookieName = `${self.apos.shortName}.${loggedInCookieName}`;
+          const cookieName = `${self.apos.shortName}.${self.loggedInCookieName}`;
           if (req.user && req.cookies[cookieName] !== 'true') {
             res.cookie(cookieName, 'true');
           }

From f98aed76dc259171bdf3de014d4ee6855dc2a7d3 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Tue, 2 Jun 2026 09:47:17 -0400
Subject: [PATCH 35/56] Revert "Make logged-in cookie name configurable via
 options (#5430)" (#5436)

This reverts commit ddcdaa7ff6864cd55d6fef9dfdfca2eaf63a5969.
---
 .../apostrophe/modules/@apostrophecms/login/index.js  | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/packages/apostrophe/modules/@apostrophecms/login/index.js b/packages/apostrophe/modules/@apostrophecms/login/index.js
index e7ce55fb7c..bdcf934859 100644
--- a/packages/apostrophe/modules/@apostrophecms/login/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/login/index.js
@@ -47,7 +47,7 @@ const { createId } = require('@paralleldrive/cuid2');
 const expressSession = require('express-session');
 
 const loginAttemptsNamespace = '@apostrophecms/loginAttempt';
-const DEFAULT_LOGGED_IN_COOKIE_NAME = 'loggedIn';
+const loggedInCookieName = 'loggedIn';
 
 module.exports = {
   cascades: [ 'requirements' ],
@@ -77,7 +77,6 @@ module.exports = {
     whoamiFields: []
   },
   async init(self) {
-    self.loggedInCookieName = self.options.loggedInCookieName || DEFAULT_LOGGED_IN_COOKIE_NAME;
     self.passport = new Passport();
     self.enableSerializeUsers();
     self.enableDeserializeUsers();
@@ -165,7 +164,8 @@ module.exports = {
             const name = self.apos.modules['@apostrophecms/express'].sessionOptions.name;
             req.res.header('set-cookie', expireCookie.serialize(name, 'deleted'));
 
-            req.res.cookie(`${self.apos.shortName}.${self.loggedInCookieName}`, 'false');
+            // TODO: get cookie name from config
+            req.res.cookie(`${self.apos.shortName}.${loggedInCookieName}`, 'false');
           }
         },
         async whoami(req) {
@@ -934,7 +934,7 @@ module.exports = {
       // Awaitable wrapper for req.login. An implementation detail of the login
       // route
       async passportLogin(req, user) {
-        const cookieName = `${self.apos.shortName}.${self.loggedInCookieName}`;
+        const cookieName = `${self.apos.shortName}.${loggedInCookieName}`;
         if (req.cookies[cookieName] !== 'true') {
           req.res.cookie(cookieName, 'true');
         }
@@ -1201,7 +1201,8 @@ module.exports = {
       addLoggedInCookie: {
         before: '@apostrophecms/i18n',
         middleware(req, res, next) {
-          const cookieName = `${self.apos.shortName}.${self.loggedInCookieName}`;
+          // TODO: get cookie name from config
+          const cookieName = `${self.apos.shortName}.${loggedInCookieName}`;
           if (req.user && req.cookies[cookieName] !== 'true') {
             res.cookie(cookieName, 'true');
           }

From 950927d29b115eb97450f440119cc099359883a9 Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Tue, 2 Jun 2026 17:41:31 +0300
Subject: [PATCH 36/56] Feature create-apostrophe (#5425)

---
 .changeset/env-secrets-support.md             |   5 +
 .changeset/soft-hats-smile.md                 |   6 +
 .gitignore                                    |   1 +
 .../modules/@apostrophecms/express/index.js   |   2 +
 .../modules/@apostrophecms/uploadfs/index.js  |   3 +
 packages/cli/bin/apostrophe                   |   1 +
 packages/cli/lib/commands/create.js           | 205 +----
 packages/cli/lib/commands/telemetry.js        |  24 +
 packages/cli/package.json                     |   1 +
 packages/create-apostrophe/.mocharc.cjs       |   9 +
 packages/create-apostrophe/README.md          | 222 +++++
 .../bin/create-apostrophe.js                  |  20 +
 packages/create-apostrophe/eslint.config.js   |  19 +
 packages/create-apostrophe/package.json       |  45 +
 packages/create-apostrophe/src/cli/main.js    | 416 ++++++++++
 .../src/core/create-project.js                | 171 ++++
 packages/create-apostrophe/src/core/db.js     | 267 ++++++
 .../create-apostrophe/src/core/env-file.js    |  66 ++
 .../src/core/env-templates.js                 |  54 ++
 packages/create-apostrophe/src/core/errors.js |  36 +
 packages/create-apostrophe/src/core/kits.js   | 135 +++
 packages/create-apostrophe/src/core/pm.js     |  36 +
 packages/create-apostrophe/src/core/spawn.js  |  78 ++
 .../src/core/steps/admin-user.js              | 107 +++
 .../create-apostrophe/src/core/steps/clone.js |  70 ++
 .../src/core/steps/db-config.js               |  96 +++
 .../src/core/steps/install.js                 |  72 ++
 .../src/core/steps/sample-data.js             | 491 +++++++++++
 .../src/core/steps/scaffold.js                | 115 +++
 packages/create-apostrophe/src/core/store.js  | 113 +++
 .../create-apostrophe/src/core/validate.js    |  19 +
 packages/create-apostrophe/src/index.js       | 220 +++++
 .../src/telemetry/commands.js                 | 158 ++++
 .../src/telemetry/consent.js                  | 145 ++++
 .../create-apostrophe/src/telemetry/index.js  | 210 +++++
 .../create-apostrophe/src/telemetry/schema.js | 275 +++++++
 .../src/telemetry/transport.js                |  43 +
 .../src/telemetry/wire-config.js              |  10 +
 packages/create-apostrophe/src/ui/db-uri.js   |  15 +
 packages/create-apostrophe/src/ui/flow.js     | 774 ++++++++++++++++++
 packages/create-apostrophe/src/ui/links.js    |  62 ++
 packages/create-apostrophe/src/ui/prompts.js  | 113 +++
 packages/create-apostrophe/src/ui/render.js   | 212 +++++
 .../create-apostrophe/test/boundary.test.js   |  34 +
 .../create-apostrophe/test/cli/main.test.js   | 703 ++++++++++++++++
 .../test/core/admin-user.test.js              | 279 +++++++
 .../create-apostrophe/test/core/clone.test.js | 147 ++++
 .../test/core/contract.test.js                | 206 +++++
 .../test/core/create-project.test.js          | 253 ++++++
 .../test/core/db-config.test.js               | 259 ++++++
 .../create-apostrophe/test/core/db.test.js    | 361 ++++++++
 .../test/core/env-file.test.js                |  71 ++
 .../test/core/env-templates.test.js           |  46 ++
 .../test/core/install.test.js                 | 196 +++++
 .../create-apostrophe/test/core/kits.test.js  | 117 +++
 .../create-apostrophe/test/core/pm.test.js    |  55 ++
 .../test/core/sample-data.test.js             | 540 ++++++++++++
 .../test/core/scaffold.test.js                | 211 +++++
 .../create-apostrophe/test/core/spawn.test.js |  44 +
 .../create-apostrophe/test/core/store.test.js | 104 +++
 .../test/core/validate.test.js                |  19 +
 .../create-apostrophe/test/exports.test.js    |  44 +
 .../create-apostrophe/test/skeleton.test.js   |  26 +
 .../test/telemetry/commands.test.js           | 218 +++++
 .../test/telemetry/consent.test.js            | 206 +++++
 .../test/telemetry/firewall.test.js           | 268 ++++++
 .../test/telemetry/index.test.js              | 302 +++++++
 .../test/telemetry/schema.test.js             | 249 ++++++
 .../test/telemetry/transport.test.js          | 316 +++++++
 packages/db-connect/package.json              |   1 +
 packages/import-export-xlsx/package.json      |   2 +-
 packages/import-export/package.json           |   2 +-
 72 files changed, 10222 insertions(+), 199 deletions(-)
 create mode 100644 .changeset/env-secrets-support.md
 create mode 100644 .changeset/soft-hats-smile.md
 create mode 100644 packages/cli/lib/commands/telemetry.js
 create mode 100644 packages/create-apostrophe/.mocharc.cjs
 create mode 100644 packages/create-apostrophe/README.md
 create mode 100755 packages/create-apostrophe/bin/create-apostrophe.js
 create mode 100644 packages/create-apostrophe/eslint.config.js
 create mode 100644 packages/create-apostrophe/package.json
 create mode 100644 packages/create-apostrophe/src/cli/main.js
 create mode 100644 packages/create-apostrophe/src/core/create-project.js
 create mode 100644 packages/create-apostrophe/src/core/db.js
 create mode 100644 packages/create-apostrophe/src/core/env-file.js
 create mode 100644 packages/create-apostrophe/src/core/env-templates.js
 create mode 100644 packages/create-apostrophe/src/core/errors.js
 create mode 100644 packages/create-apostrophe/src/core/kits.js
 create mode 100644 packages/create-apostrophe/src/core/pm.js
 create mode 100644 packages/create-apostrophe/src/core/spawn.js
 create mode 100644 packages/create-apostrophe/src/core/steps/admin-user.js
 create mode 100644 packages/create-apostrophe/src/core/steps/clone.js
 create mode 100644 packages/create-apostrophe/src/core/steps/db-config.js
 create mode 100644 packages/create-apostrophe/src/core/steps/install.js
 create mode 100644 packages/create-apostrophe/src/core/steps/sample-data.js
 create mode 100644 packages/create-apostrophe/src/core/steps/scaffold.js
 create mode 100644 packages/create-apostrophe/src/core/store.js
 create mode 100644 packages/create-apostrophe/src/core/validate.js
 create mode 100644 packages/create-apostrophe/src/index.js
 create mode 100644 packages/create-apostrophe/src/telemetry/commands.js
 create mode 100644 packages/create-apostrophe/src/telemetry/consent.js
 create mode 100644 packages/create-apostrophe/src/telemetry/index.js
 create mode 100644 packages/create-apostrophe/src/telemetry/schema.js
 create mode 100644 packages/create-apostrophe/src/telemetry/transport.js
 create mode 100644 packages/create-apostrophe/src/telemetry/wire-config.js
 create mode 100644 packages/create-apostrophe/src/ui/db-uri.js
 create mode 100644 packages/create-apostrophe/src/ui/flow.js
 create mode 100644 packages/create-apostrophe/src/ui/links.js
 create mode 100644 packages/create-apostrophe/src/ui/prompts.js
 create mode 100644 packages/create-apostrophe/src/ui/render.js
 create mode 100644 packages/create-apostrophe/test/boundary.test.js
 create mode 100644 packages/create-apostrophe/test/cli/main.test.js
 create mode 100644 packages/create-apostrophe/test/core/admin-user.test.js
 create mode 100644 packages/create-apostrophe/test/core/clone.test.js
 create mode 100644 packages/create-apostrophe/test/core/contract.test.js
 create mode 100644 packages/create-apostrophe/test/core/create-project.test.js
 create mode 100644 packages/create-apostrophe/test/core/db-config.test.js
 create mode 100644 packages/create-apostrophe/test/core/db.test.js
 create mode 100644 packages/create-apostrophe/test/core/env-file.test.js
 create mode 100644 packages/create-apostrophe/test/core/env-templates.test.js
 create mode 100644 packages/create-apostrophe/test/core/install.test.js
 create mode 100644 packages/create-apostrophe/test/core/kits.test.js
 create mode 100644 packages/create-apostrophe/test/core/pm.test.js
 create mode 100644 packages/create-apostrophe/test/core/sample-data.test.js
 create mode 100644 packages/create-apostrophe/test/core/scaffold.test.js
 create mode 100644 packages/create-apostrophe/test/core/spawn.test.js
 create mode 100644 packages/create-apostrophe/test/core/store.test.js
 create mode 100644 packages/create-apostrophe/test/core/validate.test.js
 create mode 100644 packages/create-apostrophe/test/exports.test.js
 create mode 100644 packages/create-apostrophe/test/skeleton.test.js
 create mode 100644 packages/create-apostrophe/test/telemetry/commands.test.js
 create mode 100644 packages/create-apostrophe/test/telemetry/consent.test.js
 create mode 100644 packages/create-apostrophe/test/telemetry/firewall.test.js
 create mode 100644 packages/create-apostrophe/test/telemetry/index.test.js
 create mode 100644 packages/create-apostrophe/test/telemetry/schema.test.js
 create mode 100644 packages/create-apostrophe/test/telemetry/transport.test.js

diff --git a/.changeset/env-secrets-support.md b/.changeset/env-secrets-support.md
new file mode 100644
index 0000000000..5c79300289
--- /dev/null
+++ b/.changeset/env-secrets-support.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": minor
+---
+
+The session secret and the uploadfs `disabledFileKey` can now be supplied via the `APOS_SESSION_SECRET` and `APOS_UPLOADFS_DISABLED_FILE_KEY` environment variables. As with other Apostrophe environment variables, these take precedence over the corresponding `app.js` configuration.
diff --git a/.changeset/soft-hats-smile.md b/.changeset/soft-hats-smile.md
new file mode 100644
index 0000000000..3a7897cf1d
--- /dev/null
+++ b/.changeset/soft-hats-smile.md
@@ -0,0 +1,6 @@
+---
+"@apostrophecms/cli": minor
+---
+
+**Breaking:** `apos create` is now an interactive guided installer (it delegates to `create-apostrophe`). The `<shortname>` positional argument and the `--starter` and `--mongodb-uri` options have been removed - project name, starter kit, and database are now chosen through prompts. For scripted installs, use `npm create apostrophe@latest -- --unattended` instead.
+
diff --git a/.gitignore b/.gitignore
index e88b2189a4..186dae1605 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,4 @@ coverage/
 .nyc_output
 claude-tools/logs/
 .claude
+specs/
diff --git a/packages/apostrophe/modules/@apostrophecms/express/index.js b/packages/apostrophe/modules/@apostrophecms/express/index.js
index 85165f6b04..00cc95f503 100644
--- a/packages/apostrophe/modules/@apostrophecms/express/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/express/index.js
@@ -579,6 +579,8 @@ module.exports = {
           name: self.apos.shortName + '.sid',
           cookie: {}
         });
+        // Env overrides config, per Apostrophe convention.
+        sessionOptions.secret = process.env.APOS_SESSION_SECRET || sessionOptions.secret;
         _.defaults(sessionOptions.cookie, {
           path: '/',
           httpOnly: true,
diff --git a/packages/apostrophe/modules/@apostrophecms/uploadfs/index.js b/packages/apostrophe/modules/@apostrophecms/uploadfs/index.js
index 9353fe4340..694d7df4a0 100644
--- a/packages/apostrophe/modules/@apostrophecms/uploadfs/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/uploadfs/index.js
@@ -41,6 +41,9 @@ module.exports = {
         const uploadfsSettings = {};
         _.merge(uploadfsSettings, uploadfsDefaultSettings);
         _.merge(uploadfsSettings, options);
+        if (process.env.APOS_UPLOADFS_DISABLED_FILE_KEY) {
+          uploadfsSettings.disabledFileKey = process.env.APOS_UPLOADFS_DISABLED_FILE_KEY;
+        }
         if (process.env.APOS_S3_BUCKET) {
           _.merge(uploadfsSettings, {
             backend: 's3',
diff --git a/packages/cli/bin/apostrophe b/packages/cli/bin/apostrophe
index f6e40c2c6b..deff0db6d3 100755
--- a/packages/cli/bin/apostrophe
+++ b/packages/cli/bin/apostrophe
@@ -15,6 +15,7 @@ async function execute () {
   util.checkDependencies();
 
   require('../lib/commands/create')(program);
+  require('../lib/commands/telemetry')(program);
   require('../lib/commands/add')(program, versionInfo.core);
 
   await confUtils.checkConf();
diff --git a/packages/cli/lib/commands/create.js b/packages/cli/lib/commands/create.js
index c7120ab7c0..216bf4db2c 100644
--- a/packages/cli/lib/commands/create.js
+++ b/packages/cli/lib/commands/create.js
@@ -1,202 +1,13 @@
-require('shelljs/global');
-// Utilities from shelljs
-/* globals cd rm */
-const prompts = require('prompts');
-const path = require('path');
-const util = require('../util');
-const config = require('../../config');
-const fs = require('fs');
-const { stripIndent } = require('common-tags');
+// Thin delegate: hands off to create-apostrophe's guided installer. Owns
+// no UI of its own — Commander supplies `--help` for this subcommand.
 
 module.exports = function (program) {
   program
-    .command('create <shortname-without-spaces>')
-    .description(
-      stripIndent`
-      Create an Apostrophe project (using the apostrophe essentials starter kit by default).
-      Example: \`apos create my-website\`
-    `
-    )
-    .option(
-      '--starter <url>',
-      'Use a specific git repository to use as the project starter.\n You can also use the short name of any Apostrophe starter kit, e.g. "ecommerce"'
-    )
-    .option(
-      '--mongodb-uri <url>',
-      'Add a connection string to connect to a hosted MongoDB instance.'
-    )
-    .action(async function (shortName, options) {
-      if (!/^[\w-]+$/.test(shortName)) {
-        await util.error('create', 'The shortname must only contain letters, numbers, hyphens, and underscores.');
-        return false;
-      }
-
-      // If options.starter is undefined, use config.BOILERPLATE
-      const input = options.starter ? options.starter : config.BOILERPLATE;
-
-      // Check for complete repo URL, starterkit name, or incomplete URL fallback
-      let boilerplateUrl;
-      if (/^\w+:/.test(input)) {
-        boilerplateUrl = input;
-      } else if (input.includes('/')) {
-        boilerplateUrl = `https://github.com/${
-          input.startsWith('/') ? input.slice(1) : input
-        }`;
-      } else {
-        boilerplateUrl = `https://github.com/apostrophecms/starter-kit-${input}.git`;
-      }
-      util.log(
-        'create',
-        `Grabbing the ${boilerplateUrl} starter from Github [1/4]`
-      );
-
-      // Clone the boilerplate project
-      if ((await util.spawnSafe('git', [ 'clone', boilerplateUrl, shortName ])).code !== 0) {
-        await util.error('create', 'Error cloning starter code.');
-        return false;
-      }
-
-      cd(shortName);
-
-      // Remove the initial .git directory.
-      rm('-rf', '.git/');
-
-      // Auto-detect Astro projects by checking for backend directory
-      const isAstroProject = fs.existsSync('backend');
-      const backendPath = isAstroProject ? 'backend' : '.';
-      const resolvePath = (relativePath) => {
-        if (backendPath === '.') {
-          return relativePath;
-        }
-        return path.join(backendPath, relativePath);
-      };
-
-      util.log('create', `Adding your project shortname (${shortName}) [2/4]`);
-
-      // Do some token replaces to rename the project
-      // replaces the shortname in app.js
-      replaceInConfig(/(shortName:).*?,/gi, `$1 '${shortName}',`, resolvePath);
-      // replaces the shortname in package.json
-      replaceInConfig(/("name":).*?,/g, `$1 "${shortName}",`, resolvePath);
-
-      // Generate session secret
-      let secret = util.secret();
-
-      const expressIndexPath = resolvePath('lib/modules/apostrophe-express/index.js');
-      if (fs.existsSync(expressIndexPath)) {
-        util.replaceInFiles(
-          [ expressIndexPath ],
-          /secret: undefined/,
-          `secret: '${secret}'`
-        );
-      }
-
-      // Set disabledFileKey for uploadfs
-      secret = util.secret();
-
-      util.replaceInFiles(
-        [ resolvePath('app.js') ],
-        /disabledFileKey: undefined/,
-        `disabledFileKey: '${secret}'`
-      );
-
-      // Remove lock file and install packages.
-      util.log('create', 'Installing packages [3/4]');
-
-      const packageLockPath = resolvePath('package-lock.json');
-      const yarnLockPath = resolvePath('yarn.lock');
-
-      if (fs.existsSync(packageLockPath)) {
-        rm(packageLockPath);
-      }
-      if (fs.existsSync(yarnLockPath)) {
-        rm(yarnLockPath);
-      }
-
-      // Run npm install in the appropriate directories
-      if (isAstroProject) {
-        // Install backend packages
-        try {
-          await util.spawnWithSpinner('npm install --prefix backend', {
-            spinnerMessage:
-              'Installing backend packages. This will take a little while...'
-          });
-        } catch (error) {
-          await util.error('create', 'Error installing backend packages');
-
-          console.error(error);
-        }
-
-        // Install frontend packages
-        try {
-          await util.spawnWithSpinner('npm install --prefix frontend', {
-            spinnerMessage:
-              'Installing frontend packages. This will take a little while...'
-          });
-        } catch (error) {
-          await util.error('create', 'Error installing frontend packages');
-
-          console.error(error);
-        }
-      } else {
-        try {
-          await util.spawnWithSpinner('npm install', {
-            spinnerMessage:
-              'Installing packages. This will take a little while...'
-          });
-        } catch (error) {
-          await util.error('create', 'Error installing packages');
-
-          console.error(error);
-        }
-      }
-
-      const cwd = process.cwd();
-      const aposPath = path.join(cwd, resolvePath('node_modules/apostrophe'));
-
-      // Append the installed Apostrophe version, if in an active project.
-      if (!fs.existsSync(aposPath)) {
-        await util.error('create', 'Error installing new project packages.');
-        return false;
-      }
-      const version = require(`${aposPath}/package.json`).version;
-      await util.getMajorVersion('create', version);
-
-      // Create an admin user (note this will prompt for password)
-      util.log('create', 'Creating an admin user [4/4]');
-      util.log('create', 'Choose a password for the admin user');
-
-      const response = await prompts({
-        type: 'password',
-        name: 'pw',
-        message: '🔏 Please enter a password:'
-      });
-
-      const userTask = '@apostrophecms/user:add';
-      const appJsPath = resolvePath('app.js');
-      const createUserArgs = [ appJsPath, userTask, 'admin', 'admin' ];
-
-      const createUserEnv = { ...process.env };
-      if (options.mongodbUri) {
-        createUserEnv.APOS_MONGODB_URI = options.mongodbUri;
-      }
-      util.log('create', `Creating admin user: node ${createUserArgs.join(' ')}`);
-      const createUserResult = await util.spawnSafe('node', createUserArgs, {
-        env: createUserEnv,
-        input: `${response.pw ?? ''}\n`
-      });
-      if (createUserResult.code !== 0) {
-        await util.error('create', `Admin user creation exited with code ${createUserResult.code}.`);
-        return false;
-      }
-      util.log('create', 'All done! 🎉 Login as "admin" at the /login URL.');
-
-      await util.success('create');
-      return true;
+    .command('create')
+    .description('Create an Apostrophe project — launches the guided installer.')
+    .action(async function () {
+      const { runInteractive } = await import('create-apostrophe');
+      const code = await runInteractive();
+      process.exit(typeof code === 'number' ? code : 0);
     });
 };
-
-function replaceInConfig(regex, replacement, resolvePath) {
-  const files = [ resolvePath('app.js'), resolvePath('package.json') ];
-  util.replaceInFiles(files, regex, replacement);
-}
diff --git a/packages/cli/lib/commands/telemetry.js b/packages/cli/lib/commands/telemetry.js
new file mode 100644
index 0000000000..c5c4553778
--- /dev/null
+++ b/packages/cli/lib/commands/telemetry.js
@@ -0,0 +1,24 @@
+// Thin delegate: forwards each `apos telemetry <sub>` to create-apostrophe.
+// Commander supplies `--help` for the parent and each subcommand.
+
+module.exports = function (program) {
+  const telemetry = program
+    .command('telemetry')
+    .description('Manage telemetry preference for ApostropheCMS CLI.');
+
+  for (const [ sub, summary ] of [
+    [ 'status', 'Show current telemetry preference.' ],
+    [ 'on', 'Opt in.' ],
+    [ 'off', 'Opt out.' ],
+    [ 'preview', 'Print the exact payload that would be sent.' ]
+  ]) {
+    telemetry
+      .command(sub)
+      .description(summary)
+      .action(async function () {
+        const { runTelemetryCommand } = await import('create-apostrophe');
+        const code = await runTelemetryCommand({ sub });
+        process.exit(typeof code === 'number' ? code : 0);
+      });
+  }
+};
diff --git a/packages/cli/package.json b/packages/cli/package.json
index fbad8f1f39..43e45f479c 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -21,6 +21,7 @@
     "commander": "^5.1.0",
     "common-tags": "^1.8.0",
     "conf": "^6.2.4",
+    "create-apostrophe": "workspace:^",
     "lodash": "^4.18.1",
     "ora": "^5.4.1",
     "pkginfo": "^0.4.1",
diff --git a/packages/create-apostrophe/.mocharc.cjs b/packages/create-apostrophe/.mocharc.cjs
new file mode 100644
index 0000000000..beb54011dc
--- /dev/null
+++ b/packages/create-apostrophe/.mocharc.cjs
@@ -0,0 +1,9 @@
+'use strict';
+
+// ESM specs, discovered recursively under test/. Mocha 11 runs .mjs/.js
+// ESM natively (package is "type": "module").
+module.exports = {
+  spec: [ 'test/**/*.test.js' ],
+  recursive: true,
+  timeout: 10000
+};
diff --git a/packages/create-apostrophe/README.md b/packages/create-apostrophe/README.md
new file mode 100644
index 0000000000..c563a35c4d
--- /dev/null
+++ b/packages/create-apostrophe/README.md
@@ -0,0 +1,222 @@
+# create-apostrophe
+
+The guided installer behind `npm create apostrophe`. It clones a starter kit,
+wires up your database, installs dependencies, and creates an admin user - so a
+fresh Apostrophe project is running in a few minutes.
+
+```bash
+npm create apostrophe@latest
+```
+
+That runs the interactive flow. A few supporting commands:
+
+```bash
+# Run without prompts (CI / scripting)
+npm create apostrophe@latest -- --unattended \
+  --project-name=my-site --password=secret --telemetry=off
+
+# Inspect or change your telemetry preference
+npm create apostrophe@latest -- telemetry status
+npm create apostrophe@latest -- telemetry on
+npm create apostrophe@latest -- telemetry off
+npm create apostrophe@latest -- telemetry preview   # show the exact payload
+
+# Help / version
+npm create apostrophe@latest -- --help
+```
+
+> Everything after `--` is forwarded to the installer; npm swallows args without it.
+> Run `-- --help` any time for the full flag list.
+
+Requires **Node 20+** and **npm** (pnpm and yarn aren't supported yet - running
+under either is rejected up front).
+
+## Architecture
+
+Four layers, with one hard rule: **the headless layers never import the UI.**
+
+- **`bin/`** - entry shim. Guards the Node version, then hands off to the CLI.
+- **`cli/`** - argv parsing and command dispatch (interactive vs. unattended vs.
+  `telemetry`).
+- **`core/`** - the headless installer. `createProject()` orchestrates the
+  install as a sequence of steps (clone → scaffold → install → db → sample data
+  → admin). No prompts, no `process.exit`, no UI. Returns a structured result.
+- **`telemetry/`** - consent, payload building, and the wire transport.
+- **`ui/`** - clack prompts and terminal rendering, on top of a known-good core.
+
+**Import rule:** `core/` and `telemetry/` must not import from `ui/`. `ui/` may
+import from either freely. This keeps the installer logic testable in isolation
+and reusable from a non-interactive host. The boundary is enforced by eslint
+(`no-restricted-imports`).
+
+## Public API
+
+Only `create-apostrophe` itself is importable; everything under `core/`, `ui/`,
+and `telemetry/` is private.
+
+```js
+import {
+  createProject,        // headless install orchestration
+  runInteractive,       // guided install, no argv parsing
+  runTelemetryCommand,  // status | on | off | preview
+  runCli                // argv-driven entry (full pass-through)
+} from 'create-apostrophe';
+```
+
+- **`createProject(options, deps)`** → `Promise<CreateProjectResult>`. The headless
+  orchestrator. Takes fully resolved, already-validated inputs; never prompts or
+  exits. Resolves with `{ ok, kitId, dbChoice, packageManager, durationMs }`
+  (plus `failStage` / `errorCode` on failure) instead of throwing on an expected
+  install failure.
+- **`runInteractive(deps?)`** → `Promise<number>` (exit code). The guided install
+  with no argv parsing - what `@apostrophecms/cli`'s `create` delegate calls, so
+  Commander keeps ownership of `--help`.
+- **`runTelemetryCommand({ sub }, deps?)`** → `Promise<number>`. Handles the
+  `status | on | off | preview` subcommands; used by the `apos telemetry` delegate.
+- **`runCli(argv, deps?)`** → `Promise<number>`. The argv-driven entry for the
+  standalone bin and any host that wants full pass-through.
+
+Exit codes: `0` success · `1` install failure · `2` argument error · `130`
+cancelled (Ctrl-C).
+
+## Telemetry
+
+Telemetry is **opt-in** and anonymous. It exists to tell us which kits and
+databases people actually pick, and where installs break - nothing more. You can
+see the exact payload before sending anything with `telemetry preview`.
+
+- **Consent** is stored locally and starts off. `telemetry on` flips it on and
+  generates a stable anonymous id (UUID v4) the first time; `telemetry off` keeps
+  the id so opting back in resumes the same identity.
+- **Kill switch:** `APOS_TELEMETRY=0` disables telemetry entirely, regardless of
+  stored consent.
+
+### Payload
+
+Exactly one event is emitted per install attempt: `install_success` or
+`install_fail`. The payload is built from a closed allowlist - it is structurally
+impossible to attach anything outside it (no email, paths, project name, db URI,
+or env).
+
+Both events carry:
+
+- **`event`** - `install_success` or `install_fail`.
+- **`cliVersion`** - version of the installer.
+- **`kitId`** - the starter kit chosen (e.g. `apostrophe-demo`).
+- **`dbChoice`** - `sqlite`, `mongodb`, or `postgres`.
+- **`packageManager`** - `npm`, `pnpm`, `yarn`, or `unknown` (detected).
+- **`durationMs`** - how long the attempt took.
+- **`anonymousId`** - UUID v4, present only once you've opted in.
+
+`install_fail` additionally carries:
+
+- **`failStage`** - which stage failed (see below), or `null` for a preflight
+  failure (Node / package-manager check, before any stage runs).
+- **`errorCode`** - a symbolic code, present only when it's one of the known
+  values below. Unknown codes are dropped, never raw error text.
+
+### Fail stages
+
+- **`clone`** - cloning the starter kit.
+- **`scaffold`** - writing project identity, secrets, and `.env`.
+- **`dependency_install`** - `npm install` (or pnpm/yarn).
+- **`db_connect`** - connecting to / preparing the database.
+- **`sample_data`** - downloading and importing demo content.
+- **`admin`** - creating the admin user.
+- **`unknown`** - unexpected error that didn't map to a stage.
+- **`null`** - preflight, before any stage ran.
+
+### Error codes
+
+Grouped by the stage that emits them.
+
+**Preflight**
+
+- **`unsupported_pm`** - running under an unsupported package manager.
+
+**clone**
+
+- **`target_exists`** - the target directory already exists.
+- **`git_missing`** - `git` isn't installed.
+- **`git_spawn_failed`** - `git` failed to launch (not a missing binary).
+- **`git_clone_failed`** - `git clone` exited non-zero.
+
+**scaffold**
+
+- **`missing_scaffold_file`** - the clone is missing `app.js` or `package.json`.
+- **`scaffold_io`** - an I/O error while writing project files.
+
+**dependency_install**
+
+- **`npm_missing`** - the package manager binary isn't installed.
+- **`npm_spawn_failed`** - the package manager failed to launch.
+- **`install_failed`** - the install command exited non-zero.
+- **`apostrophe_missing`** - apostrophe isn't in `node_modules` after install.
+
+**db_connect**
+
+- **`db_unreachable`** - the database server isn't reachable.
+- **`db_auth_failed`** - authentication was rejected.
+- **`db_connect_failed`** - some other connection error.
+- **`db_drop_failed`** - failed to drop a pre-existing database.
+
+**sample_data**
+
+- **`seed_manifest_invalid`** - the sample-data manifest is malformed.
+- **`seed_download_failed`** - downloading the seed archive failed.
+- **`seed_checksum_failed`** - the seed archive failed its checksum.
+- **`seed_unpack_failed`** - unpacking the seed archive failed.
+- **`seed_clear_failed`** - clearing the database before import failed.
+- **`seed_restore_failed`** - restoring the seed database failed.
+- **`seed_uploads_failed`** - extracting seed uploads (images/attachments) failed.
+
+**admin**
+
+- **`node_missing`** - `node` isn't installed.
+- **`node_spawn_failed`** - `node` failed to launch.
+- **`admin_user_failed`** - creating the admin user failed.
+
+### Starter-kit sample-data manifest
+
+The `seed_*` codes above all come from the sample-data step, which runs only for
+`*-demo-data` kits. By default it pulls a fixed pair of archives (a database dump
+and an uploads bundle) baked into the installer. A kit can override that by
+shipping a manifest at:
+
+```
+<project>/.apostrophe/sample-data.json
+```
+
+If present, the manifest **wholesale-replaces** the built-in defaults - it is not
+merged. Its shape:
+
+- **`db`** *(optional)* - the database dump archive (`.zip`).
+- **`uploads`** *(optional)* - the uploads archive (`.zip`).
+
+Each is an `{ url, sha256 }` pair:
+
+- **`url`** - where to download the archive from.
+- **`sha256`** - 64-char lowercase-hex checksum. Each archive is verified against
+  it after download and before it's unpacked - a mismatch aborts
+  (`seed_checksum_failed`) before anything touches your database or files.
+
+At least one of `db` / `uploads` must be present. No manifest file → the built-in
+defaults are used. A file that's unparseable, the wrong shape, or declares
+neither asset is a kit misconfiguration and surfaces as `seed_manifest_invalid`.
+
+```json
+{
+  "db": {
+    "url": "https://static.apostrophecms.com/public-demo/starter-database.jsonl.zip",
+    "sha256": "862fc4b380675e0eaade8447f6a137807ce54b54acbbee79636e581e0c5f29b1"
+  },
+  "uploads": {
+    "url": "https://static.apostrophecms.com/public-demo/starter-uploads.zip",
+    "sha256": "b1a70f3372f8c897fd934abbe711cc1a8b0aeaf7d38b165890dd96939ab62f58"
+  }
+}
+```
+
+## License
+
+MIT
diff --git a/packages/create-apostrophe/bin/create-apostrophe.js b/packages/create-apostrophe/bin/create-apostrophe.js
new file mode 100755
index 0000000000..e86700a3a2
--- /dev/null
+++ b/packages/create-apostrophe/bin/create-apostrophe.js
@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+// Node version guard. Kept syntactically minimal so an engine too old to
+// parse the rest of the file at least gets a useful message.
+
+const nodeVersion = process && process.versions && process.versions.node;
+const major = nodeVersion ? parseInt(nodeVersion.split('.')[0], 10) : NaN;
+if (Number.isFinite(major) && major < 20) {
+  process.stderr.write(
+    'Node.js 20 or newer is required. ' +
+    'You are running Node ' + nodeVersion + '.\n' +
+    'Please upgrade Node (https://nodejs.org) and try again.\n'
+  );
+  process.exit(1);
+}
+
+// Past the guard — anything newer can run safely now.
+const { runCli } = await import('../src/index.js');
+const code = await runCli(process.argv);
+process.exit(typeof code === 'number' ? code : 0);
diff --git a/packages/create-apostrophe/eslint.config.js b/packages/create-apostrophe/eslint.config.js
new file mode 100644
index 0000000000..9c67260dae
--- /dev/null
+++ b/packages/create-apostrophe/eslint.config.js
@@ -0,0 +1,19 @@
+import apostrophe from 'eslint-config-apostrophe';
+import { defineConfig } from 'eslint/config';
+
+export default defineConfig([
+  apostrophe,
+  {
+    // Architectural boundary: the headless layers must not depend on the UI.
+    // core/ and telemetry/ may not import anything under ui/.
+    files: [ 'src/core/**/*.js', 'src/telemetry/**/*.js' ],
+    rules: {
+      'no-restricted-imports': [ 'error', {
+        patterns: [ {
+          group: [ '**/ui', '**/ui/**' ],
+          message: 'core/ and telemetry/ must not import from ui/ (UI/logic boundary).'
+        } ]
+      } ]
+    }
+  }
+]);
diff --git a/packages/create-apostrophe/package.json b/packages/create-apostrophe/package.json
new file mode 100644
index 0000000000..107b907b81
--- /dev/null
+++ b/packages/create-apostrophe/package.json
@@ -0,0 +1,45 @@
+{
+  "name": "create-apostrophe",
+  "version": "1.0.0",
+  "description": "Guided installer for ApostropheCMS — npm create apostrophe@latest",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "create-apostrophe": "bin/create-apostrophe.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "lint": "eslint .",
+    "test": "mocha"
+  },
+  "author": "Apostrophe Technologies, Inc.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apostrophecms/apostrophe.git",
+    "directory": "packages/create-apostrophe"
+  },
+  "homepage": "https://github.com/apostrophecms/apostrophe/tree/main/packages/create-apostrophe#readme",
+  "dependencies": {
+    "@apostrophecms/db-connect": "workspace:^",
+    "@clack/prompts": "^1.4.0",
+    "@umami/node": "^0.4.0",
+    "picocolors": "^1.1.1",
+    "yauzl": "^3.2.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.1",
+    "eslint-config-apostrophe": "workspace:^",
+    "mocha": "^11.7.5"
+  }
+}
diff --git a/packages/create-apostrophe/src/cli/main.js b/packages/create-apostrophe/src/cli/main.js
new file mode 100644
index 0000000000..e0372ee74c
--- /dev/null
+++ b/packages/create-apostrophe/src/cli/main.js
@@ -0,0 +1,416 @@
+// CLI entry. Parses argv, dispatches to a subcommand handler, returns an
+// exit code. Importable from tests as `main(argv)` so the bin stays a
+// one-line shim.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { createStore as defaultCreateStore } from '../core/store.js';
+import { createProject as defaultCreateProject } from '../core/create-project.js';
+import { isKnownKit } from '../core/kits.js';
+import { assertSafeShortName } from '../core/validate.js';
+import { createTelemetry as defaultCreateTelemetry } from '../telemetry/index.js';
+import { DB_CHOICES } from '../telemetry/schema.js';
+import {
+  status as telemetryStatus,
+  optIn as telemetryOptIn,
+  optOut as telemetryOptOut,
+  preview as telemetryPreview
+} from '../telemetry/commands.js';
+import { getAnonymousId, isKillSwitchOn } from '../telemetry/consent.js';
+import { runFlow as defaultRunFlow, renderInstallResult } from '../ui/flow.js';
+import * as render from '../ui/render.js';
+import { UserCancelled } from '../ui/prompts.js';
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const PKG_PATH = join(SCRIPT_DIR, '../../package.json');
+const CLI_VERSION = JSON.parse(readFileSync(PKG_PATH, 'utf8')).version;
+
+const EXIT_OK = 0;
+const EXIT_FAIL = 1;
+const EXIT_ARG = 2;
+const EXIT_CANCEL = 130;
+
+const DEFAULT_KIT = 'apostrophe-astro-demo';
+const DEFAULT_DB = 'sqlite';
+const DEFAULT_USERNAME = 'admin';
+
+const OPTION_SPEC = Object.freeze({
+  'project-name': { type: 'string' },
+  kit: { type: 'string' },
+  db: { type: 'string' },
+  'db-uri': { type: 'string' },
+  username: { type: 'string' },
+  password: { type: 'string' },
+  telemetry: { type: 'string' },
+  unattended: { type: 'boolean' },
+  help: {
+    type: 'boolean',
+    short: 'h'
+  },
+  version: {
+    type: 'boolean',
+    short: 'V'
+  }
+});
+
+const USAGE = `${render.bold('Usage:')}
+  npm create apostrophe@latest                                           ${render.dim('Run the guided installer')}
+  npm create apostrophe@latest -- --unattended [flags]                   ${render.dim('Run without prompts')}
+  npm create apostrophe@latest -- telemetry [status|on|off|preview]      ${render.dim('Manage telemetry preference')}
+  npm create apostrophe@latest -- --help | --version
+
+${render.dim('(everything after the `--` is forwarded to the installer; npm consumes args without it)')}
+
+${render.bold('Unattended flags')} ${render.dim('(--unattended is the only trigger for the headless path)')}:
+  ${render.bold('Required:')}
+  --project-name=NAME           ${render.dim('Project directory name')}
+  --password=PASS               ${render.dim('Admin password (or use APOS_ADMIN_PASSWORD)')}
+  --telemetry=on|off            ${render.dim('Telemetry consent (no default — explicit choice)')}
+
+  ${render.bold('Defaulted (override to change):')}
+  --kit=KITID                   ${render.dim(`Starter kit id (default: ${DEFAULT_KIT})`)}
+  --db=sqlite|mongodb|postgres  ${render.dim(`Database choice (default: ${DEFAULT_DB})`)}
+  --db-uri=URI                  ${render.dim('Connection string (required when --db is mongodb or postgres)')}
+  --username=NAME               ${render.dim(`Admin username or email (default: ${DEFAULT_USERNAME})`)}
+
+${render.bold('Environment:')}
+  APOS_TELEMETRY=0              ${render.dim('Disable telemetry entirely (kill switch)')}
+  APOS_ADMIN_PASSWORD           ${render.dim('Admin password (when --password is absent)')}
+`;
+
+/**
+ * @typedef {object} MainDeps
+ * @property {typeof defaultCreateProject} [createProject]  Injected for tests
+ *   so the unattended/interactive paths can be exercised without real
+ *   git/npm/node spawns.
+ * @property {typeof defaultCreateStore}   [createStore]    Injected for tests
+ *   to keep ~/.config out of the picture.
+ * @property {typeof defaultRunFlow}       [runFlow]        Injected for tests
+ *   so the interactive path can be exercised without driving clack prompts.
+ * @property {typeof defaultCreateTelemetry} [createTelemetry] Injected for tests
+ *   to observe the resolved `consent` (e.g. the kill switch overriding
+ *   --telemetry=on) without building a live transport.
+ */
+
+/**
+ * @param {string[]} argv  Full process.argv (node + script + args).
+ * @param {MainDeps} [deps]
+ * @returns {Promise<number>} Exit code.
+ */
+export async function main(argv, deps = {}) {
+  const {
+    createProject = defaultCreateProject,
+    createStore = defaultCreateStore,
+    createTelemetry = defaultCreateTelemetry,
+    runFlow = defaultRunFlow
+  } = deps;
+  /** @type {{ values: Record<string, any>, positionals: string[] }} */
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv.slice(2),
+      options: OPTION_SPEC,
+      allowPositionals: true,
+      strict: true
+    });
+  } catch (err) {
+    render.errorBlock('Invalid arguments', err.message);
+    process.stderr.write(USAGE);
+    return EXIT_ARG;
+  }
+  const { values, positionals } = parsed;
+
+  if (values.help) {
+    process.stdout.write(USAGE);
+    return EXIT_OK;
+  }
+  if (values.version) {
+    process.stdout.write(`${CLI_VERSION}\n`);
+    return EXIT_OK;
+  }
+  if (positionals[0] === 'telemetry') {
+    return runTelemetryCommand({ sub: positionals[1] }, { createStore });
+  }
+  if (positionals.length > 0) {
+    render.errorBlock('Unknown command', positionals[0]);
+    process.stderr.write(USAGE);
+    return EXIT_ARG;
+  }
+  if (values.unattended) {
+    return runUnattended(values, {
+      createProject,
+      createStore,
+      createTelemetry
+    });
+  }
+  return runInteractive({
+    createProject,
+    createStore,
+    createTelemetry,
+    runFlow
+  });
+}
+
+/**
+ * Interactive install: walks the user through the guided flow, runs the
+ * orchestrator, renders the success/failure screen. Exposed from the
+ * public entry so umbrella CLIs (e.g. `apos create`) can launch the same
+ * flow without going through argv parsing — their command framework keeps
+ * ownership of help text and subcommand routing.
+ *
+ * @param {MainDeps} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runInteractive(deps = {}) {
+  const {
+    createProject = defaultCreateProject,
+    createStore = defaultCreateStore,
+    createTelemetry = defaultCreateTelemetry,
+    runFlow = defaultRunFlow
+  } = deps;
+  const cwd = process.cwd();
+  const env = process.env;
+  const store = createStore();
+  /** @type {import('../ui/flow.js').FlowAnswers} */
+  let answers;
+  try {
+    answers = await runFlow({
+      store,
+      cliVersion: CLI_VERSION,
+      env
+    });
+  } catch (err) {
+    if (err instanceof UserCancelled) {
+      return EXIT_CANCEL;
+    }
+    throw err;
+  }
+
+  const telemetry = createTelemetry({
+    consent: answers.telemetryConsent,
+    cliVersion: CLI_VERSION,
+    anonymousId: getAnonymousId(store)
+  });
+  const logger = render.createUiLogger();
+
+  const result = await createProject(
+    {
+      shortName: answers.shortName,
+      cwd,
+      kitId: answers.kitId,
+      dbChoice: answers.dbChoice,
+      dbUri: answers.dbUri,
+      dbReset: answers.dbReset,
+      admin: answers.admin,
+      nonInteractive: false,
+      confirmedAt: answers.confirmedAt
+    },
+    {
+      telemetry,
+      logger
+    }
+  );
+
+  renderInstallResult(result, answers);
+  await telemetry.flush();
+  return result.ok ? EXIT_OK : EXIT_FAIL;
+}
+
+/**
+ * Unattended install: all answers come from flags/env, no prompts,
+ * deterministic. Validates inputs up front; on invalid args returns
+ * `EXIT_ARG` without touching anything.
+ *
+ * @param {Record<string, any>} values  parseArgs `values`
+ * @param {Required<MainDeps>} deps
+ * @returns {Promise<number>}
+ */
+async function runUnattended(values, {
+  createProject, createStore, createTelemetry
+}) {
+  const env = process.env;
+  const issues = [];
+
+  const shortName = values['project-name'];
+  if (!shortName) {
+    issues.push('--project-name is required');
+  } else {
+    try {
+      assertSafeShortName(shortName);
+    } catch (err) {
+      issues.push(err.message);
+    }
+  }
+
+  const kitId = values.kit ?? DEFAULT_KIT;
+  if (!isKnownKit(kitId)) {
+    issues.push(`Unknown --kit: ${JSON.stringify(kitId)}`);
+  }
+
+  const dbChoice = values.db ?? DEFAULT_DB;
+  if (!DB_CHOICES.includes(dbChoice)) {
+    issues.push(`Unknown --db: ${JSON.stringify(dbChoice)}. Expected one of: ${DB_CHOICES.join(', ')}`);
+  }
+
+  const dbUri = values['db-uri'];
+  if (dbChoice !== 'sqlite' && !dbUri) {
+    issues.push(`--db-uri is required when --db=${dbChoice}`);
+  }
+
+  const username = (values.username ?? DEFAULT_USERNAME).trim();
+  if (username.length === 0) {
+    issues.push('--username cannot be empty');
+  }
+
+  const password = values.password ?? env.APOS_ADMIN_PASSWORD;
+  if (!password) {
+    issues.push('Admin password required: pass --password or set APOS_ADMIN_PASSWORD');
+  }
+
+  const telemetryFlag = values.telemetry;
+  let telemetryConsent;
+  if (telemetryFlag === undefined) {
+    issues.push('--telemetry is required (use \'on\' or \'off\')');
+  } else if (telemetryFlag === 'on') {
+    telemetryConsent = true;
+  } else if (telemetryFlag === 'off') {
+    telemetryConsent = false;
+  } else {
+    issues.push(`--telemetry must be 'on' or 'off' (got ${JSON.stringify(telemetryFlag)})`);
+  }
+
+  if (issues.length > 0) {
+    render.errorBlock(
+      'Invalid arguments',
+      issues.map(line => `• ${line}`).join('\n')
+    );
+    process.stderr.write(USAGE);
+    return EXIT_ARG;
+  }
+
+  const cwd = process.cwd();
+  const store = createStore();
+  const telemetry = createTelemetry({
+    consent: telemetryConsent && !isKillSwitchOn(env),
+    cliVersion: CLI_VERSION,
+    anonymousId: getAnonymousId(store) ?? 'unattended'
+  });
+  const logger = render.createUiLogger();
+
+  const confirmedAt = Date.now();
+  /** @type {import('../index.js').CreateProjectOptions} */
+  const options = {
+    shortName,
+    cwd,
+    kitId,
+    dbChoice,
+    dbUri,
+    // Unattended never drops a pre-existing DB — that needs interactive
+    // consent. (A seed kit still resets its own target in the seed step.)
+    dbReset: 'keep',
+    admin: {
+      username,
+      password
+    },
+    nonInteractive: true,
+    confirmedAt
+  };
+
+  const result = await createProject(options, {
+    telemetry,
+    logger
+  });
+
+  /** @type {import('../ui/flow.js').FlowAnswers} */
+  const answers = {
+    shortName,
+    build: kitId.startsWith('apostrophe-astro') ? 'astro' : 'standalone',
+    startingPoint: kitId.endsWith('-essentials') ? 'essentials' : 'demo',
+    sampleContent: kitId.endsWith('-demo-data'),
+    kitId,
+    dbChoice,
+    dbUri,
+    dbReset: 'keep',
+    admin: {
+      username,
+      password
+    },
+    telemetryConsent,
+    confirmedAt
+  };
+  renderInstallResult(result, answers);
+  await telemetry.flush();
+  return result.ok ? EXIT_OK : EXIT_FAIL;
+}
+
+/**
+ * Run a `telemetry` subcommand by name. Exposed from the public entry so
+ * umbrella CLIs can dispatch their own Commander subcommands to identical
+ * output formatting — the npm-create positional dispatcher uses this too.
+ *
+ * @param {{ sub: string | undefined }} input
+ * @param {{ createStore?: typeof defaultCreateStore, env?: NodeJS.ProcessEnv }} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runTelemetryCommand(input, deps = {}) {
+  const {
+    createStore = defaultCreateStore,
+    env = process.env
+  } = deps;
+  const store = createStore();
+  const sub = input.sub;
+
+  if (sub === 'status') {
+    const s = telemetryStatus(store, env);
+    render.summary('Telemetry status', [
+      [ 'consent', s.consent ? 'on' : 'off' ],
+      [ 'source', s.source ],
+      [ 'killSwitch', s.killSwitchOn ? 'on (APOS_TELEMETRY=0)' : 'off' ],
+      [ 'storedConsent', s.storedConsent === undefined ? '(unset)' : String(s.storedConsent) ],
+      [ 'anonymousId', s.anonymousId ?? '(none — generated on first opt-in)' ]
+    ]);
+    return EXIT_OK;
+  }
+  if (sub === 'on') {
+    const r = telemetryOptIn(store, env);
+    render.success(
+      `Telemetry: on${r.killSwitchOn ? ' (overridden by APOS_TELEMETRY=0)' : ''}`
+    );
+    if (r.idGenerated) {
+      render.muted(`Generated anonymousId: ${r.anonymousId}`);
+    }
+    return EXIT_OK;
+  }
+  if (sub === 'off') {
+    telemetryOptOut(store);
+    render.success('Telemetry: off');
+    return EXIT_OK;
+  }
+  if (sub === 'preview') {
+    const p = telemetryPreview({
+      store,
+      cliVersion: CLI_VERSION,
+      env
+    });
+    const notes = [];
+    if (p.idSentinel) {
+      notes.push('anonymousId is a placeholder — a real UUID is generated on first opt-in.');
+    }
+    if (p.killSwitchOn) {
+      notes.push('APOS_TELEMETRY=0 is set — even with consent: on, nothing would be sent.');
+    }
+    const body = notes.length === 0
+      ? JSON.stringify(p.payload, null, 2)
+      : `${JSON.stringify(p.payload, null, 2)}\n\n${render.dim(notes.join('\n'))}`;
+    render.note('Telemetry preview', body);
+    return EXIT_OK;
+  }
+  render.errorBlock(
+    'Unknown telemetry subcommand',
+    `${sub ?? '(none)'}\n\nExpected one of: status, on, off, preview`
+  );
+  return EXIT_ARG;
+}
diff --git a/packages/create-apostrophe/src/core/create-project.js b/packages/create-apostrophe/src/core/create-project.js
new file mode 100644
index 0000000000..28863ae545
--- /dev/null
+++ b/packages/create-apostrophe/src/core/create-project.js
@@ -0,0 +1,171 @@
+// Headless orchestrator. Preflight (supported pm) + steps. Resolves a structured
+// CreateProjectResult and emits exactly one terminal telemetry event.
+// Never calls process.exit; expected failures resolve (ok:false),
+// unexpected throws propagate to the caller (which converts + emits).
+
+import { getKit } from './kits.js';
+import { detectPackageManager, assertSupportedPackageManager } from './pm.js';
+import { StageError, UnsupportedPackageManagerError } from './errors.js';
+import { checkConnection, dropDatabase } from './db.js';
+import { clone as realClone } from './steps/clone.js';
+import { scaffold as realScaffold } from './steps/scaffold.js';
+import { install as realInstall } from './steps/install.js';
+import { dbConfig as realDbConfig } from './steps/db-config.js';
+import { addAdminUser as realAddAdminUser } from './steps/admin-user.js';
+import { importSampleData as realImportSampleData } from './steps/sample-data.js';
+
+/**
+ * Internal factory so steps can be substituted in unit tests. The public
+ * {@link createProject} binds the real steps; the (options, deps) contract is
+ * unchanged — the step set is not part of it.
+ */
+export function makeCreateProject({
+  clone, scaffold, install, dbConfig, addAdminUser, importSampleData
+}) {
+  return async function createProject(options, deps) {
+    const { telemetry, logger } = deps;
+    const echo = {
+      kitId: options.kitId,
+      dbChoice: options.dbChoice
+    };
+
+    // Single terminal point: build the result, emit exactly one event, return.
+    const finish = ({
+      ok, packageManager, failStage, errorCode
+    }) => {
+      const result = {
+        ok,
+        ...echo,
+        packageManager,
+        durationMs: Date.now() - options.confirmedAt
+      };
+      if (!ok) {
+        result.failStage = failStage;
+        if (errorCode) {
+          result.errorCode = errorCode;
+        }
+      }
+      const { ok: _ok, ...payload } = result;
+      telemetry.event(ok ? 'install_success' : 'install_fail', payload);
+      return result;
+    };
+
+    // Preflight (before any work). Node version stays a bin/ hard exit.
+    const packageManager = options.packageManager || detectPackageManager();
+    try {
+      assertSupportedPackageManager(packageManager);
+    } catch (err) {
+      if (err instanceof UnsupportedPackageManagerError) {
+        return finish({
+          ok: false,
+          packageManager,
+          failStage: null,
+          errorCode: err.errorCode
+        });
+      }
+      throw err;
+    }
+
+    // Validation errors (unknown kit, unsafe shortName, …) propagate as
+    // unexpected throws — the caller converts and emits.
+    const kit = getKit(options.kitId);
+
+    // The task handle is passed to the step fn so long-running steps can
+    // report progress (task.progress?.(...)); steps that don't, ignore it.
+    const step = async (label, fn) => {
+      const task = logger.task(label);
+      try {
+        const out = await fn(task);
+        task.succeed();
+        return out;
+      } catch (err) {
+        task.fail();
+        throw err;
+      }
+    };
+
+    try {
+      const { projectDir } = await step('Cloning starter', () =>
+        clone({
+          repo: kit.repo,
+          shortName: options.shortName,
+          cwd: options.cwd
+        }));
+
+      const { frontend, appRoot } = await step('Configuring project', () =>
+        scaffold({
+          projectDir,
+          shortName: options.shortName,
+          frontend: kit.frontend
+        }));
+
+      await step('Installing dependencies', () =>
+        install({
+          projectDir,
+          appRoot,
+          frontend,
+          packageManager
+        }));
+
+      await step('Configuring database', () =>
+        dbConfig({
+          appRoot,
+          dbChoice: options.dbChoice,
+          dbUri: options.dbUri,
+          shortName: options.shortName,
+          dbReset: options.dbReset
+        }, {
+          verifyConnection: checkConnection,
+          dropDatabase
+        }));
+
+      // Runs before admin-user so the admin reconciles against the restored
+      // dump. Renders its own tasks, so it is not wrapped in step().
+      if (kit.seedData) {
+        await importSampleData({
+          appRoot,
+          dbChoice: options.dbChoice,
+          dbUri: options.dbUri,
+          shortName: options.shortName
+        }, {
+          task: (label, taskOpts) => logger.task(label, taskOpts)
+        });
+      }
+
+      const adminOutcome = await step(`Creating ${options.admin.username} account`, () =>
+        addAdminUser({
+          appRoot,
+          username: options.admin.username,
+          password: options.admin.password
+        }));
+      if (adminOutcome === 'updated') {
+        logger.muted?.(`User ${options.admin.username} already existed — password updated.`);
+      }
+
+      return finish({
+        ok: true,
+        packageManager
+      });
+    } catch (err) {
+      if (err instanceof StageError) {
+        return finish({
+          ok: false,
+          packageManager,
+          failStage: err.stage,
+          errorCode: err.errorCode
+        });
+      }
+      throw err;
+    }
+  };
+}
+
+/** @type {import('../index.js').CreateProject} */
+export const createProject = makeCreateProject({
+  clone: realClone,
+  scaffold: realScaffold,
+  install: realInstall,
+  dbConfig: realDbConfig,
+  addAdminUser: realAddAdminUser,
+  importSampleData: realImportSampleData
+});
diff --git a/packages/create-apostrophe/src/core/db.js b/packages/create-apostrophe/src/core/db.js
new file mode 100644
index 0000000000..935f12a6dd
--- /dev/null
+++ b/packages/create-apostrophe/src/core/db.js
@@ -0,0 +1,267 @@
+// Single home for the installer's "DB burden": deriving the connection URI,
+// a real connection/liveness check with precise failure classification,
+// dropping a database, and restoring a JSONL dump. All built on
+// @apostrophecms/db-connect — the same library the cloned project's own
+// Apostrophe uses — so there is no shell-tool dependency (no mongorestore /
+// pg_restore) and the dump + on-disk formats match within a major version.
+//
+// Core module: the UI may import core, but core must never import UI
+// (enforced by test/boundary.test.js).
+
+import path from 'node:path';
+import dbConnect from '@apostrophecms/db-connect';
+import { assertSafeShortName } from './validate.js';
+
+/** @typedef {import('../index.js').DbChoice} DbChoice */
+
+/**
+ * Coarse, telemetry-safe reason for a failed connection. The raw driver
+ * message is preserved only for interactive display, never for telemetry.
+ * @typedef {('unreachable' | 'auth' | 'unknown')} FailureReason
+ */
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+/**
+ * The connection URI core will actually open at runtime. Mirrors
+ * @apostrophecms/db's own derivation so anything we restore lands in the
+ * exact place the app later reads.
+ *
+ *   - mongodb / postgres: the user-supplied `dbUri`, verbatim (what we wrote
+ *     to APOS_DB_URI).
+ *   - sqlite: core's formula.
+ *
+ * @param {{
+ *   dbChoice: DbChoice, dbUri?: string, appRoot: string, shortName: string
+ * }} opts
+ * @returns {string}
+ * @throws {TypeError} for an unsafe shortName, or a mongodb/postgres choice
+ *   with no dbUri.
+ */
+export function resolveDbUri({
+  dbChoice, dbUri, appRoot, shortName
+}) {
+  if (dbChoice === 'sqlite') {
+    assertSafeShortName(shortName);
+    return `sqlite://${path.resolve(appRoot, 'data', `${shortName}.sqlite`)}`;
+  }
+  if (!dbUri) {
+    throw new TypeError(`resolveDbUri: ${dbChoice} requires a dbUri.`);
+  }
+  return dbUri;
+}
+
+/**
+ * Open a real connection and report reachability plus whether the database
+ * already holds data. `listCollections().toArray()` is a genuine round-trip,
+ * so it doubles as the liveness probe and the existing-data check.
+ *
+ * Uniform across every adapter.
+ * Never throws — failures are classified into a {@link FailureReason}.
+ *
+ * @param {string} uri
+ * @param {{ timeoutMs?: number, connect?: typeof dbConnect }} [opts]
+ * @returns {Promise<{
+ *   reachable: boolean,
+ *   empty: boolean,
+ *   collectionCount: number,
+ *   reason?: FailureReason,
+ *   message?: string
+ * }>}
+ */
+export async function inspect(
+  uri,
+  { timeoutMs = DEFAULT_TIMEOUT_MS, connect = dbConnect } = {}
+) {
+  let client;
+  try {
+    client = await connect(uri, connectOptions(uri, timeoutMs));
+    const collections = await client.db().listCollections().toArray();
+    const collectionCount = collections.length;
+    return {
+      reachable: true,
+      empty: collectionCount === 0,
+      collectionCount
+    };
+  } catch (err) {
+    return {
+      reachable: false,
+      empty: false,
+      collectionCount: 0,
+      reason: classify(err),
+      message: messageOf(err)
+    };
+  } finally {
+    await closeQuietly(client);
+  }
+}
+
+/**
+ * Reachability/auth verdict only — emptiness ignored. For callers that just
+ * need to know the connection is usable.
+ *
+ * @param {string} uri
+ * @param {{ timeoutMs?: number, connect?: typeof dbConnect }} [opts]
+ * @returns {Promise<{ reachable: boolean, reason?: FailureReason, message?: string }>}
+ */
+export async function checkConnection(uri, opts) {
+  const {
+    reachable, reason, message
+  } = await inspect(uri, opts);
+  return reachable
+    ? { reachable }
+    : {
+      reachable,
+      reason,
+      message
+    };
+}
+
+/**
+ * Drop the whole database — the guaranteed clean slate behind an explicit
+ * "start fresh" / "overwrite" consent. Mongo drops the database; postgres
+ * drops the collection tables / schema; sqlite drops all tables (the file
+ * itself remains). Restore alone clears only the dump's own collections, so
+ * this is the separate step that removes orphan collections from prior data.
+ *
+ * @param {string} uri
+ * @param {{ connect?: typeof dbConnect }} [opts]
+ * @returns {Promise<void>}
+ */
+export async function dropDatabase(uri, { connect = dbConnect } = {}) {
+  let client;
+  try {
+    client = await connect(uri);
+    await client.db().dropDatabase();
+  } finally {
+    await closeQuietly(client);
+  }
+}
+
+/**
+ * Empty every existing collection (per-collection `deleteMany`) without
+ * dropping the database. Privilege-safe — needs only the `readWrite`/DELETE
+ * rights {@link restore} uses (no `dbAdmin`/DROP), so it works on a
+ * locked-down Atlas/SRV user. Unlike a bare {@link restore} (which clears
+ * only the dump's own collections) it also empties orphan collections the
+ * dump doesn't carry. No-op on an empty/fresh target.
+ *
+ * @param {string} uri
+ * @param {{ connect?: typeof dbConnect }} [opts]
+ * @returns {Promise<void>}
+ */
+export async function clearDatabase(uri, { connect = dbConnect } = {}) {
+  let client;
+  try {
+    client = await connect(uri);
+    const db = client.db();
+    const collections = await db.listCollections().toArray();
+    for (const { name } of collections) {
+      // Mongo system collections aren't writable and aren't ours to touch.
+      if (name.startsWith('system.')) {
+        continue;
+      }
+      await db.collection(name).deleteMany({});
+    }
+  } finally {
+    await closeQuietly(client);
+  }
+}
+
+/**
+ * Restore a JSONL dump into the target DB. Thin wrapper over db-connect's
+ * `restore`, which clears only the dump's own collections — to also clear
+ * orphans, call {@link clearDatabase} first ({@link dropDatabase} is the hard
+ * reset). The sqlite adapter creates the db file and its parent directories
+ * on connect, so there is nothing for us to pre-create.
+ *
+ * @param {string} uri
+ * @param {(
+ *   import('node:stream').Readable | string |
+ *   Iterable<string> | AsyncIterable<string>
+ * )} source
+ *   JSONL lines: a Readable stream (e.g. a yauzl entry), a string, or an
+ *   (async) iterable of lines.
+ * @param {{ restore?: typeof dbConnect.restore }} [opts]
+ * @returns {Promise<void>}
+ */
+export async function restore(
+  uri,
+  source,
+  { restore: restoreImpl = dbConnect.restore } = {}
+) {
+  await restoreImpl(uri, source);
+}
+
+/**
+ * Per-engine connect options carrying a bounded selection timeout so an
+ * unreachable host fails fast instead of hanging the prompt. Unknown keys
+ * are ignored by the other engine's driver, but we branch to stay precise.
+ * @param {string} uri
+ * @param {number} timeoutMs
+ * @returns {object}
+ */
+function connectOptions(uri, timeoutMs) {
+  if (/^postgres(ql)?:|^multipostgres:/i.test(uri)) {
+    return { connectionTimeoutMillis: timeoutMs };
+  }
+  return { serverSelectionTimeoutMS: timeoutMs };
+}
+
+/**
+ * Map a driver error to a coarse {@link FailureReason}. Symbolic only — the
+ * raw message never reaches this verdict.
+ * @param {any} err
+ * @returns {FailureReason}
+ */
+function classify(err) {
+  const code = err?.code;
+  const message = messageOf(err);
+  // Bad credentials: mongo AuthenticationFailed (code 18 / codeName), or
+  // postgres invalid_password (28P01) / invalid_authorization (28000).
+  if (
+    code === 18 ||
+    err?.codeName === 'AuthenticationFailed' ||
+    code === '28P01' ||
+    code === '28000' ||
+    /authentication failed/i.test(message)
+  ) {
+    return 'auth';
+  }
+  // Cannot reach the server: refused, DNS failure, server-selection timeout.
+  if (
+    code === 'ECONNREFUSED' ||
+    code === 'ENOTFOUND' ||
+    code === 'EAI_AGAIN' ||
+    err?.name === 'MongoServerSelectionError' ||
+    /server selection/i.test(message) ||
+    /timed out/i.test(message)
+  ) {
+    return 'unreachable';
+  }
+  return 'unknown';
+}
+
+/**
+ * @param {any} err
+ * @returns {string}
+ */
+function messageOf(err) {
+  return (err && err.message) ? err.message : String(err);
+}
+
+/**
+ * Close a client if one was opened, swallowing close-time errors so they
+ * never mask the original outcome.
+ * @param {{ close?: () => Promise<void> } | undefined} client
+ * @returns {Promise<void>}
+ */
+async function closeQuietly(client) {
+  if (client && typeof client.close === 'function') {
+    try {
+      await client.close();
+    } catch {
+      // A failed close must not override the success/failure we already have.
+    }
+  }
+}
diff --git a/packages/create-apostrophe/src/core/env-file.js b/packages/create-apostrophe/src/core/env-file.js
new file mode 100644
index 0000000000..b70d3e9a1a
--- /dev/null
+++ b/packages/create-apostrophe/src/core/env-file.js
@@ -0,0 +1,66 @@
+// Minimal dotenv writer.
+
+import {
+  existsSync, readFileSync, writeFileSync
+} from 'node:fs';
+
+/**
+ * Quote a value only when dotenv would otherwise mis-parse it (whitespace,
+ * `#`, quotes, backslash). Hex secrets need no quoting; a DB URI with special
+ * characters does. Control chars (newlines, NUL, …) are refused outright:
+ * embedded inside a quoted value they would smuggle additional KEY=value
+ * lines into the resulting .env, and they are never legitimate in a URI,
+ * token, or secret.
+ */
+function formatValue(value) {
+  const s = String(value);
+  // Eliminate control characters.
+  // eslint-disable-next-line no-control-regex
+  if (/[\x00-\x1f\x7f]/.test(s)) {
+    throw new TypeError(
+      'env value contains a control character (newline, NUL, …); refusing to write.'
+    );
+  }
+  if (s === '' || /[\s#"'\\]/.test(s)) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  }
+  return s;
+}
+
+/**
+ * Write `content` to `path` only if no file is there yet.
+ */
+export function writeIfAbsent(path, content) {
+  if (existsSync(path)) {
+    return false;
+  }
+  writeFileSync(path, content);
+  return true;
+}
+
+/**
+ * Upsert `KEY=value` lines. An existing key (line starting `KEY=`, possibly
+ * with an empty value from the template) is replaced in place; a new key is
+ * appended. File ends with a newline.
+ * @param {string} envPath
+ * @param {Record<string,string>} vars
+ */
+export function upsertEnv(envPath, vars) {
+  let content = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+  for (const [ key, value ] of Object.entries(vars)) {
+    const line = `${key}=${formatValue(value)}`;
+    const re = new RegExp(`^${key}=.*$`, 'm');
+    if (re.test(content)) {
+      content = content.replace(re, line);
+    } else {
+      if (content.length && !content.endsWith('\n')) {
+        content += '\n';
+      }
+      content += `${line}\n`;
+    }
+  }
+  if (content.length && !content.endsWith('\n')) {
+    content += '\n';
+  }
+  writeFileSync(envPath, content);
+}
diff --git a/packages/create-apostrophe/src/core/env-templates.js b/packages/create-apostrophe/src/core/env-templates.js
new file mode 100644
index 0000000000..c8b9debda6
--- /dev/null
+++ b/packages/create-apostrophe/src/core/env-templates.js
@@ -0,0 +1,54 @@
+const titleCase = (name) => name.charAt(0).toUpperCase() + name.slice(1);
+
+const HEADER = (what) =>
+  `# ApostropheCMS — ${what} environment configuration.
+# Generated by create-apostrophe. This file is gitignored.
+# Keep these values private; do not commit real secrets.
+`;
+
+const SECRETS = `
+# Session secret used to sign cookies.
+APOS_SESSION_SECRET=
+
+# Secures access to disabled (e.g. trashed) uploaded files.
+APOS_UPLOADFS_DISABLED_FILE_KEY=
+
+# The database connection string for the database you chose is added
+# below by the installer (SQLite needs none).
+`;
+
+/** Standalone full-stack project: a single `.env` at the project root. */
+export function standaloneEnv() {
+  return HEADER('project') + SECRETS;
+}
+
+/**
+ * Apostrophe backend `.env` for a project with an external frontend.
+ * @param {string} name External-frontend name (e.g. `'astro'`) — labels the
+ *   file; the keys are the same for any external frontend.
+ */
+export function externalBackendEnv(name) {
+  return `${HEADER(`${titleCase(name)} backend`)}
+# Required for local development when using the external frontend
+APOS_EXTERNAL_FRONT_KEY=dev
+# Set to 1 to enable development mode (always fully rebuilds, no stale admin UI)
+APOS_DEV=1
+${SECRETS}`;
+}
+
+/**
+ * External-frontend `.env` (no secrets — only the shared front key).
+ * @param {string} name External-frontend name (e.g. `'astro'`).
+ */
+export function externalFrontendEnv(name) {
+  return `${HEADER(`${titleCase(name)} frontend`)}
+# Required for local development — must match APOS_EXTERNAL_FRONT_KEY in the backend
+APOS_EXTERNAL_FRONT_KEY=dev
+`;
+}
+
+/** Keys the scaffold step fills with generated secrets (frontend gets none). */
+export const SECRET_KEYS = Object.freeze([
+  'APOS_SESSION_SECRET',
+  'APOS_UPLOADFS_DISABLED_FILE_KEY'
+]);
diff --git a/packages/create-apostrophe/src/core/errors.js b/packages/create-apostrophe/src/core/errors.js
new file mode 100644
index 0000000000..4f3103cc2d
--- /dev/null
+++ b/packages/create-apostrophe/src/core/errors.js
@@ -0,0 +1,36 @@
+/** @typedef {import('../index.js').FailStage} FailStage */
+
+export class StageError extends Error {
+  /**
+   * @param {FailStage} stage
+   * @param {{ code?: string, cause?: Error }} [info]
+   */
+  constructor(stage, { code, cause } = {}) {
+    super(`stage "${stage}" failed${code ? ` (${code})` : ''}`);
+    this.name = 'StageError';
+    /** @type {FailStage} */
+    this.stage = stage;
+    /** @type {string|undefined} symbolic, never raw error text */
+    this.errorCode = code;
+    if (cause) {
+      this.cause = cause;
+    }
+  }
+}
+
+// Thrown when the active package manager is not supported. Not a StageError:
+// a preflight precondition.
+export class UnsupportedPackageManagerError extends Error {
+  /**
+   * @param {string} packageManager Detected manager (e.g. 'pnpm', 'yarn').
+   * @param {readonly string[]} supported Supported managers (from pm.js).
+   */
+  constructor(packageManager, supported = []) {
+    super(`Unsupported package manager: ${packageManager}`);
+    this.name = 'UnsupportedPackageManagerError';
+    this.packageManager = packageManager;
+    this.supported = supported;
+    // Allowlisted preflight code (telemetry: install_fail, failStage:null).
+    this.errorCode = 'unsupported_pm';
+  }
+}
diff --git a/packages/create-apostrophe/src/core/kits.js b/packages/create-apostrophe/src/core/kits.js
new file mode 100644
index 0000000000..c08258a11a
--- /dev/null
+++ b/packages/create-apostrophe/src/core/kits.js
@@ -0,0 +1,135 @@
+/**
+ * Canonical GitHub clone URLs per kit
+ */
+const REPOS = Object.freeze({
+  // Standalone (full-stack Apostrophe).
+  essentials: 'https://github.com/apostrophecms/starter-kit-essentials.git',
+  demo: 'https://github.com/apostrophecms/public-demo.git',
+  // Astro frontend + Apostrophe backend.
+  astroEssentials: 'https://github.com/apostrophecms/starter-kit-astro-essentials.git',
+  astroDemo: 'https://github.com/apostrophecms/astro-public-demo.git'
+});
+
+/**
+ * External-frontend technology paired with the Apostrophe backend. `null`
+ * means a standalone full-stack Apostrophe project (no separate frontend).
+ * Adding a frontend is a new named string here + step handling, never a
+ * boolean.
+ * @typedef {('astro' | null)} Frontend
+ */
+
+/**
+ * kitId → { repo, label, frontend, seedData }.
+ *
+ * `label` is the human-facing name (UI/plan-preview). `seedData` marks the
+ * demo-data variants that get a DB dump + sample images applied after clone.
+ * @type {Readonly<Record<string, {
+ *   repo: string, label: string, frontend: Frontend, seedData: boolean
+ * }>>}
+ */
+export const KITS = Object.freeze({
+  'apostrophe-astro-essentials': {
+    repo: REPOS.astroEssentials,
+    label: 'Apostrophe + Astro — Essentials',
+    frontend: 'astro',
+    seedData: false
+  },
+  'apostrophe-astro-demo': {
+    repo: REPOS.astroDemo,
+    label: 'Apostrophe + Astro — Demo',
+    frontend: 'astro',
+    seedData: false
+  },
+  'apostrophe-astro-demo-data': {
+    repo: REPOS.astroDemo,
+    label: 'Apostrophe + Astro — Demo (with sample content)',
+    frontend: 'astro',
+    seedData: true
+  },
+  'apostrophe-essentials': {
+    repo: REPOS.essentials,
+    label: 'Apostrophe Standalone — Essentials',
+    frontend: null,
+    seedData: false
+  },
+  'apostrophe-demo': {
+    repo: REPOS.demo,
+    label: 'Apostrophe Standalone — Demo',
+    frontend: null,
+    seedData: false
+  },
+  'apostrophe-demo-data': {
+    repo: REPOS.demo,
+    label: 'Apostrophe Standalone — Demo (with sample content)',
+    frontend: null,
+    seedData: true
+  }
+});
+
+/** All valid KitIds, frozen. */
+export const KIT_IDS = Object.freeze(Object.keys(KITS));
+
+/** @returns {boolean} whether `kitId` is a known KitId. */
+export function isKnownKit(kitId) {
+  return Object.hasOwn(KITS, kitId);
+}
+
+/**
+ * Resolve a KitId to its registry entry.
+ * @param {string} kitId
+ * @returns {{ repo: string, label: string, frontend: Frontend, seedData: boolean }}
+ * @throws {TypeError} for an unknown KitId (programmer/validation error — the
+ *   caller validates options before createProject; not an install failure).
+ */
+export function getKit(kitId) {
+  if (!isKnownKit(kitId)) {
+    throw new TypeError(
+      `Unknown kitId: ${kitId}. Known: ${KIT_IDS.join(', ')}`
+    );
+  }
+  return KITS[kitId];
+}
+
+/**
+ * Derive a KitId from the flow's three answers:
+ *
+ *   build         : 'astro' | 'standalone'
+ *   startingPoint : 'essentials' | 'demo'
+ *   sampleContent : boolean (only meaningful when startingPoint === 'demo';
+ *                   ignored for 'essentials')
+ *
+ *   essentials                     → `<prefix>-essentials`
+ *   demo, sampleContent === false  → `<prefix>-demo`
+ *   demo, sampleContent === true   → `<prefix>-demo-data`
+ *
+ * where `<prefix>` is `apostrophe-astro` (astro) or `apostrophe` (standalone).
+ *
+ * @param {{ build: string, startingPoint: string, sampleContent?: boolean }} a
+ * @returns {string} a KitId guaranteed to be in {@link KITS}.
+ * @throws {TypeError} on an unrecognized build/startingPoint.
+ */
+export function deriveKitId({
+  build, startingPoint, sampleContent = false
+}) {
+  let prefix;
+  if (build === 'astro') {
+    prefix = 'apostrophe-astro';
+  } else if (build === 'standalone') {
+    prefix = 'apostrophe';
+  } else {
+    throw new TypeError(`Unknown build: ${build}. Expected 'astro' | 'standalone'.`);
+  }
+
+  let suffix;
+  if (startingPoint === 'essentials') {
+    suffix = 'essentials';
+  } else if (startingPoint === 'demo') {
+    suffix = sampleContent ? 'demo-data' : 'demo';
+  } else {
+    throw new TypeError(
+      `Unknown startingPoint: ${startingPoint}. Expected 'essentials' | 'demo'.`
+    );
+  }
+
+  return `${prefix}-${suffix}`;
+}
diff --git a/packages/create-apostrophe/src/core/pm.js b/packages/create-apostrophe/src/core/pm.js
new file mode 100644
index 0000000000..f507622484
--- /dev/null
+++ b/packages/create-apostrophe/src/core/pm.js
@@ -0,0 +1,36 @@
+// Package-manager detection from the npm_config_user_agent the running
+// package manager sets when it invokes `npm create` / `npx`.
+
+import { UnsupportedPackageManagerError } from './errors.js';
+
+// Single source of truth for what the installer supports. 'unknown' is run
+// as npm but is not a user-facing "supported" choice.
+export const SUPPORTED_PACKAGE_MANAGERS = Object.freeze([ 'npm' ]);
+const RUNNABLE_AS_NPM = new Set([ ...SUPPORTED_PACKAGE_MANAGERS, 'unknown' ]);
+
+/**
+ * @param {string} [userAgent] Defaults to `process.env.npm_config_user_agent`.
+ * @returns {('npm'|'pnpm'|'yarn'|'unknown')}
+ */
+export function detectPackageManager(userAgent = process.env.npm_config_user_agent) {
+  if (!userAgent) {
+    return 'unknown';
+  }
+  const name = String(userAgent).split('/')[0].trim().toLowerCase();
+  return (name === 'npm' || name === 'pnpm' || name === 'yarn')
+    ? name
+    : 'unknown';
+}
+
+/**
+ * Reject an unsupported manager before any work is done. npm / unknown pass.
+ * @param {string} pm
+ * @returns {string}
+ * @throws {UnsupportedPackageManagerError} for pnpm/yarn/etc.
+ */
+export function assertSupportedPackageManager(pm) {
+  if (!RUNNABLE_AS_NPM.has(pm)) {
+    throw new UnsupportedPackageManagerError(pm, SUPPORTED_PACKAGE_MANAGERS);
+  }
+  return pm;
+}
diff --git a/packages/create-apostrophe/src/core/spawn.js b/packages/create-apostrophe/src/core/spawn.js
new file mode 100644
index 0000000000..e851fde877
--- /dev/null
+++ b/packages/create-apostrophe/src/core/spawn.js
@@ -0,0 +1,78 @@
+// No-shell child process helper.
+//
+// `shell: false` is explicit and load-bearing: arguments are passed to the
+// kernel verbatim, so a project name or connection string containing shell
+// metacharacters is an inert string, never executed
+
+import { spawn } from 'node:child_process';
+
+/**
+ * @param {string} command            Executable name/path (no shell parsing).
+ * @param {string[]} [args]           Args passed verbatim.
+ * @param {object} [opts]
+ * @param {string}  [opts.cwd]
+ * @param {object}  [opts.env]        Defaults to `process.env`.
+ * @param {string}  [opts.input]      Written to stdin then closed, if set.
+ * @returns {Promise<{
+ *   code: number|null, stdout: string, stderr: string, error: Error|null
+ * }>} `code` is the exit code (null on spawn failure); `error` is set only
+ *   when the process could not be spawned (e.g. ENOENT — binary missing).
+ */
+export function run(command, args = [], {
+  cwd, env, input
+} = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, args, {
+        cwd,
+        env: env ?? process.env,
+        shell: false,
+        stdio: [ input != null ? 'pipe' : 'ignore', 'pipe', 'pipe' ]
+      });
+    } catch (error) {
+      resolve({
+        code: null,
+        stdout: '',
+        stderr: '',
+        error
+      });
+      return;
+    }
+
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = (res) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve(res);
+    };
+
+    child.stdout?.on('data', (d) => {
+      stdout += d;
+    });
+    child.stderr?.on('data', (d) => {
+      stderr += d;
+    });
+
+    child.on('error', (error) => finish({
+      code: null,
+      stdout,
+      stderr,
+      error
+    }));
+    child.on('close', (code) => finish({
+      code,
+      stdout,
+      stderr,
+      error: null
+    }));
+
+    if (input != null) {
+      child.stdin.end(input);
+    }
+  });
+}
diff --git a/packages/create-apostrophe/src/core/steps/admin-user.js b/packages/create-apostrophe/src/core/steps/admin-user.js
new file mode 100644
index 0000000000..6dfbb7e62d
--- /dev/null
+++ b/packages/create-apostrophe/src/core/steps/admin-user.js
@@ -0,0 +1,107 @@
+// Step: create the admin user via the project's own
+// `@apostrophecms/user:add` task. The password is written to the task's
+// stdin (never an argv, never logged).
+//
+// Recovery: if `user:add` fails because the username already exists,
+// retry as `user:change-password`.
+//
+// The `--` end-of-options marker before the user-supplied `username`
+// stops Apostrophe's argv parser (`boring({ end: true })`) from
+// re-interpreting a username like `--role=guest` as a flag — without it,
+// the task would create a different user with a different role than asked.
+
+import { run as defaultRun } from '../spawn.js';
+import { StageError } from '../errors.js';
+
+/** @typedef {import('../../index.js').AdminAccount} AdminAccount */
+
+const STAGE = 'admin';
+
+/**
+ * @param {AdminAccount & { appRoot: string }} opts
+ * @param {{ run?: typeof defaultRun }} [deps]
+ * @returns {Promise<'created' | 'updated'>} `'updated'` only when the
+ *   user already existed and we fell back to `user:change-password`.
+ * @throws {StageError} stage 'admin' if the task cannot run or exits non-zero.
+ */
+export async function addAdminUser(
+  {
+    appRoot, username, password
+  },
+  { run = defaultRun } = {}
+) {
+  if (!username) {
+    throw new TypeError('admin.username is required');
+  }
+
+  const add = await run(
+    'node',
+    [ 'app.js', '@apostrophecms/user:add', '--', username, 'admin' ],
+    {
+      cwd: appRoot,
+      input: `${password ?? ''}\n`
+    }
+  );
+
+  if (add.error) {
+    throw new StageError(STAGE, {
+      code: add.error.code === 'ENOENT' ? 'node_missing' : 'node_spawn_failed',
+      cause: add.error
+    });
+  }
+  if (add.code === 0) {
+    return 'created';
+  }
+
+  if (isDuplicateUsername(add.stderr)) {
+    const cp = await run(
+      'node',
+      [ 'app.js', '@apostrophecms/user:change-password', '--', username ],
+      {
+        cwd: appRoot,
+        input: `${password ?? ''}\n`
+      }
+    );
+    if (cp.error) {
+      throw new StageError(STAGE, {
+        code: cp.error.code === 'ENOENT' ? 'node_missing' : 'node_spawn_failed',
+        cause: cp.error
+      });
+    }
+    if (cp.code === 0) {
+      return 'updated';
+    }
+    throw new StageError(STAGE, {
+      code: 'admin_user_failed',
+      cause: new Error(
+        `@apostrophecms/user:change-password exited with code ${cp.code} ` +
+        '(recovery from duplicate @apostrophecms/user:add)'
+      )
+    });
+  }
+
+  throw new StageError(STAGE, {
+    code: 'admin_user_failed',
+    cause: new Error(`@apostrophecms/user:add exited with code ${add.code}`)
+  });
+}
+
+/**
+ * Detect a duplicate-key failure across all three adapters Apostrophe
+ * supports. `@apostrophecms/db-connect` normalizes the error *code* to
+ * `11000` for mongo/postgres/sqlite, but `e.message` (what the task
+ * runner prints) differs per adapter:
+ *
+ *   - mongo:    `E11000 duplicate key error collection: ... index: username_1 ...`
+ *   - postgres: `Duplicate key error: username "admin" already exists`
+ *   - sqlite:   `Duplicate key error: already exists`  (no field name)
+ *
+ * @param {string} stderr
+ * @returns {boolean}
+ */
+function isDuplicateUsername(stderr) {
+  if (!stderr) {
+    return false;
+  }
+  return stderr.includes('E11000') || /duplicate\s+key/i.test(stderr);
+}
diff --git a/packages/create-apostrophe/src/core/steps/clone.js b/packages/create-apostrophe/src/core/steps/clone.js
new file mode 100644
index 0000000000..5067589d26
--- /dev/null
+++ b/packages/create-apostrophe/src/core/steps/clone.js
@@ -0,0 +1,70 @@
+// Step: clone the starter kit and detach it from the starter's git history.
+// Failure → FailStage 'clone'.
+
+import { join } from 'node:path';
+import { existsSync, rmSync } from 'node:fs';
+import { run as defaultRun } from '../spawn.js';
+import { StageError } from '../errors.js';
+import { assertSafeShortName } from '../validate.js';
+
+const STAGE = 'clone';
+
+/**
+ * `git clone -- <repo> <shortName>` (no shell, via {@link run}), then strip
+ * the cloned `.git/` so the new project starts with clean history.
+ *
+ * The `--` end-of-options marker means a repo URL or shortName beginning with
+ * `-` is treated as an operand, not a git flag — defense in depth alongside
+ * the no-shell spawn.
+ *
+ * @param {{ repo: string, shortName: string, cwd?: string }} opts
+ * @param {{ run?: typeof defaultRun }} [deps] Inject `run` for unit tests.
+ * @returns {Promise<{ projectDir: string }>}
+ * @throws {StageError} stage 'clone' on spawn failure or non-zero exit.
+ */
+export async function clone(
+  {
+    repo, shortName, cwd = process.cwd()
+  },
+  { run = defaultRun } = {}
+) {
+  // Path-traversal guard before shortName is used as a clone target / path
+  // base. Defense in depth even though the caller is contracted to validate.
+  assertSafeShortName(shortName);
+
+  // Refuse to clone over an existing path. git clone itself rejects non-empty
+  // dirs but accepts empty ones (which a user may have pre-created and
+  // expected us to populate). Stop here either way with a distinct errorCode
+  // so the failure is legible — especially in unattended mode, where the
+  // alternative is a generic `git_clone_failed`.
+  if (existsSync(join(cwd, shortName))) {
+    throw new StageError(STAGE, {
+      code: 'target_exists',
+      cause: new Error(`Target path "${shortName}" already exists in ${cwd}`)
+    });
+  }
+
+  const result = await run('git', [ 'clone', '--', repo, shortName ], { cwd });
+
+  if (result.error) {
+    const code = result.error.code === 'ENOENT' ? 'git_missing' : 'git_spawn_failed';
+    throw new StageError(STAGE, {
+      code,
+      cause: result.error
+    });
+  }
+  if (result.code !== 0) {
+    throw new StageError(STAGE, {
+      code: 'git_clone_failed',
+      cause: new Error(`git clone exited with code ${result.code}`)
+    });
+  }
+
+  const projectDir = join(cwd, shortName);
+  rmSync(join(projectDir, '.git'), {
+    recursive: true,
+    force: true
+  });
+
+  return { projectDir };
+}
diff --git a/packages/create-apostrophe/src/core/steps/db-config.js b/packages/create-apostrophe/src/core/steps/db-config.js
new file mode 100644
index 0000000000..b6416bcec4
--- /dev/null
+++ b/packages/create-apostrophe/src/core/steps/db-config.js
@@ -0,0 +1,96 @@
+// Step: write the database selection into the project .env (core resolves the
+// connection from APOS_DB_URI and/or APOS_DEFAULT_DB_ADAPTER), then verify the
+// connection for real. This is the authoritative connection check — a wrong
+// password or unreachable server fails here with a precise error code.
+
+import { join } from 'node:path';
+import { StageError } from '../errors.js';
+import { upsertEnv } from '../env-file.js';
+import { resolveDbUri } from '../db.js';
+
+/** @typedef {import('../../index.js').DbChoice} DbChoice */
+
+const STAGE = 'db_connect';
+
+// DbChoice maps 1:1 to a core adapter name.
+const DB_CHOICES = new Set([ 'sqlite', 'mongodb', 'postgres' ]);
+
+// db module's classified failure reason → telemetry error code.
+const REASON_CODE = {
+  unreachable: 'db_unreachable',
+  auth: 'db_auth_failed',
+  unknown: 'db_connect_failed'
+};
+
+/**
+ * @param {{
+ *   appRoot: string, dbChoice: DbChoice, dbUri?: string, shortName: string,
+ *   dbReset?: ('keep' | 'drop')
+ * }} opts `dbReset: 'drop'` drops the database after a successful check (the
+ *   user's confirmed "start fresh" consent for a non-empty, non-seed target).
+ * @param {{
+ *   verifyConnection?: (uri: string) => Promise<{
+ *     reachable: boolean, reason?: string, message?: string
+ *   }>,
+ *   dropDatabase?: (uri: string) => Promise<void>
+ * }} [deps] When `verifyConnection` is provided, the resolved URI is checked
+ *   and an unreachable / auth / unknown verdict maps to the matching `db_*`
+ *   StageError code. `dropDatabase` performs the `dbReset: 'drop'` drop.
+ * @returns {Promise<{ dbChoice: DbChoice }>}
+ * @throws {StageError} stage 'db_connect' on a failed check or drop.
+ * @throws {TypeError} for an unknown dbChoice (validation).
+ */
+export async function dbConfig(
+  {
+    appRoot, dbChoice, dbUri, shortName, dbReset = 'keep'
+  },
+  { verifyConnection, dropDatabase } = {}
+) {
+  if (!DB_CHOICES.has(dbChoice)) {
+    throw new TypeError(`Unknown dbChoice: ${JSON.stringify(dbChoice)}.`);
+  }
+
+  const env = { APOS_DEFAULT_DB_ADAPTER: dbChoice };
+  // A connection string only applies to mongodb/postgres; SQLite is a file
+  // path core derives from the project name.
+  if (dbChoice !== 'sqlite' && dbUri) {
+    env.APOS_DB_URI = dbUri;
+  }
+  upsertEnv(join(appRoot, '.env'), env);
+
+  // The resolved URI is needed for both the check and the optional drop.
+  if (verifyConnection || dbReset === 'drop') {
+    const uri = resolveDbUri({
+      dbChoice,
+      dbUri,
+      appRoot,
+      shortName
+    });
+
+    if (verifyConnection) {
+      const result = await verifyConnection(uri);
+      if (!result.reachable) {
+        throw new StageError(STAGE, {
+          code: REASON_CODE[result.reason] ?? 'db_connect_failed',
+          cause: result.message ? new Error(result.message) : undefined
+        });
+      }
+    }
+
+    // Honour the user's "start fresh" consent: drop after we know the
+    // connection is good, so an unreachable/auth failure reports precisely
+    // rather than masquerading as a drop failure.
+    if (dbReset === 'drop' && dropDatabase) {
+      try {
+        await dropDatabase(uri);
+      } catch (err) {
+        throw new StageError(STAGE, {
+          code: 'db_drop_failed',
+          cause: err
+        });
+      }
+    }
+  }
+
+  return { dbChoice };
+}
diff --git a/packages/create-apostrophe/src/core/steps/install.js b/packages/create-apostrophe/src/core/steps/install.js
new file mode 100644
index 0000000000..b860e49a53
--- /dev/null
+++ b/packages/create-apostrophe/src/core/steps/install.js
@@ -0,0 +1,72 @@
+// Step: install dependencies with npm. Standalone installs once in the app
+// root; an external-frontend project installs in backend/ and frontend/.
+// A non-npm manager is rejected up front. Failure → 'dependency_install'.
+
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { run as defaultRun } from '../spawn.js';
+import { StageError } from '../errors.js';
+import { detectPackageManager, assertSupportedPackageManager } from '../pm.js';
+
+/** @typedef {import('../kits.js').Frontend}            Frontend       */
+/** @typedef {import('../../index.js').PackageManager}  PackageManager */
+
+const STAGE = 'dependency_install';
+
+/**
+ * @param {{
+ *   projectDir: string,
+ *   appRoot: string,
+ *   frontend?: Frontend,
+ *   packageManager?: PackageManager
+ * }} opts
+ * @param {{ run?: typeof defaultRun }} [deps]
+ * @returns {Promise<{ packageManager: PackageManager }>}
+ *   The detected manager (may be `'unknown'`); the install runs with npm.
+ * @throws {import('../errors.js').UnsupportedPackageManagerError} non-npm.
+ * @throws {StageError} stage 'dependency_install'.
+ */
+export async function install(
+  {
+    projectDir, appRoot, frontend = null, packageManager
+  },
+  { run = defaultRun } = {}
+) {
+  const detected = packageManager || detectPackageManager();
+  assertSupportedPackageManager(detected);
+
+  const dirs = [ appRoot ];
+  if (frontend !== null) {
+    const frontendDir = join(projectDir, 'frontend');
+    if (existsSync(frontendDir)) {
+      dirs.push(frontendDir);
+    }
+  }
+
+  for (const cwd of dirs) {
+    const result = await run('npm', [ 'install' ], { cwd });
+    if (result.error) {
+      throw new StageError(STAGE, {
+        code: result.error.code === 'ENOENT'
+          ? 'npm_missing'
+          : 'npm_spawn_failed',
+        cause: result.error
+      });
+    }
+    if (result.code !== 0) {
+      throw new StageError(STAGE, {
+        code: 'install_failed',
+        cause: new Error(`npm install exited with code ${result.code}`)
+      });
+    }
+  }
+
+  if (!existsSync(join(appRoot, 'node_modules', 'apostrophe'))) {
+    throw new StageError(STAGE, {
+      code: 'apostrophe_missing',
+      cause: new Error('apostrophe not present after install')
+    });
+  }
+
+  return { packageManager: detected };
+}
diff --git a/packages/create-apostrophe/src/core/steps/sample-data.js b/packages/create-apostrophe/src/core/steps/sample-data.js
new file mode 100644
index 0000000000..80763c720d
--- /dev/null
+++ b/packages/create-apostrophe/src/core/steps/sample-data.js
@@ -0,0 +1,491 @@
+// Step: seed a freshly scaffolded project with the kit's sample database dump
+// and uploaded images. Runs only for kits with `seedData: true` (the
+// `*-demo-data` variants): resolve the asset set → download + checksum-verify →
+// restore the DB → copy attachments.
+//
+// Security: no shell — node:fs only; downloads are verified against an embedded
+// (or kit-supplied) sha256 before any DB write; zip entries are zip-slip guarded.
+
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import crypto from 'node:crypto';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import yauzl from 'yauzl';
+import { StageError } from '../errors.js';
+import {
+  resolveDbUri as realResolveDbUri,
+  restore as realRestore,
+  clearDatabase as realClearDatabase
+} from '../db.js';
+
+const STAGE = 'sample_data';
+
+/** No-op task handle for headless callers that don't render progress. */
+const NOOP_TASK = Object.freeze({
+  succeed() {},
+  fail() {},
+  progress() {}
+});
+
+/**
+ * Settle a task (succeed/fail) around `fn`, re-throwing on failure so the
+ * error still propagates.
+ *
+ * @template T
+ * @param {import('../../index.js').TaskHandle} task
+ * @param {(task: import('../../index.js').TaskHandle) => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+async function runTask(task, fn) {
+  try {
+    const out = await fn(task);
+    task.succeed();
+    return out;
+  } catch (err) {
+    task.fail();
+    throw err;
+  }
+}
+
+/**
+ * Embedded, npm-signed default assets (computed 2026-05-22 from the validated
+ * `public-demo` archives). A cloned kit may wholesale-replace these via
+ * {@link resolveAssets}; verification is always on, so a tampered CDN can't
+ * substitute bytes.
+ */
+export const DEFAULT_ASSETS = Object.freeze({
+  db: {
+    url: 'https://static.apostrophecms.com/public-demo/starter-database.jsonl.zip',
+    sha256: '862fc4b380675e0eaade8447f6a137807ce54b54acbbee79636e581e0c5f29b1'
+  },
+  uploads: {
+    url: 'https://static.apostrophecms.com/public-demo/starter-uploads.zip',
+    sha256: 'b1a70f3372f8c897fd934abbe711cc1a8b0aeaf7d38b165890dd96939ab62f58'
+  }
+});
+
+const ASSET_KEYS = [ 'db', 'uploads' ];
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const MANIFEST_REL = path.join('.apostrophe', 'sample-data.json');
+
+/**
+ * Downloads the uploads archive (progress bar) then imports everything
+ * (spinner): the DB wipe+restore and the uploads extract. A db-only manifest
+ * shows only the import task. Downloads are verified before any DB write.
+ *
+ * @param {{
+ *   appRoot: string,
+ *   dbChoice: import('../../index.js').DbChoice,
+ *   dbUri?: string,
+ *   shortName: string
+ * }} opts
+ * @param {{
+ *   task?: (label: string, opts?: { progress?: boolean })
+ *     => import('../../index.js').TaskHandle,
+ *   fetchImpl?: typeof globalThis.fetch,
+ *   resolveDbUri?: typeof realResolveDbUri,
+ *   restore?: typeof realRestore,
+ *   clearDatabase?: typeof realClearDatabase,
+ *   unpackDbStream?: (zipPath: string) => Promise<Readable>,
+ *   extractAttachments?: (zipPath: string, uploadsRoot: string) => Promise<void>
+ * }} [deps]
+ * @returns {Promise<void>}
+ * @throws {StageError} stage 'sample_data' on any seed failure.
+ */
+export async function importSampleData(
+  {
+    appRoot, dbChoice, dbUri, shortName
+  },
+  {
+    task = () => NOOP_TASK,
+    fetchImpl = globalThis.fetch,
+    resolveDbUri = realResolveDbUri,
+    restore = realRestore,
+    clearDatabase = realClearDatabase,
+    unpackDbStream = defaultUnpackDbStream,
+    extractAttachments = defaultExtractAttachments
+  } = {}
+) {
+  const assets = resolveAssets(appRoot);
+
+  const tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'apos-seed-'));
+  try {
+    const files = {};
+
+    if (assets.uploads) {
+      files.uploads = path.join(tmpDir, 'uploads.zip');
+      await runTask(
+        task('Downloading sample content', { progress: true }),
+        (t) => downloadAndVerify(
+          fetchImpl, assets.uploads, files.uploads, (f) => t.progress?.(f)
+        )
+      );
+    }
+
+    await runTask(task('Importing sample content'), async () => {
+      if (assets.db) {
+        files.db = path.join(tmpDir, 'database.zip');
+        await downloadAndVerify(fetchImpl, assets.db, files.db);
+        const uri = resolveDbUri({
+          dbChoice,
+          dbUri,
+          appRoot,
+          shortName
+        });
+        try {
+          await clearDatabase(uri);
+        } catch (err) {
+          throw new StageError(STAGE, {
+            code: 'seed_clear_failed',
+            cause: err
+          });
+        }
+        let stream;
+        try {
+          stream = await unpackDbStream(files.db);
+        } catch (err) {
+          throw new StageError(STAGE, {
+            code: 'seed_unpack_failed',
+            cause: err
+          });
+        }
+        try {
+          await restore(uri, stream);
+        } catch (err) {
+          throw new StageError(STAGE, {
+            code: 'seed_restore_failed',
+            cause: err
+          });
+        }
+      }
+      if (assets.uploads) {
+        const uploadsRoot = path.join(appRoot, 'public', 'uploads');
+        try {
+          await extractAttachments(files.uploads, uploadsRoot);
+        } catch (err) {
+          throw new StageError(STAGE, {
+            code: 'seed_uploads_failed',
+            cause: err
+          });
+        }
+      }
+    });
+  } finally {
+    await fsp.rm(tmpDir, {
+      recursive: true,
+      force: true
+    });
+  }
+}
+
+/**
+ * Resolve which assets to seed. With no kit manifest the embedded
+ * {@link DEFAULT_ASSETS} are used; a kit's
+ * `<appRoot>/.apostrophe/sample-data.json` **wholesale-replaces** them
+ * (defaults not consulted), each asset optional. A malformed, mis-shaped, or
+ * empty manifest is a kit misconfiguration.
+ *
+ * @param {string} appRoot
+ * @returns {{
+ *   db?: { url: string, sha256: string },
+ *   uploads?: { url: string, sha256: string }
+ * }}
+ * @throws {StageError} stage 'sample_data', code 'seed_manifest_invalid'.
+ */
+export function resolveAssets(appRoot) {
+  let raw;
+  try {
+    raw = fs.readFileSync(path.join(appRoot, MANIFEST_REL), 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return { ...DEFAULT_ASSETS };
+    }
+    throw manifestInvalid(err);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw manifestInvalid(err);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw manifestInvalid(new Error('manifest is not a JSON object'));
+  }
+
+  /** @type {Record<string, { url: string, sha256: string }>} */
+  const resolved = {};
+  for (const key of ASSET_KEYS) {
+    if (parsed[key] === undefined) {
+      continue;
+    }
+    if (!isValidAsset(parsed[key])) {
+      throw manifestInvalid(
+        new Error(`manifest "${key}" is not a valid { url, sha256 } pair`)
+      );
+    }
+    resolved[key] = {
+      url: parsed[key].url,
+      sha256: parsed[key].sha256
+    };
+  }
+  if (Object.keys(resolved).length === 0) {
+    throw manifestInvalid(new Error('manifest declares neither "db" nor "uploads"'));
+  }
+  return resolved;
+}
+
+/**
+ * A declared asset must be `{ url: <https>, sha256: <64-hex-lowercase> }`.
+ * @param {unknown} a
+ * @returns {boolean}
+ */
+function isValidAsset(a) {
+  if (!a || typeof a !== 'object') {
+    return false;
+  }
+  const { url, sha256 } = /** @type {{ url?: unknown, sha256?: unknown }} */ (a);
+  if (typeof url !== 'string' || typeof sha256 !== 'string') {
+    return false;
+  }
+  if (!SHA256_RE.test(sha256)) {
+    return false;
+  }
+  try {
+    return new URL(url).protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/** @param {Error} cause */
+function manifestInvalid(cause) {
+  return new StageError(STAGE, {
+    code: 'seed_manifest_invalid',
+    cause
+  });
+}
+
+/**
+ * Stream a download to disk, teeing through a sha256 hash. The file is only
+ * accepted if the digest matches `asset.sha256` — a mismatch aborts before
+ * any DB write.
+ *
+ * @param {typeof globalThis.fetch} fetchImpl
+ * @param {{ url: string, sha256: string }} asset
+ * @param {string} destPath
+ * @param {((fraction: number) => void)} [onProgress]
+ * @returns {Promise<void>}
+ * @throws {StageError} 'seed_download_failed' / 'seed_checksum_failed'.
+ */
+async function downloadAndVerify(fetchImpl, asset, destPath, onProgress) {
+  let res;
+  try {
+    res = await fetchImpl(asset.url);
+  } catch (err) {
+    throw new StageError(STAGE, {
+      code: 'seed_download_failed',
+      cause: err
+    });
+  }
+  if (!res || !res.ok) {
+    throw new StageError(STAGE, {
+      code: 'seed_download_failed',
+      cause: new Error(`unexpected response ${res ? res.status : '?'} for ${asset.url}`)
+    });
+  }
+
+  const total = Number(res.headers.get('content-length')) || 0;
+  const hash = crypto.createHash('sha256');
+  let loaded = 0;
+  let lastPct = -1;
+
+  try {
+    await pipeline(
+      toNodeReadable(res.body),
+      async function * tee(source) {
+        for await (const chunk of source) {
+          hash.update(chunk);
+          loaded += chunk.length;
+          if (total && onProgress) {
+            const pct = Math.floor((loaded / total) * 100);
+            if (pct !== lastPct) {
+              lastPct = pct;
+              onProgress(loaded / total);
+            }
+          }
+          yield chunk;
+        }
+      },
+      fs.createWriteStream(destPath)
+    );
+  } catch (err) {
+    throw new StageError(STAGE, {
+      code: 'seed_download_failed',
+      cause: err
+    });
+  }
+
+  if (hash.digest('hex') !== asset.sha256) {
+    throw new StageError(STAGE, {
+      code: 'seed_checksum_failed',
+      cause: new Error(`sha256 mismatch for ${asset.url}`)
+    });
+  }
+}
+
+/**
+ * fetch bodies are WHATWG streams; tests may inject a Node Readable directly.
+ * @param {any} body
+ * @returns {Readable}
+ */
+function toNodeReadable(body) {
+  if (body && typeof body.pipe === 'function') {
+    return body;
+  }
+  return Readable.fromWeb(body);
+}
+
+/**
+ * Open the single `.jsonl` entry of the DB zip as a readable stream, closing
+ * the archive once the stream is consumed. The dump is db-connect's own
+ * restore format (flat, one file entry).
+ *
+ * @param {string} zipPath
+ * @returns {Promise<Readable>}
+ */
+function defaultUnpackDbStream(zipPath) {
+  return new Promise((resolve, reject) => {
+    yauzl.open(zipPath, { lazyEntries: true }, (err, zip) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      let found = false;
+      zip.on('entry', (entry) => {
+        if (entry.fileName.endsWith('/')) {
+          zip.readEntry();
+          return;
+        }
+        found = true;
+        zip.openReadStream(entry, (streamErr, stream) => {
+          if (streamErr) {
+            zip.close();
+            reject(streamErr);
+            return;
+          }
+          stream.once('end', () => zip.close());
+          stream.once('error', () => zip.close());
+          resolve(stream);
+        });
+      });
+      zip.once('error', reject);
+      zip.once('end', () => {
+        if (!found) {
+          zip.close();
+          reject(new Error('database archive contains no file entry'));
+        }
+      });
+      zip.readEntry();
+    });
+  });
+}
+
+/**
+ * Extract the uploads archive — which holds the attachment files directly,
+ * at its root — into `<uploadsRoot>/attachments/`. Directory entries and
+ * zip-slip-escaping entries are skipped.
+ *
+ * @param {string} zipPath
+ * @param {string} uploadsRoot  `<appRoot>/public/uploads`
+ * @returns {Promise<void>}
+ */
+function defaultExtractAttachments(zipPath, uploadsRoot) {
+  const attachmentsRoot = path.join(uploadsRoot, 'attachments');
+  return new Promise((resolve, reject) => {
+    // autoClose:false — we collect all entries first, then open their read
+    // streams; the default would close the file on the last entry. extractAll
+    // closes it when done.
+    yauzl.open(zipPath, {
+      lazyEntries: true,
+      autoClose: false
+    }, (err, zip) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      /** @type {Array<{ entry: any, dest: string }>} */
+      const entries = [];
+      zip.on('entry', (entry) => {
+        const name = entry.fileName;
+        const dest = name.endsWith('/')
+          ? null
+          : safeJoin(attachmentsRoot, name);
+        if (dest) {
+          entries.push({
+            entry,
+            dest
+          });
+        }
+        zip.readEntry();
+      });
+      zip.once('error', reject);
+      zip.once('end', () => {
+        extractAll(zip, entries).then(resolve, reject);
+      });
+      zip.readEntry();
+    });
+  });
+}
+
+/**
+ * @param {any} zip
+ * @param {Array<{ entry: any, dest: string }>} entries
+ */
+async function extractAll(zip, entries) {
+  try {
+    for (const { entry, dest } of entries) {
+      await fsp.mkdir(path.dirname(dest), { recursive: true });
+      const stream = await openEntry(zip, entry);
+      await pipeline(stream, fs.createWriteStream(dest));
+    }
+  } finally {
+    zip.close();
+  }
+}
+
+/**
+ * @param {any} zip
+ * @param {any} entry
+ * @returns {Promise<Readable>}
+ */
+function openEntry(zip, entry) {
+  return new Promise((resolve, reject) => {
+    zip.openReadStream(entry, (err, stream) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      resolve(stream);
+    });
+  });
+}
+
+/**
+ * Join an archive entry path under `root`, returning `null` if the resolved
+ * destination escapes `root` (zip-slip: `..` segments or absolute paths).
+ *
+ * @param {string} root
+ * @param {string} name
+ * @returns {string | null}
+ */
+function safeJoin(root, name) {
+  const dest = path.resolve(root, name);
+  if (dest !== root && !dest.startsWith(root + path.sep)) {
+    return null;
+  }
+  return dest;
+}
diff --git a/packages/create-apostrophe/src/core/steps/scaffold.js b/packages/create-apostrophe/src/core/steps/scaffold.js
new file mode 100644
index 0000000000..2e97ae1a08
--- /dev/null
+++ b/packages/create-apostrophe/src/core/steps/scaffold.js
@@ -0,0 +1,115 @@
+// Step: minimal imprint of the cloned starter.
+
+import { join } from 'node:path';
+import {
+  existsSync, readFileSync, writeFileSync
+} from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { StageError } from '../errors.js';
+import { assertSafeShortName } from '../validate.js';
+import { writeIfAbsent, upsertEnv } from '../env-file.js';
+import {
+  standaloneEnv, externalBackendEnv, externalFrontendEnv, SECRET_KEYS
+} from '../env-templates.js';
+
+/** @typedef {import('../kits.js').Frontend} Frontend */
+
+const STAGE = 'scaffold';
+
+/** Frontend names with a delivered `.env` template. Supporting another is a
+ * deliberate change here + a new template, not a new boolean elsewhere. */
+const SUPPORTED_FRONTENDS = new Set([ 'astro' ]);
+
+/** 32 random bytes as hex (256-bit). */
+function secret() {
+  return randomBytes(32).toString('hex');
+}
+
+function replaceInFile(file, regex, replacement) {
+  const content = readFileSync(file, 'utf8');
+  writeFileSync(file, content.replace(regex, replacement));
+}
+
+/** Fresh generated value for each secret key. */
+function generatedSecrets() {
+  return Object.fromEntries(SECRET_KEYS.map((k) => [ k, secret() ]));
+}
+
+/**
+ * @param {{
+ *   projectDir: string,
+ *   shortName: string,
+ *   frontend?: Frontend
+ * }} opts `frontend` is the kit's external-frontend name (null = standalone).
+ * @returns {{ frontend: Frontend, appRoot: string, envFiles: string[] }}
+ * @throws {StageError} stage 'scaffold' on a missing required file or I/O.
+ * @throws {TypeError} for an unsupported `frontend` name (validation error).
+ */
+export function scaffold({
+  projectDir, shortName, frontend = null
+}) {
+  assertSafeShortName(shortName);
+
+  if (frontend !== null && !SUPPORTED_FRONTENDS.has(frontend)) {
+    throw new TypeError(
+      `Unsupported frontend: ${JSON.stringify(frontend)}. ` +
+      `Expected null or one of: ${[ ...SUPPORTED_FRONTENDS ].join(', ')}.`
+    );
+  }
+
+  // An external-frontend kit nests the Apostrophe app under backend/;
+  // standalone keeps it at the project root. The frontend NAME (from the kit)
+  // decides the layout.
+  const external = frontend !== null;
+  const appRoot = external ? join(projectDir, 'backend') : projectDir;
+  const resolve = (rel) => join(appRoot, rel);
+
+  const appJs = resolve('app.js');
+  const packageJson = resolve('package.json');
+  for (const required of [ appJs, packageJson ]) {
+    if (!existsSync(required)) {
+      throw new StageError(STAGE, {
+        code: 'missing_scaffold_file',
+        cause: new Error(`expected ${required} in the cloned starter`)
+      });
+    }
+  }
+
+  try {
+    // Non-secret identity only.
+    replaceInFile(appJs, /(shortName:).*?,/gi, `$1 '${shortName}',`);
+    replaceInFile(packageJson, /("name":).*?,/g, `$1 "${shortName.toLowerCase()}",`);
+
+    // Deliver our own .env template(s) and fill the generated secrets.
+    const envFiles = [];
+    const appEnv = join(appRoot, '.env');
+    writeIfAbsent(
+      appEnv, external ? externalBackendEnv(frontend) : standaloneEnv()
+    );
+    upsertEnv(appEnv, generatedSecrets());
+    envFiles.push(appEnv);
+
+    if (external) {
+      const frontendDir = join(projectDir, 'frontend');
+      if (existsSync(frontendDir)) {
+        const frontEnv = join(frontendDir, '.env');
+        writeIfAbsent(frontEnv, externalFrontendEnv(frontend));
+        envFiles.push(frontEnv);
+      }
+    }
+
+    return {
+      frontend,
+      appRoot,
+      envFiles
+    };
+  } catch (err) {
+    if (err instanceof StageError) {
+      throw err;
+    }
+    throw new StageError(STAGE, {
+      code: 'scaffold_io',
+      cause: err
+    });
+  }
+}
diff --git a/packages/create-apostrophe/src/core/store.js b/packages/create-apostrophe/src/core/store.js
new file mode 100644
index 0000000000..7a7893dffa
--- /dev/null
+++ b/packages/create-apostrophe/src/core/store.js
@@ -0,0 +1,113 @@
+// Local persistent key/value store.
+
+import {
+  mkdirSync, readFileSync, writeFileSync, renameSync, rmSync
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/**
+ * Keys this store is allowed to hold. Anything else is a programmer error
+ * (a thrown TypeError).
+ */
+export const KNOWN_KEYS = Object.freeze([ 'telemetryConsent', 'anonymousId' ]);
+
+const APP_DIR = 'create-apostrophe';
+
+/**
+ * Per-OS user config directory, replicating the env-paths/XDG conventions
+ * with Node built-ins only (no dependency):
+ *   - Windows: %APPDATA%            (…/AppData/Roaming fallback)
+ *   - macOS:   ~/Library/Preferences
+ *   - other:   $XDG_CONFIG_HOME     (~/.config fallback)
+ * @returns {string}
+ */
+export function configDir() {
+  if (process.platform === 'win32') {
+    const base = process.env.APPDATA || join(homedir(), 'AppData', 'Roaming');
+    return join(base, APP_DIR, 'Config');
+  }
+  if (process.platform === 'darwin') {
+    return join(homedir(), 'Library', 'Preferences', APP_DIR);
+  }
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(base, APP_DIR);
+}
+
+/** Default backing-file path (…/create-apostrophe/store.json). */
+export function defaultStorePath() {
+  return join(configDir(), 'store.json');
+}
+
+function readAll(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeAll(file, data) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+  // Atomic replace on the same filesystem: a reader sees either the old or
+  // the new file, never a half-written one.
+  renameSync(tmp, file);
+}
+
+function assertKnown(key) {
+  if (!KNOWN_KEYS.includes(key)) {
+    throw new TypeError(
+      `Unknown store key: ${key}. Allowed: ${KNOWN_KEYS.join(', ')}`
+    );
+  }
+}
+
+/**
+ * Open the store. Pass `dir` to override the location — unit tests point it
+ * at a temp dir; production uses the per-OS user config dir.
+ * @param {{ dir?: string }} [opts]
+ * @returns {{
+ *   path: string,
+ *   get(key: string): *,
+ *   set(key: string, value: *): void,
+ *   delete(key: string): void,
+ *   clear(): void,
+ *   all(): object
+ * }}
+ */
+export function createStore({ dir } = {}) {
+  const file = dir ? join(dir, 'store.json') : defaultStorePath();
+
+  return {
+    path: file,
+
+    get(key) {
+      assertKnown(key);
+      return readAll(file)[key];
+    },
+
+    set(key, value) {
+      assertKnown(key);
+      const data = readAll(file);
+      data[key] = value;
+      writeAll(file, data);
+    },
+
+    delete(key) {
+      assertKnown(key);
+      const data = readAll(file);
+      delete data[key];
+      writeAll(file, data);
+    },
+
+    clear() {
+      rmSync(file, { force: true });
+    },
+
+    all() {
+      return readAll(file);
+    }
+  };
+}
diff --git a/packages/create-apostrophe/src/core/validate.js b/packages/create-apostrophe/src/core/validate.js
new file mode 100644
index 0000000000..2faae110ca
--- /dev/null
+++ b/packages/create-apostrophe/src/core/validate.js
@@ -0,0 +1,19 @@
+// Defense-in-depth input validation for security-sensitive values.
+
+/** Letters, digits, hyphen, underscore — no separators, no dots, no `..`. */
+const SAFE_SHORT_NAME = /^[\w-]+$/;
+
+/**
+ * @param {string} shortName
+ * @returns {string} the validated value (for inline use).
+ * @throws {TypeError} if it is empty, non-string, or path-unsafe.
+ */
+export function assertSafeShortName(shortName) {
+  if (typeof shortName !== 'string' || !SAFE_SHORT_NAME.test(shortName)) {
+    throw new TypeError(
+      `Unsafe shortName: ${JSON.stringify(shortName)}. ` +
+      'Only letters, numbers, hyphens and underscores are allowed.'
+    );
+  }
+  return shortName;
+}
diff --git a/packages/create-apostrophe/src/index.js b/packages/create-apostrophe/src/index.js
new file mode 100644
index 0000000000..c8640ec7f0
--- /dev/null
+++ b/packages/create-apostrophe/src/index.js
@@ -0,0 +1,220 @@
+// Public API of create-apostrophe. This is the only module consumers may
+// import; everything under core/, ui/ and telemetry/ is private.
+//
+// Re-exports:
+//   - createProject       (headless install orchestration)
+//   - runInteractive      (structured entry — guided install with no argv
+//                          parsing; the @apostrophecms/cli `create`
+//                          delegate uses this so Commander keeps ownership
+//                          of help)
+//   - runTelemetryCommand (status | on | off | preview, structured entry;
+//                          the apos `telemetry` delegate uses this)
+//   - runCli              (argv-driven entry for the standalone bin and
+//                          any host that wants full pass-through)
+//
+// The typedefs below are the shared contract between the UI, core and
+// telemetry layers.
+
+/**
+ * Starter-kit identifier. `astro` kits pair an Astro frontend with an
+ * Apostrophe backend; the others are full-stack standalone. `demo` kits
+ * scaffold a working example; `demo-data` additionally seeds a database
+ * dump and sample images. Multisite/pro kits are not offered here.
+ * @typedef {(
+ *   'apostrophe-astro-essentials' |
+ *   'apostrophe-astro-demo' |
+ *   'apostrophe-astro-demo-data' |
+ *   'apostrophe-essentials' |
+ *   'apostrophe-demo' |
+ *   'apostrophe-demo-data'
+ * )} KitId
+ */
+
+/**
+ * Database selection. Used for both the createProject input and the
+ * telemetry dbChoice value.
+ * @typedef {('sqlite' | 'mongodb' | 'postgres')} DbChoice
+ */
+
+/**
+ * Package manager, detected from the environment (never self-reported).
+ * `'unknown'` when it cannot be determined.
+ * @typedef {('npm' | 'pnpm' | 'yarn' | 'unknown')} PackageManager
+ */
+
+/**
+ * The stage a failed install is attributed to. `null` means the failure
+ * happened in preflight (Node version / package manager), before any stage
+ * ran — every step is skipped. Otherwise exactly one stage per failure.
+ * @typedef {(
+ *   'clone' | 'dependency_install' | 'db_connect' | 'scaffold' | 'sample_data'
+ *   | 'admin' | 'unknown' | null
+ * )} FailStage
+ */
+
+/**
+ * Terminal telemetry event. Exactly one is emitted per attempt.
+ * @typedef {('install_success' | 'install_fail')} TelemetryEvent
+ */
+
+/**
+ * Admin account created during install. `username` is the value the user
+ * will log in with; it may be email-shaped (a single field, no separate
+ * email). Never reaches telemetry.
+ * @typedef {object} AdminAccount
+ * @property {string} username Username or email.
+ * @property {string} password Plaintext; passed over stdin, never logged.
+ */
+
+/**
+ * Fully resolved, already-validated inputs. createProject does not prompt.
+ * @typedef {object} CreateProjectOptions
+ * @property {string}          shortName        Project/directory name.
+ * @property {string}          cwd              Authoritative working
+ *                                              directory the install runs
+ *                                              from. The caller (bin / UI)
+ *                                              captures it once and threads
+ *                                              it in; steps must not call
+ *                                              process.cwd() on their own.
+ * @property {KitId}           kitId            Starter kit.
+ * @property {DbChoice}        dbChoice         Database selection.
+ * @property {string}          [dbUri]          Connection string for
+ *                                              mongodb/postgres. Never sent to
+ *                                              telemetry. Ignored for sqlite.
+ * @property {AdminAccount}    admin            Admin account to create.
+ * @property {PackageManager}  [packageManager] Override; otherwise detected.
+ * @property {('keep' | 'drop')} [dbReset]      Consent to drop a pre-existing
+ *                                              mongodb/postgres database before
+ *                                              install. `'drop'` only when the
+ *                                              user explicitly confirmed it for
+ *                                              a non-empty, non-seed target;
+ *                                              defaults to `'keep'`. (Seed kits
+ *                                              reset the DB in the sample-data
+ *                                              step, not via this flag.)
+ * @property {boolean}         nonInteractive   CI mode: no prompts downstream.
+ * @property {number}          confirmedAt      Plan-confirmation timestamp
+ *                                              (epoch ms), set by the caller.
+ *                                              Source of durationMs.
+ */
+
+/**
+ * Structured outcome. createProject never throws for an expected install
+ * failure and never calls process.exit: it resolves with `ok: false` and a
+ * `failStage`. An unexpected throw is the caller's to convert into a fail
+ * result.
+ * @typedef {object} CreateProjectResult
+ * @property {boolean}         ok             Whether the project was created.
+ * @property {KitId}           kitId
+ * @property {DbChoice}        dbChoice       Echo of the input.
+ * @property {PackageManager}  packageManager Resolved value.
+ * @property {number}          durationMs     `Date.now() - options.confirmedAt`.
+ * @property {FailStage}       [failStage]    Present iff `ok === false`;
+ *                                            `null` for a preflight failure.
+ * @property {string}          [errorCode]    Present only for known,
+ *                                            allowlisted error codes.
+ */
+
+/**
+ * Partial payload createProject hands to {@link TelemetryHook.event}. The
+ * telemetry layer adds `event` (discriminator), `cliVersion`, and
+ * `anonymousId` before sending; the schema validators reject any field
+ * outside this allowlist. `failStage`/`errorCode` are present iff the result
+ * was a failure. `errorCode` is typed `string` here — the telemetry-side
+ * allowlist drops unknown codes, so the contract stays permissive while the
+ * wire stays strict.
+ * @typedef {object} TelemetryEventPayload
+ * @property {KitId}           kitId
+ * @property {DbChoice}        dbChoice
+ * @property {PackageManager}  packageManager
+ * @property {number}          durationMs
+ * @property {FailStage}       [failStage]
+ * @property {string}          [errorCode]
+ */
+
+/**
+ * Telemetry hook injected into createProject. Called exactly once, at the
+ * single terminal point. Fire-and-forget: `event` must not throw or delay
+ * the caller.
+ * @typedef {object} TelemetryHook
+ * @property {(name: TelemetryEvent, payload: TelemetryEventPayload) => void} event
+ */
+
+/**
+ * Hook returned by {@link createTelemetry}. Extends {@link TelemetryHook}
+ * with `flush()` so the bin can await any in-flight emission at process
+ * exit. `event()` is fire-and-forget; `flush()` is the bounded wait.
+ * @typedef {TelemetryHook & { flush(): Promise<void> }} ManagedTelemetryHook
+ */
+
+/**
+ * Handle returned by `Logger.task` to settle a unit of work.
+ * @typedef {object} TaskHandle
+ * @property {(msg?: string) => void} succeed
+ * @property {(msg?: string) => void} fail
+ * @property {(fraction: number) => void} [progress]
+ *   Optional progress channel for a task opened with `{ progress: true }`
+ *   (e.g. a streamed download). `fraction` is 0–1, forward-only, of *this*
+ *   task. Spinner tasks ignore it; loggers with no visual progress surface
+ *   (headless/test) omit it — callers treat it as optional
+ *   (`task.progress?.(...)`).
+ */
+
+/**
+ * Headless progress sink injected into createProject, keeping core
+ * UI-agnostic. The UI layer adapts its spinners to this; tests pass a
+ * recording stub. `task` opens a unit of work and returns a handle.
+ * @typedef {object} Logger
+ * @property {(msg: string) => void}         info
+ * @property {(msg: string) => void}         warn
+ * @property {(msg: string) => void}         error
+ * @property {(msg: string) => void}         [muted]  Optional dimmed-aside
+ *   channel for inline notes the user can ignore (e.g. recovery hints).
+ *   Optional so the contract stays backwards-compatible with existing
+ *   logger stubs.
+ * @property {(label: string, opts?: { progress?: boolean }) => TaskHandle} task
+ *   Open a unit of work. `{ progress: true }` renders a progress bar (advance
+ *   it via the handle's `progress()`); otherwise a spinner.
+ */
+
+/**
+ * @typedef {object} CreateProjectDeps
+ * @property {TelemetryHook} telemetry
+ * @property {Logger}        logger
+ */
+
+/**
+ * Headless project orchestration: no prompts, no process.exit, no UI imports.
+ * @typedef {(
+ *   options: CreateProjectOptions,
+ *   deps: CreateProjectDeps
+ * ) => Promise<CreateProjectResult>} CreateProject
+ */
+
+/**
+ * Construction-time config for the telemetry client. The caller reads
+ * consent + anonymousId from the local store and passes them in;
+ * createTelemetry performs no store I/O. `consent: false` makes the
+ * returned hook a no-op (no payload built, no transport invoked).
+ * @typedef {object} TelemetryConfig
+ * @property {boolean} consent      Opt-in result.
+ * @property {string}  cliVersion   Semver of the invoking package.
+ * @property {string}  [anonymousId] Stable anonymous identifier (UUID v4).
+ *                                  Generated by consent.js on first opt-in,
+ *                                  reused thereafter. Absent until the user
+ *                                  has ever opted in.
+ * @property {string}  [endpoint]   Analytics endpoint override.
+ * @property {string}  [writeKey]   Analytics write key (Umami website id)
+ *                                  override.
+ * @property {string}  [hostname]   Wire payload `hostname` override
+ *                                  (matches Umami's site-domain filter).
+ * @property {boolean} [verbose]    Surface transport errors (otherwise silent).
+ */
+
+/**
+ * @typedef {(config: TelemetryConfig) => ManagedTelemetryHook} CreateTelemetry
+ */
+
+export { createProject } from './core/create-project.js';
+export {
+  main as runCli, runInteractive, runTelemetryCommand
+} from './cli/main.js';
diff --git a/packages/create-apostrophe/src/telemetry/commands.js b/packages/create-apostrophe/src/telemetry/commands.js
new file mode 100644
index 0000000000..05a6985eca
--- /dev/null
+++ b/packages/create-apostrophe/src/telemetry/commands.js
@@ -0,0 +1,158 @@
+// Headless management surface for telemetry. Handlers the bin wires to argv
+// subcommands:
+//
+//   create-apostrophe [--telemetry-preview]   → see preview()
+//   create-apostrophe telemetry status        → see status()
+//   create-apostrophe telemetry on            → see optIn()
+//   create-apostrophe telemetry off           → see optOut()
+//
+// Each function returns a structured result; rendering is the UI layer's job.
+
+import {
+  isKillSwitchOn,
+  readConsent,
+  setConsent,
+  getAnonymousId,
+  previewPayload
+} from './consent.js';
+
+/** @typedef {ReturnType<typeof import('../core/store.js').createStore>} Store */
+/** @typedef {NodeJS.ProcessEnv}                                        Env   */
+/** @typedef {import('./schema.js').SuccessPayload}                     SuccessPayload */
+
+/**
+ * @typedef {('kill-switch' | 'stored' | 'default')} StatusSource
+ *   - `kill-switch`: `APOS_TELEMETRY=0` is forcing OFF, regardless of store.
+ *   - `stored`: store has an explicit `true`/`false`.
+ *   - `default`: store is unset (effective value is `false`, opt-in only).
+ */
+
+/**
+ * @typedef {object} StatusResult
+ * @property {boolean}           consent       Effective value the emitter acts on.
+ * @property {boolean}           killSwitchOn  `APOS_TELEMETRY=0` is set.
+ * @property {boolean|undefined} storedConsent Raw stored value (undefined = unset).
+ * @property {string|undefined}  anonymousId   Stored id (undefined until ever opted in).
+ * @property {StatusSource}      source        Which input determined `consent`.
+ */
+
+/**
+ * Read effective telemetry state without changing anything.
+ *
+ * @param {Store} store
+ * @param {Env}   [env]
+ * @returns {StatusResult}
+ */
+export function status(store, env = process.env) {
+  const killSwitchOn = isKillSwitchOn(env);
+  const raw = store.get('telemetryConsent');
+  const storedConsent = typeof raw === 'boolean' ? raw : undefined;
+  /** @type {StatusSource} */
+  let source;
+  if (killSwitchOn) {
+    source = 'kill-switch';
+  } else if (storedConsent !== undefined) {
+    source = 'stored';
+  } else {
+    source = 'default';
+  }
+  return {
+    consent: readConsent(store, env),
+    killSwitchOn,
+    storedConsent,
+    anonymousId: getAnonymousId(store),
+    source
+  };
+}
+
+/**
+ * @typedef {object} OptInResult
+ * @property {true}              consent
+ * @property {string}            anonymousId  Existing id, or newly generated.
+ * @property {boolean}           idGenerated  Whether this call created the id.
+ * @property {boolean}           killSwitchOn Persisted setting is overridden by env.
+ */
+
+/**
+ * Persist opt-in. Generates an `anonymousId` if none exists; reuses the
+ * stored one otherwise. The kill switch is reported but does NOT block the
+ * write — the user's preference is saved either way, the env wins at
+ * emission time.
+ *
+ * @param {Store} store
+ * @param {Env}   [env]
+ * @returns {OptInResult}
+ */
+export function optIn(store, env = process.env) {
+  const before = getAnonymousId(store);
+  const result = setConsent(store, true);
+  const anonymousId = result.anonymousId ?? '';
+  return {
+    consent: true,
+    anonymousId,
+    idGenerated: before === undefined && anonymousId.length > 0,
+    killSwitchOn: isKillSwitchOn(env)
+  };
+}
+
+/**
+ * @typedef {object} OptOutResult
+ * @property {false}             consent
+ * @property {string|undefined}  anonymousId  Preserved on opt-out; same value
+ *                                            as before, or undefined if none.
+ */
+
+/**
+ * Persist opt-out. Preserves any existing `anonymousId` so a later opt-in
+ * resumes the same identity. Use {@link forgetIdentity} (from consent.js) if
+ * you want a full reset — not exposed as a subcommand today.
+ *
+ * @param {Store} store
+ * @returns {OptOutResult}
+ */
+export function optOut(store) {
+  setConsent(store, false);
+  return {
+    consent: false,
+    anonymousId: getAnonymousId(store)
+  };
+}
+
+/**
+ * @typedef {object} PreviewResult
+ * @property {SuccessPayload} payload         Exact would-be payload (built via
+ *                                            `buildPayload`, no separate code path).
+ * @property {boolean}        consent         Effective state at preview time.
+ * @property {boolean}        killSwitchOn
+ * @property {boolean}        idSentinel      `true` when no real `anonymousId` is
+ *                                            stored yet; preview used the
+ *                                            placeholder `00000000-…`.
+ */
+
+/**
+ * Build the would-be payload for `--telemetry-preview`. Sends nothing.
+ *
+ * @param {{
+ *   store: Store,
+ *   cliVersion: string,
+ *   env?: Env,
+ *   sample?: Partial<Pick<import('./schema.js').BasePayloadInput,
+ *     'kitId' | 'dbChoice' | 'packageManager' | 'durationMs'>>
+ * }} opts
+ * @returns {PreviewResult}
+ */
+export function preview({
+  store, cliVersion, env = process.env, sample
+}) {
+  const payload = previewPayload({
+    store,
+    cliVersion,
+    sample
+  });
+  return {
+    payload,
+    consent: readConsent(store, env),
+    killSwitchOn: isKillSwitchOn(env),
+    idSentinel: getAnonymousId(store) === undefined
+  };
+}
diff --git a/packages/create-apostrophe/src/telemetry/consent.js b/packages/create-apostrophe/src/telemetry/consent.js
new file mode 100644
index 0000000000..ebdda2b593
--- /dev/null
+++ b/packages/create-apostrophe/src/telemetry/consent.js
@@ -0,0 +1,145 @@
+// Consent + identity surface for telemetry. Owns the rules around when the
+// CLI may emit at all (env kill switch beats stored consent), and the stable
+// anonymousId tied to consent (generated once on first opt-in, reused on
+// subsequent installs, never deleted on opt-out so a later opt-in resumes
+// the same identity).
+//
+// Pure orchestration over `core/store.js`: no I/O of its own beyond the
+// store, no transport, no UI imports.
+
+import { randomUUID } from 'node:crypto';
+import { buildPayload } from './schema.js';
+
+/** @typedef {ReturnType<typeof import('../core/store.js').createStore>} Store */
+/** @typedef {import('./schema.js').SuccessPayload} SuccessPayload      */
+/** @typedef {NodeJS.ProcessEnv}                    Env                 */
+
+/**
+ * Env var that hard-disables telemetry regardless of stored consent.
+ * Only the literal value `'0'` triggers the kill switch — any other value
+ * (including `'false'`, `'off'`, unset) defers to the stored value.
+ */
+const KILL_SWITCH_VAR = 'APOS_TELEMETRY';
+const KILL_SWITCH_OFF = '0';
+
+/**
+ * True iff the env kill switch is set. The check is intentionally narrow:
+ * only `APOS_TELEMETRY=0` counts, so a stray `APOS_TELEMETRY=true` cannot
+ * accidentally disable telemetry for a user who opted in.
+ *
+ * @param {Env} [env]
+ * @returns {boolean}
+ */
+export function isKillSwitchOn(env = process.env) {
+  return env[KILL_SWITCH_VAR] === KILL_SWITCH_OFF;
+}
+
+/**
+ * Effective consent: the value the emitter should actually act on. Env beats
+ * store; unset store is `false` (opt-in only — no preselected default).
+ *
+ * @param {Store} store
+ * @param {Env}   [env]
+ * @returns {boolean}
+ */
+export function readConsent(store, env = process.env) {
+  if (isKillSwitchOn(env)) {
+    return false;
+  }
+  return store.get('telemetryConsent') === true;
+}
+
+/**
+ * Persist the user's choice. On a transition into `true` (from `false` or
+ * unset) generate a fresh `anonymousId` if none exists. Going off does NOT
+ * clear the id — a later on/off/on cycle keeps stable identity for the user
+ * who once consented. To fully wipe identity, call {@link forgetIdentity}.
+ *
+ * @param {Store}   store
+ * @param {boolean} value
+ * @returns {{ consent: boolean, anonymousId: string | undefined }} the new
+ *   effective state of the store (anonymousId is `undefined` only when
+ *   consent is being set to `false` and none has ever been generated).
+ */
+export function setConsent(store, value) {
+  if (typeof value !== 'boolean') {
+    throw new TypeError(`setConsent: expected boolean, got ${typeof value}`);
+  }
+  store.set('telemetryConsent', value);
+  let anonymousId = getAnonymousId(store);
+  if (value && !anonymousId) {
+    anonymousId = randomUUID();
+    store.set('anonymousId', anonymousId);
+  }
+  return {
+    consent: value,
+    anonymousId
+  };
+}
+
+/**
+ * Read the stored anonymous id without generating one. Returns `undefined`
+ * until the user has opted in at least once.
+ *
+ * @param {Store} store
+ * @returns {string | undefined}
+ */
+export function getAnonymousId(store) {
+  const id = store.get('anonymousId');
+  return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
+
+/**
+ * Wipe both consent and the anonymous id. Used by the `telemetry off`
+ * command when we want a full reset (caller's policy) and by tests.
+ *
+ * @param {Store} store
+ */
+export function forgetIdentity(store) {
+  store.delete('telemetryConsent');
+  store.delete('anonymousId');
+}
+
+/**
+ * Placeholder values used by {@link previewPayload} when the caller has not
+ * yet made their selections (e.g. `--telemetry-preview` invoked standalone).
+ * They are valid enum values so the schema accepts them; the *shape* of the
+ * payload is what the preview is meant to demonstrate.
+ * @type {Required<Pick<import('./schema.js').BasePayloadInput,
+ *   'kitId' | 'dbChoice' | 'packageManager' | 'durationMs'>>}
+ */
+const PREVIEW_DEFAULTS = Object.freeze({
+  kitId: 'apostrophe-astro-demo',
+  dbChoice: 'sqlite',
+  packageManager: 'npm',
+  durationMs: 0
+});
+
+/**
+ * Build the exact payload the CLI would emit for an `install_success`
+ * event, suitable for printing to the user. Uses the real `anonymousId` if
+ * one is stored; otherwise a sentinel string the UI can render as
+ * "(will be generated on opt-in)". Goes through {@link buildPayload}, so
+ * the result is field-for-field what the live emitter would send — there is
+ * no separate "preview" code path that could drift.
+ *
+ * @param {{
+ *   store: Store,
+ *   cliVersion: string,
+ *   sample?: Partial<Pick<import('./schema.js').BasePayloadInput,
+ *     'kitId' | 'dbChoice' | 'packageManager' | 'durationMs'>>
+ * }} opts
+ * @returns {SuccessPayload}
+ */
+export function previewPayload({
+  store, cliVersion, sample = {}
+}) {
+  return buildPayload('install_success', {
+    cliVersion,
+    anonymousId: getAnonymousId(store) ?? '00000000-0000-0000-0000-000000000000',
+    kitId: sample.kitId ?? PREVIEW_DEFAULTS.kitId,
+    dbChoice: sample.dbChoice ?? PREVIEW_DEFAULTS.dbChoice,
+    packageManager: sample.packageManager ?? PREVIEW_DEFAULTS.packageManager,
+    durationMs: sample.durationMs ?? PREVIEW_DEFAULTS.durationMs
+  });
+}
diff --git a/packages/create-apostrophe/src/telemetry/index.js b/packages/create-apostrophe/src/telemetry/index.js
new file mode 100644
index 0000000000..526da89c3e
--- /dev/null
+++ b/packages/create-apostrophe/src/telemetry/index.js
@@ -0,0 +1,210 @@
+// Telemetry hook constructor. The body merges `cliVersion` + `anonymousId`
+// from config into the partial payload, runs `buildPayload` to validate, and
+// hands off to `transport`.
+//
+// Two invariants the test suite enforces:
+//   1. event() never throws and never delays the caller (fire-and-forget).
+//   2. consent === false makes the hook a true no-op — no payload is built,
+//      no transport is invoked, nothing reaches the wire.
+
+import { buildPayload } from './schema.js';
+import { createUmamiTransport } from './transport.js';
+import {
+  TELEMETRY_ENDPOINT,
+  TELEMETRY_WRITE_KEY,
+  TELEMETRY_HOSTNAME
+} from './wire-config.js';
+
+/** @typedef {import('../index.js').TelemetryConfig}        TelemetryConfig        */
+/** @typedef {import('../index.js').TelemetryHook}          TelemetryHook          */
+/** @typedef {import('../index.js').TelemetryEvent}         TelemetryEvent         */
+/** @typedef {import('../index.js').TelemetryEventPayload}  TelemetryEventPayload  */
+/** @typedef {import('../index.js').ManagedTelemetryHook}   ManagedTelemetryHook   */
+/** @typedef {import('./schema.js').TelemetryPayload}       TelemetryPayload       */
+/** @typedef {import('./schema.js').PayloadInput}           PayloadInput           */
+
+/**
+ * Async wire transport. Resolves on success, rejects on failure. The default
+ * is a no-op; the live transport is injected at construction.
+ * @typedef {(payload: TelemetryPayload) => Promise<void>} Transport
+ */
+
+/**
+ * Minimal logger used for verbose diagnostics. Defaults to `console` so the
+ * standalone bin works without wiring.
+ * @typedef {object} VerboseLogger
+ * @property {(msg: string) => void} info
+ * @property {(msg: string) => void} warn
+ */
+
+/**
+ * Construction-time config. Extends the public {@link TelemetryConfig} with
+ * injection seams (`transport`, `timeoutMs`, `logger`) plus `anonymousId`
+ * (the caller reads it from the store and threads it in).
+ * @typedef {TelemetryConfig & {
+ *   anonymousId?: string,
+ *   transport?:   Transport,
+ *   timeoutMs?:   number,
+ *   logger?:      VerboseLogger
+ * }} TelemetryConfigExt
+ */
+
+const DEFAULT_TIMEOUT_MS = 3000;
+
+/** @type {Transport} */
+const noopTransport = async () => {};
+
+/**
+ * Caller overrides win per field; missing fields fall through to
+ * `wire-config.js`. Empties out to no-op rather than building a broken
+ * client when the resolved endpoint or write key is missing.
+ *
+ * @param {{ endpoint?: string, writeKey?: string, hostname?: string }} overrides
+ * @returns {Transport}
+ */
+function buildDefaultTransport(overrides) {
+  const endpoint = overrides.endpoint ?? TELEMETRY_ENDPOINT;
+  const writeKey = overrides.writeKey ?? TELEMETRY_WRITE_KEY;
+  const hostname = overrides.hostname ?? TELEMETRY_HOSTNAME;
+  if (endpoint && writeKey) {
+    return createUmamiTransport({
+      endpoint,
+      writeKey,
+      hostname
+    });
+  }
+  return noopTransport;
+}
+
+/**
+ * Race `promise` against a timer that rejects after `ms`. Used to bound the
+ * transport so a slow / hanging network call cannot wedge the CLI.
+ *
+ * @template T
+ * @param {Promise<T>} promise
+ * @param {number}     ms
+ * @returns {Promise<T>}
+ */
+async function withTimeout(promise, ms) {
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(
+      () => reject(new Error(`telemetry: timeout after ${ms}ms`)),
+      ms
+    );
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([ promise, timeout ]);
+  } finally {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/**
+ * Construct the telemetry hook.
+ *
+ * @param {TelemetryConfigExt} config
+ * @returns {ManagedTelemetryHook}
+ */
+export function createTelemetry(config) {
+  const {
+    consent,
+    cliVersion,
+    anonymousId,
+    endpoint,
+    writeKey,
+    hostname,
+    verbose = false,
+    transport: injectedTransport,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    logger = console
+  } = config;
+
+  const transport = injectedTransport ?? buildDefaultTransport({
+    endpoint,
+    writeKey,
+    hostname
+  });
+
+  /**
+   * Pending fire-and-forget jobs; `flush()` waits on them.
+   * @type {Set<Promise<void>>}
+   */
+  const inflight = new Set();
+
+  /**
+   * Inner async emission. Never rejects: every failure path is caught and
+   * (under `verbose`) logged. Callers must not `await` it directly — the
+   * outer `event()` registers the job with `inflight` so `flush()` does.
+   *
+   * @param {TelemetryEvent}        name
+   * @param {TelemetryEventPayload} partial
+   */
+  const emit = async (name, partial) => {
+    /** @type {TelemetryPayload} */
+    let payload;
+    try {
+      payload = buildPayload(name, {
+        cliVersion,
+        anonymousId,
+        ...partial
+      });
+    } catch (err) {
+      if (verbose) {
+        logger.warn(`telemetry: invalid payload — ${describe(err)}`);
+      }
+      return;
+    }
+    if (verbose) {
+      logger.info(`telemetry: would send ${JSON.stringify(payload)}`);
+    }
+    try {
+      await withTimeout(transport(payload), timeoutMs);
+    } catch (err) {
+      if (verbose) {
+        logger.warn(`telemetry: transport failed — ${describe(err)}`);
+      }
+    }
+  };
+
+  return {
+    /**
+     * Fire-and-forget. Returns void synchronously. A `consent === false`
+     * hook short-circuits *before* any payload work — no build, no log.
+     *
+     * @param {TelemetryEvent}        name
+     * @param {TelemetryEventPayload} partial
+     */
+    event(name, partial) {
+      if (!consent) {
+        return;
+      }
+      const job = emit(name, partial);
+      inflight.add(job);
+      job.finally(() => inflight.delete(job));
+    },
+
+    /**
+     * Resolve once every pending `event()` job has either completed or hit
+     * its timeout. Safe to call when nothing is pending.
+     */
+    async flush() {
+      await Promise.allSettled([ ...inflight ]);
+    }
+  };
+}
+
+/**
+ * @param {unknown} err
+ * @returns {string}
+ */
+function describe(err) {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  return String(err);
+}
diff --git a/packages/create-apostrophe/src/telemetry/schema.js b/packages/create-apostrophe/src/telemetry/schema.js
new file mode 100644
index 0000000000..4e9ffc5fd8
--- /dev/null
+++ b/packages/create-apostrophe/src/telemetry/schema.js
@@ -0,0 +1,275 @@
+// Telemetry payload builder + validators. The privacy guarantee lives here:
+// payloads are constructed from a closed allowlist of fields with closed
+// enum values, so it is structurally impossible to attach an excluded field
+// (email, paths, project name, dbUri, env, …) — even by accident from an
+// upstream caller passing extra keys.
+
+import { KIT_IDS } from '../core/kits.js';
+
+/** @typedef {import('../index.js').KitId}           KitId           */
+/** @typedef {import('../index.js').DbChoice}        DbChoice        */
+/** @typedef {import('../index.js').PackageManager}  PackageManager  */
+/** @typedef {import('../index.js').FailStage}       FailStage       */
+/** @typedef {import('../index.js').TelemetryEvent}  TelemetryEvent  */
+
+/**
+ * Symbolic error codes. Each value corresponds to a single
+ * `throw new StageError(..., { code })` site (or the preflight
+ * `UnsupportedPackageManagerError`). Not a contract type — internal to
+ * the schema, mirrored from grep'ing `src/core/steps/*` + `errors.js`.
+ * @typedef {(
+ *   'unsupported_pm' |
+ *   'target_exists' |
+ *   'git_missing' | 'git_spawn_failed' | 'git_clone_failed' |
+ *   'missing_scaffold_file' | 'scaffold_io' |
+ *   'npm_missing' | 'npm_spawn_failed' | 'install_failed' | 'apostrophe_missing' |
+ *   'db_unreachable' | 'db_auth_failed' | 'db_connect_failed' | 'db_drop_failed' |
+ *   'seed_manifest_invalid' | 'seed_download_failed' | 'seed_checksum_failed' |
+ *   'seed_unpack_failed' | 'seed_clear_failed' | 'seed_restore_failed' |
+ *   'seed_uploads_failed' |
+ *   'node_missing' | 'node_spawn_failed' | 'admin_user_failed'
+ * )} ErrorCode
+ */
+
+/** @type {ReadonlyArray<TelemetryEvent>} */
+export const EVENT_NAMES = Object.freeze([ 'install_success', 'install_fail' ]);
+
+/** @type {ReadonlyArray<DbChoice>} */
+export const DB_CHOICES = Object.freeze([ 'sqlite', 'mongodb', 'postgres' ]);
+
+/** @type {ReadonlyArray<PackageManager>} */
+export const PACKAGE_MANAGERS = Object.freeze([
+  'npm', 'pnpm', 'yarn', 'unknown'
+]);
+
+/**
+ * FailStage enum, in array form so the validator can `.includes(null)`
+ * directly against either a string or `null` (preflight).
+ * @type {ReadonlyArray<FailStage>}
+ */
+export const FAIL_STAGES = Object.freeze([
+  'clone', 'dependency_install', 'db_connect', 'scaffold', 'sample_data',
+  'admin', 'unknown', null
+]);
+
+/**
+ * Strict allowlist of symbolic error codes the orchestrator may attach to a
+ * payload. Adding a new throw site means adding the code here. Unknown codes
+ * are dropped from the payload — never pass raw error strings.
+ * @type {ReadonlyArray<ErrorCode>}
+ */
+export const ERROR_CODES = Object.freeze([
+  'unsupported_pm',
+  'target_exists',
+  'git_missing', 'git_spawn_failed', 'git_clone_failed',
+  'missing_scaffold_file', 'scaffold_io',
+  'npm_missing', 'npm_spawn_failed', 'install_failed', 'apostrophe_missing',
+  'db_unreachable', 'db_auth_failed', 'db_connect_failed', 'db_drop_failed',
+  'seed_manifest_invalid', 'seed_download_failed', 'seed_checksum_failed',
+  'seed_unpack_failed', 'seed_clear_failed', 'seed_restore_failed',
+  'seed_uploads_failed',
+  'node_missing', 'node_spawn_failed', 'admin_user_failed'
+]);
+
+/** @type {ReadonlySet<string>} */
+const ERROR_CODE_SET = new Set(ERROR_CODES);
+
+/**
+ * Type-guard: narrows a permissive `string` (contract) to the strict
+ * {@link ErrorCode} allowlist. Used by {@link buildPayload} to drop unknown
+ * codes without leaking raw error strings into the wire payload.
+ * @param {string} code
+ * @returns {code is ErrorCode}
+ */
+function isErrorCode(code) {
+  return ERROR_CODE_SET.has(code);
+}
+
+/**
+ * Shared fields every payload carries, regardless of event. `anonymousId` is
+ * optional at the schema level: consent.js generates and threads it on opt-in,
+ * but the schema only enforces shape and stays decoupled from generation.
+ * @typedef {object} BasePayloadInput
+ * @property {string}          cliVersion
+ * @property {string}          [anonymousId]
+ * @property {KitId}           kitId
+ * @property {DbChoice}        dbChoice
+ * @property {PackageManager}  packageManager
+ * @property {number}          durationMs
+ */
+
+/**
+ * Additional input fields for `install_fail`. `errorCode` is typed `string`
+ * here — the schema validates it against {@link ERROR_CODES} at runtime and
+ * silently drops unknown values, so the contract stays permissive while the
+ * wire stays strict.
+ * @typedef {object} FailPayloadInputFields
+ * @property {FailStage} failStage
+ * @property {string}    [errorCode]
+ */
+
+/**
+ * Additional output fields for `install_fail` — `errorCode` is narrowed to
+ * the {@link ErrorCode} allowlist (unknown values are dropped at build time).
+ * @typedef {object} FailPayloadFields
+ * @property {FailStage} failStage
+ * @property {ErrorCode} [errorCode]
+ */
+
+/**
+ * Input the builder accepts. Anything outside this allowlist is ignored —
+ * the builder copies only from this set.
+ * @typedef {BasePayloadInput & Partial<FailPayloadInputFields>} PayloadInput
+ */
+
+/**
+ * Outgoing payload for `install_success` — base + `event`.
+ * @typedef {BasePayloadInput & { event: 'install_success' }} SuccessPayload
+ */
+
+/**
+ * Outgoing payload for `install_fail` — base + fail fields + `event`.
+ * @typedef {BasePayloadInput & FailPayloadFields & { event: 'install_fail' }} FailPayload
+ */
+
+/** @typedef {SuccessPayload | FailPayload} TelemetryPayload */
+
+class SchemaError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = 'SchemaError';
+  }
+}
+
+/**
+ * @template T
+ * @param {string} name
+ * @param {unknown} value
+ * @param {ReadonlyArray<T>} allowed
+ * @returns {asserts value is T}
+ */
+function requireOneOf(name, value, allowed) {
+  if (!allowed.includes(/** @type {T} */ (value))) {
+    throw new SchemaError(`Invalid ${name}: ${JSON.stringify(value)}`);
+  }
+}
+
+/**
+ * @param {string} name
+ * @param {unknown} value
+ * @returns {asserts value is string}
+ */
+function requireString(name, value) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new SchemaError(`Invalid ${name}: expected non-empty string`);
+  }
+}
+
+/**
+ * @param {string} name
+ * @param {unknown} value
+ * @returns {asserts value is number}
+ */
+function requireFiniteNumber(name, value) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new SchemaError(`Invalid ${name}: expected finite number`);
+  }
+}
+
+/**
+ * @overload
+ * @param {'install_success'} event
+ * @param {PayloadInput} input
+ * @returns {SuccessPayload}
+ */
+/**
+ * @overload
+ * @param {'install_fail'} event
+ * @param {PayloadInput} input
+ * @returns {FailPayload}
+ */
+/**
+ * @overload
+ * @param {TelemetryEvent} event
+ * @param {PayloadInput} input
+ * @returns {TelemetryPayload}
+ */
+/**
+ * Build a validated payload for one of the two events. Strictly allowlisted:
+ * only fields from {@link BasePayloadInput} (and, for fail, {@link FailPayloadFields})
+ * appear on the result.
+ *
+ * @param {TelemetryEvent} event
+ * @param {PayloadInput} input
+ * @returns {TelemetryPayload}
+ * @throws {SchemaError} for an invalid enum value, missing required field,
+ *   or wrong type.
+ */
+export function buildPayload(event, input) {
+  requireOneOf('event', event, EVENT_NAMES);
+  requireString('cliVersion', input.cliVersion);
+  requireOneOf('kitId', input.kitId, KIT_IDS);
+  requireOneOf('dbChoice', input.dbChoice, DB_CHOICES);
+  requireOneOf('packageManager', input.packageManager, PACKAGE_MANAGERS);
+  requireFiniteNumber('durationMs', input.durationMs);
+  if (input.anonymousId !== undefined) {
+    requireString('anonymousId', input.anonymousId);
+  }
+
+  /** @type {BasePayloadInput} */
+  const base = {
+    cliVersion: input.cliVersion,
+    kitId: input.kitId,
+    dbChoice: input.dbChoice,
+    packageManager: input.packageManager,
+    durationMs: input.durationMs,
+    ...(input.anonymousId !== undefined
+      ? { anonymousId: input.anonymousId }
+      : {})
+  };
+
+  if (event === 'install_success') {
+    return {
+      event,
+      ...base
+    };
+  }
+
+  requireOneOf('failStage', input.failStage, FAIL_STAGES);
+  /** @type {FailPayload} */
+  const fail = {
+    event,
+    ...base,
+    failStage: input.failStage
+  };
+  if (input.errorCode !== undefined && isErrorCode(input.errorCode)) {
+    fail.errorCode = input.errorCode;
+  }
+  return fail;
+}
+
+/**
+ * The closed set of keys that may appear on a payload, by event. Exported for
+ * the firewall test to make the guarantee explicit.
+ * @param {TelemetryEvent} event
+ * @returns {ReadonlyArray<keyof SuccessPayload | keyof FailPayload>}
+ */
+export function allowedFields(event) {
+  return event === 'install_fail'
+    ? FAIL_FIELDS
+    : SUCCESS_FIELDS;
+}
+
+/** @type {ReadonlyArray<keyof SuccessPayload>} */
+const SUCCESS_FIELDS = Object.freeze([
+  'event', 'cliVersion', 'anonymousId', 'kitId', 'dbChoice',
+  'packageManager', 'durationMs'
+]);
+
+/** @type {ReadonlyArray<keyof FailPayload>} */
+const FAIL_FIELDS = Object.freeze([
+  ...SUCCESS_FIELDS, 'failStage', 'errorCode'
+]);
+
+export { SchemaError };
diff --git a/packages/create-apostrophe/src/telemetry/transport.js b/packages/create-apostrophe/src/telemetry/transport.js
new file mode 100644
index 0000000000..e5e0cfc864
--- /dev/null
+++ b/packages/create-apostrophe/src/telemetry/transport.js
@@ -0,0 +1,43 @@
+// Live wire transport over `@umami/node`. The telemetry layer owns the
+// consent gate, payload validation, timeout, and silence; this module only
+// knows how to send one already-validated payload to a Umami instance.
+//
+// Keeping the `fetch`-touching code in its own file lets the existing test
+// suite continue to inject its own `transport` without `@umami/node` ever
+// running, and lets us mock global fetch in one focused test file.
+
+import { Umami } from '@umami/node';
+
+/** @typedef {import('./schema.js').TelemetryPayload} TelemetryPayload */
+/** @typedef {import('./index.js').Transport}         Transport         */
+
+/**
+ * Build a {@link Transport} backed by a Umami client.
+ *
+ * @param {object} opts
+ * @param {string} opts.endpoint  Umami host URL (e.g. `https://cloud.umami.is`).
+ * @param {string} opts.writeKey  Umami website id.
+ * @param {string} opts.hostname  Domain attached to every payload so Umami
+ *                                accepts it (matches the website's configured
+ *                                domain in the Cloud admin).
+ * @returns {Transport}
+ */
+export function createUmamiTransport({
+  endpoint, writeKey, hostname
+}) {
+  const client = new Umami({
+    hostUrl: endpoint,
+    websiteId: writeKey
+  });
+  return async (payload) => {
+    const { event: name, ...data } = payload;
+    const response = await client.track({
+      name,
+      hostname,
+      data
+    });
+    if (response && response.ok === false) {
+      throw new Error(`umami: HTTP ${response.status}`);
+    }
+  };
+}
diff --git a/packages/create-apostrophe/src/telemetry/wire-config.js b/packages/create-apostrophe/src/telemetry/wire-config.js
new file mode 100644
index 0000000000..21d03a0646
--- /dev/null
+++ b/packages/create-apostrophe/src/telemetry/wire-config.js
@@ -0,0 +1,10 @@
+// Umami Cloud wiring. Centralized so flipping endpoints/keys is a
+// one-file change reviewable on its own — and never spreads through callers.
+
+export const TELEMETRY_ENDPOINT = 'https://cloud.umami.is';
+
+export const TELEMETRY_WRITE_KEY = 'bdf673e4-10de-4cb5-a787-b76c6bda0f89';
+
+// Umami drops events whose `hostname` doesn't match the website's configured
+// domain. The CLI has no real domain, so we attach a fixed placeholder.
+export const TELEMETRY_HOSTNAME = 'cli.apostrophecms.com';
diff --git a/packages/create-apostrophe/src/ui/db-uri.js b/packages/create-apostrophe/src/ui/db-uri.js
new file mode 100644
index 0000000000..9d03bbaf94
--- /dev/null
+++ b/packages/create-apostrophe/src/ui/db-uri.js
@@ -0,0 +1,15 @@
+/**
+ * Suggested local development URI. The postgres form pre-fills the
+ * conventional `postgres` superuser so the structure is obvious; the
+ * user adds `:yourpassword` after `postgres` inline.
+ *
+ * @param {'mongodb' | 'postgres'} dbChoice
+ * @param {string}                 shortName
+ * @returns {string}
+ */
+export function defaultDbUri(dbChoice, shortName) {
+  if (dbChoice === 'mongodb') {
+    return `mongodb://localhost:27017/${shortName}`;
+  }
+  return `postgres://postgres@localhost:5432/${shortName}`;
+}
diff --git a/packages/create-apostrophe/src/ui/flow.js b/packages/create-apostrophe/src/ui/flow.js
new file mode 100644
index 0000000000..59db858d71
--- /dev/null
+++ b/packages/create-apostrophe/src/ui/flow.js
@@ -0,0 +1,774 @@
+// Guided interactive flow. Drives the headless installer with a
+// UI-aware logger and renders progress + success/failure screens.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import * as render from './render.js';
+import * as prompts from './prompts.js';
+import { defaultDbUri } from './db-uri.js';
+import * as db from '../core/db.js';
+import { link, kitGuide } from './links.js';
+import { assertSafeShortName } from '../core/validate.js';
+import { deriveKitId, getKit } from '../core/kits.js';
+import {
+  status as telemetryStatus,
+  optIn as telemetryOptIn,
+  optOut as telemetryOptOut,
+  preview as telemetryPreview
+} from '../telemetry/commands.js';
+
+// Effective step count for the run. Set once at the top of `runFlow`
+// based on whether the telemetry-consent step will actually be shown
+// (skipped when the kill switch is on, or a stored preference exists).
+// All `stepLabel(n, totalSteps, ...)` calls read this so a 5-step run
+// renders "N/5" instead of misleading "N/6".
+let totalSteps = 6;
+
+/** @typedef {'astro' | 'standalone'}             BuildType */
+/** @typedef {'essentials' | 'demo'}              StartingPoint */
+/** @typedef {import('../index.js').DbChoice}     DbChoice */
+/** @typedef {import('../index.js').AdminAccount} AdminAccount */
+/** @typedef {ReturnType<typeof import('../core/store.js').createStore>} Store */
+
+/**
+ * @typedef {object} FlowAnswers
+ * @property {string}         shortName
+ * @property {BuildType}      build
+ * @property {StartingPoint}  startingPoint
+ * @property {boolean}        sampleContent
+ * @property {string}         kitId
+ * @property {DbChoice}       dbChoice
+ * @property {string}         [dbUri]
+ * @property {'keep' | 'drop'} dbReset  Consent to drop a pre-existing
+ *                                      mongodb/postgres DB; `'keep'` unless
+ *                                      the user confirmed "start fresh".
+ * @property {boolean}        [replacesData]  True when a confirmed seed import
+ *   will overwrite a non-empty database. Absent/false for an empty or sqlite
+ *   target.
+ * @property {AdminAccount}   admin
+ * @property {boolean}        telemetryConsent
+ * @property {number}         confirmedAt  Epoch ms when the user confirmed
+ *                                         the plan; the install duration
+ *                                         is measured from this point.
+ */
+
+/**
+ * @typedef {object} RunFlowDeps
+ * @property {Store}             store
+ * @property {string}            cliVersion
+ * @property {NodeJS.ProcessEnv} [env]
+ */
+
+/**
+ * Run the guided flow. Throws `UserCancelled` if the user aborts at any
+ * prompt; the bin catches it, renders a cancel message, and exits 130.
+ *
+ * @param {RunFlowDeps} deps
+ * @returns {Promise<FlowAnswers>}
+ */
+export async function runFlow(deps) {
+  render.intro('Welcome to ApostropheCMS! Let\'s set up your project.');
+  render.muted('Press Ctrl-C at any time to cancel.');
+  /** @type {Omit<FlowAnswers, 'confirmedAt'> | undefined} */
+  let defaults;
+  while (true) {
+    const answers = await collectAnswers(deps, defaults);
+    const confirmedAt = await reviewAndConfirm(answers, deps);
+    if (confirmedAt !== null) {
+      return {
+        ...answers,
+        confirmedAt
+      };
+    }
+    defaults = answers;
+  }
+}
+
+/**
+ * @param {RunFlowDeps} deps
+ * @param {Omit<FlowAnswers, 'confirmedAt'>} [defaults]
+ * @returns {Promise<Omit<FlowAnswers, 'confirmedAt'>>}
+ */
+async function collectAnswers(deps, defaults) {
+  totalSteps = willPromptForConsent(deps) ? 6 : 5;
+  const shortName = await askProjectName(defaults?.shortName);
+  const build = await askBuildType(defaults?.build);
+  const startingPoint = await askStartingPoint(defaults?.startingPoint);
+  const sampleContent = startingPoint === 'demo'
+    ? await askSampleContent(defaults?.sampleContent)
+    : false;
+  const kitId = deriveKitId({
+    build,
+    startingPoint,
+    sampleContent
+  });
+  const {
+    dbChoice, dbUri, dbReset, replacesData
+  } = await askDatabase(
+    shortName, defaults, getKit(kitId).seedData
+  );
+  const admin = await askAdminAccount(defaults?.admin);
+  const telemetryConsent = await resolveTelemetryConsent(deps);
+  return {
+    shortName,
+    build,
+    startingPoint,
+    sampleContent,
+    kitId,
+    dbChoice,
+    dbUri,
+    dbReset,
+    replacesData,
+    admin,
+    telemetryConsent
+  };
+}
+
+/** @param {string} [defaultShortName] */
+async function askProjectName(defaultShortName = 'my-project') {
+  return prompts.text({
+    message: render.stepLabel(1, totalSteps, 'Project name'),
+    placeholder: 'my-project',
+    defaultValue: defaultShortName,
+    // clack runs validate against the *typed* value, then substitutes
+    // defaultValue afterwards — so an empty submission would skip every
+    // check below. Substitute the default here so validation always sees
+    // the effective name.
+    validate: (value) => validateProjectName(value || defaultShortName)
+  });
+}
+
+/**
+ * @param {BuildType} [initial]
+ * @returns {Promise<BuildType>}
+ */
+async function askBuildType(initial = 'astro') {
+  return prompts.select({
+    message: render.stepLabel(2, totalSteps, 'How would you like to build?'),
+    initialValue: initial,
+    options: [
+      {
+        value: 'astro',
+        label: 'Apostrophe + Astro',
+        hint: 'recommended — Astro frontend, Apostrophe content'
+      },
+      {
+        value: 'standalone',
+        label: 'Apostrophe Standalone',
+        hint: 'full-stack, no separate frontend'
+      }
+    ]
+  });
+}
+
+/**
+ * @param {StartingPoint} [initial]
+ * @returns {Promise<StartingPoint>}
+ */
+async function askStartingPoint(initial = 'demo') {
+  const message =
+    `${render.stepLabel(3, totalSteps, 'Choose a starting point:')}\n` +
+    render.dim(`Preview the Demo site: ${link('demoSite')}`);
+  return prompts.select({
+    message,
+    initialValue: initial,
+    options: [
+      {
+        value: 'essentials',
+        label: 'Essentials',
+        hint: 'clean slate, no sample content'
+      },
+      {
+        value: 'demo',
+        label: 'Demo',
+        hint: 'working blog, widgets, components'
+      }
+    ]
+  });
+}
+
+/** @param {boolean} [initial] */
+async function askSampleContent(initial = false) {
+  return prompts.confirm({
+    message: render.stepLabel('3b', totalSteps, 'Pre-fill with sample content?'),
+    initialValue: initial
+  });
+}
+
+/**
+ * Database selection with the optional connection-string sub-step. Loops
+ * until the user has a reachable URI or switches to a DB that needs none.
+ * When `defaults` is provided (restart pass) the previous dbChoice and,
+ * if the user re-picks the same DB, the previous URI are reused.
+ *
+ * @param {string} shortName
+ * @param {{ dbChoice?: DbChoice, dbUri?: string }} [defaults]
+ * @param {boolean} seedData  True for `*-demo-data` kits; drives the
+ *   "import will replace existing data" confirm vs the plain nuke prompt.
+ * @returns {Promise<{
+ *   dbChoice: DbChoice, dbUri?: string, dbReset: 'keep' | 'drop',
+ *   replacesData: boolean
+ * }>}
+ */
+async function askDatabase(shortName, defaults, seedData) {
+  let initialChoice = defaults?.dbChoice;
+  while (true) {
+    const dbChoice = await askDbChoice(initialChoice);
+    if (dbChoice === 'sqlite') {
+      // SQLite lives inside the fresh project dir — no pre-existing DB to
+      // confront here.
+      return {
+        dbChoice,
+        dbReset: 'keep',
+        replacesData: false
+      };
+    }
+    const initialUri = defaults?.dbChoice === dbChoice
+      ? defaults?.dbUri
+      : undefined;
+    const result = await collectAndVerifyDbUri(
+      dbChoice, shortName, initialUri, seedData
+    );
+    if (result.kind === 'ok') {
+      return {
+        dbChoice,
+        dbUri: result.dbUri,
+        dbReset: result.dbReset,
+        replacesData: result.replacesData
+      };
+    }
+    // 'switch' falls through to re-ask the DB choice; preselect whatever
+    // they were on so re-picking the same DB stays one keystroke away.
+    initialChoice = dbChoice;
+  }
+}
+
+/**
+ * @param {DbChoice} [initial]
+ * @returns {Promise<DbChoice>}
+ */
+async function askDbChoice(initial = 'sqlite') {
+  const message =
+    `${render.stepLabel(4, totalSteps, 'Choose a database:')}\n` +
+    render.dim(`Help choosing a database: ${link('dbGuide')}`);
+  const choice = await prompts.select({
+    message,
+    initialValue: initial,
+    options: [
+      {
+        value: 'sqlite',
+        label: 'SQLite',
+        hint: 'local file, no setup — recommended'
+      },
+      {
+        value: 'mongodb',
+        label: 'MongoDB',
+        hint: 'flexible documents, no fixed schema, scales well'
+      },
+      {
+        value: 'postgres',
+        label: 'PostgreSQL',
+        hint: 'structured tables, strong for complex queries'
+      }
+    ]
+  });
+  return /** @type {DbChoice} */ (choice);
+}
+
+/**
+ * Per-DB hint shown under the connection-string prompt label. Returns
+ * `undefined` when nothing extra needs to be said for the given choice.
+ *
+ * @param {'mongodb' | 'postgres'} dbChoice
+ * @returns {string | undefined}
+ */
+function dbUriHint(dbChoice) {
+  if (dbChoice === 'postgres') {
+    return 'Postgres usually needs a password — add `:yourpassword` after `postgres` in the URI.';
+  }
+  return undefined;
+}
+
+/**
+ * Human-readable line for a failed connection check, keyed off the core db
+ * module's classified reason. The raw driver message is only shown for the
+ * `unknown` fallback.
+ *
+ * @param {{ reason?: string, message?: string }} result
+ * @returns {string}
+ */
+function describeConnectionFailure(result) {
+  if (result.reason === 'auth') {
+    return 'Authentication failed — check the username and password in the URI';
+  }
+  if (result.reason === 'unreachable') {
+    return 'Could not reach the database server — is it running, and the host/port correct?';
+  }
+  return `Could not connect — ${result.message}`;
+}
+
+/**
+ * Inner loop: ask for a connection string, verify it with a real
+ * connection, and on failure offer retry-or-switch. Returns
+ * `{ kind: 'ok', dbUri }` when reachable, or `{ kind: 'switch' }` to bounce
+ * back to the DB select.
+ *
+ * @param {'mongodb' | 'postgres'} dbChoice
+ * @param {string}                 shortName
+ * @param {string}                 [initialUri]  Preserves the user's
+ *   previously-entered URI across a flow restart so they don't have to
+ *   retype it.
+ * @param {boolean}                seedData
+ * @returns {Promise<
+ *   { kind: 'ok', dbUri: string, dbReset: 'keep' | 'drop', replacesData: boolean }
+ *   | { kind: 'switch' }
+ * >}
+ */
+async function collectAndVerifyDbUri(dbChoice, shortName, initialUri, seedData) {
+  let candidate = initialUri ?? defaultDbUri(dbChoice, shortName);
+  const hint = dbUriHint(dbChoice);
+  const message = hint
+    ? `${render.stepLabel('4b', totalSteps, 'Connection string:')}\n${render.dim(hint)}`
+    : render.stepLabel('4b', totalSteps, 'Connection string:');
+  while (true) {
+    candidate = await prompts.text({
+      message,
+      defaultValue: candidate,
+      initialValue: candidate
+    });
+    const spin = render.startSpinner('Verifying connection');
+    const result = await db.inspect(candidate);
+    if (!result.reachable) {
+      spin.fail(describeConnectionFailure(result));
+      const next = await prompts.select({
+        message: 'How would you like to proceed?',
+        options: [
+          {
+            value: 'retry',
+            label: 'Re-enter the connection string'
+          },
+          {
+            value: 'switch',
+            label: 'Choose a different database'
+          }
+        ]
+      });
+      if (next === 'switch') {
+        return { kind: 'switch' };
+      }
+      continue;
+    }
+    spin.succeed('Connection verified');
+
+    // Empty target: nothing to overwrite, proceed straight away.
+    if (result.empty) {
+      return {
+        kind: 'ok',
+        dbUri: candidate,
+        dbReset: 'keep',
+        replacesData: false
+      };
+    }
+    // Non-empty: confront the destructive case before the user commits.
+    const decision = await confirmExistingData(result.collectionCount, seedData);
+    if (decision === 'switch') {
+      return { kind: 'switch' };
+    }
+    return {
+      kind: 'ok',
+      dbUri: candidate,
+      dbReset: decision,
+      // A seed import that proceeds over a non-empty target overwrites it.
+      replacesData: seedData && decision === 'keep'
+    };
+  }
+}
+
+/**
+ * The DB the user pointed at already holds data. Confirm what to do — and
+ * surface the destruction plainly so a real database is never wiped by
+ * reflex. The default is always the non-destructive option. A seed kit's
+ * "overwrite" maps to `'keep'`: the import does its own reset, so there is
+ * nothing to drop here.
+ *
+ * @param {number}  count     Existing collection count, shown in the copy.
+ * @param {boolean} seedData
+ * @returns {Promise<'keep' | 'drop' | 'switch'>} ('cancel' throws UserCancelled)
+ */
+async function confirmExistingData(count, seedData) {
+  if (seedData) {
+    const choice = await prompts.select({
+      message:
+        `${render.bold('This database already contains data')} (${count} collections).\n` +
+        render.dim('Importing the sample content will REPLACE everything in it.'),
+      initialValue: 'switch',
+      options: [
+        {
+          value: 'switch',
+          label: 'Choose a different (empty) database'
+        },
+        {
+          value: 'overwrite',
+          label: `Overwrite and import — permanently deletes all ${count} collections`
+        },
+        {
+          value: 'cancel',
+          label: 'Cancel'
+        }
+      ]
+    });
+    if (choice === 'cancel') {
+      throw new prompts.UserCancelled();
+    }
+    return choice === 'overwrite' ? 'keep' : 'switch';
+  }
+  return prompts.select({
+    message:
+      `${render.bold('This database already contains data')} (${count} collections).`,
+    initialValue: 'keep',
+    options: [
+      {
+        value: 'keep',
+        label: 'Use it as-is'
+      },
+      {
+        value: 'drop',
+        label: `Drop it and start fresh — permanently deletes all ${count} collections`
+      },
+      {
+        value: 'switch',
+        label: 'Choose a different database'
+      }
+    ]
+  });
+}
+
+/**
+ * Carries the previous username as the new default on a restart pass.
+ * The password is intentionally NOT carried — re-typed every time, never
+ * echoed back to the terminal as a default.
+ *
+ * @param {AdminAccount} [defaults]
+ * @returns {Promise<AdminAccount>}
+ */
+async function askAdminAccount(defaults) {
+  const username = await prompts.text({
+    message: render.stepLabel(5, totalSteps, 'Create your admin account — username or email:'),
+    defaultValue: defaults?.username ?? 'admin',
+    placeholder: 'admin',
+    validate: validateAdminUsername
+  });
+  const password = await prompts.password({
+    message: 'Password:',
+    validate: validateAdminPassword
+  });
+  return {
+    username,
+    password
+  };
+}
+
+/**
+ * Empty / unset is accepted so clack's `defaultValue` resolves on bare
+ * Enter — clack passes `undefined` on empty submissions, not `''`.
+ * Whitespace-only is rejected — the admin task takes the value verbatim.
+ *
+ * @param {string | undefined} value
+ * @returns {string | undefined}
+ */
+function validateAdminUsername(value) {
+  if (!value) {
+    return undefined;
+  }
+  if (value.trim().length === 0) {
+    return 'Username or email cannot be blank.';
+  }
+  return undefined;
+}
+
+/**
+ * Apostrophe core only requires a non-empty password — no length floor.
+ *
+ * @param {string | undefined} value
+ * @returns {string | undefined}
+ */
+function validateAdminPassword(value) {
+  if (!value) {
+    return 'Password is required.';
+  }
+  return undefined;
+}
+
+/**
+ * Resolves the effective consent for this install. The prompt is
+ * suppressed when a preference is already stored, or when
+ * `APOS_TELEMETRY=0` is set (kill switch wins — consent is `false`
+ * regardless of what's stored). Only a first-time user with no kill
+ * switch reaches the interactive prompt.
+ *
+ * @param {RunFlowDeps} deps
+ * @returns {Promise<boolean>}
+ */
+async function resolveTelemetryConsent(deps) {
+  const current = telemetryStatus(deps.store, deps.env);
+  if (current.killSwitchOn) {
+    return false;
+  }
+  if (current.storedConsent !== undefined) {
+    return current.storedConsent;
+  }
+  return askTelemetryConsent(deps);
+}
+
+/**
+ * Non-destructive peek that mirrors {@link resolveTelemetryConsent}'s
+ * skip conditions. Called before any prompt fires so the step counter
+ * can render the actual run length ("N/5" vs "N/6").
+ *
+ * @param {RunFlowDeps} deps
+ * @returns {boolean}
+ */
+function willPromptForConsent(deps) {
+  const current = telemetryStatus(deps.store, deps.env);
+  return !current.killSwitchOn && current.storedConsent === undefined;
+}
+
+/**
+ * "See what would be sent" is the first option AND the default — bare
+ * Enter shows the preview rather than silently committing. After viewing
+ * the payload, the prompt re-opens with `off` preselected so a second
+ * Enter is a deliberate commit (this path runs only for users with no
+ * stored preference yet).
+ *
+ * @param {RunFlowDeps} deps
+ * @returns {Promise<boolean>}
+ */
+async function askTelemetryConsent({
+  store, cliVersion, env
+}) {
+  while (true) {
+    const choice = await prompts.select({
+      message: telemetryPromptMessage(),
+      initialValue: 'details',
+      options: [
+        {
+          value: 'details',
+          label: 'See exactly what would be sent',
+          hint: 'prints the redacted payload — nothing is sent'
+        },
+        {
+          value: 'on',
+          label: 'Yes, share anonymous data',
+          hint: 'no personal info, no content'
+        },
+        {
+          value: 'off',
+          label: 'No thanks'
+        }
+      ]
+    });
+    if (choice === 'details') {
+      renderTelemetryPreview({
+        store,
+        cliVersion,
+        env
+      });
+      continue;
+    }
+    if (choice === 'on') {
+      telemetryOptIn(store, env);
+      return true;
+    }
+    telemetryOptOut(store);
+    return false;
+  }
+}
+
+/** Header line + dimmed two-line body (lead + policy link) for the consent
+ *  select. Returned as a single string; clack renders newlines below the
+ *  header in the same prompt rail. */
+function telemetryPromptMessage() {
+  return [
+    render.stepLabel(6, totalSteps, 'Help us improve Apostrophe?'),
+    render.dim('Anonymous usage data — no content, no personal info.'),
+    render.dim(`Policy: ${link('telemetryPolicy')}`)
+  ].join('\n');
+}
+
+/**
+ * @param {RunFlowDeps} deps
+ */
+function renderTelemetryPreview({
+  store, cliVersion, env
+}) {
+  const p = telemetryPreview({
+    store,
+    cliVersion,
+    env
+  });
+  const body =
+    JSON.stringify(p.payload, null, 2) +
+    '\n\n' +
+    (p.idSentinel
+      ? 'anonymousId is a placeholder — a real UUID is generated on first opt-in.\n'
+      : '') +
+    'Nothing has been sent. This is just a preview of the data that would be shared if you opt in.';
+  render.note('Telemetry preview', body);
+}
+
+/**
+ * Render the plan summary and ask the user to confirm. Returns the
+ * confirmation timestamp on `Yes` — the install duration is measured
+ * from this value — or `null` on `No`, which signals the orchestrator
+ * to restart the prompts with the prior selections as defaults.
+ *
+ * @param {Omit<FlowAnswers, 'confirmedAt'>} answers
+ * @param {RunFlowDeps} deps
+ * @returns {Promise<number | null>}
+ */
+async function reviewAndConfirm(answers, deps) {
+  render.summary('Review your choices', [
+    [ 'Project', answers.shortName ],
+    [ 'Type', buildLabel(answers.build) ],
+    [ 'Starter', starterLabel(answers.startingPoint, answers.sampleContent) ],
+    [ 'Database', dbLabel(answers.dbChoice) ],
+    [ 'Username', answers.admin.username ],
+    [ 'Telemetry', telemetryLabel(answers.telemetryConsent, deps) ]
+  ]);
+  if (answers.dbReset === 'drop') {
+    render.warn('The existing contents of this database will be dropped before install.');
+  } else if (answers.replacesData) {
+    render.warn('Importing sample content will replace the existing data in this database.');
+  }
+  const ready = await prompts.confirm({
+    message: 'Ready to create?',
+    initialValue: true
+  });
+  return ready ? Date.now() : null;
+}
+
+/** @param {BuildType} build */
+function buildLabel(build) {
+  return build === 'astro' ? 'Apostrophe + Astro' : 'Apostrophe Standalone';
+}
+
+/**
+ * @param {StartingPoint} startingPoint
+ * @param {boolean}       sampleContent
+ */
+function starterLabel(startingPoint, sampleContent) {
+  if (startingPoint === 'essentials') {
+    return 'Essentials';
+  }
+  return sampleContent ? 'Demo (with sample content)' : 'Demo';
+}
+
+/** @param {DbChoice} dbChoice */
+function dbLabel(dbChoice) {
+  if (dbChoice === 'sqlite') {
+    return 'SQLite';
+  }
+  if (dbChoice === 'mongodb') {
+    return 'MongoDB';
+  }
+  return 'PostgreSQL';
+}
+
+/**
+ * Distinguishes explicit opt-out from the env kill switch so a user
+ * who set `APOS_TELEMETRY=0` sees why the line reads "Off".
+ *
+ * @param {boolean}     consent
+ * @param {RunFlowDeps} deps
+ */
+function telemetryLabel(consent, deps) {
+  if (consent) {
+    return 'On';
+  }
+  const status = telemetryStatus(deps.store, deps.env);
+  return status.killSwitchOn ? 'Off (APOS_TELEMETRY=0)' : 'Off';
+}
+
+/** @typedef {import('../index.js').CreateProjectResult} CreateProjectResult */
+
+/**
+ * Render the install outcome. Branches on `result.ok` and dispatches to
+ * the Astro / Standalone success screen or the generic failure block.
+ * Bin calls this after `createProject` resolves; flow.js is UI only.
+ *
+ * @param {CreateProjectResult} result
+ * @param {FlowAnswers}         answers
+ */
+export function renderInstallResult(result, answers) {
+  if (result.ok) {
+    renderSuccess(answers);
+  } else {
+    renderFailure(answers, result);
+  }
+}
+
+/** Dev-server ports per kit frontend — Astro uses 4321, standalone 3000. */
+const DEV_PORT = Object.freeze({
+  astro: 4321,
+  standalone: 3000
+});
+
+/** @param {FlowAnswers} answers */
+function renderSuccess(answers) {
+  const port = DEV_PORT[answers.build];
+  const body = [
+    'Your project is ready.',
+    '',
+    `  cd ${answers.shortName}`,
+    '  npm run dev',
+    '',
+    `  Open:           http://localhost:${port}`,
+    `  Login:          http://localhost:${port}/login`,
+    `  Get Oriented:   ${kitGuide(answers.kitId)}`,
+    '',
+    `  Docs:     ${link('docs')}`,
+    `  Discord:  ${link('discord', { stamp: false })}`
+  ].join('\n');
+  render.note('All set', body);
+  render.outro('Happy building!');
+}
+
+/**
+ * @param {FlowAnswers}         answers
+ * @param {CreateProjectResult} result
+ */
+function renderFailure(answers, result) {
+  const stage = result.failStage ?? 'unknown';
+  const code = result.errorCode ?? '(none)';
+  const lines = [
+    `Stage:  ${stage}`,
+    `Code:   ${code}`,
+    `Kit:    ${answers.kitId}`,
+    '',
+    'See the messages above for the underlying error.',
+    `Docs:    ${link('docs')}`,
+    `Discord: ${link('discord', { stamp: false })}`
+  ];
+  render.errorBlock('Install failed', lines.join('\n'));
+  render.outro('Install did not complete.');
+}
+
+/**
+ * Empty / unset input is accepted so clack's `defaultValue` resolves on
+ * bare Enter — clack passes `undefined` on empty submissions, not `''`.
+ *
+ * @param {string | undefined} value
+ * @returns {string | undefined}
+ */
+function validateProjectName(value) {
+  try {
+    assertSafeShortName(value);
+  } catch {
+    return 'Use letters, numbers, hyphens, or underscores only.';
+  }
+  if (existsSync(join(process.cwd(), value))) {
+    return `A file or folder named "${value}" already exists here — choose another name.`;
+  }
+  return undefined;
+}
diff --git a/packages/create-apostrophe/src/ui/links.js b/packages/create-apostrophe/src/ui/links.js
new file mode 100644
index 0000000000..bcbd2ff7aa
--- /dev/null
+++ b/packages/create-apostrophe/src/ui/links.js
@@ -0,0 +1,62 @@
+// Centralized URL registry for every link the flow renders to the user.
+// Real URLs land later; these stubs let copy-and-link work end-to-end
+// today and stay editable in exactly one place. `link()` and
+// `kitGuide()` stamp `utm_source` so we can attribute the install funnel
+// without each call site remembering to do it.
+
+const LINKS = Object.freeze({
+  telemetryPolicy: '[link to telemetry policy]',
+  docs: 'https://docs.apostrophecms.com',
+  discord: 'https://discord.gg/apostrophe',
+  demoSite: 'https://demo.apostrophecms.com',
+  dbGuide: 'https://apostrophecms.com/guides/choosing-a-db'
+});
+
+/** Per-kit "get oriented" guides. `*-demo` and `*-demo-data` share a guide. */
+const KIT_GUIDES = Object.freeze({
+  'apostrophe-astro-essentials': 'https://apostrophecms.com/guides/astro-essentials-overview',
+  'apostrophe-astro-demo': 'https://apostrophecms.com/guides/astro-demo-overview',
+  'apostrophe-astro-demo-data': 'https://apostrophecms.com/guides/astro-demo-overview',
+  'apostrophe-essentials': 'https://apostrophecms.com/guides/apostrophe-standalone-essentials-overview',
+  'apostrophe-demo': 'https://apostrophecms.com/guides/apostrophe-demo-overview',
+  'apostrophe-demo-data': 'https://apostrophecms.com/guides/apostrophe-demo-overview'
+});
+
+/** @typedef {keyof typeof LINKS} LinkName */
+
+/**
+ * @param {string} url
+ * @param {string} utmSource
+ * @returns {string}
+ */
+function stampUtm(url, utmSource) {
+  const sep = url.includes('?') ? '&' : '?';
+  return `${url}${sep}utm_source=${utmSource}`;
+}
+
+/**
+ * @param {LinkName} name
+ * @param {{ utmSource?: string, stamp?: boolean }} [opts]
+ *   `stamp: false` returns the bare URL (e.g. for Discord invite links).
+ * @returns {string}
+ */
+export function link(name, { utmSource = 'cli', stamp = true } = {}) {
+  const base = LINKS[name];
+  if (!base) {
+    throw new TypeError(`Unknown link: ${JSON.stringify(name)}`);
+  }
+  return stamp ? stampUtm(base, utmSource) : base;
+}
+
+/**
+ * @param {string} kitId
+ * @param {{ utmSource?: string }} [opts]
+ * @returns {string}
+ */
+export function kitGuide(kitId, { utmSource = 'cli' } = {}) {
+  const base = KIT_GUIDES[kitId];
+  if (!base) {
+    throw new TypeError(`No guide registered for kitId: ${JSON.stringify(kitId)}`);
+  }
+  return stampUtm(base, utmSource);
+}
diff --git a/packages/create-apostrophe/src/ui/prompts.js b/packages/create-apostrophe/src/ui/prompts.js
new file mode 100644
index 0000000000..7a32fac41f
--- /dev/null
+++ b/packages/create-apostrophe/src/ui/prompts.js
@@ -0,0 +1,113 @@
+// Typed thin wrappers over @clack/prompts. The goal is twofold:
+//   1. Stable, narrowly-typed signatures the flow can call without
+//      importing clack directly (so swapping the prompt lib stays a
+//      local change).
+//   2. Uniform cancel handling: clack returns a sentinel symbol on
+//      Ctrl-C / escape; every wrapper here turns that into a
+//      `UserCancelled` throw so the flow can unwind via try/catch and
+//      the bin can render `render.cancel(...)` + exit 130 in one place.
+
+import * as clack from '@clack/prompts';
+
+/**
+ * Thrown by every prompt wrapper when the user cancels (Ctrl-C / escape).
+ * The bin/flow catches it, renders a cancel message, and exits cleanly.
+ */
+export class UserCancelled extends Error {
+  constructor() {
+    super('User cancelled.');
+    this.name = 'UserCancelled';
+  }
+}
+
+/**
+ * @template T
+ * @param {T | symbol} value
+ * @returns {T}
+ */
+function unwrap(value) {
+  if (clack.isCancel(value)) {
+    throw new UserCancelled();
+  }
+  return /** @type {T} */ (value);
+}
+
+/**
+ * Free-form text input with optional default and synchronous validator.
+ * `validate` returns a string error message to keep the user on the
+ * prompt, or `undefined` to accept the value.
+ *
+ * @param {{
+ *   message: string,
+ *   placeholder?: string,
+ *   defaultValue?: string,
+ *   initialValue?: string,
+ *   validate?: (value: string) => string | undefined
+ * }} opts
+ * @returns {Promise<string>}
+ */
+export async function text(opts) {
+  const value = await clack.text({
+    message: opts.message,
+    placeholder: opts.placeholder,
+    defaultValue: opts.defaultValue,
+    initialValue: opts.initialValue,
+    validate: opts.validate
+  });
+  return unwrap(value);
+}
+
+/**
+ * Single-choice select. Returns the `value` of the chosen option, typed
+ * to whatever the caller declares for the option set.
+ *
+ * @template T
+ * @param {{
+ *   message: string,
+ *   options: ReadonlyArray<{ value: T, label: string, hint?: string }>,
+ *   initialValue?: T
+ * }} opts
+ * @returns {Promise<T>}
+ */
+export async function select(opts) {
+  const value = await clack.select({
+    message: opts.message,
+    options: /** @type {any} */ (opts.options),
+    initialValue: opts.initialValue
+  });
+  return unwrap(value);
+}
+
+/**
+ * Yes/no. Pass `initialValue: undefined` to leave the cursor unbiased
+ * (clack defaults it to `true` otherwise).
+ *
+ * @param {{ message: string, initialValue?: boolean }} opts
+ * @returns {Promise<boolean>}
+ */
+export async function confirm(opts) {
+  const value = await clack.confirm({
+    message: opts.message,
+    initialValue: opts.initialValue
+  });
+  return unwrap(value);
+}
+
+/**
+ * Masked password input. `validate` runs without echoing the value.
+ *
+ * @param {{
+ *   message: string,
+ *   mask?: string,
+ *   validate?: (value: string) => string | undefined
+ * }} opts
+ * @returns {Promise<string>}
+ */
+export async function password(opts) {
+  const value = await clack.password({
+    message: opts.message,
+    mask: opts.mask,
+    validate: opts.validate
+  });
+  return unwrap(value);
+}
diff --git a/packages/create-apostrophe/src/ui/render.js b/packages/create-apostrophe/src/ui/render.js
new file mode 100644
index 0000000000..55a15d2537
--- /dev/null
+++ b/packages/create-apostrophe/src/ui/render.js
@@ -0,0 +1,212 @@
+// Presentation primitives for the guided flow. picocolors for styling,
+// @clack/prompts for the streamed I/O. No business logic, no prompts —
+// just composable helpers the flow/bin draw with. Reusable by any caller
+// that mounts this package's UI (e.g. @apostrophecms/cli `create`).
+
+import pc from 'picocolors';
+import * as clack from '@clack/prompts';
+
+/**
+ * Banner line that opens the flow. clack draws it with a divider that
+ * connects visually to the subsequent prompts.
+ *
+ * @param {string} title
+ */
+export function intro(title) {
+  clack.intro(pc.bgCyan(pc.black(` ${title} `)));
+}
+
+/**
+ * Closing line. The caller passes the final user-facing message; success
+ * vs. failure framing happens in the flow.
+ *
+ * @param {string} message
+ */
+export function outro(message) {
+  clack.outro(message);
+}
+
+/**
+ * "N/total  Label" — used as a prompt's title so the step counter sits
+ * right above the question. Returns a string; the caller passes it to a
+ * clack prompt.
+ *
+ * @param {number | string} n
+ * @param {number | string} total
+ * @param {string} label
+ * @returns {string}
+ */
+export function stepLabel(n, total, label) {
+  return `${pc.cyan(`${n}/${total}`)}  ${pc.bold(label)}`;
+}
+
+/** @param {string} msg */
+export function info(msg) {
+  clack.log.info(msg);
+}
+/** @param {string} msg */
+export function warn(msg) {
+  clack.log.warn(msg);
+}
+/** @param {string} msg */
+export function error(msg) {
+  clack.log.error(msg);
+}
+/** @param {string} msg */
+export function success(msg) {
+  clack.log.success(msg);
+}
+
+/** Dimmed, icon-less aside for low-priority hints. */
+/** @param {string} msg */
+export function muted(msg) {
+  clack.log.message(pc.dim(msg));
+}
+
+/**
+ * String-transform helpers (no I/O). Inline these inside template
+ * strings when a multi-line block needs spot styling — `bold` for
+ * section headers, `dim` for placeholders/asides.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function bold(text) {
+  return pc.bold(text);
+}
+/** @param {string} text */
+export function dim(text) {
+  return pc.dim(text);
+}
+
+/**
+ * Bordered block. Useful for the plan/review screen and for any aside
+ * that should stand apart from the prompt stream.
+ *
+ * @param {string} title
+ * @param {string} body
+ */
+export function note(title, body) {
+  clack.note(body, title);
+}
+
+/**
+ * Plan/review box rendered as a clack note. `rows` are `[label, value]`
+ * tuples; labels are right-padded to the longest one so values align.
+ *
+ * @param {string} title
+ * @param {ReadonlyArray<[string, string]>} rows
+ */
+export function summary(title, rows) {
+  if (rows.length === 0) {
+    note(title, '');
+    return;
+  }
+  const width = Math.max(...rows.map(([ label ]) => label.length));
+  const body = rows
+    .map(([ label, value ]) => `${pc.dim(label.padEnd(width))}  ${value}`)
+    .join('\n');
+  note(title, body);
+}
+
+/**
+ * Multi-line error block — title in red+bold, details below.
+ *
+ * @param {string} title
+ * @param {string} details
+ */
+export function errorBlock(title, details) {
+  clack.log.error(`${pc.bold(pc.red(title))}\n${details}`);
+}
+
+/**
+ * Cancel framing for a user-initiated abort (Ctrl-C / escape).
+ *
+ * @param {string} [message]
+ */
+export function cancel(message = 'Cancelled.') {
+  clack.cancel(message);
+}
+
+/**
+ * One unit of work with a spinner. Mirrors the headless Logger.task()
+ * contract — start happens at construction, the handle settles it.
+ *
+ * @typedef {object} TaskHandle
+ * @property {(msg?: string) => void} succeed
+ * @property {(msg?: string) => void} fail
+ * @property {(fraction: number) => void} progress  Advance the task's bar
+ *   (0–1). No-op for spinner tasks; forward-only.
+ */
+
+/**
+ * Bridge from the headless {@link import('../index.js').Logger} contract
+ * to the clack/picocolors UI, keeping the orchestrator and steps UI-agnostic.
+ *
+ * @returns {import('../index.js').Logger}
+ */
+export function createUiLogger() {
+  return {
+    info,
+    warn,
+    error,
+    muted,
+    task(label, { progress: useProgress = false } = {}) {
+      // clack writes a connector line on every start(), so pick spinner vs.
+      // bar up front rather than swapping mid-task (which would stack lines).
+      const active = useProgress
+        ? clack.progress({
+          style: 'block',
+          max: 100,
+          size: 24
+        })
+        : clack.spinner();
+      active.start(label);
+      let lastPct = 0;
+      return {
+        succeed(msg) {
+          active.stop(msg ?? label);
+        },
+        fail(msg) {
+          // clack's stop() always renders success; error() is the red variant.
+          active.error(msg ?? label);
+        },
+        progress(fraction) {
+          if (!useProgress) {
+            return;
+          }
+          const pct = Math.max(0, Math.min(100, Math.round(fraction * 100)));
+          const delta = pct - lastPct;
+          if (delta > 0) {
+            active.advance(delta, `${label}  ${pct}%`);
+            lastPct = pct;
+          }
+        }
+      };
+    }
+  };
+}
+
+/**
+ * Lower-level spinner for cases that aren't a Logger.task — e.g. the UI's
+ * own pre-orchestrator checks (db reachability probe).
+ *
+ * @param {string} label
+ * @returns {TaskHandle & { update(msg: string): void }}
+ */
+export function startSpinner(label) {
+  const s = clack.spinner();
+  s.start(label);
+  return {
+    succeed(msg) {
+      s.stop(msg ?? label);
+    },
+    fail(msg) {
+      // clack's stop() always renders success; error() is the red variant.
+      s.error(msg ?? label);
+    },
+    update(msg) {
+      s.message(msg);
+    }
+  };
+}
diff --git a/packages/create-apostrophe/test/boundary.test.js b/packages/create-apostrophe/test/boundary.test.js
new file mode 100644
index 0000000000..66a10aa7dc
--- /dev/null
+++ b/packages/create-apostrophe/test/boundary.test.js
@@ -0,0 +1,34 @@
+import assert from 'node:assert/strict';
+import { fileURLToPath } from 'node:url';
+import { ESLint } from 'eslint';
+
+const cwd = fileURLToPath(new URL('..', import.meta.url));
+const eslint = new ESLint({ cwd });
+
+// A path the boundary override matches (src/core/**/*.js). The file need not
+// exist on disk — lintText uses filePath only to resolve the config.
+const probe = fileURLToPath(new URL('../src/core/__probe__.js', import.meta.url));
+
+const importFrom = spec => `import x from ${JSON.stringify(spec)};\nexport { x };\n`;
+
+async function ruleHits(code) {
+  const [ result ] = await eslint.lintText(code, { filePath: probe });
+  return result.messages.filter(m => m.ruleId === 'no-restricted-imports');
+}
+
+describe('UI/logic boundary (eslint no-restricted-imports)', function () {
+  it('flags an import from ui/ inside core/', async function () {
+    const hits = await ruleHits(importFrom('../ui/render.js'));
+    assert.equal(hits.length, 1, 'expected the boundary rule to fire');
+  });
+
+  it('flags a deeper ui/ import too', async function () {
+    const hits = await ruleHits(importFrom('../../src/ui/flow.js'));
+    assert.equal(hits.length, 1);
+  });
+
+  it('allows a non-ui import', async function () {
+    const hits = await ruleHits(importFrom('node:fs/promises'));
+    assert.equal(hits.length, 0, 'non-ui imports must not trip the boundary rule');
+  });
+});
diff --git a/packages/create-apostrophe/test/cli/main.test.js b/packages/create-apostrophe/test/cli/main.test.js
new file mode 100644
index 0000000000..2304b61825
--- /dev/null
+++ b/packages/create-apostrophe/test/cli/main.test.js
@@ -0,0 +1,703 @@
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, rmSync, readFileSync
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { main, runTelemetryCommand } from '../../src/cli/main.js';
+import { createStore as realCreateStore } from '../../src/core/store.js';
+import { UserCancelled } from '../../src/ui/prompts.js';
+
+const PKG_PATH = fileURLToPath(new URL('../../package.json', import.meta.url));
+const CLI_VERSION = JSON.parse(readFileSync(PKG_PATH, 'utf8')).version;
+
+// Swap process.stdout.write / process.stderr.write (and clack writes through
+// these) for the duration of `fn`. Strip ANSI codes so assertions can match
+// the visible text. `output` is the combined stream — clack renders error
+// blocks to stdout and we write raw USAGE to stderr, so per-stream matching
+// is brittle. The merged view is what the user actually sees.
+async function captureIO(fn) {
+  const stdoutWrite = process.stdout.write.bind(process.stdout);
+  const stderrWrite = process.stderr.write.bind(process.stderr);
+  let out = '';
+  let err = '';
+  process.stdout.write = (chunk) => {
+    out += String(chunk);
+    return true;
+  };
+  process.stderr.write = (chunk) => {
+    err += String(chunk);
+    return true;
+  };
+  try {
+    const code = await fn();
+    return {
+      code,
+      stdout: stripAnsi(out),
+      stderr: stripAnsi(err),
+      output: stripAnsi(out + err)
+    };
+  } finally {
+    process.stdout.write = stdoutWrite;
+    process.stderr.write = stderrWrite;
+  }
+}
+
+// eslint-disable-next-line no-control-regex
+const ANSI = /\[[0-9;]*m/g;
+function stripAnsi(s) {
+  return s.replace(ANSI, '');
+}
+
+const ARGV0 = [ 'node', 'create-apostrophe' ];
+
+/**
+ * Capture invocations of a stubbed createProject. Returns `result` to the
+ * caller; tests inspect `calls` afterwards.
+ */
+function stubCreateProject(result = {
+  ok: true,
+  kitId: 'k',
+  dbChoice: 'sqlite',
+  packageManager: 'npm',
+  durationMs: 1
+}) {
+  /** @type {Array<{ options: object, deps: object }>} */
+  const calls = [];
+  const fn = async (options, deps) => {
+    calls.push({
+      options,
+      deps
+    });
+    return result;
+  };
+  return {
+    fn,
+    calls
+  };
+}
+
+/** Store factory pointed at a fresh empty tmp dir. Returns the path so
+ *  the test can clean it up after. */
+function isolatedStoreFactory() {
+  const dir = mkdtempSync(join(tmpdir(), 'ca-main-store-'));
+  return {
+    createStore: () => realCreateStore({ dir }),
+    dir,
+    cleanup: () => rmSync(dir, {
+      recursive: true,
+      force: true
+    })
+  };
+}
+
+describe('cli/main — argv & early-return paths', function () {
+  it('--help returns 0 and prints usage', async function () {
+    const { code, stdout } = await captureIO(() => main([ ...ARGV0, '--help' ]));
+    assert.equal(code, 0);
+    assert.match(stdout, /Usage:/);
+    assert.match(stdout, /--unattended \[flags]/);
+    assert.match(stdout, /--project-name=NAME/);
+  });
+
+  it('-h alias also returns usage', async function () {
+    const { code, stdout } = await captureIO(() => main([ ...ARGV0, '-h' ]));
+    assert.equal(code, 0);
+    assert.match(stdout, /Usage:/);
+  });
+
+  it('--version returns 0 and prints the version', async function () {
+    const { code, stdout } = await captureIO(() => main([ ...ARGV0, '--version' ]));
+    assert.equal(code, 0);
+    assert.equal(stdout.trim(), CLI_VERSION);
+  });
+
+  it('-V alias also returns the version', async function () {
+    const { code, stdout } = await captureIO(() => main([ ...ARGV0, '-V' ]));
+    assert.equal(code, 0);
+    assert.equal(stdout.trim(), CLI_VERSION);
+  });
+
+  it('unknown flag (parseArgs error) → exit 2 with usage', async function () {
+    const { code, output } = await captureIO(() =>
+      main([ ...ARGV0, '--nope' ]));
+    assert.equal(code, 2);
+    assert.match(output, /Invalid arguments/);
+    assert.match(output, /Usage:/);
+  });
+
+  it('old flag --non-interactive is rejected (renamed in 5b)', async function () {
+    const { code, output } = await captureIO(() =>
+      main([ ...ARGV0, '--non-interactive' ]));
+    assert.equal(code, 2);
+    assert.match(output, /Unknown option '--non-interactive'/);
+  });
+
+  it('old flag --short-name is rejected (renamed in 5b)', async function () {
+    const { code, output } = await captureIO(() =>
+      main([ ...ARGV0, '--unattended', '--short-name=foo' ]));
+    assert.equal(code, 2);
+    assert.match(output, /Unknown option '--short-name'/);
+  });
+
+  it('unknown positional → exit 2', async function () {
+    const { code, output } = await captureIO(() =>
+      main([ ...ARGV0, 'bogus' ]));
+    assert.equal(code, 2);
+    assert.match(output, /Unknown command/);
+  });
+
+  it('telemetry subcommand unknown → exit 2', async function () {
+    const { code, output } = await captureIO(() =>
+      main([ ...ARGV0, 'telemetry', 'whatever' ]));
+    assert.equal(code, 2);
+    assert.match(output, /Unknown telemetry subcommand/);
+  });
+});
+
+describe('cli/main — unattended validation', function () {
+  it('--unattended with no other args → exit 2 lists exactly the strictly-required flags', async function () {
+    const { code, output } = await captureIO(() =>
+      main([ ...ARGV0, '--unattended' ]));
+    assert.equal(code, 2);
+    assert.match(output, /--project-name is required/);
+    assert.match(output, /Admin password required/);
+    assert.match(output, /--telemetry is required/);
+    // Defaulted flags must NOT be listed as required.
+    assert.doesNotMatch(output, /--kit is required/);
+    assert.doesNotMatch(output, /--db is required/);
+    assert.doesNotMatch(output, /--username is required/);
+  });
+
+  it('invalid --project-name → exit 2 with naming error', async function () {
+    const { code, output } = await captureIO(() =>
+      main([
+        ...ARGV0,
+        '--unattended',
+        '--project-name=../escape',
+        '--password=pw',
+        '--telemetry=off'
+      ]));
+    assert.equal(code, 2);
+    assert.match(output, /Invalid arguments/);
+  });
+
+  it('--telemetry with bad value → exit 2', async function () {
+    const { code, output } = await captureIO(() =>
+      main([
+        ...ARGV0,
+        '--unattended',
+        '--project-name=p',
+        '--password=pw',
+        '--telemetry=maybe'
+      ]));
+    assert.equal(code, 2);
+    assert.match(output, /--telemetry must be 'on' or 'off'/);
+  });
+
+  it('--db=mongodb without --db-uri → exit 2', async function () {
+    const { code, output } = await captureIO(() =>
+      main([
+        ...ARGV0,
+        '--unattended',
+        '--project-name=p',
+        '--password=pw',
+        '--telemetry=off',
+        '--db=mongodb'
+      ]));
+    assert.equal(code, 2);
+    assert.match(output, /--db-uri is required when --db=mongodb/);
+  });
+
+  it('--db=sqlite needs no --db-uri (sqlite is file-based)', async function () {
+    // Trigger a different validation failure (unknown kit) so we exit
+    // before any real I/O. Proves the sqlite branch passes the db-uri check.
+    const { code, output } = await captureIO(() =>
+      main([
+        ...ARGV0,
+        '--unattended',
+        '--project-name=p',
+        '--password=pw',
+        '--telemetry=off',
+        '--db=sqlite',
+        '--kit=does-not-exist'
+      ]));
+    assert.equal(code, 2);
+    assert.match(output, /Unknown --kit/);
+    // USAGE block (printed after the error block) mentions --db-uri, so
+    // assert on the actual error string, not just the flag name.
+    assert.doesNotMatch(output, /--db-uri is required/);
+  });
+
+  it('--kit unknown → exit 2', async function () {
+    const { code, output } = await captureIO(() =>
+      main([
+        ...ARGV0,
+        '--unattended',
+        '--project-name=p',
+        '--password=pw',
+        '--telemetry=off',
+        '--kit=nope'
+      ]));
+    assert.equal(code, 2);
+    assert.match(output, /Unknown --kit/);
+  });
+
+  it('--db unknown → exit 2 with the allowed-values hint', async function () {
+    const { code, output } = await captureIO(() =>
+      main([
+        ...ARGV0,
+        '--unattended',
+        '--project-name=p',
+        '--password=pw',
+        '--telemetry=off',
+        '--db=cassandra'
+      ]));
+    assert.equal(code, 2);
+    assert.match(output, /Unknown --db/);
+    assert.match(output, /sqlite, mongodb, postgres/);
+  });
+});
+
+describe('cli/main — unattended happy path (mocked createProject)', function () {
+  let store;
+  beforeEach(function () {
+    store = isolatedStoreFactory();
+  });
+  afterEach(function () {
+    store.cleanup();
+  });
+
+  it('threads required + defaulted args into CreateProjectOptions', async function () {
+    const cp = stubCreateProject();
+    const { code } = await captureIO(() => main(
+      [
+        ...ARGV0,
+        '--unattended',
+        '--project-name=my-proj',
+        '--password=pw',
+        '--telemetry=off'
+      ],
+      {
+        createProject: cp.fn,
+        createStore: store.createStore
+      }
+    ));
+    assert.equal(code, 0);
+    assert.equal(cp.calls.length, 1);
+    const { options } = cp.calls[0];
+    assert.equal(options.shortName, 'my-proj');
+    assert.equal(options.kitId, 'apostrophe-astro-demo'); // 5b default
+    assert.equal(options.dbChoice, 'sqlite');             // 5b default
+    assert.equal(options.dbUri, undefined);               // sqlite needs none
+    assert.deepEqual(options.admin, {
+      username: 'admin',                                  // 5b default
+      password: 'pw'
+    });
+    assert.equal(options.nonInteractive, true);
+    assert.ok(typeof options.confirmedAt === 'number');
+    assert.equal(typeof options.cwd, 'string');
+  });
+
+  it('passes through explicit overrides for kit/db/db-uri/username', async function () {
+    const cp = stubCreateProject();
+    await captureIO(() => main(
+      [
+        ...ARGV0,
+        '--unattended',
+        '--project-name=my-proj',
+        '--password=pw',
+        '--telemetry=off',
+        '--kit=apostrophe-essentials',
+        '--db=postgres',
+        '--db-uri=postgres://localhost/x',
+        '--username=ops@example.com'
+      ],
+      {
+        createProject: cp.fn,
+        createStore: store.createStore
+      }
+    ));
+    const { options } = cp.calls[0];
+    assert.equal(options.kitId, 'apostrophe-essentials');
+    assert.equal(options.dbChoice, 'postgres');
+    assert.equal(options.dbUri, 'postgres://localhost/x');
+    assert.equal(options.admin.username, 'ops@example.com');
+  });
+
+  it('result.ok === false → exit 1', async function () {
+    const cp = stubCreateProject({
+      ok: false,
+      kitId: 'k',
+      dbChoice: 'sqlite',
+      packageManager: 'npm',
+      durationMs: 0,
+      failStage: 'clone',
+      errorCode: 'git_clone_failed'
+    });
+    const { code } = await captureIO(() => main(
+      [
+        ...ARGV0,
+        '--unattended',
+        '--project-name=my-proj',
+        '--password=pw',
+        '--telemetry=off'
+      ],
+      {
+        createProject: cp.fn,
+        createStore: store.createStore
+      }
+    ));
+    assert.equal(code, 1);
+  });
+
+  it('--password absent → falls back to APOS_ADMIN_PASSWORD', async function () {
+    const cp = stubCreateProject();
+    const prev = process.env.APOS_ADMIN_PASSWORD;
+    process.env.APOS_ADMIN_PASSWORD = 'from-env';
+    try {
+      await captureIO(() => main(
+        [
+          ...ARGV0,
+          '--unattended',
+          '--project-name=my-proj',
+          '--telemetry=off'
+        ],
+        {
+          createProject: cp.fn,
+          createStore: store.createStore
+        }
+      ));
+    } finally {
+      if (prev === undefined) {
+        delete process.env.APOS_ADMIN_PASSWORD;
+      } else {
+        process.env.APOS_ADMIN_PASSWORD = prev;
+      }
+    }
+    assert.equal(cp.calls.length, 1);
+    assert.equal(cp.calls[0].options.admin.password, 'from-env');
+  });
+});
+
+describe('cli/main — unattended telemetry consent (kill switch)', function () {
+  let store;
+  beforeEach(function () {
+    store = isolatedStoreFactory();
+  });
+  afterEach(function () {
+    store.cleanup();
+  });
+
+  // Capture the config createTelemetry is called with, without building a
+  // live transport. Returns a no-op hook so the install path runs to the end.
+  function recordingTelemetry() {
+    const configs = [];
+    const fn = (config) => {
+      configs.push(config);
+      return {
+        event() {},
+        flush: async () => {}
+      };
+    };
+    return {
+      fn,
+      configs
+    };
+  }
+
+  // Set APOS_TELEMETRY for the duration of `fn`, then restore it.
+  async function withKillSwitch(value, fn) {
+    const prev = process.env.APOS_TELEMETRY;
+    if (value === undefined) {
+      delete process.env.APOS_TELEMETRY;
+    } else {
+      process.env.APOS_TELEMETRY = value;
+    }
+    try {
+      return await fn();
+    } finally {
+      if (prev === undefined) {
+        delete process.env.APOS_TELEMETRY;
+      } else {
+        process.env.APOS_TELEMETRY = prev;
+      }
+    }
+  }
+
+  function runUnattendedWith(telemetryFlag, tele) {
+    return captureIO(() => main(
+      [
+        ...ARGV0,
+        '--unattended',
+        '--project-name=my-proj',
+        '--password=pw',
+        `--telemetry=${telemetryFlag}`
+      ],
+      {
+        createProject: stubCreateProject().fn,
+        createStore: store.createStore,
+        createTelemetry: tele.fn
+      }
+    ));
+  }
+
+  it('APOS_TELEMETRY=0 overrides --telemetry=on → consent false', async function () {
+    const tele = recordingTelemetry();
+    await withKillSwitch('0', () => runUnattendedWith('on', tele));
+    assert.equal(tele.configs.length, 1);
+    assert.equal(tele.configs[0].consent, false);
+  });
+
+  it('no kill switch + --telemetry=on → consent true', async function () {
+    const tele = recordingTelemetry();
+    await withKillSwitch(undefined, () => runUnattendedWith('on', tele));
+    assert.equal(tele.configs.length, 1);
+    assert.equal(tele.configs[0].consent, true);
+  });
+
+  it('a non-0 APOS_TELEMETRY value does not disable --telemetry=on', async function () {
+    const tele = recordingTelemetry();
+    await withKillSwitch('1', () => runUnattendedWith('on', tele));
+    assert.equal(tele.configs[0].consent, true);
+  });
+});
+
+describe('cli/main — interactive path (mocked runFlow)', function () {
+  let store;
+  beforeEach(function () {
+    store = isolatedStoreFactory();
+  });
+  afterEach(function () {
+    store.cleanup();
+  });
+
+  // Build a FlowAnswers stand-in that matches the contract `runInteractive`
+  // expects. Tests vary individual fields by overriding.
+  function flowAnswers(extra = {}) {
+    return {
+      shortName: 'my-proj',
+      build: 'astro',
+      startingPoint: 'demo',
+      sampleContent: false,
+      kitId: 'apostrophe-astro-demo',
+      dbChoice: 'sqlite',
+      dbUri: undefined,
+      admin: {
+        username: 'admin',
+        password: 'pw'
+      },
+      telemetryConsent: false,
+      confirmedAt: Date.now(),
+      ...extra
+    };
+  }
+
+  it('flow answers → createProject options; exit 0 on ok:true', async function () {
+    const cp = stubCreateProject();
+    const answers = flowAnswers({
+      shortName: 'sample',
+      kitId: 'apostrophe-essentials',
+      dbChoice: 'postgres',
+      dbUri: 'postgres://localhost/x',
+      admin: {
+        username: 'ops',
+        password: 'pw'
+      }
+    });
+    const { code } = await captureIO(() => main(
+      [ ...ARGV0 ],
+      {
+        createProject: cp.fn,
+        createStore: store.createStore,
+        runFlow: async () => answers
+      }
+    ));
+    assert.equal(code, 0);
+    assert.equal(cp.calls.length, 1);
+    const { options } = cp.calls[0];
+    assert.equal(options.shortName, 'sample');
+    assert.equal(options.kitId, 'apostrophe-essentials');
+    assert.equal(options.dbChoice, 'postgres');
+    assert.equal(options.dbUri, 'postgres://localhost/x');
+    assert.equal(options.admin.username, 'ops');
+    assert.equal(options.nonInteractive, false);
+    assert.equal(options.confirmedAt, answers.confirmedAt);
+  });
+
+  it('createProject ok:false → exit 1', async function () {
+    const cp = stubCreateProject({
+      ok: false,
+      kitId: 'k',
+      dbChoice: 'sqlite',
+      packageManager: 'npm',
+      durationMs: 0,
+      failStage: 'admin',
+      errorCode: 'admin_user_failed'
+    });
+    const { code } = await captureIO(() => main(
+      [ ...ARGV0 ],
+      {
+        createProject: cp.fn,
+        createStore: store.createStore,
+        runFlow: async () => flowAnswers()
+      }
+    ));
+    assert.equal(code, 1);
+  });
+
+  it('UserCancelled at any prompt → exit 130; createProject never called', async function () {
+    const cp = stubCreateProject();
+    const { code } = await captureIO(() => main(
+      [ ...ARGV0 ],
+      {
+        createProject: cp.fn,
+        createStore: store.createStore,
+        runFlow: async () => {
+          throw new UserCancelled();
+        }
+      }
+    ));
+    assert.equal(code, 130);
+    assert.equal(cp.calls.length, 0);
+  });
+
+  it('unexpected runFlow throw is not swallowed (propagates)', async function () {
+    const cp = stubCreateProject();
+    const boom = new Error('boom');
+    await assert.rejects(
+      () => captureIO(() => main(
+        [ ...ARGV0 ],
+        {
+          createProject: cp.fn,
+          createStore: store.createStore,
+          runFlow: async () => {
+            throw boom;
+          }
+        }
+      )),
+      /boom/
+    );
+  });
+});
+
+describe('cli/main — telemetry subcommands', function () {
+  let store;
+  beforeEach(function () {
+    store = isolatedStoreFactory();
+  });
+  afterEach(function () {
+    store.cleanup();
+  });
+
+  // env: {} isolates these from an ambient APOS_TELEMETRY kill switch so the
+  // rendered consent/source lines are deterministic on any machine.
+  const noKillSwitch = { env: {} };
+
+  it('status → exit 0, renders effective state (fresh store: off/default)', async function () {
+    const { code, output } = await captureIO(() => runTelemetryCommand(
+      { sub: 'status' },
+      {
+        createStore: store.createStore,
+        ...noKillSwitch
+      }
+    ));
+    assert.equal(code, 0);
+    assert.match(output, /Telemetry status/);
+    assert.match(output, /consent\s+off/);
+    assert.match(output, /source\s+default/);
+  });
+
+  it('on → exit 0, confirms opt-in and reports the generated id', async function () {
+    const { code, output } = await captureIO(() => runTelemetryCommand(
+      { sub: 'on' },
+      {
+        createStore: store.createStore,
+        ...noKillSwitch
+      }
+    ));
+    assert.equal(code, 0);
+    assert.match(output, /Telemetry: on/);
+    assert.match(output, /Generated anonymousId:/);
+  });
+
+  it('off → exit 0, confirms opt-out', async function () {
+    const { code, output } = await captureIO(() => runTelemetryCommand(
+      { sub: 'off' },
+      {
+        createStore: store.createStore,
+        ...noKillSwitch
+      }
+    ));
+    assert.equal(code, 0);
+    assert.match(output, /Telemetry: off/);
+  });
+
+  it('preview → exit 0, prints the would-be payload with the id sentinel', async function () {
+    const { code, output } = await captureIO(() => runTelemetryCommand(
+      { sub: 'preview' },
+      {
+        createStore: store.createStore,
+        ...noKillSwitch
+      }
+    ));
+    assert.equal(code, 0);
+    assert.match(output, /Telemetry preview/);
+    // No id stored yet → preview uses the all-zero placeholder and says so.
+    assert.match(output, /00000000-0000-0000-0000-000000000000/);
+    assert.match(output, /placeholder/);
+  });
+
+  it('on persists; a following status reads it back as on/stored', async function () {
+    await captureIO(() => runTelemetryCommand(
+      { sub: 'on' },
+      {
+        createStore: store.createStore,
+        ...noKillSwitch
+      }
+    ));
+    const { code, output } = await captureIO(() => runTelemetryCommand(
+      { sub: 'status' },
+      {
+        createStore: store.createStore,
+        ...noKillSwitch
+      }
+    ));
+    assert.equal(code, 0);
+    assert.match(output, /consent\s+on/);
+    assert.match(output, /source\s+stored/);
+  });
+
+  it('missing subcommand → exit 2 with the expected-values hint', async function () {
+    const { code, output } = await captureIO(() => runTelemetryCommand(
+      { sub: undefined },
+      {
+        createStore: store.createStore,
+        ...noKillSwitch
+      }
+    ));
+    assert.equal(code, 2);
+    assert.match(output, /Unknown telemetry subcommand/);
+    assert.match(output, /\(none\)/);
+    assert.match(output, /status, on, off, preview/);
+  });
+
+  it('positional dispatch: `telemetry preview` routes through main', async function () {
+    const { code, output } = await captureIO(() => main(
+      [ ...ARGV0, 'telemetry', 'preview' ],
+      { createStore: store.createStore }
+    ));
+    assert.equal(code, 0);
+    assert.match(output, /Telemetry preview/);
+  });
+
+  it('positional dispatch: `telemetry status` routes through main', async function () {
+    const { code, output } = await captureIO(() => main(
+      [ ...ARGV0, 'telemetry', 'status' ],
+      { createStore: store.createStore }
+    ));
+    assert.equal(code, 0);
+    assert.match(output, /Telemetry status/);
+  });
+});
diff --git a/packages/create-apostrophe/test/core/admin-user.test.js b/packages/create-apostrophe/test/core/admin-user.test.js
new file mode 100644
index 0000000000..a600bc6b7b
--- /dev/null
+++ b/packages/create-apostrophe/test/core/admin-user.test.js
@@ -0,0 +1,279 @@
+import assert from 'node:assert/strict';
+import { addAdminUser } from '../../src/core/steps/admin-user.js';
+import { StageError } from '../../src/core/errors.js';
+
+describe('core/steps/admin-user', function () {
+  it('runs the user:add task with the username, password over stdin', async function () {
+    const calls = [];
+    const run = async (command, args, opts) => {
+      calls.push({
+        command,
+        args,
+        opts
+      });
+      return {
+        code: 0,
+        stdout: '',
+        stderr: '',
+        error: null
+      };
+    };
+
+    const outcome = await addAdminUser(
+      {
+        appRoot: '/proj',
+        username: 'me@example.com',
+        password: 's3cret'
+      },
+      { run }
+    );
+
+    assert.equal(outcome, 'created');
+    assert.deepEqual(calls[0].command, 'node');
+    assert.deepEqual(calls[0].args, [
+      'app.js', '@apostrophecms/user:add', '--', 'me@example.com', 'admin'
+    ]);
+    assert.equal(calls[0].opts.cwd, '/proj');
+    // Password goes over stdin, never as an argument.
+    assert.equal(calls[0].opts.input, 's3cret\n');
+    assert.ok(!calls[0].args.includes('s3cret'));
+  });
+
+  for (const variant of [
+    {
+      adapter: 'mongo',
+      stderr: 'E11000 duplicate key error collection: my-project.aposUsersSafe index: username_1 dup key: { username: "admin" }'
+    },
+    {
+      adapter: 'postgres',
+      stderr: 'Duplicate key error: username "admin" already exists'
+    },
+    {
+      adapter: 'sqlite',
+      stderr: 'Duplicate key error: already exists'
+    }
+  ]) {
+    it(`duplicate-username (${variant.adapter}) → falls back to change-password; returns "updated"`, async function () {
+      const calls = [];
+      const run = async (command, args, opts) => {
+        calls.push({
+          command,
+          args,
+          opts
+        });
+        if (args[1] === '@apostrophecms/user:add') {
+          return {
+            code: 1,
+            stdout: '',
+            stderr: variant.stderr,
+            error: null
+          };
+        }
+        return {
+          code: 0,
+          stdout: '',
+          stderr: '',
+          error: null
+        };
+      };
+
+      const outcome = await addAdminUser(
+        {
+          appRoot: '/proj',
+          username: 'admin',
+          password: 'pw'
+        },
+        { run }
+      );
+
+      assert.equal(outcome, 'updated');
+      assert.equal(calls.length, 2);
+      assert.deepEqual(calls[1].args, [
+        'app.js', '@apostrophecms/user:change-password', '--', 'admin'
+      ]);
+      assert.equal(calls[1].opts.input, 'pw\n');
+      assert.ok(!calls[1].args.includes('pw'));
+    });
+  }
+
+  it('non-duplicate non-zero exit → no fallback, original StageError stands', async function () {
+    const calls = [];
+    const run = async (command, args, opts) => {
+      calls.push({
+        command,
+        args,
+        opts
+      });
+      return {
+        code: 1,
+        stdout: '',
+        stderr: 'Database connection lost',
+        error: null
+      };
+    };
+
+    await assert.rejects(
+      () => addAdminUser({
+        appRoot: '/p',
+        username: 'admin',
+        password: 'x'
+      }, { run }),
+      (err) => {
+        assert.equal(err.errorCode, 'admin_user_failed');
+        return true;
+      }
+    );
+    // change-password must NOT have been attempted.
+    assert.equal(calls.length, 1);
+    assert.deepEqual(calls[0].args[1], '@apostrophecms/user:add');
+  });
+
+  it('fallback non-zero exit → admin_user_failed attributed to change-password', async function () {
+    const run = async (command, args) => ({
+      code: 1,
+      stdout: '',
+      stderr: args[1] === '@apostrophecms/user:add'
+        ? 'E11000 duplicate key error index: username_1'
+        : 'No such user.',
+      error: null
+    });
+
+    await assert.rejects(
+      () => addAdminUser({
+        appRoot: '/p',
+        username: 'admin',
+        password: 'x'
+      }, { run }),
+      (err) => {
+        assert.equal(err.errorCode, 'admin_user_failed');
+        // The cause must point at the failed recovery, not the duplicate
+        // user:add that triggered it.
+        assert.match(err.cause.message, /user:change-password exited with code 1/);
+        return true;
+      }
+    );
+  });
+
+  it('fallback spawn error (ENOENT) → node_missing, not admin_user_failed', async function () {
+    const run = async (command, args) => {
+      if (args[1] === '@apostrophecms/user:add') {
+        return {
+          code: 1,
+          stdout: '',
+          stderr: 'E11000 duplicate key error index: username_1',
+          error: null
+        };
+      }
+      const err = new Error('spawn ENOENT');
+      err.code = 'ENOENT';
+      return {
+        code: null,
+        stdout: '',
+        stderr: '',
+        error: err
+      };
+    };
+
+    await assert.rejects(
+      () => addAdminUser({
+        appRoot: '/p',
+        username: 'admin',
+        password: 'x'
+      }, { run }),
+      (err) => {
+        assert.equal(err.errorCode, 'node_missing');
+        return true;
+      }
+    );
+  });
+
+  it('username that looks like a flag is passed as a positional (-- separator)', async function () {
+    // Apostrophe parses task argv with `boring({ end: true })` and resolves
+    // username as `argv._[1] || argv.username`. Without the `--` end-of-
+    // options marker, a username like `--role=guest` would be re-interpreted
+    // as a flag, the task would see no positional username, and would create
+    // a different user with a different role than asked. The `--` keeps the
+    // user-supplied value strictly positional.
+    const calls = [];
+    const run = async (command, args, opts) => {
+      calls.push({
+        command,
+        args,
+        opts
+      });
+      return {
+        code: 0,
+        stdout: '',
+        stderr: '',
+        error: null
+      };
+    };
+
+    await addAdminUser(
+      {
+        appRoot: '/proj',
+        username: '--role=guest',
+        password: 'pw'
+      },
+      { run }
+    );
+
+    // The `--` MUST appear immediately before the user-supplied username.
+    const sepIdx = calls[0].args.indexOf('--');
+    assert.ok(sepIdx >= 0, '-- separator must be present');
+    assert.equal(calls[0].args[sepIdx + 1], '--role=guest');
+  });
+
+  it('requires a username', async function () {
+    await assert.rejects(
+      () => addAdminUser({
+        appRoot: '/p',
+        password: 'x'
+      }, { run: async () => ({ code: 0 }) }),
+      TypeError
+    );
+  });
+
+  it('non-zero exit → StageError(admin, admin_user_failed); no password leak', async function () {
+    const run = async () => ({
+      code: 1,
+      stdout: '',
+      stderr: 'Something unrelated went wrong',
+      error: null
+    });
+    await assert.rejects(
+      () => addAdminUser({
+        appRoot: '/p',
+        username: 'admin',
+        password: 'topsecret'
+      }, { run }),
+      (err) => {
+        assert.ok(err instanceof StageError);
+        assert.equal(err.stage, 'admin');
+        assert.equal(err.errorCode, 'admin_user_failed');
+        assert.doesNotMatch(err.message, /topsecret/);
+        assert.doesNotMatch(String(err.cause && err.cause.message), /topsecret/);
+        return true;
+      }
+    );
+  });
+
+  it('node missing → StageError(admin, node_missing)', async function () {
+    const run = async () => ({
+      code: null,
+      error: Object.assign(new Error('spawn ENOENT'), { code: 'ENOENT' })
+    });
+    await assert.rejects(
+      () => addAdminUser({
+        appRoot: '/p',
+        username: 'admin',
+        password: 'x'
+      }, { run }),
+      (err) => {
+        assert.equal(err.stage, 'admin');
+        assert.equal(err.errorCode, 'node_missing');
+        return true;
+      }
+    );
+  });
+});
diff --git a/packages/create-apostrophe/test/core/clone.test.js b/packages/create-apostrophe/test/core/clone.test.js
new file mode 100644
index 0000000000..fb55237012
--- /dev/null
+++ b/packages/create-apostrophe/test/core/clone.test.js
@@ -0,0 +1,147 @@
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, rmSync, mkdirSync, existsSync, writeFileSync
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { clone } from '../../src/core/steps/clone.js';
+import { StageError } from '../../src/core/errors.js';
+
+describe('core/steps/clone', function () {
+  let cwd;
+
+  beforeEach(function () {
+    cwd = mkdtempSync(join(tmpdir(), 'ca-clone-'));
+  });
+
+  afterEach(function () {
+    rmSync(cwd, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('invokes no-shell git with an end-of-options guard, then strips .git', async function () {
+    const calls = [];
+    // Fake `run` that simulates a successful clone by materializing the
+    // project dir + a .git/ the step is expected to remove.
+    const fakeRun = async (command, args, opts) => {
+      calls.push({
+        command,
+        args,
+        opts
+      });
+      const dir = join(opts.cwd, 'my-site');
+      mkdirSync(join(dir, '.git', 'refs'), { recursive: true });
+      writeFileSync(join(dir, 'app.js'), '// project');
+      return {
+        code: 0,
+        stdout: '',
+        stderr: '',
+        error: null
+      };
+    };
+
+    const { projectDir } = await clone(
+      {
+        repo: 'https://github.com/apostrophecms/public-demo.git',
+        shortName: 'my-site',
+        cwd
+      },
+      { run: fakeRun }
+    );
+
+    assert.deepEqual(calls[0].command, 'git');
+    assert.deepEqual(calls[0].args, [
+      'clone', '--', 'https://github.com/apostrophecms/public-demo.git', 'my-site'
+    ]);
+    assert.equal(projectDir, join(cwd, 'my-site'));
+    assert.equal(existsSync(join(projectDir, 'app.js')), true);
+    assert.equal(existsSync(join(projectDir, '.git')), false, '.git must be stripped');
+  });
+
+  it('rejects a path-traversal shortName before spawning git', async function () {
+    let spawned = false;
+    const fakeRun = async () => {
+      spawned = true; return { code: 0 };
+    };
+    for (const bad of [ '../evil', 'a/b', '/abs', '..', 'na me', '.' ]) {
+      await assert.rejects(
+        () => clone({
+          repo: 'r',
+          shortName: bad,
+          cwd
+        }, { run: fakeRun }),
+        TypeError
+      );
+    }
+    assert.equal(spawned, false, 'git must not be spawned for an unsafe name');
+  });
+
+  it('throws StageError(clone, target_exists) when the target dir already exists', async function () {
+    mkdirSync(join(cwd, 'my-site'));
+    let spawned = false;
+    const fakeRun = async () => {
+      spawned = true; return { code: 0 };
+    };
+    await assert.rejects(
+      () => clone({
+        repo: 'r',
+        shortName: 'my-site',
+        cwd
+      }, { run: fakeRun }),
+      (err) => {
+        assert.ok(err instanceof StageError);
+        assert.equal(err.stage, 'clone');
+        assert.equal(err.errorCode, 'target_exists');
+        return true;
+      }
+    );
+    assert.equal(spawned, false, 'git must not be spawned when target already exists');
+  });
+
+  it('throws StageError(clone, git_missing) when git is absent', async function () {
+    const fakeRun = async () => ({
+      code: null,
+      stdout: '',
+      stderr: '',
+      error: Object.assign(new Error('spawn git ENOENT'), { code: 'ENOENT' })
+    });
+    await assert.rejects(
+      () => clone({
+        repo: 'r',
+        shortName: 's',
+        cwd
+      }, { run: fakeRun }),
+      (err) => {
+        assert.ok(err instanceof StageError);
+        assert.equal(err.stage, 'clone');
+        assert.equal(err.errorCode, 'git_missing');
+        return true;
+      }
+    );
+  });
+
+  it('throws StageError(clone, git_clone_failed) on a non-zero exit', async function () {
+    const fakeRun = async () => ({
+      code: 128,
+      stdout: '',
+      stderr: 'fatal: repository not found',
+      error: null
+    });
+    await assert.rejects(
+      () => clone({
+        repo: 'r',
+        shortName: 's',
+        cwd
+      }, { run: fakeRun }),
+      (err) => {
+        assert.equal(err.stage, 'clone');
+        assert.equal(err.errorCode, 'git_clone_failed');
+        // Raw stderr must not leak into the symbolic errorCode (D7).
+        assert.ok(!String(err.errorCode).includes('fatal'));
+        return true;
+      }
+    );
+  });
+});
diff --git a/packages/create-apostrophe/test/core/contract.test.js b/packages/create-apostrophe/test/core/contract.test.js
new file mode 100644
index 0000000000..0808f01e5c
--- /dev/null
+++ b/packages/create-apostrophe/test/core/contract.test.js
@@ -0,0 +1,206 @@
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, rmSync, mkdirSync, writeFileSync, existsSync
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { makeCreateProject } from '../../src/core/create-project.js';
+import { scaffold } from '../../src/core/steps/scaffold.js';
+import { dbConfig } from '../../src/core/steps/db-config.js';
+import { KIT_IDS, getKit } from '../../src/core/kits.js';
+import { StageError } from '../../src/core/errors.js';
+
+const APP_JS = 'module.exports = { shortName: \'x\' };\n';
+const PKG = '{ "name": "x" }\n';
+const DBS = [ 'sqlite', 'mongodb', 'postgres' ];
+
+function spies() {
+  const events = [];
+  const logger = {
+    info() {},
+    warn() {},
+    error() {},
+    task() {
+      return {
+        succeed() {},
+        fail() {}
+      };
+    }
+  };
+  const telemetry = {
+    event(name, payload) {
+      events.push({
+        name,
+        payload
+      });
+    }
+  };
+  return {
+    events,
+    logger,
+    telemetry
+  };
+}
+
+describe('core contract — createProject', function () {
+  let dir;
+
+  beforeEach(function () {
+    dir = mkdtempSync(join(tmpdir(), 'ca-contract-'));
+  });
+
+  afterEach(function () {
+    rmSync(dir, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  // Real scaffold + db-config; clone faked to lay out the kit's structure;
+  // install/admin faked (no npm/node spawn).
+  function orchestrator(extra = {}) {
+    return makeCreateProject({
+      clone: async ({ shortName }) => {
+        const projectDir = join(dir, shortName);
+        const frontend = getKit(extra.kitId).frontend;
+        const appRoot = frontend ? join(projectDir, 'backend') : projectDir;
+        mkdirSync(appRoot, { recursive: true });
+        writeFileSync(join(appRoot, 'app.js'), APP_JS);
+        writeFileSync(join(appRoot, 'package.json'), PKG);
+        if (frontend) {
+          mkdirSync(join(projectDir, 'frontend'), { recursive: true });
+        }
+        return { projectDir };
+      },
+      scaffold,
+      // Real env-writing + URI resolution, but the live connection probe is
+      // stubbed reachable — connectivity itself is covered by db.test.js /
+      // db-config.test.js, not this orchestration contract (which spans
+      // mongodb/postgres combos with no live server).
+      dbConfig: (opts) => dbConfig(opts, {
+        verifyConnection: async () => ({ reachable: true })
+      }),
+      install: async () => {},
+      addAdminUser: async () => {},
+      importSampleData: async () => {},
+      ...extra.steps
+    });
+  }
+
+  it('produces a real project for every kit × db; exactly one success event', async function () {
+    for (const kitId of KIT_IDS) {
+      for (const dbChoice of DBS) {
+        const {
+          events, logger, telemetry
+        } = spies();
+        const shortName = 'p';
+        const createProject = orchestrator({ kitId });
+        const res = await createProject(
+          {
+            shortName,
+            cwd: dir,
+            kitId,
+            dbChoice,
+            dbUri: dbChoice === 'sqlite' ? undefined : `${dbChoice}://localhost/p`,
+            admin: {
+              username: 'admin',
+              password: 'pw'
+            },
+            packageManager: 'npm',
+            nonInteractive: true,
+            confirmedAt: Date.now() - 10
+          },
+          {
+            telemetry,
+            logger
+          }
+        );
+
+        const label = `${kitId}/${dbChoice}`;
+        assert.equal(res.ok, true, label);
+        assert.equal(res.kitId, kitId, label);
+        assert.equal(res.dbChoice, dbChoice, label);
+        assert.ok(res.durationMs >= 0, label);
+        assert.equal(events.length, 1, label);
+        assert.equal(events[0].name, 'install_success', label);
+
+        const { frontend } = getKit(kitId);
+        const appRoot = frontend
+          ? join(dir, shortName, 'backend')
+          : join(dir, shortName);
+        const env = join(appRoot, '.env');
+        assert.equal(existsSync(env), true, `${label} .env`);
+        if (frontend) {
+          assert.equal(
+            existsSync(join(dir, shortName, 'frontend', '.env')), true,
+            `${label} frontend .env`
+          );
+        }
+        rmSync(join(dir, shortName), {
+          recursive: true,
+          force: true
+        });
+      }
+    }
+  });
+
+  const failCases = [
+    [ 'scaffold', 'scaffold', 'missing_scaffold_file' ],
+    [ 'install', 'dependency_install', 'install_failed' ],
+    [ 'dbConfig', 'db_connect', 'db_connect_failed' ],
+    [ 'addAdminUser', 'admin', 'admin_user_failed' ]
+  ];
+
+  for (const [ stepName, failStage, code ] of failCases) {
+    it(`attributes a ${failStage} failure (one install_fail, later steps skipped)`, async function () {
+      const {
+        events, logger, telemetry
+      } = spies();
+      const ran = [];
+      const trace = (name, fn) => async (...a) => {
+        ran.push(name); return fn(...a);
+      };
+      const createProject = orchestrator({
+        kitId: 'apostrophe-essentials',
+        steps: {
+          scaffold: trace('scaffold', scaffold),
+          dbConfig: trace('dbConfig', dbConfig),
+          install: trace('install', async () => {}),
+          addAdminUser: trace('addAdminUser', async () => {}),
+          [stepName]: trace(stepName, async () => {
+            throw new StageError(failStage, { code });
+          })
+        }
+      });
+
+      const res = await createProject(
+        {
+          shortName: 'p',
+          cwd: dir,
+          kitId: 'apostrophe-essentials',
+          dbChoice: 'sqlite',
+          admin: {
+            username: 'admin',
+            password: 'pw'
+          },
+          packageManager: 'npm',
+          nonInteractive: true,
+          confirmedAt: Date.now() - 5
+        },
+        {
+          telemetry,
+          logger
+        }
+      );
+
+      assert.equal(res.ok, false);
+      assert.equal(res.failStage, failStage);
+      assert.equal(res.errorCode, code);
+      assert.equal(events.length, 1);
+      assert.equal(events[0].name, 'install_fail');
+      assert.equal(events[0].payload.failStage, failStage);
+      // The failing step is the last that ran.
+      assert.equal(ran[ran.length - 1], stepName);
+    });
+  }
+});
diff --git a/packages/create-apostrophe/test/core/create-project.test.js b/packages/create-apostrophe/test/core/create-project.test.js
new file mode 100644
index 0000000000..aa00a3d1f5
--- /dev/null
+++ b/packages/create-apostrophe/test/core/create-project.test.js
@@ -0,0 +1,253 @@
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, rmSync, mkdirSync, writeFileSync, existsSync
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { makeCreateProject } from '../../src/core/create-project.js';
+import { createProject as publicCreateProject } from '../../src/index.js';
+import { StageError } from '../../src/core/errors.js';
+
+const APP_JS = 'module.exports = { shortName: \'x\' };\n';
+const PKG = '{ "name": "x" }\n';
+
+function spies() {
+  const events = [];
+  const tasks = [];
+  const logger = {
+    info() {},
+    warn() {},
+    error() {},
+    task(label) {
+      const rec = {
+        label,
+        settled: null
+      };
+      tasks.push(rec);
+      return {
+        succeed() {
+          rec.settled = 'succeed';
+        },
+        fail() {
+          rec.settled = 'fail';
+        }
+      };
+    }
+  };
+  const telemetry = {
+    event(name, payload) {
+      events.push({
+        name,
+        payload
+      });
+    }
+  };
+  return {
+    events,
+    tasks,
+    logger,
+    telemetry
+  };
+}
+
+const baseOptions = (over = {}) => ({
+  shortName: 'my-site',
+  cwd: '/tmp/p',
+  kitId: 'apostrophe-essentials',
+  dbChoice: 'sqlite',
+  admin: {
+    username: 'admin',
+    password: 'pw'
+  },
+  packageManager: 'npm',
+  nonInteractive: true,
+  confirmedAt: Date.now() - 25,
+  ...over
+});
+
+describe('core/create-project', function () {
+  let dir;
+
+  beforeEach(function () {
+    dir = mkdtempSync(join(tmpdir(), 'ca-cp-'));
+  });
+
+  afterEach(function () {
+    rmSync(dir, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  // Fake clone that materializes a standalone project so the REAL scaffold and
+  // db-config run against it. install/admin are faked (no npm/node spawn).
+  function fakeStandaloneClone(calls) {
+    return async ({ shortName }) => {
+      const projectDir = join(dir, shortName);
+      mkdirSync(projectDir, { recursive: true });
+      writeFileSync(join(projectDir, 'app.js'), APP_JS);
+      writeFileSync(join(projectDir, 'package.json'), PKG);
+      calls.push('clone');
+      return { projectDir };
+    };
+  }
+
+  it('success: real scaffold+db, one install_success, tasks all succeed', async function () {
+    const {
+      events, tasks, logger, telemetry
+    } = spies();
+    const calls = [];
+    const createProject = makeCreateProject({
+      clone: fakeStandaloneClone(calls),
+      scaffold: (await import('../../src/core/steps/scaffold.js')).scaffold,
+      dbConfig: (await import('../../src/core/steps/db-config.js')).dbConfig,
+      install: async () => {
+        calls.push('install');
+      },
+      addAdminUser: async () => {
+        calls.push('admin');
+      }
+    });
+
+    const res = await createProject(baseOptions(), {
+      telemetry,
+      logger
+    });
+
+    assert.equal(res.ok, true);
+    assert.equal(res.kitId, 'apostrophe-essentials');
+    assert.equal(res.dbChoice, 'sqlite');
+    assert.equal(res.packageManager, 'npm');
+    assert.ok(res.durationMs >= 0);
+    assert.equal(res.failStage, undefined);
+
+    // Real artifacts produced.
+    const env = join(dir, 'my-site', '.env');
+    assert.equal(existsSync(env), true);
+
+    // Exactly one terminal event, success.
+    assert.equal(events.length, 1);
+    assert.equal(events[0].name, 'install_success');
+    assert.deepEqual(events[0].payload, {
+      kitId: 'apostrophe-essentials',
+      dbChoice: 'sqlite',
+      packageManager: 'npm',
+      durationMs: res.durationMs
+    });
+    assert.deepEqual(calls, [ 'clone', 'install', 'admin' ]);
+    assert.deepEqual(tasks.map((t) => [ t.label, t.settled ]), [
+      [ 'Cloning starter', 'succeed' ],
+      [ 'Configuring project', 'succeed' ],
+      [ 'Installing dependencies', 'succeed' ],
+      [ 'Configuring database', 'succeed' ],
+      [ 'Creating admin account', 'succeed' ]
+    ]);
+  });
+
+  it('preflight: pnpm → ok:false failStage:null unsupported_pm, no steps', async function () {
+    const {
+      events, tasks, logger, telemetry
+    } = spies();
+    const calls = [];
+    const createProject = makeCreateProject({
+      clone: fakeStandaloneClone(calls),
+      scaffold: () => {
+        throw new Error('should not run');
+      },
+      dbConfig: () => {},
+      install: () => {},
+      addAdminUser: () => {}
+    });
+
+    const res = await createProject(
+      baseOptions({ packageManager: 'pnpm' }),
+      {
+        telemetry,
+        logger
+      }
+    );
+
+    assert.deepEqual(res, {
+      ok: false,
+      kitId: 'apostrophe-essentials',
+      dbChoice: 'sqlite',
+      packageManager: 'pnpm',
+      durationMs: res.durationMs,
+      failStage: null,
+      errorCode: 'unsupported_pm'
+    });
+    assert.equal(calls.length, 0);
+    assert.equal(tasks.length, 0);
+    assert.equal(events.length, 1);
+    assert.equal(events[0].name, 'install_fail');
+    assert.equal(events[0].payload.failStage, null);
+    assert.equal(events[0].payload.errorCode, 'unsupported_pm');
+  });
+
+  it('step StageError → ok:false with that failStage, one install_fail', async function () {
+    const {
+      events, tasks, logger, telemetry
+    } = spies();
+    const after = [];
+    const createProject = makeCreateProject({
+      clone: async () => {
+        throw new StageError('clone', { code: 'git_clone_failed' });
+      },
+      scaffold: () => {
+        after.push('scaffold');
+      },
+      dbConfig: () => {
+        after.push('db');
+      },
+      install: () => {
+        after.push('install');
+      },
+      addAdminUser: () => {
+        after.push('admin');
+      }
+    });
+
+    const res = await createProject(baseOptions(), {
+      telemetry,
+      logger
+    });
+
+    assert.equal(res.ok, false);
+    assert.equal(res.failStage, 'clone');
+    assert.equal(res.errorCode, 'git_clone_failed');
+    assert.deepEqual(after, []); // nothing after the failing step ran
+    assert.equal(events.length, 1);
+    assert.equal(events[0].name, 'install_fail');
+    assert.deepEqual(tasks.map((t) => [ t.label, t.settled ]), [
+      [ 'Cloning starter', 'fail' ]
+    ]);
+  });
+
+  it('unexpected throw propagates; no telemetry emitted (caller emits)', async function () {
+    const {
+      events, logger, telemetry
+    } = spies();
+    const createProject = makeCreateProject({
+      clone: async () => {
+        throw new Error('boom');
+      },
+      scaffold: () => {},
+      dbConfig: () => {},
+      install: () => {},
+      addAdminUser: () => {}
+    });
+
+    await assert.rejects(
+      () => createProject(baseOptions(), {
+        telemetry,
+        logger
+      }),
+      /boom/
+    );
+    assert.equal(events.length, 0);
+  });
+
+  it('public index.js exposes createProject', function () {
+    assert.equal(typeof publicCreateProject, 'function');
+  });
+});
diff --git a/packages/create-apostrophe/test/core/db-config.test.js b/packages/create-apostrophe/test/core/db-config.test.js
new file mode 100644
index 0000000000..1e7fb337b0
--- /dev/null
+++ b/packages/create-apostrophe/test/core/db-config.test.js
@@ -0,0 +1,259 @@
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, rmSync, writeFileSync, readFileSync
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { dbConfig } from '../../src/core/steps/db-config.js';
+import { StageError } from '../../src/core/errors.js';
+
+describe('core/steps/db-config', function () {
+  let appRoot;
+  const readEnv = () => readFileSync(join(appRoot, '.env'), 'utf8');
+
+  beforeEach(function () {
+    appRoot = mkdtempSync(join(tmpdir(), 'ca-db-'));
+  });
+
+  afterEach(function () {
+    rmSync(appRoot, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('sqlite: adapter only, no URI even if dbUri is passed', async function () {
+    const res = await dbConfig({
+      appRoot,
+      dbChoice: 'sqlite',
+      dbUri: 'ignored://x'
+    });
+    assert.deepEqual(res, { dbChoice: 'sqlite' });
+    const env = readEnv();
+    assert.match(env, /^APOS_DEFAULT_DB_ADAPTER=sqlite$/m);
+    assert.doesNotMatch(env, /APOS_DB_URI/);
+  });
+
+  it('mongodb with a connection string: adapter + APOS_DB_URI', async function () {
+    await dbConfig({
+      appRoot,
+      dbChoice: 'mongodb',
+      dbUri: 'mongodb://localhost:27017/my-site'
+    });
+    const env = readEnv();
+    assert.match(env, /^APOS_DEFAULT_DB_ADAPTER=mongodb$/m);
+    assert.match(env, /^APOS_DB_URI=mongodb:\/\/localhost:27017\/my-site$/m);
+  });
+
+  it('postgres without a connection string: adapter only (core defaults host)', async function () {
+    await dbConfig({
+      appRoot,
+      dbChoice: 'postgres'
+    });
+    const env = readEnv();
+    assert.match(env, /^APOS_DEFAULT_DB_ADAPTER=postgres$/m);
+    assert.doesNotMatch(env, /APOS_DB_URI/);
+  });
+
+  it('preserves scaffold-written keys (upsert, not overwrite)', async function () {
+    writeFileSync(join(appRoot, '.env'), 'APOS_SESSION_SECRET=abc\n');
+    await dbConfig({
+      appRoot,
+      dbChoice: 'sqlite'
+    });
+    const env = readEnv();
+    assert.match(env, /^APOS_SESSION_SECRET=abc$/m);
+    assert.match(env, /^APOS_DEFAULT_DB_ADAPTER=sqlite$/m);
+  });
+
+  it('rejects an unknown dbChoice', async function () {
+    await assert.rejects(
+      () => dbConfig({
+        appRoot,
+        dbChoice: 'mysql'
+      }),
+      TypeError
+    );
+  });
+
+  it('verifies the resolved URI; success returns normally', async function () {
+    let seen;
+    const res = await dbConfig(
+      {
+        appRoot,
+        dbChoice: 'postgres',
+        dbUri: 'postgres://h/db',
+        shortName: 'my-site'
+      },
+      {
+        verifyConnection: async (uri) => {
+          seen = uri;
+          return { reachable: true };
+        }
+      }
+    );
+    // mongodb/postgres pass the user URI through verbatim.
+    assert.equal(seen, 'postgres://h/db');
+    assert.deepEqual(res, { dbChoice: 'postgres' });
+  });
+
+  it('verifies the derived sqlite URI (no user dbUri)', async function () {
+    let seen;
+    await dbConfig(
+      {
+        appRoot,
+        dbChoice: 'sqlite',
+        shortName: 'my-site'
+      },
+      {
+        verifyConnection: async (uri) => {
+          seen = uri;
+          return { reachable: true };
+        }
+      }
+    );
+    assert.match(seen, /^sqlite:\/\/.*\/data\/my-site\.sqlite$/);
+  });
+
+  it('skips the check entirely when no verifyConnection is wired', async function () {
+    // No deps → env written, no connection attempted (shortName not required).
+    const res = await dbConfig({
+      appRoot,
+      dbChoice: 'mongodb',
+      dbUri: 'mongodb://h/db'
+    });
+    assert.deepEqual(res, { dbChoice: 'mongodb' });
+  });
+
+  it('dbReset=drop: drops the resolved URI after a passing check', async function () {
+    const seen = {};
+    await dbConfig(
+      {
+        appRoot,
+        dbChoice: 'postgres',
+        dbUri: 'postgres://h/db',
+        shortName: 'my-site',
+        dbReset: 'drop'
+      },
+      {
+        verifyConnection: async (uri) => {
+          seen.checked = uri;
+          return { reachable: true };
+        },
+        dropDatabase: async (uri) => {
+          seen.dropped = uri;
+        }
+      }
+    );
+    assert.equal(seen.checked, 'postgres://h/db');
+    assert.equal(seen.dropped, 'postgres://h/db');
+  });
+
+  it('dbReset=keep (default): never drops', async function () {
+    let dropped = false;
+    await dbConfig(
+      {
+        appRoot,
+        dbChoice: 'postgres',
+        dbUri: 'postgres://h/db',
+        shortName: 'my-site'
+      },
+      {
+        verifyConnection: async () => ({ reachable: true }),
+        dropDatabase: async () => {
+          dropped = true;
+        }
+      }
+    );
+    assert.equal(dropped, false);
+  });
+
+  it('a failed check short-circuits before any drop', async function () {
+    let dropped = false;
+    await assert.rejects(
+      () => dbConfig(
+        {
+          appRoot,
+          dbChoice: 'mongodb',
+          dbUri: 'mongodb://bad/db',
+          shortName: 'my-site',
+          dbReset: 'drop'
+        },
+        {
+          verifyConnection: async () => ({
+            reachable: false,
+            reason: 'auth'
+          }),
+          dropDatabase: async () => {
+            dropped = true;
+          }
+        }
+      ),
+      (err) => err instanceof StageError && err.errorCode === 'db_auth_failed'
+    );
+    assert.equal(dropped, false, 'must not drop when the connection check failed');
+  });
+
+  it('drop failure → StageError(db_connect, db_drop_failed)', async function () {
+    await assert.rejects(
+      () => dbConfig(
+        {
+          appRoot,
+          dbChoice: 'postgres',
+          dbUri: 'postgres://h/db',
+          shortName: 'my-site',
+          dbReset: 'drop'
+        },
+        {
+          verifyConnection: async () => ({ reachable: true }),
+          dropDatabase: async () => {
+            throw new Error('permission denied to drop tables');
+          }
+        }
+      ),
+      (err) => {
+        assert.ok(err instanceof StageError);
+        assert.equal(err.stage, 'db_connect');
+        assert.equal(err.errorCode, 'db_drop_failed');
+        assert.doesNotMatch(String(err.errorCode), /permission denied/);
+        return true;
+      }
+    );
+  });
+
+  /** @type {Array<[string, string]>} reason → mapped errorCode */
+  const reasonCases = [
+    [ 'unreachable', 'db_unreachable' ],
+    [ 'auth', 'db_auth_failed' ],
+    [ 'unknown', 'db_connect_failed' ]
+  ];
+  for (const [ reason, code ] of reasonCases) {
+    it(`unreachable verdict (${reason}) → StageError(db_connect, ${code})`, async function () {
+      await assert.rejects(
+        () => dbConfig(
+          {
+            appRoot,
+            dbChoice: 'mongodb',
+            dbUri: 'mongodb://bad/db',
+            shortName: 'my-site'
+          },
+          {
+            verifyConnection: async () => ({
+              reachable: false,
+              reason,
+              message: 'connect ECONNREFUSED 127.0.0.1:27017'
+            })
+          }
+        ),
+        (err) => {
+          assert.ok(err instanceof StageError);
+          assert.equal(err.stage, 'db_connect');
+          assert.equal(err.errorCode, code);
+          // The symbolic code never carries the raw driver string.
+          assert.doesNotMatch(String(err.errorCode), /ECONNREFUSED/);
+          return true;
+        }
+      );
+    });
+  }
+});
diff --git a/packages/create-apostrophe/test/core/db.test.js b/packages/create-apostrophe/test/core/db.test.js
new file mode 100644
index 0000000000..48d4fe8ec4
--- /dev/null
+++ b/packages/create-apostrophe/test/core/db.test.js
@@ -0,0 +1,361 @@
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, rmSync, existsSync
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import dbConnect from '@apostrophecms/db-connect';
+import {
+  resolveDbUri, inspect, checkConnection, dropDatabase, clearDatabase, restore
+} from '../../src/core/db.js';
+
+// A fake db-connect client whose db() exposes just the surface db.js uses.
+// Records whether close()/dropDatabase() were called and what connect opts
+// it was handed.
+function makeClient(collections = []) {
+  const calls = {
+    closed: false,
+    dropped: false,
+    cleared: [] // names passed to collection().deleteMany()
+  };
+  const client = {
+    db() {
+      return {
+        listCollections() {
+          return {
+            async toArray() {
+              return collections;
+            }
+          };
+        },
+        async dropDatabase() {
+          calls.dropped = true;
+        },
+        collection(name) {
+          return {
+            async deleteMany() {
+              calls.cleared.push(name);
+            }
+          };
+        }
+      };
+    },
+    async close() {
+      calls.closed = true;
+    }
+  };
+  return {
+    client,
+    calls
+  };
+}
+
+// connect stub that records the (uri, opts) it was called with and returns
+// the given client (or throws the given error).
+function stubConnect({ client, error } = {}) {
+  const seen = {};
+  const connect = async (uri, opts) => {
+    seen.uri = uri;
+    seen.opts = opts;
+    if (error) {
+      throw error;
+    }
+    return client;
+  };
+  return {
+    connect,
+    seen
+  };
+}
+
+describe('core/db — resolveDbUri', function () {
+  const appRoot = '/srv/app';
+
+  it('sqlite: core formula — sqlite:// + <appRoot>/data/<shortName>.sqlite', function () {
+    const uri = resolveDbUri({
+      dbChoice: 'sqlite',
+      appRoot,
+      shortName: 'my-site'
+    });
+    assert.equal(uri, `sqlite://${resolve(appRoot, 'data', 'my-site.sqlite')}`);
+  });
+
+  it('mongodb / postgres: the supplied dbUri verbatim', function () {
+    assert.equal(
+      resolveDbUri({
+        dbChoice: 'mongodb',
+        dbUri: 'mongodb://localhost:27017/my-site',
+        appRoot,
+        shortName: 'my-site'
+      }),
+      'mongodb://localhost:27017/my-site'
+    );
+    assert.equal(
+      resolveDbUri({
+        dbChoice: 'postgres',
+        dbUri: 'postgres://postgres@localhost:5432/my-site',
+        appRoot,
+        shortName: 'my-site'
+      }),
+      'postgres://postgres@localhost:5432/my-site'
+    );
+  });
+
+  it('throws when mongodb/postgres has no dbUri', function () {
+    assert.throws(
+      () => resolveDbUri({
+        dbChoice: 'mongodb',
+        appRoot,
+        shortName: 'my-site'
+      }),
+      TypeError
+    );
+  });
+
+  it('re-validates shortName at the path boundary (zip-slip / traversal)', function () {
+    for (const bad of [ '../evil', 'a/b', 'x\0y', '' ]) {
+      assert.throws(
+        () => resolveDbUri({
+          dbChoice: 'sqlite',
+          appRoot,
+          shortName: bad
+        }),
+        TypeError,
+        `should reject ${JSON.stringify(bad)}`
+      );
+    }
+  });
+});
+
+describe('core/db — sqlite end-to-end (real temp file)', function () {
+  let appRoot;
+  let uri;
+
+  const DUMP = [
+    '{"_collection":"articles","_indexes":[]}',
+    '{"_doc":{"_id":"a1","title":"Hello"}}',
+    '{"_doc":{"_id":"a2","title":"World"}}'
+  ].join('\n');
+
+  beforeEach(function () {
+    appRoot = mkdtempSync(join(tmpdir(), 'ca-db-'));
+    uri = resolveDbUri({
+      dbChoice: 'sqlite',
+      appRoot,
+      shortName: 'site'
+    });
+  });
+
+  afterEach(function () {
+    rmSync(appRoot, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('restore writes the dump and it reads back', async function () {
+    await restore(uri, DUMP);
+
+    // The sqlite adapter created data/ and the db file on connect.
+    assert.ok(existsSync(join(appRoot, 'data', 'site.sqlite')));
+
+    const client = await dbConnect(uri);
+    try {
+      const names = (await client.db().listCollections().toArray())
+        .map(c => c.name);
+      assert.ok(names.includes('articles'), 'articles collection present');
+      const docs = await client.db().collection('articles').find({}).toArray();
+      assert.equal(docs.length, 2);
+      assert.deepEqual(docs.map(d => d.title).sort(), [ 'Hello', 'World' ]);
+    } finally {
+      await client.close();
+    }
+  });
+
+  it('dropDatabase clears collections (empty read-back)', async function () {
+    await restore(uri, DUMP);
+    await dropDatabase(uri);
+
+    const client = await dbConnect(uri);
+    try {
+      const names = await client.db().listCollections().toArray();
+      assert.equal(names.length, 0, 'no collections after drop');
+    } finally {
+      await client.close();
+    }
+  });
+
+  it('clearDatabase empties documents (privilege-safe deleteMany)', async function () {
+    await restore(uri, DUMP);
+    await clearDatabase(uri);
+
+    const client = await dbConnect(uri);
+    try {
+      const docs = await client.db().collection('articles').find({}).toArray();
+      assert.equal(docs.length, 0, 'documents removed by clearDatabase');
+    } finally {
+      await client.close();
+    }
+  });
+
+  it('clearDatabase on a fresh sqlite is a no-op (no throw)', async function () {
+    await clearDatabase(uri);
+    const res = await inspect(uri);
+    assert.equal(res.empty, true);
+  });
+
+  it('inspect reports a fresh sqlite as reachable + empty', async function () {
+    const res = await inspect(uri);
+    assert.deepEqual(res, {
+      reachable: true,
+      empty: true,
+      collectionCount: 0
+    });
+  });
+
+  it('inspect reports a populated sqlite as reachable + non-empty', async function () {
+    await restore(uri, DUMP);
+    const res = await inspect(uri);
+    assert.deepEqual(res, {
+      reachable: true,
+      empty: false,
+      collectionCount: 1
+    });
+  });
+});
+
+describe('core/db — inspect (mongodb/postgres via injected connect)', function () {
+  it('reachable + empty when listCollections returns nothing', async function () {
+    const { client, calls } = makeClient([]);
+    const { connect, seen } = stubConnect({ client });
+    const res = await inspect('mongodb://h/db', { connect });
+    assert.deepEqual(res, {
+      reachable: true,
+      empty: true,
+      collectionCount: 0
+    });
+    assert.equal(calls.closed, true, 'client closed');
+    // mongo gets a server-selection timeout.
+    assert.ok('serverSelectionTimeoutMS' in seen.opts);
+  });
+
+  it('reachable + non-empty reports the collection count', async function () {
+    const { client } = makeClient([ { name: 'a' }, { name: 'b' }, { name: 'c' } ]);
+    const { connect } = stubConnect({ client });
+    const res = await inspect('mongodb://h/db', { connect });
+    assert.deepEqual(res, {
+      reachable: true,
+      empty: false,
+      collectionCount: 3
+    });
+  });
+
+  it('postgres gets a connection timeout option', async function () {
+    const { client } = makeClient([]);
+    const { connect, seen } = stubConnect({ client });
+    await inspect('postgres://h/db', {
+      connect,
+      timeoutMs: 1234
+    });
+    assert.deepEqual(seen.opts, { connectionTimeoutMillis: 1234 });
+  });
+
+  it('classifies ECONNREFUSED as unreachable', async function () {
+    const err = Object.assign(new Error('connect ECONNREFUSED'), { code: 'ECONNREFUSED' });
+    const { connect } = stubConnect({ error: err });
+    const res = await inspect('mongodb://h/db', { connect });
+    assert.equal(res.reachable, false);
+    assert.equal(res.reason, 'unreachable');
+    assert.equal(res.message, 'connect ECONNREFUSED');
+  });
+
+  it('classifies mongo AuthenticationFailed as auth', async function () {
+    const err = Object.assign(new Error('Authentication failed.'), {
+      code: 18,
+      codeName: 'AuthenticationFailed'
+    });
+    const { connect } = stubConnect({ error: err });
+    const res = await inspect('mongodb://h/db', { connect });
+    assert.equal(res.reason, 'auth');
+  });
+
+  it('classifies postgres 28P01 as auth', async function () {
+    const err = Object.assign(new Error('password authentication failed'), { code: '28P01' });
+    const { connect } = stubConnect({ error: err });
+    const res = await inspect('postgres://h/db', { connect });
+    assert.equal(res.reason, 'auth');
+  });
+
+  it('classifies an unknown error as unknown and preserves the message', async function () {
+    const { connect } = stubConnect({ error: new Error('something odd') });
+    const res = await inspect('mongodb://h/db', { connect });
+    assert.equal(res.reason, 'unknown');
+    assert.equal(res.message, 'something odd');
+  });
+});
+
+describe('core/db — checkConnection', function () {
+  it('reachable: returns only { reachable: true }', async function () {
+    const { client } = makeClient([ { name: 'x' } ]);
+    const { connect } = stubConnect({ client });
+    const res = await checkConnection('mongodb://h/db', { connect });
+    assert.deepEqual(res, { reachable: true });
+  });
+
+  it('unreachable: surfaces reason + message', async function () {
+    const err = Object.assign(new Error('boom'), { code: 'ECONNREFUSED' });
+    const { connect } = stubConnect({ error: err });
+    const res = await checkConnection('mongodb://h/db', { connect });
+    assert.deepEqual(res, {
+      reachable: false,
+      reason: 'unreachable',
+      message: 'boom'
+    });
+  });
+});
+
+describe('core/db — dropDatabase (via injected connect)', function () {
+  it('drops the database and closes the client', async function () {
+    const { client, calls } = makeClient([ { name: 'x' } ]);
+    const { connect } = stubConnect({ client });
+    await dropDatabase('mongodb://h/db', { connect });
+    assert.equal(calls.dropped, true);
+    assert.equal(calls.closed, true);
+  });
+});
+
+describe('core/db — clearDatabase (via injected connect)', function () {
+  it('deleteMany on each collection, skips system.*, closes', async function () {
+    const { client, calls } = makeClient([
+      { name: 'aposDocs' },
+      { name: 'aposUsersSafe' },
+      { name: 'system.indexes' }
+    ]);
+    const { connect } = stubConnect({ client });
+    await clearDatabase('mongodb://h/db', { connect });
+    assert.deepEqual(calls.cleared, [ 'aposDocs', 'aposUsersSafe' ]);
+    assert.equal(calls.dropped, false, 'does not drop the database');
+    assert.equal(calls.closed, true);
+  });
+
+  it('no collections → no writes, still closes', async function () {
+    const { client, calls } = makeClient([]);
+    const { connect } = stubConnect({ client });
+    await clearDatabase('mongodb://h/db', { connect });
+    assert.deepEqual(calls.cleared, []);
+    assert.equal(calls.closed, true);
+  });
+});
+
+describe('core/db — restore (via injected impl)', function () {
+  it('delegates to db-connect restore with (uri, source) for non-sqlite', async function () {
+    const seen = {};
+    const restoreImpl = async (uri, source) => {
+      seen.uri = uri;
+      seen.source = source;
+    };
+    await restore('mongodb://h/db', 'the-source', { restore: restoreImpl });
+    assert.equal(seen.uri, 'mongodb://h/db');
+    assert.equal(seen.source, 'the-source');
+  });
+});
diff --git a/packages/create-apostrophe/test/core/env-file.test.js b/packages/create-apostrophe/test/core/env-file.test.js
new file mode 100644
index 0000000000..ba56d15239
--- /dev/null
+++ b/packages/create-apostrophe/test/core/env-file.test.js
@@ -0,0 +1,71 @@
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { writeIfAbsent, upsertEnv } from '../../src/core/env-file.js';
+
+describe('core/env-file', function () {
+  let dir;
+  let env;
+
+  beforeEach(function () {
+    dir = mkdtempSync(join(tmpdir(), 'ca-env-'));
+    env = join(dir, '.env');
+  });
+
+  afterEach(function () {
+    rmSync(dir, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('writeIfAbsent writes when absent, refuses to clobber', function () {
+    assert.equal(writeIfAbsent(env, 'A=1\n'), true);
+    assert.equal(readFileSync(env, 'utf8'), 'A=1\n');
+    assert.equal(writeIfAbsent(env, 'B=2\n'), false);
+    assert.equal(readFileSync(env, 'utf8'), 'A=1\n');
+  });
+
+  it('upsertEnv replaces an existing/empty key in place, appends new ones', function () {
+    writeFileSync(env, 'A=\nB=keep\n');
+    upsertEnv(env, {
+      A: 'filled',
+      C: 'added'
+    });
+    assert.equal(readFileSync(env, 'utf8'), 'A=filled\nB=keep\nC=added\n');
+  });
+
+  it('upsertEnv quotes values needing it, leaves hex bare', function () {
+    upsertEnv(env, {
+      HEX: 'deadbeef',
+      URI: 'postgres://u:p@h:5432/db?x=1 2',
+      HASH: 'a#b'
+    });
+    const out = readFileSync(env, 'utf8');
+    assert.match(out, /^HEX=deadbeef$/m);
+    assert.match(out, /^URI="postgres:\/\/u:p@h:5432\/db\?x=1 2"$/m);
+    assert.match(out, /^HASH="a#b"$/m);
+  });
+
+  it('upsertEnv on a missing file creates it with a trailing newline', function () {
+    assert.equal(existsSync(env), false);
+    upsertEnv(env, { A: '1' });
+    assert.equal(readFileSync(env, 'utf8'), 'A=1\n');
+  });
+
+  it('upsertEnv refuses control chars in a value (no smuggled lines)', function () {
+    // Without the guard, a newline inside a quoted value would smuggle an
+    // extra KEY=value line into .env (`URI="x\nINJECTED=y"` → parsers that
+    // don't honour multiline quoting see two entries).
+    for (const evil of [ 'x\nINJECTED=y', 'x\rINJECTED=y', 'x\x00y' ]) {
+      assert.throws(
+        () => upsertEnv(env, { URI: evil }),
+        TypeError,
+        `expected TypeError for ${JSON.stringify(evil)}`
+      );
+    }
+  });
+});
diff --git a/packages/create-apostrophe/test/core/env-templates.test.js b/packages/create-apostrophe/test/core/env-templates.test.js
new file mode 100644
index 0000000000..69653e62fa
--- /dev/null
+++ b/packages/create-apostrophe/test/core/env-templates.test.js
@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict';
+import {
+  standaloneEnv, externalBackendEnv, externalFrontendEnv, SECRET_KEYS
+} from '../../src/core/env-templates.js';
+
+describe('core/env-templates', function () {
+  it('SECRET_KEYS is the frozen provisional set', function () {
+    assert.deepEqual([ ...SECRET_KEYS ], [
+      'APOS_SESSION_SECRET',
+      'APOS_UPLOADFS_DISABLED_FILE_KEY'
+    ]);
+  });
+
+  it('standalone template has empty secret slots, no front key', function () {
+    const t = standaloneEnv();
+    for (const k of SECRET_KEYS) {
+      assert.match(t, new RegExp(`^${k}=$`, 'm'), `${k} slot present and empty`);
+    }
+    assert.match(t, /gitignored/);
+    assert.doesNotMatch(t, /APOS_EXTERNAL_FRONT_KEY/);
+  });
+
+  it('externalBackendEnv(name) adds dev keys + secret slots, labels by name', function () {
+    const t = externalBackendEnv('astro');
+    assert.match(t, /^APOS_EXTERNAL_FRONT_KEY=dev$/m);
+    assert.match(t, /^APOS_DEV=1$/m);
+    assert.match(t, /Astro backend/); // name titled into the header
+    for (const k of SECRET_KEYS) {
+      assert.match(t, new RegExp(`^${k}=$`, 'm'));
+    }
+  });
+
+  it('externalFrontendEnv(name) is just the matching front key, no secrets', function () {
+    const t = externalFrontendEnv('astro');
+    assert.match(t, /^APOS_EXTERNAL_FRONT_KEY=dev$/m);
+    assert.match(t, /Astro frontend/);
+    for (const k of SECRET_KEYS) {
+      assert.doesNotMatch(t, new RegExp(k));
+    }
+  });
+
+  it('templates are frontend-name parametrized (works for a future name)', function () {
+    assert.match(externalBackendEnv('nextjs'), /Nextjs backend/);
+    assert.match(externalFrontendEnv('nextjs'), /Nextjs frontend/);
+  });
+});
diff --git a/packages/create-apostrophe/test/core/install.test.js b/packages/create-apostrophe/test/core/install.test.js
new file mode 100644
index 0000000000..7204634ab6
--- /dev/null
+++ b/packages/create-apostrophe/test/core/install.test.js
@@ -0,0 +1,196 @@
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, rmSync, mkdirSync, writeFileSync, existsSync
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { install } from '../../src/core/steps/install.js';
+import { StageError, UnsupportedPackageManagerError } from '../../src/core/errors.js';
+
+function fakeRunFactory(calls, { code = 0, error = null } = {}) {
+  return async (command, args, opts) => {
+    calls.push({
+      command,
+      args,
+      cwd: opts.cwd
+    });
+    if (!error && code === 0) {
+      mkdirSync(join(opts.cwd, 'node_modules', 'apostrophe'), { recursive: true });
+    }
+    return {
+      code,
+      stdout: '',
+      stderr: '',
+      error
+    };
+  };
+}
+
+describe('core/steps/install', function () {
+  let dir;
+
+  beforeEach(function () {
+    dir = mkdtempSync(join(tmpdir(), 'ca-install-'));
+  });
+
+  afterEach(function () {
+    rmSync(dir, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('standalone: one npm install in appRoot, lockfile preserved', async function () {
+    const projectDir = join(dir, 'proj');
+    mkdirSync(projectDir, { recursive: true });
+    writeFileSync(join(projectDir, 'package-lock.json'), '{}');
+
+    const calls = [];
+    const res = await install(
+      {
+        projectDir,
+        appRoot: projectDir,
+        packageManager: 'npm'
+      },
+      { run: fakeRunFactory(calls) }
+    );
+
+    assert.deepEqual(res, { packageManager: 'npm' });
+    assert.deepEqual(calls, [ {
+      command: 'npm',
+      args: [ 'install' ],
+      cwd: projectDir
+    } ]);
+    // Lockfile is no longer purged.
+    assert.equal(existsSync(join(projectDir, 'package-lock.json')), true);
+  });
+
+  it('external frontend: npm install in backend/ then frontend/', async function () {
+    const projectDir = join(dir, 'proj');
+    const appRoot = join(projectDir, 'backend');
+    mkdirSync(appRoot, { recursive: true });
+    mkdirSync(join(projectDir, 'frontend'), { recursive: true });
+
+    const calls = [];
+    await install(
+      {
+        projectDir,
+        appRoot,
+        frontend: 'astro',
+        packageManager: 'npm'
+      },
+      { run: fakeRunFactory(calls) }
+    );
+
+    assert.deepEqual(calls.map((c) => [ c.command, c.cwd ]), [
+      [ 'npm', appRoot ],
+      [ 'npm', join(projectDir, 'frontend') ]
+    ]);
+  });
+
+  it('unknown pm runs npm, reports \'unknown\'', async function () {
+    const projectDir = join(dir, 'proj');
+    mkdirSync(projectDir, { recursive: true });
+    const calls = [];
+    const res = await install(
+      {
+        projectDir,
+        appRoot: projectDir,
+        packageManager: 'unknown'
+      },
+      { run: fakeRunFactory(calls) }
+    );
+    assert.equal(calls[0].command, 'npm');
+    assert.equal(res.packageManager, 'unknown');
+  });
+
+  it('rejects pnpm/yarn before any work, without spawning', async function () {
+    const projectDir = join(dir, 'proj');
+    mkdirSync(projectDir, { recursive: true });
+    for (const pm of [ 'pnpm', 'yarn' ]) {
+      let spawned = false;
+      await assert.rejects(
+        () => install(
+          {
+            projectDir,
+            appRoot: projectDir,
+            packageManager: pm
+          },
+          {
+            run: async () => {
+              spawned = true; return { code: 0 };
+            }
+          }
+        ),
+        (err) => {
+          assert.ok(err instanceof UnsupportedPackageManagerError);
+          assert.equal(err.packageManager, pm);
+          return true;
+        }
+      );
+      assert.equal(spawned, false);
+    }
+  });
+
+  it('npm missing → StageError(dependency_install, npm_missing)', async function () {
+    const projectDir = join(dir, 'proj');
+    mkdirSync(projectDir, { recursive: true });
+    const run = async () => ({
+      code: null,
+      error: Object.assign(new Error('spawn ENOENT'), { code: 'ENOENT' })
+    });
+    await assert.rejects(
+      () => install({
+        projectDir,
+        appRoot: projectDir,
+        packageManager: 'npm'
+      }, { run }),
+      (err) => {
+        assert.ok(err instanceof StageError);
+        assert.equal(err.stage, 'dependency_install');
+        assert.equal(err.errorCode, 'npm_missing');
+        return true;
+      }
+    );
+  });
+
+  it('non-zero exit → StageError(dependency_install, install_failed)', async function () {
+    const projectDir = join(dir, 'proj');
+    mkdirSync(projectDir, { recursive: true });
+    await assert.rejects(
+      () => install(
+        {
+          projectDir,
+          appRoot: projectDir,
+          packageManager: 'npm'
+        },
+        { run: fakeRunFactory([], { code: 1 }) }
+      ),
+      (err) => {
+        assert.equal(err.errorCode, 'install_failed');
+        return true;
+      }
+    );
+  });
+
+  it('apostrophe absent after install → apostrophe_missing', async function () {
+    const projectDir = join(dir, 'proj');
+    mkdirSync(projectDir, { recursive: true });
+    const run = async () => ({
+      code: 0,
+      error: null
+    });
+    await assert.rejects(
+      () => install({
+        projectDir,
+        appRoot: projectDir,
+        packageManager: 'npm'
+      }, { run }),
+      (err) => {
+        assert.equal(err.stage, 'dependency_install');
+        assert.equal(err.errorCode, 'apostrophe_missing');
+        return true;
+      }
+    );
+  });
+});
diff --git a/packages/create-apostrophe/test/core/kits.test.js b/packages/create-apostrophe/test/core/kits.test.js
new file mode 100644
index 0000000000..b59f1e67aa
--- /dev/null
+++ b/packages/create-apostrophe/test/core/kits.test.js
@@ -0,0 +1,117 @@
+import assert from 'node:assert/strict';
+import {
+  KITS, KIT_IDS, isKnownKit, getKit, deriveKitId
+} from '../../src/core/kits.js';
+
+describe('core/kits', function () {
+  it('registry holds exactly the six contract KitIds', function () {
+    assert.deepEqual([ ...KIT_IDS ].sort(), [
+      'apostrophe-astro-demo',
+      'apostrophe-astro-demo-data',
+      'apostrophe-astro-essentials',
+      'apostrophe-demo',
+      'apostrophe-demo-data',
+      'apostrophe-essentials'
+    ]);
+  });
+
+  it('every entry has a clone URL, label, and consistent flags', function () {
+    for (const [ id, kit ] of Object.entries(KITS)) {
+      assert.match(kit.repo, /^https:\/\/github\.com\/.+\.git$/, id);
+      assert.equal(typeof kit.label, 'string');
+      assert.ok(kit.label.length > 0, id);
+      assert.equal(
+        kit.frontend,
+        id.startsWith('apostrophe-astro-') ? 'astro' : null,
+        id
+      );
+      assert.equal(kit.seedData, id.endsWith('-demo-data'), id);
+    }
+  });
+
+  it('demo and demo-data share one repo per build (data applied post-clone)', function () {
+    assert.equal(
+      KITS['apostrophe-demo'].repo,
+      KITS['apostrophe-demo-data'].repo
+    );
+    assert.equal(
+      KITS['apostrophe-astro-demo'].repo,
+      KITS['apostrophe-astro-demo-data'].repo
+    );
+    // essentials is a distinct repo from demo.
+    assert.notEqual(
+      KITS['apostrophe-essentials'].repo,
+      KITS['apostrophe-demo'].repo
+    );
+  });
+
+  it('getKit / isKnownKit resolve known ids and reject unknown', function () {
+    assert.equal(isKnownKit('apostrophe-demo'), true);
+    assert.equal(isKnownKit('nope'), false);
+    assert.equal(getKit('apostrophe-essentials'), KITS['apostrophe-essentials']);
+    assert.throws(() => getKit('nope'), TypeError);
+  });
+
+  it('deriveKitId covers the full D6 matrix', function () {
+    const cases = [
+      [ {
+        build: 'astro',
+        startingPoint: 'essentials'
+      }, 'apostrophe-astro-essentials' ],
+      [ {
+        build: 'astro',
+        startingPoint: 'demo',
+        sampleContent: false
+      }, 'apostrophe-astro-demo' ],
+      [ {
+        build: 'astro',
+        startingPoint: 'demo',
+        sampleContent: true
+      }, 'apostrophe-astro-demo-data' ],
+      [ {
+        build: 'standalone',
+        startingPoint: 'essentials'
+      }, 'apostrophe-essentials' ],
+      [ {
+        build: 'standalone',
+        startingPoint: 'demo',
+        sampleContent: false
+      }, 'apostrophe-demo' ],
+      [ {
+        build: 'standalone',
+        startingPoint: 'demo',
+        sampleContent: true
+      }, 'apostrophe-demo-data' ]
+    ];
+    for (const [ input, expected ] of cases) {
+      const id = deriveKitId(input);
+      assert.equal(id, expected);
+      assert.ok(isKnownKit(id), `derived ${id} must be in the registry`);
+    }
+  });
+
+  it('deriveKitId ignores sampleContent for essentials', function () {
+    assert.equal(
+      deriveKitId({
+        build: 'standalone',
+        startingPoint: 'essentials',
+        sampleContent: true
+      }),
+      'apostrophe-essentials'
+    );
+  });
+
+  it('deriveKitId rejects unknown build / startingPoint', function () {
+    assert.throws(() => deriveKitId({
+      build: 'x',
+      startingPoint: 'demo'
+    }), TypeError);
+    assert.throws(
+      () => deriveKitId({
+        build: 'astro',
+        startingPoint: 'x'
+      }),
+      TypeError
+    );
+  });
+});
diff --git a/packages/create-apostrophe/test/core/pm.test.js b/packages/create-apostrophe/test/core/pm.test.js
new file mode 100644
index 0000000000..c7a09f0794
--- /dev/null
+++ b/packages/create-apostrophe/test/core/pm.test.js
@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+import {
+  detectPackageManager,
+  assertSupportedPackageManager,
+  SUPPORTED_PACKAGE_MANAGERS
+} from '../../src/core/pm.js';
+import { UnsupportedPackageManagerError } from '../../src/core/errors.js';
+
+describe('core/pm', function () {
+  it('detects the manager from the user-agent first token', function () {
+    assert.equal(detectPackageManager('npm/9.8.1 node/v20.5.0 linux x64'), 'npm');
+    assert.equal(detectPackageManager('pnpm/8.6.0 npm/? node/v20'), 'pnpm');
+    assert.equal(detectPackageManager('yarn/1.22.19 npm/? node/v20'), 'yarn');
+  });
+
+  it('is unknown for empty / unrecognized agents', function () {
+    assert.equal(detectPackageManager(''), 'unknown');
+    assert.equal(detectPackageManager('bun/1.0.0 node/v20'), 'unknown');
+  });
+
+  it('assertSupportedPackageManager: npm/unknown pass, others throw', function () {
+    assert.equal(assertSupportedPackageManager('npm'), 'npm');
+    assert.equal(assertSupportedPackageManager('unknown'), 'unknown');
+    for (const pm of [ 'pnpm', 'yarn', 'bun' ]) {
+      assert.throws(
+        () => assertSupportedPackageManager(pm),
+        (err) => {
+          assert.ok(err instanceof UnsupportedPackageManagerError);
+          assert.equal(err.packageManager, pm);
+          // error carries the single-source list, no hardcoded copy
+          assert.equal(err.supported, SUPPORTED_PACKAGE_MANAGERS);
+          assert.equal(err.errorCode, 'unsupported_pm');
+          assert.doesNotMatch(err.message, /npm only|supports/);
+          return true;
+        }
+      );
+    }
+  });
+
+  it('with no arg, reads npm_config_user_agent', function () {
+    const saved = process.env.npm_config_user_agent;
+    try {
+      process.env.npm_config_user_agent = 'yarn/3.0.0 node/v20';
+      assert.equal(detectPackageManager(), 'yarn');
+      delete process.env.npm_config_user_agent;
+      assert.equal(detectPackageManager(), 'unknown');
+    } finally {
+      if (saved === undefined) {
+        delete process.env.npm_config_user_agent;
+      } else {
+        process.env.npm_config_user_agent = saved;
+      }
+    }
+  });
+});
diff --git a/packages/create-apostrophe/test/core/sample-data.test.js b/packages/create-apostrophe/test/core/sample-data.test.js
new file mode 100644
index 0000000000..eb5cebd81f
--- /dev/null
+++ b/packages/create-apostrophe/test/core/sample-data.test.js
@@ -0,0 +1,540 @@
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, rmSync, mkdirSync, writeFileSync, existsSync
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import crypto from 'node:crypto';
+import { Readable } from 'node:stream';
+import dbConnect from '@apostrophecms/db-connect';
+import {
+  importSampleData, resolveAssets, DEFAULT_ASSETS
+} from '../../src/core/steps/sample-data.js';
+import { StageError } from '../../src/core/errors.js';
+
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+
+// A fetch stub that serves fixed bytes (or simulates a network/HTTP failure).
+function stubFetch(bytes, {
+  ok = true, status = 200, throws = false
+} = {}) {
+  return async () => {
+    if (throws) {
+      throw new Error('ENOTFOUND static.apostrophecms.com');
+    }
+    return {
+      ok,
+      status,
+      headers: {
+        get: (k) => (k.toLowerCase() === 'content-length' ? String(bytes.length) : null)
+      },
+      body: Readable.from([ Buffer.from(bytes) ])
+    };
+  };
+}
+
+function writeManifest(appRoot, obj) {
+  mkdirSync(join(appRoot, '.apostrophe'), { recursive: true });
+  writeFileSync(
+    join(appRoot, '.apostrophe', 'sample-data.json'),
+    typeof obj === 'string' ? obj : JSON.stringify(obj)
+  );
+}
+
+describe('core/steps/sample-data — resolveAssets', function () {
+  let appRoot;
+  beforeEach(function () {
+    appRoot = mkdtempSync(join(tmpdir(), 'ca-seed-'));
+  });
+  afterEach(function () {
+    rmSync(appRoot, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('no manifest → embedded DEFAULT_ASSETS (both)', function () {
+    assert.deepEqual(resolveAssets(appRoot), { ...DEFAULT_ASSETS });
+  });
+
+  it('manifest wholesale-replaces; each asset optional (db only)', function () {
+    const db = {
+      url: 'https://x/db.zip',
+      sha256: 'a'.repeat(64)
+    };
+    writeManifest(appRoot, { db });
+    assert.deepEqual(resolveAssets(appRoot), { db });
+  });
+
+  it('manifest with both assets', function () {
+    const m = {
+      db: {
+        url: 'https://x/db.zip',
+        sha256: 'a'.repeat(64)
+      },
+      uploads: {
+        url: 'https://x/up.zip',
+        sha256: 'b'.repeat(64)
+      }
+    };
+    writeManifest(appRoot, m);
+    assert.deepEqual(resolveAssets(appRoot), m);
+  });
+
+  /** @type {Array<[string, any]>} */
+  const invalidCases = [
+    [ 'unparseable JSON', '{ not json' ],
+    [ 'not an object', '"a string"' ],
+    [ 'an array', '[]' ],
+    [ 'declares neither asset', {} ],
+    [ 'declares neither asset (unknown keys)', { foo: 1 } ],
+    [ 'bad sha length', {
+      db: {
+        url: 'https://x/db.zip',
+        sha256: 'abc'
+      }
+    } ],
+    [ 'uppercase sha', {
+      db: {
+        url: 'https://x/db.zip',
+        sha256: 'A'.repeat(64)
+      }
+    } ],
+    [ 'non-https url', {
+      db: {
+        url: 'http://x/db.zip',
+        sha256: 'a'.repeat(64)
+      }
+    } ],
+    [ 'missing sha', { db: { url: 'https://x/db.zip' } } ]
+  ];
+  for (const [ label, body ] of invalidCases) {
+    it(`seed_manifest_invalid: ${label}`, function () {
+      writeManifest(appRoot, body);
+      assert.throws(
+        () => resolveAssets(appRoot),
+        (err) => err instanceof StageError &&
+          err.stage === 'sample_data' &&
+          err.errorCode === 'seed_manifest_invalid'
+      );
+    });
+  }
+});
+
+describe('core/steps/sample-data — download + checksum', function () {
+  let appRoot;
+  const DB_BYTES = Buffer.from('pretend-zip-bytes');
+  const dbManifest = (sha) => ({
+    db: {
+      url: 'https://x/db.zip',
+      sha256: sha
+    }
+  });
+
+  // Inject no-op DB ops so these tests isolate the download/verify stage.
+  const noopDbDeps = {
+    resolveDbUri: () => 'sqlite:///tmp/x.sqlite',
+    restore: async () => {},
+    clearDatabase: async () => {},
+    unpackDbStream: async () => Readable.from('')
+  };
+
+  beforeEach(function () {
+    appRoot = mkdtempSync(join(tmpdir(), 'ca-seed-'));
+  });
+  afterEach(function () {
+    rmSync(appRoot, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('matching sha256 passes verification', async function () {
+    writeManifest(appRoot, dbManifest(sha256(DB_BYTES)));
+    await importSampleData(
+      {
+        appRoot,
+        dbChoice: 'sqlite',
+        shortName: 'site'
+      },
+      {
+        ...noopDbDeps,
+        fetchImpl: stubFetch(DB_BYTES)
+      }
+    );
+    // No throw == verified.
+  });
+
+  it('mismatched sha256 → seed_checksum_failed (before any DB write)', async function () {
+    writeManifest(appRoot, dbManifest('f'.repeat(64)));
+    let restored = false;
+    let cleared = false;
+    await assert.rejects(
+      () => importSampleData(
+        {
+          appRoot,
+          dbChoice: 'sqlite',
+          shortName: 'site'
+        },
+        {
+          ...noopDbDeps,
+          clearDatabase: async () => {
+            cleared = true;
+          },
+          restore: async () => {
+            restored = true;
+          },
+          fetchImpl: stubFetch(DB_BYTES)
+        }
+      ),
+      (err) => err instanceof StageError && err.errorCode === 'seed_checksum_failed'
+    );
+    assert.equal(cleared, false, 'must not wipe the DB when the checksum fails');
+    assert.equal(restored, false, 'must not write to the DB when the checksum fails');
+  });
+
+  it('non-2xx response → seed_download_failed', async function () {
+    writeManifest(appRoot, dbManifest(sha256(DB_BYTES)));
+    await assert.rejects(
+      () => importSampleData(
+        {
+          appRoot,
+          dbChoice: 'sqlite',
+          shortName: 'site'
+        },
+        {
+          ...noopDbDeps,
+          fetchImpl: stubFetch(DB_BYTES, {
+            ok: false,
+            status: 404
+          })
+        }
+      ),
+      (err) => err instanceof StageError && err.errorCode === 'seed_download_failed'
+    );
+  });
+
+  it('network error → seed_download_failed', async function () {
+    writeManifest(appRoot, dbManifest(sha256(DB_BYTES)));
+    await assert.rejects(
+      () => importSampleData(
+        {
+          appRoot,
+          dbChoice: 'sqlite',
+          shortName: 'site'
+        },
+        {
+          ...noopDbDeps,
+          fetchImpl: stubFetch(DB_BYTES, { throws: true })
+        }
+      ),
+      (err) => err instanceof StageError && err.errorCode === 'seed_download_failed'
+    );
+  });
+});
+
+describe('core/steps/sample-data — error mapping (stubbed unpack/restore/uploads)', function () {
+  let appRoot;
+  const BYTES = Buffer.from('zip');
+
+  beforeEach(function () {
+    appRoot = mkdtempSync(join(tmpdir(), 'ca-seed-'));
+  });
+  afterEach(function () {
+    rmSync(appRoot, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  function deps(over = {}) {
+    return {
+      fetchImpl: stubFetch(BYTES),
+      resolveDbUri: () => 'sqlite:///tmp/x.sqlite',
+      restore: async () => {},
+      clearDatabase: async () => {},
+      unpackDbStream: async () => Readable.from('{"_collection":"x","_indexes":[]}\n'),
+      extractAttachments: async () => {},
+      ...over
+    };
+  }
+
+  it('unpack failure → seed_unpack_failed', async function () {
+    writeManifest(appRoot, {
+      db: {
+        url: 'https://x/db.zip',
+        sha256: sha256(BYTES)
+      }
+    });
+    await assert.rejects(
+      () => importSampleData({
+        appRoot,
+        dbChoice: 'sqlite',
+        shortName: 'site'
+      }, deps({
+        unpackDbStream: async () => {
+          throw new Error('garbled zip');
+        }
+      })),
+      (err) => err instanceof StageError && err.errorCode === 'seed_unpack_failed'
+    );
+  });
+
+  it('clear failure → seed_clear_failed', async function () {
+    writeManifest(appRoot, {
+      db: {
+        url: 'https://x/db.zip',
+        sha256: sha256(BYTES)
+      }
+    });
+    await assert.rejects(
+      () => importSampleData({
+        appRoot,
+        dbChoice: 'sqlite',
+        shortName: 'site'
+      }, deps({
+        clearDatabase: async () => {
+          throw new Error('clear boom');
+        }
+      })),
+      (err) => err instanceof StageError && err.errorCode === 'seed_clear_failed'
+    );
+  });
+
+  it('restore failure → seed_restore_failed', async function () {
+    writeManifest(appRoot, {
+      db: {
+        url: 'https://x/db.zip',
+        sha256: sha256(BYTES)
+      }
+    });
+    await assert.rejects(
+      () => importSampleData({
+        appRoot,
+        dbChoice: 'sqlite',
+        shortName: 'site'
+      }, deps({
+        restore: async () => {
+          throw new Error('restore boom');
+        }
+      })),
+      (err) => err instanceof StageError && err.errorCode === 'seed_restore_failed'
+    );
+  });
+
+  it('uploads failure → seed_uploads_failed', async function () {
+    writeManifest(appRoot, {
+      uploads: {
+        url: 'https://x/up.zip',
+        sha256: sha256(BYTES)
+      }
+    });
+    await assert.rejects(
+      () => importSampleData({
+        appRoot,
+        dbChoice: 'sqlite',
+        shortName: 'site'
+      }, deps({
+        extractAttachments: async () => {
+          throw new Error('extract boom');
+        }
+      })),
+      (err) => err instanceof StageError && err.errorCode === 'seed_uploads_failed'
+    );
+  });
+
+  it('wipes the target (clearDatabase) before restoring, same uri', async function () {
+    writeManifest(appRoot, {
+      db: {
+        url: 'https://x/db.zip',
+        sha256: sha256(BYTES)
+      }
+    });
+    const order = [];
+    let clearedUri;
+    let restoredUri;
+    await importSampleData({
+      appRoot,
+      dbChoice: 'sqlite',
+      shortName: 'site'
+    }, deps({
+      resolveDbUri: () => 'sqlite:///tmp/site.sqlite',
+      clearDatabase: async (uri) => {
+        order.push('clear');
+        clearedUri = uri;
+      },
+      restore: async (uri) => {
+        order.push('restore');
+        restoredUri = uri;
+      }
+    }));
+    assert.deepEqual(order, [ 'clear', 'restore' ], 'wipe runs before restore');
+    assert.equal(clearedUri, 'sqlite:///tmp/site.sqlite');
+    assert.equal(restoredUri, 'sqlite:///tmp/site.sqlite');
+  });
+
+  it('uploads target is <appRoot>/public/uploads (with the downloaded file)', async function () {
+    writeManifest(appRoot, {
+      uploads: {
+        url: 'https://x/up.zip',
+        sha256: sha256(BYTES)
+      }
+    });
+    let seenRoot;
+    let seenZip;
+    await importSampleData({
+      appRoot,
+      dbChoice: 'sqlite',
+      shortName: 'site'
+    }, deps({
+      extractAttachments: async (zipPath, uploadsRoot) => {
+        seenZip = zipPath;
+        seenRoot = uploadsRoot;
+      }
+    }));
+    assert.equal(seenRoot, join(appRoot, 'public', 'uploads'));
+    assert.match(seenZip, /uploads\.zip$/);
+  });
+});
+
+describe('core/steps/sample-data — task labels per manifest shape', function () {
+  let appRoot;
+  const BYTES = Buffer.from('zip');
+
+  // A task factory that records the labels in creation order; each handle is
+  // a no-op (succeed/fail/progress).
+  function recordingTasks() {
+    const labels = [];
+    const task = (label) => {
+      labels.push(label);
+      return {
+        succeed() {},
+        fail() {},
+        progress() {}
+      };
+    };
+    return {
+      task,
+      labels
+    };
+  }
+
+  function deps(over = {}) {
+    return {
+      fetchImpl: stubFetch(BYTES),
+      resolveDbUri: () => 'sqlite:///tmp/x.sqlite',
+      restore: async () => {},
+      clearDatabase: async () => {},
+      unpackDbStream: async () => Readable.from('{"_collection":"x","_indexes":[]}\n'),
+      extractAttachments: async () => {},
+      ...over
+    };
+  }
+
+  const dbAsset = {
+    url: 'https://x/db.zip',
+    sha256: sha256(BYTES)
+  };
+  const uploadsAsset = {
+    url: 'https://x/up.zip',
+    sha256: sha256(BYTES)
+  };
+
+  beforeEach(function () {
+    appRoot = mkdtempSync(join(tmpdir(), 'ca-seed-'));
+  });
+  afterEach(function () {
+    rmSync(appRoot, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('db-only manifest → just the import task (no download task)', async function () {
+    writeManifest(appRoot, { db: dbAsset });
+    const { task, labels } = recordingTasks();
+    await importSampleData({
+      appRoot,
+      dbChoice: 'sqlite',
+      shortName: 'site'
+    }, deps({ task }));
+    assert.deepEqual(labels, [ 'Importing sample content' ]);
+  });
+
+  it('both assets → download bar then import', async function () {
+    writeManifest(appRoot, {
+      db: dbAsset,
+      uploads: uploadsAsset
+    });
+    const { task, labels } = recordingTasks();
+    await importSampleData({
+      appRoot,
+      dbChoice: 'sqlite',
+      shortName: 'site'
+    }, deps({ task }));
+    assert.deepEqual(labels, [ 'Downloading sample content', 'Importing sample content' ]);
+  });
+
+  it('uploads-only manifest → download bar then import', async function () {
+    writeManifest(appRoot, { uploads: uploadsAsset });
+    const { task, labels } = recordingTasks();
+    await importSampleData({
+      appRoot,
+      dbChoice: 'sqlite',
+      shortName: 'site'
+    }, deps({ task }));
+    assert.deepEqual(labels, [ 'Downloading sample content', 'Importing sample content' ]);
+  });
+});
+
+describe('core/steps/sample-data — db restore into a real sqlite (no network/zip)', function () {
+  let appRoot;
+  const JSONL = [
+    '{"_collection":"articles","_indexes":[]}',
+    '{"_doc":{"_id":"a1","title":"Hello"}}',
+    '{"_doc":{"_id":"a2","title":"World"}}'
+  ].join('\n');
+  const BYTES = Buffer.from('db-zip-bytes');
+
+  beforeEach(function () {
+    appRoot = mkdtempSync(join(tmpdir(), 'ca-seed-'));
+  });
+  afterEach(function () {
+    rmSync(appRoot, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('downloads (stubbed), restores via the real db module, reads back', async function () {
+    writeManifest(appRoot, {
+      db: {
+        url: 'https://x/db.zip',
+        sha256: sha256(BYTES)
+      }
+    });
+    // Real resolveDbUri/restore (default deps); only fetch and the unzip are
+    // stubbed — the latter yields the JSONL the real restore consumes.
+    await importSampleData(
+      {
+        appRoot,
+        dbChoice: 'sqlite',
+        shortName: 'site'
+      },
+      {
+        fetchImpl: stubFetch(BYTES),
+        unpackDbStream: async () => Readable.from(JSONL)
+      }
+    );
+
+    const uri = `sqlite://${resolve(appRoot, 'data', 'site.sqlite')}`;
+    assert.ok(existsSync(resolve(appRoot, 'data', 'site.sqlite')));
+    const client = await dbConnect(uri);
+    try {
+      const docs = await client.db().collection('articles').find({}).toArray();
+      assert.deepEqual(docs.map((d) => d.title).sort(), [ 'Hello', 'World' ]);
+    } finally {
+      await client.close();
+    }
+  });
+});
diff --git a/packages/create-apostrophe/test/core/scaffold.test.js b/packages/create-apostrophe/test/core/scaffold.test.js
new file mode 100644
index 0000000000..adccae38a9
--- /dev/null
+++ b/packages/create-apostrophe/test/core/scaffold.test.js
@@ -0,0 +1,211 @@
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync, existsSync
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { scaffold } from '../../src/core/steps/scaffold.js';
+import { StageError } from '../../src/core/errors.js';
+
+const APP_JS = [
+  'module.exports = {',
+  '  shortName: \'PLACEHOLDER\',',
+  '  modules: {},',
+  '  uploadfs: { disabledFileKey: undefined }',
+  '};',
+  ''
+].join('\n');
+
+const PKG_JSON = '{\n  "name": "placeholder",\n  "version": "1.0.0"\n}\n';
+
+// `external` mirrors a kit with an external frontend: app nested in backend/,
+// plus a sibling frontend/ dir (unless withFrontendDir === false).
+function makeProject(root, { external = false, withFrontendDir = external } = {}) {
+  const appRoot = external ? join(root, 'backend') : root;
+  mkdirSync(appRoot, { recursive: true });
+  writeFileSync(join(appRoot, 'app.js'), APP_JS);
+  writeFileSync(join(appRoot, 'package.json'), PKG_JSON);
+  if (external && withFrontendDir) {
+    mkdirSync(join(root, 'frontend'), { recursive: true });
+  }
+  return appRoot;
+}
+
+const read = (p) => readFileSync(p, 'utf8');
+const hex64 = (s, key) => {
+  const m = s.match(new RegExp(`^${key}=([0-9a-f]+)$`, 'm'));
+  assert.ok(m, `${key} filled`);
+  assert.equal(m[1].length, 64); // 32 bytes
+  return m[1];
+};
+
+describe('core/steps/scaffold', function () {
+  let dir;
+
+  beforeEach(function () {
+    dir = mkdtempSync(join(tmpdir(), 'ca-scaffold-'));
+  });
+
+  afterEach(function () {
+    rmSync(dir, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('standalone (frontend:null): identity replace; .env with filled secrets', function () {
+    const projectDir = join(dir, 'proj');
+    makeProject(projectDir);
+
+    const res = scaffold({
+      projectDir,
+      shortName: 'my_site-1'
+    });
+    assert.equal(res.frontend, null);
+    assert.equal(res.appRoot, projectDir);
+    assert.deepEqual(res.envFiles, [ join(projectDir, '.env') ]);
+
+    const app = read(join(projectDir, 'app.js'));
+    assert.match(app, /shortName: 'my_site-1',/);
+    assert.match(read(join(projectDir, 'package.json')), /"name": "my_site-1",/);
+    assert.match(app, /disabledFileKey: undefined/); // secret not in source
+
+    const env = read(join(projectDir, '.env'));
+    assert.notEqual(
+      hex64(env, 'APOS_SESSION_SECRET'),
+      hex64(env, 'APOS_UPLOADFS_DISABLED_FILE_KEY')
+    );
+    assert.match(env, /gitignored/);
+  });
+
+  it('lowercases the npm package name; preserves shortName casing elsewhere', function () {
+    // npm package names must be lowercase; Apostrophe's own shortName is
+    // case-tolerant and the user's chosen casing is kept in app.js + dir.
+    const projectDir = join(dir, 'proj');
+    makeProject(projectDir);
+
+    scaffold({
+      projectDir,
+      shortName: 'MyProject'
+    });
+
+    assert.match(read(join(projectDir, 'app.js')), /shortName: 'MyProject',/);
+    assert.match(read(join(projectDir, 'package.json')), /"name": "myproject",/);
+  });
+
+  it('frontend:\'astro\': backend/.env (secrets + dev keys) and frontend/.env', function () {
+    const projectDir = join(dir, 'proj');
+    const appRoot = makeProject(projectDir, { external: true });
+
+    const res = scaffold({
+      projectDir,
+      shortName: 'astro-site',
+      frontend: 'astro'
+    });
+    assert.equal(res.frontend, 'astro');
+    assert.equal(res.appRoot, appRoot);
+    assert.deepEqual(res.envFiles, [
+      join(appRoot, '.env'),
+      join(projectDir, 'frontend', '.env')
+    ]);
+
+    const backendEnv = read(join(appRoot, '.env'));
+    assert.match(backendEnv, /^APOS_EXTERNAL_FRONT_KEY=dev$/m);
+    assert.match(backendEnv, /^APOS_DEV=1$/m);
+    hex64(backendEnv, 'APOS_SESSION_SECRET');
+
+    const frontEnv = read(join(projectDir, 'frontend', '.env'));
+    assert.match(frontEnv, /^APOS_EXTERNAL_FRONT_KEY=dev$/m);
+    assert.doesNotMatch(frontEnv, /APOS_SESSION_SECRET/); // no secrets
+  });
+
+  it('frontend:\'astro\' without a frontend/ dir: backend .env only', function () {
+    const projectDir = join(dir, 'proj');
+    const appRoot = makeProject(projectDir, {
+      external: true,
+      withFrontendDir: false
+    });
+    const res = scaffold({
+      projectDir,
+      shortName: 'x',
+      frontend: 'astro'
+    });
+    assert.deepEqual(res.envFiles, [ join(appRoot, '.env') ]);
+  });
+
+  it('rejects an unsupported frontend name', function () {
+    const projectDir = join(dir, 'proj');
+    makeProject(projectDir);
+    assert.throws(
+      () => scaffold({
+        projectDir,
+        shortName: 'x',
+        frontend: 'nextjs'
+      }),
+      TypeError
+    );
+  });
+
+  it('frontend:\'astro\' but no backend/ → StageError(scaffold)', function () {
+    const projectDir = join(dir, 'proj');
+    makeProject(projectDir); // standalone layout, no backend/
+    assert.throws(
+      () => scaffold({
+        projectDir,
+        shortName: 'x',
+        frontend: 'astro'
+      }),
+      (err) => {
+        assert.ok(err instanceof StageError);
+        assert.equal(err.stage, 'scaffold');
+        assert.equal(err.errorCode, 'missing_scaffold_file');
+        return true;
+      }
+    );
+  });
+
+  it('never clobbers an existing .env, but still fills secrets', function () {
+    const projectDir = join(dir, 'proj');
+    makeProject(projectDir);
+    writeFileSync(join(projectDir, '.env'), 'KEEP=mine\n');
+
+    scaffold({
+      projectDir,
+      shortName: 'x'
+    });
+    const env = read(join(projectDir, '.env'));
+    assert.match(env, /^KEEP=mine$/m); // preserved
+    hex64(env, 'APOS_SESSION_SECRET'); // still upserted
+  });
+
+  it('throws StageError(scaffold) when app.js is missing', function () {
+    const projectDir = join(dir, 'proj');
+    mkdirSync(projectDir, { recursive: true });
+    writeFileSync(join(projectDir, 'package.json'), PKG_JSON);
+    assert.throws(
+      () => scaffold({
+        projectDir,
+        shortName: 'x'
+      }),
+      (err) => {
+        assert.equal(err.stage, 'scaffold');
+        assert.equal(err.errorCode, 'missing_scaffold_file');
+        return true;
+      }
+    );
+  });
+
+  it('rejects an unsafe shortName before touching files', function () {
+    const projectDir = join(dir, 'proj');
+    makeProject(projectDir);
+    assert.throws(
+      () => scaffold({
+        projectDir,
+        shortName: '../evil'
+      }),
+      TypeError
+    );
+    assert.match(read(join(projectDir, 'app.js')), /PLACEHOLDER/);
+    assert.equal(existsSync(join(projectDir, '.env')), false);
+  });
+});
diff --git a/packages/create-apostrophe/test/core/spawn.test.js b/packages/create-apostrophe/test/core/spawn.test.js
new file mode 100644
index 0000000000..0b9df1cd86
--- /dev/null
+++ b/packages/create-apostrophe/test/core/spawn.test.js
@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict';
+import { run } from '../../src/core/spawn.js';
+
+const node = process.execPath;
+
+describe('core/spawn', function () {
+  it('captures stdout and a zero exit code', async function () {
+    const r = await run(node, [ '-e', 'process.stdout.write("hi")' ]);
+    assert.equal(r.code, 0);
+    assert.equal(r.stdout, 'hi');
+    assert.equal(r.error, null);
+  });
+
+  it('reports a non-zero exit code without throwing', async function () {
+    const r = await run(node, [ '-e', 'process.exit(3)' ]);
+    assert.equal(r.code, 3);
+    assert.equal(r.error, null);
+  });
+
+  it('returns an ENOENT error (not a throw) for a missing binary', async function () {
+    const r = await run('definitely-not-a-real-binary-xyz', [ 'arg' ]);
+    assert.equal(r.code, null);
+    assert.equal(r.error?.code, 'ENOENT');
+  });
+
+  it('does not run a shell: metacharacter args are inert literals', async function () {
+    // If a shell were involved, `; echo pwned` would execute. With
+    // shell:false it is a single, literal argv entry echoed back unchanged.
+    const evil = '; echo pwned > /tmp/ca-pwned';
+    const r = await run(node, [ '-e', 'process.stdout.write(process.argv[1])', evil ]);
+    assert.equal(r.code, 0);
+    assert.equal(r.stdout, evil);
+  });
+
+  it('writes provided input to stdin', async function () {
+    const r = await run(
+      node,
+      [ '-e', 'process.stdin.on("data", d => process.stdout.write("got:" + d))' ],
+      { input: 'secret\n' }
+    );
+    assert.equal(r.code, 0);
+    assert.equal(r.stdout, 'got:secret\n');
+  });
+});
diff --git a/packages/create-apostrophe/test/core/store.test.js b/packages/create-apostrophe/test/core/store.test.js
new file mode 100644
index 0000000000..11ab2bfcf9
--- /dev/null
+++ b/packages/create-apostrophe/test/core/store.test.js
@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, rmSync, readFileSync, writeFileSync
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  createStore, defaultStorePath, configDir, KNOWN_KEYS
+} from '../../src/core/store.js';
+
+describe('core/store', function () {
+  let dir;
+
+  beforeEach(function () {
+    dir = mkdtempSync(join(tmpdir(), 'ca-store-'));
+  });
+
+  afterEach(function () {
+    rmSync(dir, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('round-trips known keys and persists across instances', function () {
+    const a = createStore({ dir });
+    assert.equal(a.get('telemetryConsent'), undefined);
+
+    a.set('telemetryConsent', true);
+    a.set('anonymousId', 'abc-123');
+
+    const b = createStore({ dir });
+    assert.equal(b.get('telemetryConsent'), true);
+    assert.equal(b.get('anonymousId'), 'abc-123');
+    assert.deepEqual(b.all(), {
+      telemetryConsent: true,
+      anonymousId: 'abc-123'
+    });
+  });
+
+  it('delete removes a single key; clear removes the file', function () {
+    const s = createStore({ dir });
+    s.set('telemetryConsent', false);
+    s.set('anonymousId', 'x');
+
+    s.delete('telemetryConsent');
+    assert.equal(s.get('telemetryConsent'), undefined);
+    assert.equal(s.get('anonymousId'), 'x');
+
+    s.clear();
+    assert.deepEqual(s.all(), {});
+    // clear() is idempotent.
+    s.clear();
+  });
+
+  it('rejects unknown keys on every accessor', function () {
+    const s = createStore({ dir });
+    for (const op of [
+      () => s.get('nope'),
+      () => s.set('nope', 1),
+      () => s.delete('nope')
+    ]) {
+      assert.throws(op, TypeError);
+    }
+  });
+
+  it('tolerates a missing and a corrupt backing file', function () {
+    const s = createStore({ dir });
+    // Missing file → empty.
+    assert.deepEqual(s.all(), {});
+
+    // Corrupt JSON → treated as empty, not a throw; a write recovers it.
+    writeFileSync(s.path, '{ not json', 'utf8');
+    assert.deepEqual(s.all(), {});
+    s.set('anonymousId', 'recovered');
+    assert.equal(createStore({ dir }).get('anonymousId'), 'recovered');
+  });
+
+  it('writes atomically (pretty JSON, trailing newline, no temp left behind)', function () {
+    const s = createStore({ dir });
+    s.set('telemetryConsent', true);
+    const raw = readFileSync(s.path, 'utf8');
+    assert.equal(raw, '{\n  "telemetryConsent": true\n}\n');
+  });
+
+  it('creates the config directory if it does not exist', function () {
+    const nested = join(dir, 'deep', 'missing');
+    const s = createStore({ dir: nested });
+    s.set('anonymousId', 'y');
+    assert.equal(createStore({ dir: nested }).get('anonymousId'), 'y');
+  });
+
+  it('defaultStorePath lives under the per-OS config dir', function () {
+    assert.equal(defaultStorePath(), join(configDir(), 'store.json'));
+    assert.ok(configDir().includes('create-apostrophe'));
+  });
+
+  it('KNOWN_KEYS is the frozen two-key allowlist', function () {
+    assert.deepEqual([ ...KNOWN_KEYS ], [ 'telemetryConsent', 'anonymousId' ]);
+    assert.throws(() => {
+      KNOWN_KEYS.push('x');
+    }, TypeError);
+  });
+});
diff --git a/packages/create-apostrophe/test/core/validate.test.js b/packages/create-apostrophe/test/core/validate.test.js
new file mode 100644
index 0000000000..c9b08c5020
--- /dev/null
+++ b/packages/create-apostrophe/test/core/validate.test.js
@@ -0,0 +1,19 @@
+import assert from 'node:assert/strict';
+import { assertSafeShortName } from '../../src/core/validate.js';
+
+describe('core/validate', function () {
+  it('accepts safe names and returns the value', function () {
+    for (const ok of [ 'my-site', 'my_site', 'site1', 'A', 'a-b_c-1' ]) {
+      assert.equal(assertSafeShortName(ok), ok);
+    }
+  });
+
+  it('rejects path-unsafe / malformed names', function () {
+    for (const bad of [
+      '../evil', 'a/b', 'a\\b', '/abs', '..', '.', 'na me',
+      'dot.name', '', 'pwn;rm', undefined, null, 42, {}
+    ]) {
+      assert.throws(() => assertSafeShortName(bad), TypeError);
+    }
+  });
+});
diff --git a/packages/create-apostrophe/test/exports.test.js b/packages/create-apostrophe/test/exports.test.js
new file mode 100644
index 0000000000..6745c20b8f
--- /dev/null
+++ b/packages/create-apostrophe/test/exports.test.js
@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict';
+
+// Uses package self-referencing (Node resolves the package by its own name via
+// the "exports" map from within the package), so this verifies the published
+// surface independently of node_modules layout.
+
+async function importByName(spec) {
+  return import(spec);
+}
+
+describe('public exports map', function () {
+  it('resolves the public entry point', async function () {
+    const mod = await importByName('create-apostrophe');
+    assert.ok(mod, 'create-apostrophe should resolve to src/index.js');
+  });
+
+  it('exposes exactly { createProject, runCli, runInteractive, runTelemetryCommand } at the public surface', async function () {
+    const mod = await importByName('create-apostrophe');
+    const names = Object.keys(mod).sort();
+    assert.deepEqual(names, [
+      'createProject', 'runCli', 'runInteractive', 'runTelemetryCommand'
+    ]);
+    assert.equal(typeof mod.createProject, 'function');
+    assert.equal(typeof mod.runCli, 'function');
+    assert.equal(typeof mod.runInteractive, 'function');
+    assert.equal(typeof mod.runTelemetryCommand, 'function');
+  });
+
+  for (const sub of [
+    'create-apostrophe/src/core/store.js',
+    'create-apostrophe/src/ui/flow.js',
+    'create-apostrophe/src/telemetry/index.js',
+    'create-apostrophe/src/index.js',
+    'create-apostrophe/package.json'
+  ]) {
+    it(`blocks private subpath: ${sub}`, async function () {
+      await assert.rejects(
+        () => importByName(sub),
+        err => err.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED',
+        `expected ${sub} to be hidden by the exports map`
+      );
+    });
+  }
+});
diff --git a/packages/create-apostrophe/test/skeleton.test.js b/packages/create-apostrophe/test/skeleton.test.js
new file mode 100644
index 0000000000..0717766a38
--- /dev/null
+++ b/packages/create-apostrophe/test/skeleton.test.js
@@ -0,0 +1,26 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const bin = fileURLToPath(new URL('../bin/create-apostrophe.js', import.meta.url));
+const pkg = JSON.parse(
+  readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8')
+);
+
+describe('bin smoke', function () {
+  it('public entry point is importable', async function () {
+    await import('../src/index.js');
+  });
+
+  it('--version prints the package version and exits 0', function () {
+    const out = execFileSync(process.execPath, [ bin, '--version' ], { encoding: 'utf8' });
+    assert.equal(out.trim(), pkg.version);
+  });
+
+  it('--help prints usage and exits 0', function () {
+    const out = execFileSync(process.execPath, [ bin, '--help' ], { encoding: 'utf8' });
+    assert.match(out, /Usage:/);
+    assert.match(out, /telemetry/);
+  });
+});
diff --git a/packages/create-apostrophe/test/telemetry/commands.test.js b/packages/create-apostrophe/test/telemetry/commands.test.js
new file mode 100644
index 0000000000..ad13a4f240
--- /dev/null
+++ b/packages/create-apostrophe/test/telemetry/commands.test.js
@@ -0,0 +1,218 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createStore } from '../../src/core/store.js';
+import {
+  status, optIn, optOut, preview
+} from '../../src/telemetry/commands.js';
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+describe('telemetry/commands — status', function () {
+  let dir;
+  /** @type {ReturnType<typeof createStore>} */
+  let store;
+
+  beforeEach(function () {
+    dir = mkdtempSync(join(tmpdir(), 'ca-cmd-'));
+    store = createStore({ dir });
+  });
+
+  afterEach(function () {
+    rmSync(dir, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('default: unset store, no env', function () {
+    const r = status(store, {});
+    assert.deepEqual(r, {
+      consent: false,
+      killSwitchOn: false,
+      storedConsent: undefined,
+      anonymousId: undefined,
+      source: 'default'
+    });
+  });
+
+  it('stored true: source=stored, id present', function () {
+    optIn(store, {});
+    const r = status(store, {});
+    assert.equal(r.consent, true);
+    assert.equal(r.storedConsent, true);
+    assert.equal(r.source, 'stored');
+    assert.match(r.anonymousId, UUID_RE);
+    assert.equal(r.killSwitchOn, false);
+  });
+
+  it('kill switch: consent=false, source=kill-switch, stored value reported', function () {
+    optIn(store, {});
+    const r = status(store, { APOS_TELEMETRY: '0' });
+    assert.equal(r.consent, false);
+    assert.equal(r.killSwitchOn, true);
+    assert.equal(r.storedConsent, true);
+    assert.equal(r.source, 'kill-switch');
+  });
+
+  it('stored false: source=stored, consent=false', function () {
+    optOut(store);
+    const r = status(store, {});
+    assert.equal(r.consent, false);
+    assert.equal(r.storedConsent, false);
+    assert.equal(r.source, 'stored');
+  });
+});
+
+describe('telemetry/commands — optIn', function () {
+  let dir;
+  /** @type {ReturnType<typeof createStore>} */
+  let store;
+
+  beforeEach(function () {
+    dir = mkdtempSync(join(tmpdir(), 'ca-cmd-'));
+    store = createStore({ dir });
+  });
+
+  afterEach(function () {
+    rmSync(dir, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('first time: idGenerated=true; UUID returned', function () {
+    const r = optIn(store, {});
+    assert.equal(r.consent, true);
+    assert.equal(r.idGenerated, true);
+    assert.equal(r.killSwitchOn, false);
+    assert.match(r.anonymousId, UUID_RE);
+  });
+
+  it('second time: idGenerated=false; same id', function () {
+    const first = optIn(store, {});
+    const second = optIn(store, {});
+    assert.equal(second.idGenerated, false);
+    assert.equal(second.anonymousId, first.anonymousId);
+  });
+
+  it('after opt-out then opt-in: idGenerated=false; id preserved', function () {
+    const first = optIn(store, {});
+    optOut(store);
+    const reon = optIn(store, {});
+    assert.equal(reon.idGenerated, false);
+    assert.equal(reon.anonymousId, first.anonymousId);
+  });
+
+  it('kill switch on: still persists, killSwitchOn flag set', function () {
+    const r = optIn(store, { APOS_TELEMETRY: '0' });
+    assert.equal(r.consent, true);
+    assert.equal(r.killSwitchOn, true);
+    // Effective state reflects the override.
+    assert.equal(status(store, { APOS_TELEMETRY: '0' }).consent, false);
+  });
+});
+
+describe('telemetry/commands — optOut', function () {
+  let dir;
+  /** @type {ReturnType<typeof createStore>} */
+  let store;
+
+  beforeEach(function () {
+    dir = mkdtempSync(join(tmpdir(), 'ca-cmd-'));
+    store = createStore({ dir });
+  });
+
+  afterEach(function () {
+    rmSync(dir, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('returns consent=false; preserves anonymousId', function () {
+    const on = optIn(store, {});
+    const off = optOut(store);
+    assert.equal(off.consent, false);
+    assert.equal(off.anonymousId, on.anonymousId);
+  });
+
+  it('opt-out on unused store: consent=false; anonymousId undefined', function () {
+    const r = optOut(store);
+    assert.equal(r.consent, false);
+    assert.equal(r.anonymousId, undefined);
+  });
+});
+
+describe('telemetry/commands — preview', function () {
+  let dir;
+  /** @type {ReturnType<typeof createStore>} */
+  let store;
+
+  beforeEach(function () {
+    dir = mkdtempSync(join(tmpdir(), 'ca-cmd-'));
+    store = createStore({ dir });
+  });
+
+  afterEach(function () {
+    rmSync(dir, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('idSentinel=true when no id stored; payload uses zero-UUID', function () {
+    const r = preview({
+      store,
+      cliVersion: '0.1.0',
+      env: {}
+    });
+    assert.equal(r.idSentinel, true);
+    assert.equal(r.consent, false);
+    assert.equal(r.killSwitchOn, false);
+    assert.equal(r.payload.anonymousId, '00000000-0000-0000-0000-000000000000');
+    assert.equal(r.payload.event, 'install_success');
+  });
+
+  it('idSentinel=false when id stored; payload uses real id', function () {
+    const opt = optIn(store, {});
+    const r = preview({
+      store,
+      cliVersion: '0.1.0',
+      env: {}
+    });
+    assert.equal(r.idSentinel, false);
+    assert.equal(r.consent, true);
+    assert.equal(r.payload.anonymousId, opt.anonymousId);
+  });
+
+  it('reports kill-switch + consent state', function () {
+    optIn(store, {});
+    const r = preview({
+      store,
+      cliVersion: '0.1.0',
+      env: { APOS_TELEMETRY: '0' }
+    });
+    assert.equal(r.consent, false);
+    assert.equal(r.killSwitchOn, true);
+  });
+
+  it('sample overrides reach the payload', function () {
+    const r = preview({
+      store,
+      cliVersion: '0.1.0',
+      env: {},
+      sample: {
+        kitId: 'apostrophe-demo',
+        dbChoice: 'mongodb',
+        packageManager: 'yarn',
+        durationMs: 9999
+      }
+    });
+    assert.equal(r.payload.kitId, 'apostrophe-demo');
+    assert.equal(r.payload.dbChoice, 'mongodb');
+    assert.equal(r.payload.packageManager, 'yarn');
+    assert.equal(r.payload.durationMs, 9999);
+  });
+});
diff --git a/packages/create-apostrophe/test/telemetry/consent.test.js b/packages/create-apostrophe/test/telemetry/consent.test.js
new file mode 100644
index 0000000000..eefc99b56d
--- /dev/null
+++ b/packages/create-apostrophe/test/telemetry/consent.test.js
@@ -0,0 +1,206 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createStore } from '../../src/core/store.js';
+import {
+  isKillSwitchOn, readConsent, setConsent, getAnonymousId, forgetIdentity,
+  previewPayload
+} from '../../src/telemetry/consent.js';
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+describe('telemetry/consent — kill switch', function () {
+  it('only the literal "0" disables', function () {
+    assert.equal(isKillSwitchOn({ APOS_TELEMETRY: '0' }), true);
+    assert.equal(isKillSwitchOn({ APOS_TELEMETRY: '1' }), false);
+    assert.equal(isKillSwitchOn({ APOS_TELEMETRY: 'false' }), false);
+    assert.equal(isKillSwitchOn({ APOS_TELEMETRY: '' }), false);
+    assert.equal(isKillSwitchOn({}), false);
+  });
+});
+
+describe('telemetry/consent — precedence', function () {
+  let dir;
+  /** @type {ReturnType<typeof createStore>} */
+  let store;
+
+  beforeEach(function () {
+    dir = mkdtempSync(join(tmpdir(), 'ca-consent-'));
+    store = createStore({ dir });
+  });
+
+  afterEach(function () {
+    rmSync(dir, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('unset store + no env → false (opt-in only, no default)', function () {
+    assert.equal(readConsent(store, {}), false);
+  });
+
+  it('stored true, no env → true', function () {
+    store.set('telemetryConsent', true);
+    assert.equal(readConsent(store, {}), true);
+  });
+
+  it('stored false, no env → false', function () {
+    store.set('telemetryConsent', false);
+    assert.equal(readConsent(store, {}), false);
+  });
+
+  it('stored true, kill switch on → false (env beats store)', function () {
+    store.set('telemetryConsent', true);
+    assert.equal(readConsent(store, { APOS_TELEMETRY: '0' }), false);
+  });
+
+  it('stored false, kill switch on → still false', function () {
+    store.set('telemetryConsent', false);
+    assert.equal(readConsent(store, { APOS_TELEMETRY: '0' }), false);
+  });
+
+  it('only boolean true is "on"; truthy strings/numbers are ignored', function () {
+    // Direct store poke — bypasses setConsent's TypeError guard.
+    store.set('telemetryConsent', /** @type {any} */ ('yes'));
+    assert.equal(readConsent(store, {}), false);
+  });
+});
+
+describe('telemetry/consent — identity lifecycle', function () {
+  let dir;
+  /** @type {ReturnType<typeof createStore>} */
+  let store;
+
+  beforeEach(function () {
+    dir = mkdtempSync(join(tmpdir(), 'ca-consent-'));
+    store = createStore({ dir });
+  });
+
+  afterEach(function () {
+    rmSync(dir, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('getAnonymousId returns undefined until first opt-in', function () {
+    assert.equal(getAnonymousId(store), undefined);
+  });
+
+  it('first opt-in generates a UUID and persists it', function () {
+    const r = setConsent(store, true);
+    assert.match(r.anonymousId, UUID_RE);
+    assert.equal(getAnonymousId(store), r.anonymousId);
+  });
+
+  it('opt-out preserves the id (stable across toggles)', function () {
+    const onR = setConsent(store, true);
+    const id = onR.anonymousId;
+    setConsent(store, false);
+    assert.equal(getAnonymousId(store), id);
+    // And a later opt-in reuses it — no new generation.
+    const reonR = setConsent(store, true);
+    assert.equal(reonR.anonymousId, id);
+  });
+
+  it('a second opt-in with an id already present does not regenerate', function () {
+    setConsent(store, true);
+    const id = getAnonymousId(store);
+    setConsent(store, true);
+    assert.equal(getAnonymousId(store), id);
+  });
+
+  it('setConsent rejects non-boolean (programmer error)', function () {
+    assert.throws(
+      () => setConsent(store, /** @type {any} */ ('on')),
+      TypeError
+    );
+    assert.throws(
+      () => setConsent(store, /** @type {any} */ (1)),
+      TypeError
+    );
+  });
+
+  it('forgetIdentity wipes both consent and id', function () {
+    setConsent(store, true);
+    forgetIdentity(store);
+    assert.equal(readConsent(store, {}), false);
+    assert.equal(getAnonymousId(store), undefined);
+  });
+
+  it('opt-in survives a fresh store instance (persisted on disk)', function () {
+    setConsent(store, true);
+    const id = getAnonymousId(store);
+    const reopened = createStore({ dir });
+    assert.equal(getAnonymousId(reopened), id);
+    assert.equal(readConsent(reopened, {}), true);
+  });
+});
+
+describe('telemetry/consent — previewPayload', function () {
+  let dir;
+  /** @type {ReturnType<typeof createStore>} */
+  let store;
+
+  beforeEach(function () {
+    dir = mkdtempSync(join(tmpdir(), 'ca-consent-'));
+    store = createStore({ dir });
+  });
+
+  afterEach(function () {
+    rmSync(dir, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('uses the stored id when one exists', function () {
+    setConsent(store, true);
+    const id = getAnonymousId(store);
+    const p = previewPayload({
+      store,
+      cliVersion: '0.1.0'
+    });
+    assert.equal(p.anonymousId, id);
+  });
+
+  it('uses the zero-UUID sentinel when no id stored', function () {
+    const p = previewPayload({
+      store,
+      cliVersion: '0.1.0'
+    });
+    assert.equal(p.anonymousId, '00000000-0000-0000-0000-000000000000');
+  });
+
+  it('payload is a real install_success — same shape the wire sees', function () {
+    const p = previewPayload({
+      store,
+      cliVersion: '0.1.0'
+    });
+    assert.equal(p.event, 'install_success');
+    assert.equal(p.cliVersion, '0.1.0');
+    assert.equal(p.kitId, 'apostrophe-astro-demo');
+    assert.equal(p.dbChoice, 'sqlite');
+    assert.equal(p.packageManager, 'npm');
+    assert.equal(p.durationMs, 0);
+  });
+
+  it('sample overrides take effect', function () {
+    const p = previewPayload({
+      store,
+      cliVersion: '9.9.9',
+      sample: {
+        kitId: 'apostrophe-essentials',
+        dbChoice: 'postgres',
+        packageManager: 'pnpm',
+        durationMs: 5000
+      }
+    });
+    assert.equal(p.kitId, 'apostrophe-essentials');
+    assert.equal(p.dbChoice, 'postgres');
+    assert.equal(p.packageManager, 'pnpm');
+    assert.equal(p.durationMs, 5000);
+  });
+});
diff --git a/packages/create-apostrophe/test/telemetry/firewall.test.js b/packages/create-apostrophe/test/telemetry/firewall.test.js
new file mode 100644
index 0000000000..70b9e88ff7
--- /dev/null
+++ b/packages/create-apostrophe/test/telemetry/firewall.test.js
@@ -0,0 +1,268 @@
+// The PII firewall is THE privacy guarantee. These tests do not exercise
+// internal mechanics — they assert the externally observable invariant:
+// nothing outside the §7 allowlist can ever leave the package. If a future
+// refactor breaks the firewall, this file is the alarm.
+
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createStore } from '../../src/core/store.js';
+import { createTelemetry } from '../../src/telemetry/index.js';
+import { previewPayload, setConsent } from '../../src/telemetry/consent.js';
+import { preview } from '../../src/telemetry/commands.js';
+import { allowedFields } from '../../src/telemetry/schema.js';
+
+/**
+ * Exhaustive sampler of values that must NEVER appear on a payload, drawn
+ * from the explicit exclusions doc 03 lists and from the createProject
+ * inputs that surround the telemetry call. Each is paired with a key name
+ * a careless implementation might use.
+ */
+const FORBIDDEN_INPUTS = Object.freeze({
+  // Identity / personal
+  email: 'ceo@example.com',
+  name: 'Real Person Name',
+  login: 'admin@example.com',
+  username: 'reactor-core',
+  password: 'hunter2',
+  // Network / hosts / paths
+  ip: '203.0.113.42',
+  hostname: 'db.internal.example.com',
+  cwd: '/home/jane/secret-startup',
+  projectDir: '/home/jane/secret-startup/my-app',
+  appRoot: '/home/jane/secret-startup/my-app/backend',
+  // Project specifics
+  shortName: 'top-secret-project',
+  projectName: 'Top Secret Project',
+  // DB connections / credentials
+  dbUri: 'mongodb://admin:hunter2@db.internal:27017/secret',
+  postgresUri: 'postgres://x:y@db.internal:5432/secret',
+  connectionString: 'sqlite:./local.db',
+  // Env / secrets / tokens
+  env: { APOS_SESSION_SECRET: 'A'.repeat(64) },
+  APOS_SESSION_SECRET: 'A'.repeat(64),
+  authorization: 'Bearer leaked.jwt.token',
+  token: 'gho_fakeghtoken',
+  // Git / source
+  gitRemote: 'git@github.com:secret-org/secret-repo.git',
+  // Free-form raw error blobs the orchestrator must never forward
+  rawError: 'ENOENT: no such file or directory, open ' +
+    '/home/jane/.npm-cache/locks/staging.lock',
+  stack: 'Error: boom\n    at /home/jane/secret-startup/...'
+});
+
+const VALID_PARTIAL = Object.freeze({
+  kitId: 'apostrophe-astro-demo',
+  dbChoice: 'sqlite',
+  packageManager: 'npm',
+  durationMs: 1234
+});
+
+const VALID_FAIL_PARTIAL = Object.freeze({
+  ...VALID_PARTIAL,
+  failStage: /** @type {const} */ ('dependency_install'),
+  errorCode: 'install_failed'
+});
+
+/**
+ * Run the telemetry hook end-to-end with a poisoned partial payload, return
+ * what the transport actually saw.
+ */
+async function emitAndCapture(event, poisonedPartial) {
+  /** @type {Array<Record<string, unknown>>} */
+  const sent = [];
+  const t = createTelemetry({
+    consent: true,
+    cliVersion: '0.1.0',
+    anonymousId: '22222222-2222-2222-2222-222222222222',
+    transport: async (p) => {
+      sent.push(p);
+    },
+    logger: {
+      info() {},
+      warn() {}
+    }
+  });
+  t.event(event, poisonedPartial);
+  await t.flush();
+  return sent;
+}
+
+describe('PII firewall — install_success', function () {
+  it('a payload poisoned with every excluded field still emits the §7 keys only', async function () {
+    const sent = await emitAndCapture('install_success', {
+      ...VALID_PARTIAL,
+      ...FORBIDDEN_INPUTS
+    });
+    assert.equal(sent.length, 1);
+    const allowed = new Set(allowedFields('install_success'));
+    for (const k of Object.keys(sent[0])) {
+      assert.ok(
+        allowed.has(k),
+        `forbidden key reached wire: ${k}`
+      );
+    }
+    // Spot-check: every forbidden key is absent.
+    for (const k of Object.keys(FORBIDDEN_INPUTS)) {
+      assert.equal(k in sent[0], false, `${k} leaked`);
+    }
+  });
+
+  it('the JSON serialized wire payload contains none of the forbidden VALUES', async function () {
+    const sent = await emitAndCapture('install_success', {
+      ...VALID_PARTIAL,
+      ...FORBIDDEN_INPUTS
+    });
+    const wire = JSON.stringify(sent[0]);
+    const checks = [
+      'ceo@example.com',
+      'Real Person Name',
+      'admin@example.com',
+      'reactor-core',
+      'hunter2',
+      '203.0.113.42',
+      'db.internal.example.com',
+      '/home/jane',
+      'top-secret-project',
+      'Top Secret Project',
+      'mongodb://admin',
+      'postgres://x:y',
+      'sqlite:./local.db',
+      'APOS_SESSION_SECRET',
+      'AAAAAAAA',
+      'Bearer leaked',
+      'gho_fakeghtoken',
+      'github.com:secret-org',
+      'ENOENT: no such file',
+      '.npm-cache/locks',
+      'Error: boom'
+    ];
+    for (const needle of checks) {
+      assert.equal(
+        wire.includes(needle), false,
+        `forbidden substring leaked into wire payload: ${needle}\n${wire}`
+      );
+    }
+  });
+});
+
+describe('PII firewall — install_fail', function () {
+  it('poisoned fail payload emits only allowed keys; unknown errorCode dropped', async function () {
+    const sent = await emitAndCapture('install_fail', {
+      ...VALID_FAIL_PARTIAL,
+      errorCode: 'EACCES /home/jane/.npm: permission denied',
+      ...FORBIDDEN_INPUTS
+    });
+    assert.equal(sent.length, 1);
+    const allowed = new Set(allowedFields('install_fail'));
+    for (const k of Object.keys(sent[0])) {
+      assert.ok(allowed.has(k), `forbidden key reached wire: ${k}`);
+    }
+    // Unknown errorCode is dropped, but the rest of the payload still emits.
+    assert.equal('errorCode' in sent[0], false);
+    assert.equal(sent[0].failStage, 'dependency_install');
+  });
+
+  it('JSON wire payload contains no forbidden values (errorCode path)', async function () {
+    const sent = await emitAndCapture('install_fail', {
+      ...VALID_FAIL_PARTIAL,
+      errorCode: 'EACCES /home/jane/.npm: permission denied',
+      ...FORBIDDEN_INPUTS
+    });
+    const wire = JSON.stringify(sent[0]);
+    assert.equal(wire.includes('/home/jane'), false);
+    assert.equal(wire.includes('permission denied'), false);
+  });
+});
+
+describe('PII firewall — previewPayload (no wire, but same allowlist)', function () {
+  let dir;
+  /** @type {ReturnType<typeof createStore>} */
+  let store;
+
+  beforeEach(function () {
+    dir = mkdtempSync(join(tmpdir(), 'ca-fw-'));
+    store = createStore({ dir });
+  });
+
+  afterEach(function () {
+    rmSync(dir, {
+      recursive: true,
+      force: true
+    });
+  });
+
+  it('previewPayload silently ignores forbidden keys on sample', function () {
+    setConsent(store, true);
+    const p = previewPayload({
+      store,
+      cliVersion: '0.1.0',
+      // @ts-expect-error — intentionally poisoned sample
+      sample: {
+        ...FORBIDDEN_INPUTS,
+        kitId: 'apostrophe-demo',
+        dbChoice: 'postgres',
+        packageManager: 'npm',
+        durationMs: 1
+      }
+    });
+    const allowed = new Set(allowedFields('install_success'));
+    for (const k of Object.keys(p)) {
+      assert.ok(allowed.has(k), `forbidden key in preview: ${k}`);
+    }
+  });
+
+  it('preview() result wraps the same allowlist guarantee', function () {
+    const r = preview({
+      store,
+      cliVersion: '0.1.0',
+      env: {},
+      // @ts-expect-error — poisoned sample
+      sample: {
+        ...FORBIDDEN_INPUTS,
+        kitId: 'apostrophe-demo',
+        dbChoice: 'postgres',
+        packageManager: 'npm',
+        durationMs: 1
+      }
+    });
+    const allowed = new Set(allowedFields('install_success'));
+    for (const k of Object.keys(r.payload)) {
+      assert.ok(allowed.has(k), `forbidden key in commands.preview payload: ${k}`);
+    }
+  });
+});
+
+describe('PII firewall — consent gate is a hard wall', function () {
+  it('consent=false: not even a verbose log writes the would-be payload', async function () {
+    /** @type {Array<string>} */
+    const info = [];
+    /** @type {Array<string>} */
+    const warn = [];
+    /** @type {Array<object>} */
+    const sent = [];
+    const t = createTelemetry({
+      consent: false,
+      cliVersion: '0.1.0',
+      anonymousId: '22222222-2222-2222-2222-222222222222',
+      transport: async (p) => {
+        sent.push(p);
+      },
+      logger: {
+        info: (m) => info.push(m),
+        warn: (m) => warn.push(m)
+      },
+      verbose: true
+    });
+    t.event('install_success', {
+      ...VALID_PARTIAL,
+      ...FORBIDDEN_INPUTS
+    });
+    await t.flush();
+    assert.equal(sent.length, 0);
+    // No "would send" log: consent gate short-circuits before any work.
+    assert.equal(info.length, 0);
+    assert.equal(warn.length, 0);
+  });
+});
diff --git a/packages/create-apostrophe/test/telemetry/index.test.js b/packages/create-apostrophe/test/telemetry/index.test.js
new file mode 100644
index 0000000000..87e1bd9e81
--- /dev/null
+++ b/packages/create-apostrophe/test/telemetry/index.test.js
@@ -0,0 +1,302 @@
+import assert from 'node:assert/strict';
+import { performance } from 'node:perf_hooks';
+import { createTelemetry } from '../../src/telemetry/index.js';
+
+const PARTIAL = Object.freeze({
+  kitId: 'apostrophe-astro-demo',
+  dbChoice: 'sqlite',
+  packageManager: 'npm',
+  durationMs: 1234
+});
+
+const PARTIAL_FAIL = Object.freeze({
+  ...PARTIAL,
+  failStage: /** @type {const} */ ('dependency_install'),
+  errorCode: 'install_failed'
+});
+
+/** Capture transport calls + log lines. */
+function spies() {
+  /** @type {Array<object>} */
+  const sent = [];
+  /** @type {Array<string>} */
+  const info = [];
+  /** @type {Array<string>} */
+  const warn = [];
+  return {
+    sent,
+    info,
+    warn,
+    transport: async (payload) => {
+      sent.push(payload);
+    },
+    logger: {
+      info: (m) => info.push(m),
+      warn: (m) => warn.push(m)
+    }
+  };
+}
+
+describe('telemetry/createTelemetry — consent gate', function () {
+  it('consent=false makes event() a true no-op (no transport call)', async function () {
+    const s = spies();
+    const t = createTelemetry({
+      consent: false,
+      cliVersion: '0.1.0',
+      transport: s.transport,
+      logger: s.logger,
+      verbose: true
+    });
+    t.event('install_success', PARTIAL);
+    await t.flush();
+    assert.equal(s.sent.length, 0);
+    assert.equal(s.info.length, 0);
+    assert.equal(s.warn.length, 0);
+  });
+
+  it('consent=true → transport called exactly once with the wire payload', async function () {
+    const s = spies();
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      anonymousId: '11111111-1111-1111-1111-111111111111',
+      transport: s.transport,
+      logger: s.logger
+    });
+    t.event('install_success', PARTIAL);
+    await t.flush();
+    assert.equal(s.sent.length, 1);
+    assert.deepEqual(s.sent[0], {
+      event: 'install_success',
+      cliVersion: '0.1.0',
+      kitId: PARTIAL.kitId,
+      dbChoice: PARTIAL.dbChoice,
+      packageManager: PARTIAL.packageManager,
+      durationMs: PARTIAL.durationMs,
+      anonymousId: '11111111-1111-1111-1111-111111111111'
+    });
+  });
+
+  it('omits anonymousId when none provided', async function () {
+    const s = spies();
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      transport: s.transport,
+      logger: s.logger
+    });
+    t.event('install_success', PARTIAL);
+    await t.flush();
+    assert.equal('anonymousId' in s.sent[0], false);
+  });
+
+  it('install_fail payload threads failStage + allowlisted errorCode', async function () {
+    const s = spies();
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      anonymousId: 'id',
+      transport: s.transport,
+      logger: s.logger
+    });
+    t.event('install_fail', PARTIAL_FAIL);
+    await t.flush();
+    assert.equal(s.sent[0].event, 'install_fail');
+    assert.equal(s.sent[0].failStage, 'dependency_install');
+    assert.equal(s.sent[0].errorCode, 'install_failed');
+  });
+});
+
+describe('telemetry/createTelemetry — fire-and-forget contract', function () {
+  it('event() returns void synchronously (not a thenable)', function () {
+    const s = spies();
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      transport: s.transport,
+      logger: s.logger
+    });
+    const ret = t.event('install_success', PARTIAL);
+    assert.equal(ret, undefined);
+  });
+
+  it('a slow transport does not block event() (returns before transport resolves)', async function () {
+    let resolveTransport;
+    const slowTransport = () => new Promise((resolve) => {
+      resolveTransport = resolve;
+    });
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      transport: slowTransport,
+      logger: spies().logger
+    });
+    const start = Date.now();
+    t.event('install_success', PARTIAL);
+    const elapsed = Date.now() - start;
+    assert.ok(elapsed < 50, `event() returned in ${elapsed}ms (should be sync)`);
+    // Let the test exit cleanly.
+    resolveTransport();
+    await t.flush();
+  });
+
+  it('schema rejection: never throws to caller; verbose warn fired', async function () {
+    const s = spies();
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      transport: s.transport,
+      logger: s.logger,
+      verbose: true
+    });
+    // Bad kitId → buildPayload throws SchemaError — must be swallowed.
+    t.event('install_success', {
+      ...PARTIAL,
+      kitId: /** @type {any} */ ('apostrophe-multisite')
+    });
+    await t.flush();
+    assert.equal(s.sent.length, 0);
+    assert.equal(s.warn.length, 1);
+    assert.match(s.warn[0], /invalid payload/);
+  });
+
+  it('schema rejection: verbose=false stays silent (no log lines)', async function () {
+    const s = spies();
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      transport: s.transport,
+      logger: s.logger
+    });
+    t.event('install_success', {
+      ...PARTIAL,
+      kitId: /** @type {any} */ ('apostrophe-multisite')
+    });
+    await t.flush();
+    assert.equal(s.warn.length, 0);
+    assert.equal(s.info.length, 0);
+  });
+
+  it('transport rejection: never throws to caller; verbose warn fired', async function () {
+    const s = spies();
+    const failingTransport = async () => {
+      throw new Error('connection refused');
+    };
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      transport: failingTransport,
+      logger: s.logger,
+      verbose: true
+    });
+    t.event('install_success', PARTIAL);
+    await t.flush();
+    assert.equal(s.warn.length, 1);
+    assert.match(s.warn[0], /transport failed/);
+    assert.match(s.warn[0], /connection refused/);
+  });
+});
+
+describe('telemetry/createTelemetry — timeout', function () {
+  it('a hanging transport rejects after timeoutMs without throwing to caller', async function () {
+    const s = spies();
+    const hang = () => new Promise(() => {});
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      transport: hang,
+      timeoutMs: 30,
+      logger: s.logger,
+      verbose: true
+    });
+    const TOLERANCE_MS = 5;
+    const start = performance.now();
+    t.event('install_success', PARTIAL);
+    await t.flush();
+    const elapsed = performance.now() - start;
+    assert.ok(
+      elapsed >= 30 - TOLERANCE_MS,
+      `flush returned in ${elapsed.toFixed(1)}ms (expected ≳ 30)`
+    );
+    assert.ok(elapsed < 500, `flush took too long: ${elapsed.toFixed(1)}ms`);
+    assert.equal(s.warn.length, 1);
+    assert.match(s.warn[0], /transport failed/);
+    assert.match(s.warn[0], /timeout/);
+  });
+
+  it('fast transport beats the timeout; no warn fired', async function () {
+    const s = spies();
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      transport: s.transport,
+      timeoutMs: 5000,
+      logger: s.logger,
+      verbose: true
+    });
+    t.event('install_success', PARTIAL);
+    await t.flush();
+    assert.equal(s.sent.length, 1);
+    // info: "would send" entry; warn: none.
+    assert.equal(s.warn.length, 0);
+  });
+});
+
+describe('telemetry/createTelemetry — flush()', function () {
+  it('resolves immediately when nothing is pending', async function () {
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      logger: spies().logger
+    });
+    const start = Date.now();
+    await t.flush();
+    assert.ok(Date.now() - start < 20);
+  });
+
+  it('waits for all pending jobs', async function () {
+    let pending = 0;
+    let maxPending = 0;
+    const slowTransport = async () => {
+      pending++;
+      maxPending = Math.max(maxPending, pending);
+      await new Promise((resolve) => setTimeout(resolve, 15));
+      pending--;
+    };
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      transport: slowTransport,
+      logger: spies().logger
+    });
+    t.event('install_success', PARTIAL);
+    t.event('install_success', PARTIAL);
+    t.event('install_success', PARTIAL);
+    // event() invokes transport synchronously up to its first await, so all
+    // three are already in-flight before flush starts.
+    assert.equal(maxPending, 3);
+    assert.equal(pending, 3);
+    await t.flush();
+    assert.equal(pending, 0);
+  });
+});
+
+describe('telemetry/createTelemetry — verbose log content', function () {
+  it('logs the exact payload that would be sent', async function () {
+    const s = spies();
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      anonymousId: 'abc',
+      transport: s.transport,
+      logger: s.logger,
+      verbose: true
+    });
+    t.event('install_success', PARTIAL);
+    await t.flush();
+    assert.equal(s.info.length, 1);
+    assert.match(s.info[0], /would send/);
+    assert.match(s.info[0], /"anonymousId":"abc"/);
+    assert.match(s.info[0], /"event":"install_success"/);
+  });
+});
diff --git a/packages/create-apostrophe/test/telemetry/schema.test.js b/packages/create-apostrophe/test/telemetry/schema.test.js
new file mode 100644
index 0000000000..f563c84f8d
--- /dev/null
+++ b/packages/create-apostrophe/test/telemetry/schema.test.js
@@ -0,0 +1,249 @@
+import assert from 'node:assert/strict';
+import {
+  buildPayload, allowedFields, EVENT_NAMES, DB_CHOICES, PACKAGE_MANAGERS,
+  FAIL_STAGES, ERROR_CODES, SchemaError
+} from '../../src/telemetry/schema.js';
+import { KIT_IDS } from '../../src/core/kits.js';
+
+const VALID = Object.freeze({
+  cliVersion: '0.1.0',
+  anonymousId: '11111111-1111-1111-1111-111111111111',
+  kitId: 'apostrophe-astro-demo',
+  dbChoice: 'sqlite',
+  packageManager: 'npm',
+  durationMs: 1234
+});
+
+describe('telemetry/schema — enum exports', function () {
+  it('event names: success + fail only', function () {
+    assert.deepEqual([ ...EVENT_NAMES ], [ 'install_success', 'install_fail' ]);
+  });
+
+  it('dbChoices: single mongodb (no atlas/local split)', function () {
+    assert.deepEqual([ ...DB_CHOICES ], [ 'sqlite', 'mongodb', 'postgres' ]);
+  });
+
+  it('packageManagers includes unknown', function () {
+    assert.deepEqual(
+      [ ...PACKAGE_MANAGERS ],
+      [ 'npm', 'pnpm', 'yarn', 'unknown' ]
+    );
+  });
+
+  it('failStages include admin + preflight null', function () {
+    assert.ok(FAIL_STAGES.includes('admin'));
+    assert.ok(FAIL_STAGES.includes(null));
+  });
+
+  it('failStages include sample_data (demo-data seed import)', function () {
+    assert.ok(FAIL_STAGES.includes('sample_data'));
+  });
+
+  it('errorCodes include the seed_* codes', function () {
+    for (const code of [
+      'seed_manifest_invalid', 'seed_download_failed', 'seed_checksum_failed',
+      'seed_unpack_failed', 'seed_restore_failed', 'seed_uploads_failed'
+    ]) {
+      assert.ok(ERROR_CODES.includes(code), code);
+    }
+  });
+
+  it('errorCodes refine db_connect into reachable/auth/drop verdicts', function () {
+    for (const code of [
+      'db_unreachable', 'db_auth_failed', 'db_connect_failed', 'db_drop_failed'
+    ]) {
+      assert.ok(ERROR_CODES.includes(code), code);
+    }
+  });
+
+  it('every kit-registry id is a valid kitId enum value', function () {
+    for (const id of KIT_IDS) {
+      const p = buildPayload('install_success', {
+        ...VALID,
+        kitId: id
+      });
+      assert.equal(p.kitId, id);
+    }
+  });
+});
+
+describe('telemetry/schema — buildPayload (success)', function () {
+  it('returns exactly the §7 fields, in order', function () {
+    const p = buildPayload('install_success', VALID);
+    assert.deepEqual(Object.keys(p), [
+      'event', 'cliVersion', 'kitId', 'dbChoice',
+      'packageManager', 'durationMs', 'anonymousId'
+    ]);
+    assert.equal(p.event, 'install_success');
+    assert.equal(p.cliVersion, VALID.cliVersion);
+    assert.equal(p.anonymousId, VALID.anonymousId);
+    assert.equal(p.kitId, VALID.kitId);
+    assert.equal(p.dbChoice, VALID.dbChoice);
+    assert.equal(p.packageManager, VALID.packageManager);
+    assert.equal(p.durationMs, VALID.durationMs);
+  });
+
+  it('omits anonymousId when not supplied', function () {
+    const { anonymousId, ...noId } = VALID;
+    const p = buildPayload('install_success', noId);
+    assert.equal('anonymousId' in p, false);
+  });
+
+  it('drops every field outside the allowlist (PII firewall)', function () {
+    const p = buildPayload('install_success', {
+      ...VALID,
+      // Anything that could leak — paths, names, secrets, env, content.
+      shortName: 'top-secret-project',
+      dbUri: 'mongodb://admin:pw@db.internal/secret',
+      'admin.username': 'ceo@company.com',
+      cwd: '/home/secret/path',
+      env: { APOS_SECRET: 'xxx' },
+      headers: { authorization: 'Bearer leaked' }
+    });
+    for (const k of [
+      'shortName', 'dbUri', 'admin.username', 'cwd', 'env', 'headers'
+    ]) {
+      assert.equal(k in p, false, `${k} must not appear in payload`);
+    }
+  });
+});
+
+describe('telemetry/schema — buildPayload (fail)', function () {
+  const FAIL_INPUT = Object.freeze({
+    ...VALID,
+    failStage: /** @type {const} */ ('dependency_install'),
+    errorCode: 'install_failed'
+  });
+
+  it('adds failStage and a known errorCode', function () {
+    const p = buildPayload('install_fail', FAIL_INPUT);
+    assert.equal(p.event, 'install_fail');
+    assert.equal(p.failStage, 'dependency_install');
+    assert.equal(p.errorCode, 'install_failed');
+  });
+
+  it('accepts failStage: sample_data with a seed errorCode', function () {
+    const p = buildPayload('install_fail', {
+      ...FAIL_INPUT,
+      failStage: 'sample_data',
+      errorCode: 'seed_checksum_failed'
+    });
+    assert.equal(p.failStage, 'sample_data');
+    assert.equal(p.errorCode, 'seed_checksum_failed');
+  });
+
+  it('accepts failStage: null (preflight)', function () {
+    const p = buildPayload('install_fail', {
+      ...FAIL_INPUT,
+      failStage: null,
+      errorCode: 'unsupported_pm'
+    });
+    assert.equal(p.failStage, null);
+    assert.equal(p.errorCode, 'unsupported_pm');
+  });
+
+  it('drops an unknown errorCode (allowlist), never raw error strings', function () {
+    const p = buildPayload('install_fail', {
+      ...FAIL_INPUT,
+      errorCode: 'EACCES: permission denied at /home/x/.npm-cache'
+    });
+    assert.equal('errorCode' in p, false);
+    // The rest of the payload still goes through.
+    assert.equal(p.failStage, FAIL_INPUT.failStage);
+  });
+
+  it('omits errorCode when undefined', function () {
+    const { errorCode, ...noCode } = FAIL_INPUT;
+    const p = buildPayload('install_fail', noCode);
+    assert.equal('errorCode' in p, false);
+  });
+
+  it('every allowlisted code roundtrips', function () {
+    for (const code of ERROR_CODES) {
+      const p = buildPayload('install_fail', {
+        ...FAIL_INPUT,
+        errorCode: code
+      });
+      assert.equal(p.errorCode, code, code);
+    }
+  });
+});
+
+describe('telemetry/schema — validators reject bad input', function () {
+  /** @type {Array<[string, object]>} */
+  const cases = [
+    [ 'invalid event', { event: 'install_started' } ],
+    [ 'empty cliVersion', { cliVersion: '' } ],
+    [ 'missing cliVersion', { cliVersion: undefined } ],
+    [ 'unknown kitId', { kitId: 'apostrophe-multisite' } ],
+    [ 'unknown dbChoice', { dbChoice: 'mongodb-atlas' } ],
+    [ 'unknown packageManager', { packageManager: 'bun' } ],
+    [ 'non-number durationMs', { durationMs: '1234' } ],
+    [ 'Infinite durationMs', { durationMs: Infinity } ],
+    [ 'empty anonymousId', { anonymousId: '' } ]
+  ];
+  for (const [ label, override ] of cases) {
+    it(`rejects: ${label}`, function () {
+      const input = {
+        ...VALID,
+        ...override
+      };
+      const event = ('event' in override) ? override.event : 'install_success';
+      assert.throws(
+        () => buildPayload(event, input),
+        SchemaError,
+        label
+      );
+    });
+  }
+
+  it('rejects unknown failStage on install_fail', function () {
+    assert.throws(
+      () => buildPayload('install_fail', {
+        ...VALID,
+        failStage: 'docker_failed',
+        errorCode: 'install_failed'
+      }),
+      SchemaError
+    );
+  });
+});
+
+describe('telemetry/schema — allowedFields', function () {
+  it('install_success: 7 fields, no failStage/errorCode', function () {
+    const f = [ ...allowedFields('install_success') ];
+    assert.deepEqual(f.sort(), [
+      'anonymousId', 'cliVersion', 'dbChoice', 'durationMs',
+      'event', 'kitId', 'packageManager'
+    ]);
+  });
+
+  it('install_fail: 9 fields with failStage + errorCode', function () {
+    const f = [ ...allowedFields('install_fail') ];
+    assert.deepEqual(f.sort(), [
+      'anonymousId', 'cliVersion', 'dbChoice', 'durationMs',
+      'errorCode', 'event', 'failStage', 'kitId', 'packageManager'
+    ]);
+  });
+
+  it('every built-payload key is in allowedFields()', function () {
+    const success = buildPayload('install_success', VALID);
+    for (const k of Object.keys(success)) {
+      assert.ok(
+        allowedFields('install_success').includes(k),
+        `success key ${k} not in allowedFields`
+      );
+    }
+    const fail = buildPayload('install_fail', {
+      ...VALID,
+      failStage: 'clone',
+      errorCode: 'git_clone_failed'
+    });
+    for (const k of Object.keys(fail)) {
+      assert.ok(
+        allowedFields('install_fail').includes(k),
+        `fail key ${k} not in allowedFields`
+      );
+    }
+  });
+});
diff --git a/packages/create-apostrophe/test/telemetry/transport.test.js b/packages/create-apostrophe/test/telemetry/transport.test.js
new file mode 100644
index 0000000000..16951d7ffd
--- /dev/null
+++ b/packages/create-apostrophe/test/telemetry/transport.test.js
@@ -0,0 +1,316 @@
+import assert from 'node:assert/strict';
+import { createUmamiTransport } from '../../src/telemetry/transport.js';
+import { createTelemetry } from '../../src/telemetry/index.js';
+import {
+  TELEMETRY_ENDPOINT,
+  TELEMETRY_WRITE_KEY,
+  TELEMETRY_HOSTNAME
+} from '../../src/telemetry/wire-config.js';
+
+// Swap global fetch to observe what the @umami/node client sends.
+
+const SUCCESS_PARTIAL = Object.freeze({
+  kitId: 'apostrophe-astro-demo',
+  dbChoice: 'sqlite',
+  packageManager: 'npm',
+  durationMs: 1234
+});
+
+function silentLogger() {
+  return {
+    info() {},
+    warn() {}
+  };
+}
+
+describe('telemetry/transport — createUmamiTransport', function () {
+  /** @type {typeof globalThis.fetch} */
+  let originalFetch;
+
+  beforeEach(function () {
+    originalFetch = globalThis.fetch;
+  });
+  afterEach(function () {
+    globalThis.fetch = originalFetch;
+  });
+
+  function recordingFetch(response = {
+    ok: true,
+    status: 200
+  }) {
+    /** @type {Array<{ url: string, init: { method: string, body: string } }>} */
+    const calls = [];
+    globalThis.fetch = async (url, init) => {
+      calls.push({
+        url: String(url),
+        init
+      });
+      return response;
+    };
+    return calls;
+  }
+
+  it('POSTs the payload to <endpoint>/api/send as a Umami event', async function () {
+    const calls = recordingFetch();
+    const transport = createUmamiTransport({
+      endpoint: 'https://umami.example',
+      writeKey: 'WEBSITE-XYZ',
+      hostname: 'cli.example.com'
+    });
+    await transport({
+      event: 'install_success',
+      cliVersion: '0.1.0',
+      kitId: 'apostrophe-astro-demo',
+      dbChoice: 'sqlite',
+      packageManager: 'npm',
+      durationMs: 1234,
+      anonymousId: 'id-1'
+    });
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].url, 'https://umami.example/api/send');
+    assert.equal(calls[0].init.method, 'POST');
+    const body = JSON.parse(calls[0].init.body);
+    assert.equal(body.type, 'event');
+    assert.equal(body.payload.website, 'WEBSITE-XYZ');
+    assert.equal(body.payload.name, 'install_success');
+    assert.equal(body.payload.hostname, 'cli.example.com');
+    assert.deepEqual(body.payload.data, {
+      cliVersion: '0.1.0',
+      kitId: 'apostrophe-astro-demo',
+      dbChoice: 'sqlite',
+      packageManager: 'npm',
+      durationMs: 1234,
+      anonymousId: 'id-1'
+    });
+  });
+
+  it('threads install_fail with failStage + errorCode', async function () {
+    const calls = recordingFetch();
+    const transport = createUmamiTransport({
+      endpoint: 'https://umami.example',
+      writeKey: 'k',
+      hostname: 'cli.example.com'
+    });
+    await transport({
+      event: 'install_fail',
+      cliVersion: '0.1.0',
+      kitId: 'apostrophe-astro-demo',
+      dbChoice: 'sqlite',
+      packageManager: 'npm',
+      durationMs: 1,
+      failStage: 'dependency_install',
+      errorCode: 'install_failed'
+    });
+    const body = JSON.parse(calls[0].init.body);
+    assert.equal(body.payload.name, 'install_fail');
+    assert.equal(body.payload.data.failStage, 'dependency_install');
+    assert.equal(body.payload.data.errorCode, 'install_failed');
+  });
+
+  it('rejects on non-2xx so the telemetry layer can warn under verbose', async function () {
+    recordingFetch({
+      ok: false,
+      status: 500
+    });
+    const transport = createUmamiTransport({
+      endpoint: 'https://umami.example',
+      writeKey: 'k',
+      hostname: 'cli.example.com'
+    });
+    await assert.rejects(
+      () => transport({
+        event: 'install_success',
+        ...SUCCESS_PARTIAL,
+        cliVersion: '0.1.0'
+      }),
+      /HTTP 500/
+    );
+  });
+
+  it('propagates fetch network errors', async function () {
+    globalThis.fetch = async () => {
+      throw new Error('ECONNREFUSED');
+    };
+    const transport = createUmamiTransport({
+      endpoint: 'https://nope.example',
+      writeKey: 'k',
+      hostname: 'cli.example.com'
+    });
+    await assert.rejects(
+      () => transport({
+        event: 'install_fail',
+        ...SUCCESS_PARTIAL,
+        cliVersion: '0.1.0',
+        failStage: 'clone',
+        errorCode: 'git_clone_failed'
+      }),
+      /ECONNREFUSED/
+    );
+  });
+});
+
+describe('telemetry/createTelemetry — default live transport (wire-config)', function () {
+  /** @type {typeof globalThis.fetch} */
+  let originalFetch;
+
+  beforeEach(function () {
+    originalFetch = globalThis.fetch;
+  });
+  afterEach(function () {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('uses the wire-config live transport when no transport is injected', async function () {
+    /** @type {Array<{ url: string, body: string }>} */
+    const calls = [];
+    globalThis.fetch = async (url, init) => {
+      calls.push({
+        url: String(url),
+        body: String(init.body)
+      });
+      return {
+        ok: true,
+        status: 200
+      };
+    };
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      anonymousId: 'id-x',
+      logger: silentLogger()
+    });
+    t.event('install_success', SUCCESS_PARTIAL);
+    await t.flush();
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].url, `${TELEMETRY_ENDPOINT}/api/send`);
+    const body = JSON.parse(calls[0].body);
+    assert.equal(body.payload.website, TELEMETRY_WRITE_KEY);
+    assert.equal(body.payload.hostname, TELEMETRY_HOSTNAME);
+  });
+
+  it('consent=false blocks the live transport (no fetch even though wire-config is set)', async function () {
+    let fetched = false;
+    globalThis.fetch = async () => {
+      fetched = true;
+      return {
+        ok: true,
+        status: 200
+      };
+    };
+    const t = createTelemetry({
+      consent: false,
+      cliVersion: '0.1.0',
+      logger: silentLogger()
+    });
+    t.event('install_success', SUCCESS_PARTIAL);
+    await t.flush();
+    assert.equal(fetched, false);
+  });
+
+  it('an injected transport wins over the wire-config default (test seam)', async function () {
+    let fetched = false;
+    globalThis.fetch = async () => {
+      fetched = true;
+      return {
+        ok: true,
+        status: 200
+      };
+    };
+    /** @type {Array<object>} */
+    const sent = [];
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      transport: async (payload) => {
+        sent.push(payload);
+      },
+      logger: silentLogger()
+    });
+    t.event('install_success', SUCCESS_PARTIAL);
+    await t.flush();
+    assert.equal(fetched, false);
+    assert.equal(sent.length, 1);
+  });
+
+  it('config overrides redirect the live transport at a sandbox endpoint', async function () {
+    /** @type {Array<{ url: string, body: string }>} */
+    const calls = [];
+    globalThis.fetch = async (url, init) => {
+      calls.push({
+        url: String(url),
+        body: String(init.body)
+      });
+      return {
+        ok: true,
+        status: 200
+      };
+    };
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      endpoint: 'https://umami.sandbox.local',
+      writeKey: 'SANDBOX-KEY',
+      hostname: 'sandbox.test',
+      logger: silentLogger()
+    });
+    t.event('install_success', SUCCESS_PARTIAL);
+    await t.flush();
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].url, 'https://umami.sandbox.local/api/send');
+    const body = JSON.parse(calls[0].body);
+    assert.equal(body.payload.website, 'SANDBOX-KEY');
+    assert.equal(body.payload.hostname, 'sandbox.test');
+    assert.notEqual(body.payload.website, TELEMETRY_WRITE_KEY);
+  });
+
+  it('partial override (writeKey only) falls back to wire-config for the rest', async function () {
+    /** @type {Array<{ url: string, body: string }>} */
+    const calls = [];
+    globalThis.fetch = async (url, init) => {
+      calls.push({
+        url: String(url),
+        body: String(init.body)
+      });
+      return {
+        ok: true,
+        status: 200
+      };
+    };
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      writeKey: 'SANDBOX-KEY',
+      logger: silentLogger()
+    });
+    t.event('install_success', SUCCESS_PARTIAL);
+    await t.flush();
+    assert.equal(calls[0].url, `${TELEMETRY_ENDPOINT}/api/send`);
+    const body = JSON.parse(calls[0].body);
+    assert.equal(body.payload.website, 'SANDBOX-KEY');
+    assert.equal(body.payload.hostname, TELEMETRY_HOSTNAME);
+  });
+
+  it('a hanging live transport is bounded by timeoutMs and never throws', async function () {
+    globalThis.fetch = () => new Promise(() => {});
+    /** @type {Array<string>} */
+    const warn = [];
+    const t = createTelemetry({
+      consent: true,
+      cliVersion: '0.1.0',
+      timeoutMs: 30,
+      verbose: true,
+      logger: {
+        info() {},
+        warn: (m) => warn.push(m)
+      }
+    });
+    const start = Date.now();
+    t.event('install_success', SUCCESS_PARTIAL);
+    await t.flush();
+    const elapsed = Date.now() - start;
+    assert.ok(elapsed < 500, `flush took too long: ${elapsed}ms`);
+    assert.equal(warn.length, 1);
+    assert.match(warn[0], /transport failed/);
+    assert.match(warn[0], /timeout/);
+  });
+});
diff --git a/packages/db-connect/package.json b/packages/db-connect/package.json
index 5eeedf8aac..37150cddfe 100644
--- a/packages/db-connect/package.json
+++ b/packages/db-connect/package.json
@@ -2,6 +2,7 @@
   "name": "@apostrophecms/db-connect",
   "version": "1.0.0",
   "description": "Database connection library and dump/restore tools for ApostropheCMS",
+  "license": "MIT",
   "main": "index.js",
   "bin": {
     "apos-db-dump": "./bin/apos-db-dump.js",
diff --git a/packages/import-export-xlsx/package.json b/packages/import-export-xlsx/package.json
index cdf5b84dfa..754cb29be3 100644
--- a/packages/import-export-xlsx/package.json
+++ b/packages/import-export-xlsx/package.json
@@ -15,7 +15,7 @@
   },
   "homepage": "https://github.com/apostrophecms/apostrophe/tree/main/packages/import-export-xlsx#readme",
   "author": "Apostrophe Technologies",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "devDependencies": {
     "eslint": "^9.39.1",
     "eslint-config-apostrophe": "workspace:^",
diff --git a/packages/import-export/package.json b/packages/import-export/package.json
index ab3b56118c..a3466d74ad 100644
--- a/packages/import-export/package.json
+++ b/packages/import-export/package.json
@@ -17,7 +17,7 @@
   },
   "homepage": "https://github.com/apostrophecms/apostrophe/tree/main/import-export#readme",
   "author": "Apostrophe Technologies",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "devDependencies": {
     "apostrophe": "workspace:^",
     "eslint": "^9.39.1",

From f67c272002f70ef945a7aac406443e22fdf18e17 Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Tue, 2 Jun 2026 18:56:17 +0300
Subject: [PATCH 37/56] Fix new schema areas in existing documents (Astro)
 (#5434)

* Fix orphan or new-in-the-schema areas in external front-ends
* Save missing empty areas in the DB, refactor nunjucks path
---
 .changeset/ripe-terms-happen.md               |  11 ++
 .../components/AposArea.astro                 |  77 ++++++---
 .../modules/@apostrophecms/area/index.js      |  36 ++++-
 .../area/lib/custom-tags/area.js              |  32 ++--
 .../modules/@apostrophecms/template/index.js  |  45 +++++-
 .../modules/@apostrophecms/util/index.js      |   6 +-
 packages/apostrophe/test/external-front.js    | 148 +++++++++++++++++-
 7 files changed, 299 insertions(+), 56 deletions(-)
 create mode 100644 .changeset/ripe-terms-happen.md

diff --git a/.changeset/ripe-terms-happen.md b/.changeset/ripe-terms-happen.md
new file mode 100644
index 0000000000..4ad5dec883
--- /dev/null
+++ b/.changeset/ripe-terms-happen.md
@@ -0,0 +1,11 @@
+---
+"@apostrophecms/apostrophe-astro": minor
+"apostrophe": minor
+---
+
+Fixed adding or removing an area field from a schema breaking existing documents on an external front such as Astro.
+
+- `AposArea` now renders only schema-backed areas. A missing area no longer throws, and an area orphaned by removing its field from the schema (while its content remains in the document) renders nothing instead of breaking sibling areas in edit mode. Logged-in editors get a diagnostic message in place of an orphaned area; anonymous visitors see nothing.
+- Editable documents sent to an external front now materialize empty area objects for schema area fields added after the document was created, so they can be edited in context.
+- `apos.util.getManagerOf` accepts a `{ log }` option to suppress its error log when probing objects that may not have a manager.
+
diff --git a/packages/apostrophe-astro/components/AposArea.astro b/packages/apostrophe-astro/components/AposArea.astro
index 418b01d45d..94b6c27f8e 100644
--- a/packages/apostrophe-astro/components/AposArea.astro
+++ b/packages/apostrophe-astro/components/AposArea.astro
@@ -13,9 +13,13 @@ const {
 
 let attributes = {};
 
-const widgets = area?.items || [];
+// The backend sets `field` only on areas still in the schema; a missing or
+// orphaned area lacks it and renders nothing.
+const isArea = Boolean(area?.field);
 
-const isEdit = area?._edit && Astro.url.searchParams.get("aposEdit");
+const widgets: Record<string, any>[] = area?.items || [];
+
+const isEdit = isArea && area?._edit && Astro.url.searchParams.get("aposEdit");
 const forceWrapper = aposAttributes || aposStyle || aposClassName;
 
 const WidgetComponent = widgetComponent ?? AposWidget;
@@ -43,16 +47,16 @@ if (isEdit) {
   };
 }
 const Wrapper = isEdit || forceWrapper ? "div" : Fragment;
-const widgetOptions = getWidgetOptions(area.options);
+const widgetOptions = getWidgetOptions(area?.options);
 
-function getWidgetOptions(options) {
-  let widgets = options.widgets || {};
+function getWidgetOptions(options: any = {}) {
+  let widgets = { ...(options.widgets || {}) };
 
   if (options.groups) {
     for (const group of Object.keys(options.groups)) {
       widgets = {
         ...widgets,
-        ...options.groups[group].widgets,
+        ...(options.groups[group]?.widgets || {}),
       };
     }
   }
@@ -60,22 +64,45 @@ function getWidgetOptions(options) {
 }
 ---
 
-<Wrapper {...attributes}>
-  {
-    widgets?.map((item) => {
-      const options = {
-        ...item._options,
-        ...widgetOptions[item.type],
-      };
-      return (
-        <WidgetComponent
-          widget={item}
-          options={options}
-          area={area}
-          canEdit={isEdit}
-          {...props}
-        />
-      );
-    })
-  }
-</Wrapper>
+{
+  isArea ? (
+    <Wrapper {...attributes}>
+      {widgets.map((item) => {
+        const options = {
+          ...item._options,
+          ...widgetOptions[item.type],
+        };
+        return (
+          <WidgetComponent
+            widget={item}
+            options={options}
+            area={area}
+            canEdit={isEdit}
+            {...props}
+          />
+        );
+      })}
+    </Wrapper>
+  ) : (
+    // Orphaned area. Dev-only diagnostic: `import.meta.env.DEV` is replaced
+    // with `false` in production, so this branch is dead-code eliminated.
+    (import.meta as any).env.DEV &&
+    area?.metaType === "area" && (
+      <div
+        data-apos-area-error
+        role="alert"
+        style="margin:1rem 0;padding:0.75rem 1rem;border:2px solid #dc2626;border-radius:4px;background:#fff1f2;color:#991b1b;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:0.85rem;line-height:1.5;"
+      >
+        <strong>ApostropheCMS:</strong> an area passed to{" "}
+        <code>{"<AposArea />"}</code> is not defined in the schema, so it was
+        not rendered. Its field was likely removed from the schema while content
+        remains in the document. Restore the field in the schema, or remove the
+        matching <code>{"<AposArea />"}</code> from this template.
+        <br />
+        <small>
+          area _id: {area._id} — document: {area._docId}
+        </small>
+      </div>
+    )
+  )
+}
diff --git a/packages/apostrophe/modules/@apostrophecms/area/index.js b/packages/apostrophe/modules/@apostrophecms/area/index.js
index a96d8248c8..5d74add608 100644
--- a/packages/apostrophe/modules/@apostrophecms/area/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/area/index.js
@@ -285,6 +285,37 @@ module.exports = {
           self.missingWidgetTypes[name] = true;
         }
       },
+      // Build an empty area and attach it to `parent[name]`. When `parent`
+      // is doc-backed (has `_docId`, or is itself a doc) and `areaDotPath`
+      // is provided, also persist the area at that dot-path. The write is
+      // idempotent via `$eq: null`, so concurrent renders won't clobber each
+      // other. Returns the area.
+      //
+      // Used by the `{% area %}` tag and the external front annotator as a
+      // single source of truth for stubbing schema areas that have no value
+      // yet.
+      async addMissingArea(parent, name, areaDotPath) {
+        const area = {
+          metaType: 'area',
+          _id: self.apos.util.generateId(),
+          items: []
+        };
+        parent[name] = area;
+        const docId = parent._docId ??
+          (parent.metaType === 'doc' ? parent._id : null);
+        if (docId && areaDotPath) {
+          await self.apos.doc.db.updateOne(
+            {
+              _id: docId,
+              [areaDotPath]: { $eq: null }
+            },
+            {
+              $set: { [areaDotPath]: self.apos.util.clonePermanent(area) }
+            }
+          );
+        }
+        return area;
+      },
       prepForRender(area, context, fieldName) {
         const manager = self.apos.util.getManagerOf(context);
         const field = manager.schema.find(field => field.name === fieldName);
@@ -451,7 +482,10 @@ module.exports = {
         // Loop over the docs in the array passed in.
         for (const doc of within) {
           if (self.apos.externalFrontKey) {
-            self.apos.template.annotateDocForExternalFront(doc, { scene: req.scene });
+            await self.apos.template.annotateDocForExternalFront(
+              doc,
+              { scene: req.scene }
+            );
           }
 
           const rendered = [];
diff --git a/packages/apostrophe/modules/@apostrophecms/area/lib/custom-tags/area.js b/packages/apostrophe/modules/@apostrophecms/area/lib/custom-tags/area.js
index 5b8bb7f5fb..c9e5615ad1 100644
--- a/packages/apostrophe/modules/@apostrophecms/area/lib/custom-tags/area.js
+++ b/packages/apostrophe/modules/@apostrophecms/area/lib/custom-tags/area.js
@@ -63,15 +63,10 @@ module.exports = function(self) {
         // has a value, for instance the field could be new in the schema.
         // But we need an area _id. Stub it into the db on the fly
         // without race conditions
-        area = {
-          metaType: 'area',
-          _id: self.apos.util.generateId(),
-          items: []
-        };
-        doc[name] = area;
         const docId = doc._docId || ((doc.metaType === 'doc') ? doc._id : null);
+        let areaDotPath;
         if (docId) {
-          let mainDoc = await self.apos.doc.db.findOne({ _id: docId });
+          const mainDoc = await self.apos.doc.db.findOne({ _id: docId });
           if (!mainDoc) {
             throw self.apos.error('notfound');
           }
@@ -83,21 +78,14 @@ module.exports = function(self) {
             // Unlikely thanks to advisory locking
             throw self.apos.error('notfound');
           }
-          const areaDotPath = docDotPath ? `${docDotPath}.${name}` : name;
-          await self.apos.doc.db.updateOne({
-            _id: docId,
-            // Prevent race condition
-            [areaDotPath]: {
-              $eq: null
-            }
-          }, {
-            $set: {
-              [areaDotPath]: self.apos.util.clonePermanent(area)
-            }
-          });
-          mainDoc = await self.apos.doc.db.findOne({ _id: docId });
-          // Prevent race condition
-          area._id = self.apos.util.get(mainDoc, areaDotPath)._id;
+          areaDotPath = docDotPath ? `${docDotPath}.${name}` : name;
+        }
+        area = await self.apos.area.addMissingArea(doc, name, areaDotPath);
+        if (docId) {
+          // Race-safety: re-read the persisted _id in case another request
+          // wrote first (our $eq: null write was a no-op in that case).
+          const refreshed = await self.apos.doc.db.findOne({ _id: docId });
+          area._id = self.apos.util.get(refreshed, areaDotPath)._id;
         }
       }
       const manager = self.apos.util.getManagerOf(doc);
diff --git a/packages/apostrophe/modules/@apostrophecms/template/index.js b/packages/apostrophe/modules/@apostrophecms/template/index.js
index a11a00e375..2884df913b 100644
--- a/packages/apostrophe/modules/@apostrophecms/template/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/template/index.js
@@ -1231,7 +1231,7 @@ module.exports = {
       async annotateDataForExternalFront(req, template, data, moduleName) {
         const docs = self.getDocsForExternalFront(req, template, data, moduleName);
         for (const doc of docs) {
-          self.annotateDocForExternalFront(doc, { scene: req.scene });
+          await self.annotateDocForExternalFront(doc, { scene: req.scene });
         }
         data.aposBodyData = await self.getBodyData(req);
         // Already contains module name too
@@ -1283,12 +1283,27 @@ module.exports = {
         ].filter(doc => !!doc);
       },
 
-      annotateDocForExternalFront(doc, { scene } = {}) {
-        self.apos.doc.walk(doc, (o, k, v) => {
+      async annotateDocForExternalFront(doc, { scene } = {}) {
+        const handled = new WeakSet();
+        const missingAreas = [];
+        self.apos.doc.walk(doc, (o, k, v, __dotPath) => {
+          if (o._edit === true && !handled.has(o)) {
+            handled.add(o);
+            // `__dotPath` is the path to `v` (= o[k]); the container `o` lives
+            // one segment up — '' for the top-level doc.
+            const dot = __dotPath.lastIndexOf('.');
+            const containerDotPath = dot === -1 ? '' : __dotPath.substring(0, dot);
+            for (const field of self.missingSchemaAreas(o)) {
+              missingAreas.push([ o, field, containerDotPath ]);
+            }
+          }
           if (v && v.metaType === 'area') {
             const manager = self.apos.util.getManagerOf(o);
             if (!manager) {
-              self.apos.util.warnDevOnce('noManagerForDocInExternalFront', `No manager for: ${o.metaType} ${o.type || ''}`);
+              self.apos.util.warnDevOnce(
+                'noManagerForDocInExternalFront',
+                `No manager for: ${o.metaType} ${o.type || ''}`
+              );
               return;
             }
             const field = manager.schema.find(f => f.name === k);
@@ -1302,6 +1317,21 @@ module.exports = {
             return self.annotateAreaForExternalFront(field, v, { scene });
           }
         });
+        // Materialize every missing area, after the walk so we never add keys
+        // to an object while it is being traversed.
+        for (const [ o, field, containerDotPath ] of missingAreas) {
+          const areaDotPath = containerDotPath
+            ? `${containerDotPath}.${field.name}`
+            : field.name;
+          const area = await self.apos.area.addMissingArea(
+            o,
+            field.name,
+            areaDotPath
+          );
+          area._edit = true;
+          area._docId = o._docId ?? (o.metaType === 'doc' ? o._id : null);
+          self.annotateAreaForExternalFront(field, area, { scene });
+        }
       },
 
       // Annotate an area for easy rendering by an external front end
@@ -1343,6 +1373,13 @@ module.exports = {
             throw self.apos.error('invalid', 'Missing widget type');
           }
         }
+      },
+
+      // The schema area fields of `object` that have no value yet. Returns an
+      // empty array for anything without a schema manager.
+      missingSchemaAreas(object) {
+        const schema = self.apos.util.getManagerOf(object, { log: false })?.schema ?? [];
+        return schema.filter(field => field.type === 'area' && !object[field.name]);
       }
     };
   }
diff --git a/packages/apostrophe/modules/@apostrophecms/util/index.js b/packages/apostrophe/modules/@apostrophecms/util/index.js
index ab47fd0137..38b9e54527 100644
--- a/packages/apostrophe/modules/@apostrophecms/util/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/util/index.js
@@ -724,7 +724,7 @@ module.exports = {
       },
       // Given a widget or doc, return the appropriate manager module. If the manager
       // cannot be determined for any reason, undefined is returned.
-      getManagerOf(object) {
+      getManagerOf(object, { log = true } = {}) {
         if (object.metaType === 'doc') {
           return self.apos.doc.getManager(object.type);
         } else if (object.metaType === 'widget') {
@@ -733,10 +733,10 @@ module.exports = {
           return self.apos.schema.getArrayManager(object.scopedArrayName);
         } else if (object.metaType === 'object') {
           return self.apos.schema.getObjectManager(object.scopedObjectName);
-        } else {
+        } else if (log) {
           self.apos.util.error(`Unsupported metaType in getManagerOf: ${object.metaType}`);
-          return undefined;
         }
+        return undefined;
       },
       // fetch the value at the given path from the object or
       // array `o`. `path` supports dot notation like MongoDB, and
diff --git a/packages/apostrophe/test/external-front.js b/packages/apostrophe/test/external-front.js
index a750fce038..b49424cfe7 100644
--- a/packages/apostrophe/test/external-front.js
+++ b/packages/apostrophe/test/external-front.js
@@ -17,12 +17,158 @@ describe('External Front', function() {
 
   it('apostrophe should initialize normally', async function() {
     apos = await t.create({
-      root: module
+      root: module,
+      modules: {
+        product: {
+          extend: '@apostrophecms/piece-type',
+          options: {
+            alias: 'product'
+          },
+          fields: {
+            add: {
+              main: {
+                type: 'area',
+                options: {
+                  widgets: {
+                    '@apostrophecms/rich-text': {}
+                  }
+                }
+              },
+              extra: {
+                type: 'area',
+                options: {
+                  widgets: {
+                    '@apostrophecms/rich-text': {}
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
     });
 
     assert(apos.page.__meta.name === '@apostrophecms/page');
   });
 
+  // A doc as it would look in memory, with `extra` simulating an area field
+  // added to the schema after the doc was created (so it has no value).
+  function productMissingExtra() {
+    const doc = apos.product.newInstance();
+    doc._id = 'product1:en:published';
+    doc.metaType = 'doc';
+    doc.title = 'Product 1';
+    doc.slug = 'product-1';
+    delete doc.extra;
+    return doc;
+  }
+
+  it('missingSchemaAreas returns unfilled area fields, ignores non-schema objects', function() {
+    const missing = apos.template.missingSchemaAreas(productMissingExtra());
+    assert.strictEqual(missing.length, 1);
+    assert.strictEqual(missing[0].name, 'extra');
+
+    // An area object carries `_edit` but has no schema manager: returns []
+    // quietly (getManagerOf called with log: false).
+    const area = {
+      metaType: 'area',
+      _edit: true
+    };
+    assert.deepStrictEqual(apos.template.missingSchemaAreas(area), []);
+  });
+
+  it('annotateDocForExternalFront materializes missing areas on an editable doc', async function() {
+    const doc = productMissingExtra();
+    doc._edit = true;
+    // As loaded for an editor, existing areas carry _edit too
+    doc.main._edit = true;
+
+    await apos.template.annotateDocForExternalFront(doc);
+
+    // Existing area still annotated, unchanged behavior
+    assert(doc.main.field && doc.main.field.name === 'main');
+    assert(doc.main.options);
+
+    // Missing area added as an empty, editable, annotated area
+    assert(doc.extra, 'extra area was materialized');
+    assert.strictEqual(doc.extra.metaType, 'area');
+    assert.deepStrictEqual(doc.extra.items, []);
+    assert.strictEqual(doc.extra._edit, true);
+    assert.strictEqual(doc.extra._docId, doc._id);
+    assert(doc.extra._id, 'has an id');
+    assert(doc.extra.field && doc.extra.field.name === 'extra');
+    assert(doc.extra.options, 'annotated with options');
+    assert(Array.isArray(doc.extra.choices));
+  });
+
+  it('annotateDocForExternalFront leaves missing areas alone on a non-editable doc', async function() {
+    const doc = productMissingExtra();
+
+    await apos.template.annotateDocForExternalFront(doc);
+
+    assert.strictEqual(doc.extra, undefined, 'extra not added for anonymous');
+    // Existing area annotated as before
+    assert(doc.main.field && doc.main.field.name === 'main');
+  });
+
+  it('annotateDocForExternalFront persists materialized areas at their schema path with the same _id sent to the UI', async function() {
+    // Insert a doc directly with only `main`, no `extra`, simulating a field
+    // added to the schema after the doc was created.
+    const docId = 'persist-test:en:draft';
+    await apos.doc.db.deleteOne({ _id: docId });
+    await apos.doc.db.insertOne({
+      _id: docId,
+      type: 'product',
+      metaType: 'doc',
+      aposMode: 'draft',
+      aposDocId: 'persist-test',
+      aposLocale: 'en:draft',
+      title: 'Persist Test',
+      slug: 'persist-test',
+      main: {
+        metaType: 'area',
+        _id: 'main-id-persist',
+        items: []
+      }
+    });
+
+    // Load the doc and mark editable (mirroring what doc-type load does)
+    const doc = await apos.doc.db.findOne({ _id: docId });
+    doc._edit = true;
+    doc.main._edit = true;
+
+    await apos.template.annotateDocForExternalFront(doc);
+
+    // In-memory: extra was materialized and annotated
+    assert(doc.extra && doc.extra._id, 'extra has an id in memory');
+    const inMemoryId = doc.extra._id;
+
+    // In the DB: extra was written at the schema path with the same _id, so a
+    // subsequent editor patch using @<inMemoryId>.items will resolve
+    const persisted = await apos.doc.db.findOne({ _id: docId });
+    assert(persisted.extra, 'extra was persisted');
+    assert.strictEqual(persisted.extra.metaType, 'area');
+    assert.deepStrictEqual(persisted.extra.items, []);
+    assert.strictEqual(
+      persisted.extra._id, inMemoryId,
+      'persisted _id matches the one sent to the UI'
+    );
+
+    // Idempotent: a second annotate keeps the same persisted _id (the
+    // $eq: null condition prevents overwrite)
+    const doc2 = await apos.doc.db.findOne({ _id: docId });
+    doc2._edit = true;
+    delete doc2.extra; // simulate the missing-area branch firing again
+    await apos.template.annotateDocForExternalFront(doc2);
+    const persistedAgain = await apos.doc.db.findOne({ _id: docId });
+    assert.strictEqual(
+      persistedAgain.extra._id, inMemoryId,
+      'persisted _id is unchanged on re-annotate'
+    );
+
+    await apos.doc.db.deleteOne({ _id: docId });
+  });
+
   it('fetch home with external front', async function() {
     const data = await await apos.http.get('/', {
       headers: {

From c9433138e964db3fd3f4fbcc65d4d9a10f9d9154 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Tue, 2 Jun 2026 13:37:47 -0400
Subject: [PATCH 38/56] PRO-6295: jsx as an optional alternative to nunjucks
 (#5391)

* jsx as an optional alternative to nunjucks

* eslint, all tests pass

* log a useful stack trace on attachment errors! Holy shit!

* fix lint

* clarify behavior

* more tests
pass linter

* This is just a unit test, but it can't hurt to be thorough & satisfy github-advanced-security

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

* true access to the apos object in jsx, per the spec

* more test coverage, no code changes

* fix watchers

---------

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
---
 claude-tools/check-demo-jsx.mjs               |  49 ++
 packages/apostrophe/eslint.config.js          |   1 +
 .../@apostrophecms/attachment/index.js        |   5 +-
 .../modules/@apostrophecms/oembed/index.js    |   3 +-
 .../modules/@apostrophecms/template/index.js  |  66 +++
 .../@apostrophecms/template/lib/jsxLoader.js  | 128 +++++
 .../@apostrophecms/template/lib/jsxRender.js  | 490 ++++++++++++++++
 .../@apostrophecms/template/lib/jsxRuntime.js | 276 +++++++++
 .../template/lib/nunjucksLoader.js            |  47 +-
 .../template/lib/viewWatcher.js               | 108 ++++
 packages/apostrophe/package.json              |   4 +
 .../add-missing-schema-fields-project/test.js |  17 +-
 .../test/modules/jsx-area-test/index.js       |  23 +
 .../modules/jsx-area-test/views/bad-area.jsx  |   7 +
 .../jsx-area-test/views/with-area-ctx.jsx     |  13 +
 .../modules/jsx-area-test/views/with-area.jsx |   7 +
 .../jsx-area-test/views/with-widget-ctx.jsx   |  12 +
 .../jsx-area-test/views/with-widget.jsx       |   7 +
 .../test/modules/jsx-async-widget/index.js    |   6 +
 .../modules/jsx-async-widget/views/widget.jsx |  11 +
 .../test/modules/jsx-bridge-test/index.js     |   1 +
 .../jsx-bridge-test/views/cross-module.jsx    |   7 +
 .../views/disambig-name-only.jsx              |   7 +
 .../jsx-bridge-test/views/disambig-target.jsx |   8 +
 .../views/disambig-with-template-name.jsx     |   7 +
 .../jsx-bridge-test/views/include-html.jsx    |   7 +
 .../jsx-bridge-test/views/include-target.html |   4 +
 .../views/jsx-extends-via-extend.jsx          |   9 +
 .../jsx-bridge-test/views/jsx-extends.jsx     |   9 +
 .../jsx-bridge-test/views/jsx-layout.jsx      |  14 +
 .../jsx-bridge-test/views/njk-extends.jsx     |  14 +
 .../jsx-bridge-test/views/njk-layout.html     |   9 +
 .../jsx-bridge-test/views/short-form.jsx      |   7 +
 .../jsx-bridge-test/views/short-target.jsx    |   3 +
 .../test/modules/jsx-component-test/index.js  |  15 +
 .../jsx-component-test/views/greet.html       |   1 +
 .../views/uses-component.jsx                  |   8 +
 .../test/modules/jsx-ctx-widget/index.js      |   6 +
 .../modules/jsx-ctx-widget/views/widget.jsx   |   4 +
 .../test/modules/jsx-mixed-test/index.js      |   9 +
 .../jsx-mixed-test/views/apos-full.jsx        |  21 +
 .../jsx-mixed-test/views/async-list.jsx       |  12 +
 .../jsx-mixed-test/views/lib/format.js        |   3 +
 .../jsx-mixed-test/views/localized.jsx        |   3 +
 .../modules/jsx-mixed-test/views/partial.jsx  |   3 +
 .../jsx-mixed-test/views/safe-helper.jsx      |   3 +
 .../jsx-mixed-test/views/syntax-error.jsx     |   3 +
 .../modules/jsx-mixed-test/views/throws.jsx   |   5 +
 .../jsx-mixed-test/views/uses-import.jsx      |   5 +
 .../jsx-mixed-test/views/uses-require.jsx     |   5 +
 .../modules/jsx-watcher-cross-test/index.js   |   5 +
 .../views/cross-template.jsx                  |   3 +
 .../test/modules/jsx-watcher-test/index.js    |   5 +
 .../jsx-watcher-test/views/watcher-test.jsx   |   3 +
 .../template-jsx-options-test/index.js        |  12 +
 .../views/options-test.jsx                    |   9 +
 .../template-jsx-subclass-test/index.js       |   3 +
 .../views/override-test.jsx                   |   3 +
 .../test/modules/template-jsx-test/index.js   |   9 +
 .../template-jsx-test/views/boolean-attrs.jsx |  11 +
 .../template-jsx-test/views/class-and-for.jsx |   7 +
 .../views/dangerously-set.jsx                 |   3 +
 .../template-jsx-test/views/escape-attr.jsx   |   3 +
 .../template-jsx-test/views/escape-body.jsx   |   3 +
 .../template-jsx-test/views/inherit-test.jsx  |   3 +
 .../modules/template-jsx-test/views/list.jsx  |   7 +
 .../template-jsx-test/views/override-test.jsx |   3 +
 .../template-jsx-test/views/svg-attrs.jsx     |  27 +
 .../modules/template-jsx-test/views/test.jsx  |   3 +
 .../template-jsx-test/views/void-elements.jsx |   9 +
 .../apostrophe/test/templates-jsx-watcher.js  | 135 +++++
 packages/apostrophe/test/templates-jsx.js     | 537 ++++++++++++++++++
 packages/db-connect/adapters/postgres.js      |   3 -
 packages/db-connect/adapters/sqlite.js        |   4 +-
 packages/db-connect/lib/dump.js               |   2 +-
 packages/db-connect/test/adapter.test.js      |  15 +-
 packages/db-connect/test/shared.test.js       |   2 +-
 77 files changed, 2269 insertions(+), 52 deletions(-)
 create mode 100644 claude-tools/check-demo-jsx.mjs
 create mode 100644 packages/apostrophe/modules/@apostrophecms/template/lib/jsxLoader.js
 create mode 100644 packages/apostrophe/modules/@apostrophecms/template/lib/jsxRender.js
 create mode 100644 packages/apostrophe/modules/@apostrophecms/template/lib/jsxRuntime.js
 create mode 100644 packages/apostrophe/modules/@apostrophecms/template/lib/viewWatcher.js
 create mode 100644 packages/apostrophe/test/modules/jsx-area-test/index.js
 create mode 100644 packages/apostrophe/test/modules/jsx-area-test/views/bad-area.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-area-test/views/with-area-ctx.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-area-test/views/with-area.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-area-test/views/with-widget-ctx.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-area-test/views/with-widget.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-async-widget/index.js
 create mode 100644 packages/apostrophe/test/modules/jsx-async-widget/views/widget.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-bridge-test/index.js
 create mode 100644 packages/apostrophe/test/modules/jsx-bridge-test/views/cross-module.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-bridge-test/views/disambig-name-only.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-bridge-test/views/disambig-target.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-bridge-test/views/disambig-with-template-name.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-bridge-test/views/include-html.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-bridge-test/views/include-target.html
 create mode 100644 packages/apostrophe/test/modules/jsx-bridge-test/views/jsx-extends-via-extend.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-bridge-test/views/jsx-extends.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-bridge-test/views/jsx-layout.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-bridge-test/views/njk-extends.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-bridge-test/views/njk-layout.html
 create mode 100644 packages/apostrophe/test/modules/jsx-bridge-test/views/short-form.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-bridge-test/views/short-target.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-component-test/index.js
 create mode 100644 packages/apostrophe/test/modules/jsx-component-test/views/greet.html
 create mode 100644 packages/apostrophe/test/modules/jsx-component-test/views/uses-component.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-ctx-widget/index.js
 create mode 100644 packages/apostrophe/test/modules/jsx-ctx-widget/views/widget.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-mixed-test/index.js
 create mode 100644 packages/apostrophe/test/modules/jsx-mixed-test/views/apos-full.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-mixed-test/views/async-list.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-mixed-test/views/lib/format.js
 create mode 100644 packages/apostrophe/test/modules/jsx-mixed-test/views/localized.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-mixed-test/views/partial.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-mixed-test/views/safe-helper.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-mixed-test/views/syntax-error.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-mixed-test/views/throws.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-mixed-test/views/uses-import.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-mixed-test/views/uses-require.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-watcher-cross-test/index.js
 create mode 100644 packages/apostrophe/test/modules/jsx-watcher-cross-test/views/cross-template.jsx
 create mode 100644 packages/apostrophe/test/modules/jsx-watcher-test/index.js
 create mode 100644 packages/apostrophe/test/modules/jsx-watcher-test/views/watcher-test.jsx
 create mode 100644 packages/apostrophe/test/modules/template-jsx-options-test/index.js
 create mode 100644 packages/apostrophe/test/modules/template-jsx-options-test/views/options-test.jsx
 create mode 100644 packages/apostrophe/test/modules/template-jsx-subclass-test/index.js
 create mode 100644 packages/apostrophe/test/modules/template-jsx-subclass-test/views/override-test.jsx
 create mode 100644 packages/apostrophe/test/modules/template-jsx-test/index.js
 create mode 100644 packages/apostrophe/test/modules/template-jsx-test/views/boolean-attrs.jsx
 create mode 100644 packages/apostrophe/test/modules/template-jsx-test/views/class-and-for.jsx
 create mode 100644 packages/apostrophe/test/modules/template-jsx-test/views/dangerously-set.jsx
 create mode 100644 packages/apostrophe/test/modules/template-jsx-test/views/escape-attr.jsx
 create mode 100644 packages/apostrophe/test/modules/template-jsx-test/views/escape-body.jsx
 create mode 100644 packages/apostrophe/test/modules/template-jsx-test/views/inherit-test.jsx
 create mode 100644 packages/apostrophe/test/modules/template-jsx-test/views/list.jsx
 create mode 100644 packages/apostrophe/test/modules/template-jsx-test/views/override-test.jsx
 create mode 100644 packages/apostrophe/test/modules/template-jsx-test/views/svg-attrs.jsx
 create mode 100644 packages/apostrophe/test/modules/template-jsx-test/views/test.jsx
 create mode 100644 packages/apostrophe/test/modules/template-jsx-test/views/void-elements.jsx
 create mode 100644 packages/apostrophe/test/templates-jsx-watcher.js
 create mode 100644 packages/apostrophe/test/templates-jsx.js

diff --git a/claude-tools/check-demo-jsx.mjs b/claude-tools/check-demo-jsx.mjs
new file mode 100644
index 0000000000..518fc60019
--- /dev/null
+++ b/claude-tools/check-demo-jsx.mjs
@@ -0,0 +1,49 @@
+// Quick syntax check for every .jsx template under public-demo. Loads
+// each via the same JSX loader used in production and reports compile
+// errors with proper file/line info.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const apostropheRoot = path.resolve(here, '..');
+const require = createRequire(path.join(apostropheRoot, 'packages/apostrophe/index.js'));
+
+const { install } = require(path.join(apostropheRoot, 'packages/apostrophe/modules/@apostrophecms/template/lib/jsxLoader.js'));
+install();
+
+const demoRoot = '/srv/workspace/apostrophecms/public-demo';
+
+function* walk(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === 'data') continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walk(full);
+    } else if (entry.name.endsWith('.jsx')) {
+      yield full;
+    }
+  }
+}
+
+let failed = 0;
+for (const file of walk(demoRoot)) {
+  try {
+    require(file);
+    console.log('OK ', file);
+  } catch (err) {
+    failed += 1;
+    console.error('FAIL', file);
+    console.error('   ', err.message);
+    if (err.stack) {
+      console.error(err.stack.split('\n').slice(1, 5).join('\n'));
+    }
+  }
+}
+
+if (failed > 0) {
+  console.error(`\n${failed} file(s) failed to compile/load.`);
+  process.exit(1);
+}
+console.log(`\nAll JSX templates loaded successfully.`);
diff --git a/packages/apostrophe/eslint.config.js b/packages/apostrophe/eslint.config.js
index 969698e6ef..5169f67265 100644
--- a/packages/apostrophe/eslint.config.js
+++ b/packages/apostrophe/eslint.config.js
@@ -7,6 +7,7 @@ module.exports = defineConfig([
     '**/blueimp/**/*.js',
     'test/public',
     'test/apos-build',
+    'test/modules/jsx-mixed-test/views/syntax-error.jsx',
     'coverage',
     'claude-tools'
   ]),
diff --git a/packages/apostrophe/modules/@apostrophecms/attachment/index.js b/packages/apostrophe/modules/@apostrophecms/attachment/index.js
index da44ba9052..63441912b9 100644
--- a/packages/apostrophe/modules/@apostrophecms/attachment/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/attachment/index.js
@@ -656,7 +656,10 @@ module.exports = {
       // to avoid template errors
       getMissingAttachmentUrl() {
         const defaultIconUrl = '/modules/@apostrophecms/attachment/img/missing-icon.svg';
-        self.apos.util.warn('Template warning: Impossible to retrieve the attachment url since it is missing, a default icon has been set. Please fix this ASAP!');
+        const e = new Error();
+        self.apos.util.warn('Template warning: Impossible to retrieve the attachment url since it is missing, a default icon has been set. Please fix this ASAP!\n\n' +
+          e.stack
+        );
         // Convert static asset path to full URL, which matters when static
         // assets are in uploadfs
         return self.apos.asset.url(defaultIconUrl);
diff --git a/packages/apostrophe/modules/@apostrophecms/oembed/index.js b/packages/apostrophe/modules/@apostrophecms/oembed/index.js
index d21e458da7..f76bfe5ea7 100644
--- a/packages/apostrophe/modules/@apostrophecms/oembed/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/oembed/index.js
@@ -54,7 +54,8 @@ module.exports = {
 
         self.oembetter.allowlist(minimumAllowlist.concat(self.options.allowlist || []));
 
-        const minimumEndpoints = self.options.minimumEndpoints || self.oembetter.suggestedEndpoints;
+        const minimumEndpoints = self.options.minimumEndpoints ||
+          self.oembetter.suggestedEndpoints;
         self.oembetter.endpoints(
           minimumEndpoints.concat(self.options.endpoints || [])
         );
diff --git a/packages/apostrophe/modules/@apostrophecms/template/index.js b/packages/apostrophe/modules/@apostrophecms/template/index.js
index 2884df913b..5cd51cadd5 100644
--- a/packages/apostrophe/modules/@apostrophecms/template/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/template/index.js
@@ -76,6 +76,32 @@ module.exports = {
     self.insertions = {};
     self.runtimeNodes = {};
 
+    // Install the .jsx require hook and teach the JSX runtime about
+    // Nunjucks' SafeString class so its instances pass through unescaped.
+    self.initJsx();
+
+    // Wire up the view-folder watcher with the two default invalidation
+    // handlers — Nunjucks loader caches and compiled .jsx modules. Both
+    // engines share a single set of chokidar watchers so we don't pay
+    // twice for watching the same directories.
+    const jsxLoader = require('./lib/jsxLoader.js');
+    self.onViewChange(function clearNunjucksLoaderCaches() {
+      // Setting `cache = {}` mirrors the historical in-loader behavior
+      // and is exactly what Nunjucks itself reads when looking up a
+      // previously-loaded template.
+      for (const loader of Object.values(self.loaders || {})) {
+        loader.cache = {};
+      }
+    });
+    self.onViewChange(function invalidateJsxModules(filePath) {
+      if (filePath && filePath.endsWith('.jsx')) {
+        jsxLoader.invalidate(path.resolve(filePath));
+      } else {
+        // Anything else (e.g. a Nunjucks file) might be a template imported
+        // by a `.jsx` file via require()/import — be safe and drop them all.
+        jsxLoader.invalidateAll();
+      }
+    });
   },
   handlers(self) {
     return {
@@ -117,9 +143,15 @@ module.exports = {
       },
       'apostrophe:destroy': {
         async nunjucksLoaderCleanup() {
+          // Older code paths used to manage chokidar watchers per loader;
+          // a no-op `destroy()` is still defined for backwards compat.
           for (const loader of Object.values(self.loaders || {})) {
             await loader.destroy();
           }
+        },
+        async closeViewWatchers() {
+          // Tear down chokidar watchers (Nunjucks + JSX share these).
+          await self.closeViewWatchers();
         }
       }
     };
@@ -127,6 +159,19 @@ module.exports = {
   methods(self) {
     return {
       ...require('./lib/bundlesLoader')(self),
+      ...require('./lib/jsxRender')(self),
+      ...require('./lib/viewWatcher')(self),
+
+      // Arm chokidar for the view-folder chain of the module whose views
+      // actually contain the resolved JSX file. For a same-module render
+      // that's the caller; for a cross-module render like
+      // `@apostrophecms/page` rendering `@apostrophecms/home-page:page`
+      // it's the target module. Idempotent per absolute directory.
+      watchJsxRenderTargets(callerModule, resolved) {
+        const owner = (resolved && self.apos.modules[resolved.moduleName]) ||
+          callerModule;
+        self.watchViewFolders(self.getViewFolders(owner));
+      },
 
       // Add helpers in the namespace for a particular module.
       // They will be visible in nunjucks at
@@ -261,6 +306,24 @@ module.exports = {
 
         let result;
 
+        // For named files, resolve through the module's view-folder
+        // chain. Chain position wins: a closer directory's .html/.njk
+        // beats a more distant directory's .jsx. JSX only takes
+        // precedence over Nunjucks within the same directory. See
+        // resolveTemplate. Falling back to Nunjucks happens automatically
+        // below when the resolved file is not JSX.
+        if (type === 'file') {
+          const resolved = self.resolveTemplate(module, s);
+          if (resolved && resolved.kind === 'jsx') {
+            const renderData = self.getRenderDataArgs(req, data, module);
+            result = await self.renderJsxTemplate(req, resolved, renderData, module);
+            if (process.platform === 'win32') {
+              result = result.replaceAll('\r', '');
+            }
+            return result;
+          }
+        }
+
         const args = self.getRenderArgs(req, data, module);
 
         const env = self.getEnv(req, module);
@@ -495,6 +558,9 @@ module.exports = {
         }
         if (!self.loaders[key]) {
           self.loaders[key] = self.newLoader(moduleName, dirs);
+          // Register these dirs with the shared view watcher (idempotent
+          // per absolute path, so calling it for every loader is fine).
+          self.watchViewFolders(dirs);
         }
         return self.loaders[key];
       },
diff --git a/packages/apostrophe/modules/@apostrophecms/template/lib/jsxLoader.js b/packages/apostrophe/modules/@apostrophecms/template/lib/jsxLoader.js
new file mode 100644
index 0000000000..cf5fdfc12d
--- /dev/null
+++ b/packages/apostrophe/modules/@apostrophecms/template/lib/jsxLoader.js
@@ -0,0 +1,128 @@
+// Compiles Apostrophe `.jsx` template files via Babel and registers a
+// `require.extensions['.jsx']` hook so they can be loaded with `require()`
+// (and `import` after CommonJS transformation) just like normal modules.
+//
+// Each compiled module is automatically prefixed with a `require()` of our
+// JSX runtime so the `h` and `Fragment` identifiers produced by the Babel
+// transform resolve without the user importing them. Both `import` and
+// `require` work inside `.jsx` files because the CommonJS transform also
+// runs.
+//
+// Source maps are kept in memory and wired through `source-map-support`,
+// which means stack traces from a JSX template point at the original
+// `views/page.jsx` line/column rather than the compiled output.
+
+const fs = require('fs');
+const Module = require('module');
+const babel = require('@babel/core');
+const sourceMapSupport = require('source-map-support');
+
+const runtimePath = require.resolve('./jsxRuntime.js');
+
+const sourceMaps = new Map();
+let installed = false;
+
+// Idempotent: register the require hook + source-map handler once per
+// process even if multiple Apostrophe instances boot in the same Node
+// process (e.g. tests, multisite).
+function install() {
+  if (installed) {
+    return;
+  }
+  installed = true;
+
+  sourceMapSupport.install({
+    environment: 'node',
+    hookRequire: false,
+    handleUncaughtExceptions: false,
+    retrieveSourceMap(filename) {
+      const map = sourceMaps.get(filename);
+      if (!map) {
+        return null;
+      }
+      return {
+        url: filename,
+        map
+      };
+    }
+  });
+
+  Module._extensions['.jsx'] = function(module, filename) {
+    const src = fs.readFileSync(filename, 'utf-8');
+    const compiled = compile(src, filename);
+    sourceMaps.set(filename, compiled.map);
+    module._compile(compiled.code, filename);
+  };
+}
+
+// Compile a JSX source string for `filename`. Returns `{ code, map }`.
+// `code` is CommonJS-compatible JS with our runtime injected at the top.
+function compile(src, filename) {
+  let result;
+  try {
+    result = babel.transformSync(src, {
+      filename,
+      sourceMaps: true,
+      sourceFileName: filename,
+      babelrc: false,
+      configFile: false,
+      compact: false,
+      plugins: [
+        [
+          require.resolve('@babel/plugin-transform-react-jsx'),
+          {
+            pragma: '__aposJsx.h',
+            pragmaFrag: '__aposJsx.Fragment',
+            useBuiltIns: false,
+            throwIfNamespace: false
+          }
+        ],
+        require.resolve('@babel/plugin-transform-modules-commonjs')
+      ]
+    });
+  } catch (e) {
+    // Babel errors already include code frames pointing at the offending
+    // line/column. Preserve that detail and add the file path for clarity.
+    const err = new Error(`JSX compile error in ${filename}: ${e.message}`);
+    err.cause = e;
+    err.code = 'APOS_JSX_COMPILE_ERROR';
+    err.filename = filename;
+    throw err;
+  }
+
+  // Inject runtime references. Using a single `__aposJsx` namespace avoids
+  // colliding with user variables named `h` or `Fragment` while still
+  // matching the pragma we passed to Babel above. Source maps remain valid
+  // because we only prepend a single line and rely on a leading `\n` to
+  // keep line numbers stable.
+  const prefix = `var __aposJsx = require(${JSON.stringify(runtimePath)});\n`;
+  return {
+    code: prefix + result.code,
+    map: result.map
+  };
+}
+
+// Drop a single .jsx file from the require cache and our source-map cache.
+// Called by the template module's chokidar watcher when a JSX file changes,
+// so the next render picks up the new code without restarting the process.
+function invalidate(filename) {
+  sourceMaps.delete(filename);
+  delete Module._cache[filename];
+}
+
+// Drop every cached .jsx module and source map. Used when watcher events
+// don't carry a specific path or when an unknown view file was modified.
+function invalidateAll() {
+  for (const filename of sourceMaps.keys()) {
+    delete Module._cache[filename];
+  }
+  sourceMaps.clear();
+}
+
+module.exports = {
+  install,
+  compile,
+  invalidate,
+  invalidateAll,
+  runtimePath
+};
diff --git a/packages/apostrophe/modules/@apostrophecms/template/lib/jsxRender.js b/packages/apostrophe/modules/@apostrophecms/template/lib/jsxRender.js
new file mode 100644
index 0000000000..f1320fe20a
--- /dev/null
+++ b/packages/apostrophe/modules/@apostrophecms/template/lib/jsxRender.js
@@ -0,0 +1,490 @@
+// JSX render orchestration. Mixed into the `@apostrophecms/template`
+// module by `index.js`, this file implements:
+//
+// * Template path resolution that walks the same module chain as Nunjucks
+//   but knows about `.jsx` and prefers it when present alongside `.html`.
+// * `renderJsxTemplate(req, resolved, data, module)` which loads the
+//   compiled JSX module, invokes its default-exported function with
+//   `(data, helpers)`, and flattens the resulting node tree into HTML.
+// * The `Area`, `Component`, `Template`, `Extend`, and `Widget` runtime
+//   helpers exposed to JSX templates as the second argument to their
+//   default function.
+// * The cross-engine bridge: when a JSX template invokes `Template`/
+//   `Extend` against a Nunjucks `.html` layout, the helper synthesizes a
+//   Nunjucks string that extends the target and turns each named prop
+//   into a `{% block ... %}` override.
+
+const fs = require('fs');
+const path = require('path');
+const _ = require('lodash');
+
+const jsxLoader = require('./jsxLoader.js');
+const {
+  Raw, flatten, registerSafeClass
+} = require('./jsxRuntime.js');
+
+const TEMPLATE_EXTENSIONS = [ 'jsx', 'njk', 'html' ];
+
+module.exports = function(self) {
+  return {
+    // Install the global JSX `require` hook and teach the runtime about
+    // Nunjucks `SafeString` instances so they pass through unescaped.
+    initJsx() {
+      jsxLoader.install();
+      registerSafeClass(self.nunjucks.runtime.SafeString);
+    },
+
+    // Walk a module's view-folder chain and find the first file matching
+    // `name` with one of the supported extensions. JSX wins over Nunjucks
+    // when both exist in the same directory, but the chain ordering still
+    // takes precedence (a child module's `.html` still overrides a parent
+    // module's `.jsx` if it appears earlier in the chain).
+    //
+    // `name` may be `'localname'` (resolved against the supplied
+    // `module`'s chain) or `'modulename:localname'` (resolved against the
+    // named module's chain). An explicit extension is honored verbatim.
+    //
+    // Returns `{ kind: 'jsx' | 'nunjucks', path, ext, moduleName,
+    // baseName, ext, requestedName }` or `null` when nothing was found.
+    resolveTemplate(module, name) {
+      let moduleName = module.__meta.name;
+      let filename = name;
+      const colonAt = name.indexOf(':');
+      if (colonAt !== -1) {
+        moduleName = name.substring(0, colonAt);
+        filename = name.substring(colonAt + 1);
+      }
+      const targetModule = self.apos.modules[moduleName];
+      if (!targetModule) {
+        return null;
+      }
+      const dirs = self.getViewFolders(targetModule);
+      const m = filename.match(/^(.*)\.([^/.]+)$/);
+      let baseName = filename;
+      let requestedExt = null;
+      if (m) {
+        baseName = m[1];
+        requestedExt = m[2];
+      }
+      // For requests without an extension, or for the well-known template
+      // extensions, allow falling back to any of them. For an unknown
+      // extension (e.g. `.svg`) preserve current Nunjucks-loader behavior:
+      // try only the literal name.
+      const exts = (!requestedExt || TEMPLATE_EXTENSIONS.includes(requestedExt))
+        ? TEMPLATE_EXTENSIONS
+        : [ requestedExt ];
+
+      for (const dir of dirs) {
+        for (const ext of exts) {
+          const fullpath = path.join(dir, `${baseName}.${ext}`);
+          if (fs.existsSync(fullpath)) {
+            return {
+              kind: ext === 'jsx' ? 'jsx' : 'nunjucks',
+              path: fullpath,
+              ext,
+              moduleName,
+              baseName,
+              relativeName: `${baseName}.${ext}`,
+              requestedName: name
+            };
+          }
+        }
+      }
+      return null;
+    },
+
+    // Render the JSX module at `resolved.path` against `data`. Loads the
+    // compiled module via Node's require (the `.jsx` extension hook
+    // installed by `jsxLoader` does the Babel transform on first load),
+    // calls its default function, and flattens the returned node tree.
+    async renderJsxTemplate(req, resolved, data, module) {
+      self.watchJsxRenderTargets(module, resolved);
+      let mod;
+      try {
+        mod = require(resolved.path);
+      } catch (e) {
+        throw decorateJsxError(e, resolved.path);
+      }
+      const fn = (mod && mod.default) || mod;
+      if (typeof fn !== 'function') {
+        throw new Error(
+          `JSX template ${resolved.path} must export a default function. ` +
+          `Got ${typeof fn}.`
+        );
+      }
+      const helpers = self.buildJsxHelpers(req, module, data);
+      let result;
+      try {
+        result = await fn(data, helpers);
+      } catch (e) {
+        throw decorateJsxError(e, resolved.path);
+      }
+      try {
+        return await flatten(result);
+      } catch (e) {
+        throw decorateJsxError(e, resolved.path);
+      }
+    },
+
+    // Build the `{ apos, helpers, Area, Component, Extend, Template,
+    // Widget, ... }` object passed as the second argument to every JSX
+    // template. The closure captures `req`, `module` (the module whose
+    // template is currently being rendered, used to resolve `Template`
+    // names without a `module:` prefix), and `ambientData` (the merged
+    // render data for the current invocation, threaded through
+    // `Template`/`Extend` to mirror Nunjucks' `extends` semantics).
+    buildJsxHelpers(req, module, ambientData) {
+      const helpers = {
+        // Full `self.apos`. Unlike Nunjucks, JSX supports await, so
+        // there is no need to restrict access to this object.
+        apos: self.apos,
+        // The Nunjucks-compatible wrapper. Carries `addHelpers`-registered
+        // helpers under `helpers.modules['module-name'].method(...)` and
+        // module aliases, matching the `apos` object available in
+        // Nunjucks templates. Distinct from the JSX `apos` above.
+        helpers: self.templateApos,
+        // Localization helper, matching the Nunjucks `__t` global.
+        __t: req.t && req.t.bind(req),
+
+        Area: (props) => self.jsxArea(req, props),
+        Component: (props) => self.jsxComponent(req, props),
+        Widget: (props) => self.jsxWidget(req, props),
+        Template: (props) => self.jsxInvoke(req, module, props, {
+          mode: 'include',
+          ambientData
+        }),
+        Extend: (props) => self.jsxInvoke(req, module, props, {
+          mode: 'extend',
+          ambientData
+        })
+      };
+      return helpers;
+    },
+
+    // Implementation of the `<Area doc={..} name=".." with={..} />` helper.
+    // Mirrors the Nunjucks `{% area %}` custom tag closely so behavior
+    // (including stub-area persistence) is identical.
+    jsxArea(req, props) {
+      const {
+        doc, name, with: ctx
+      } = props || {};
+      return (async () => {
+        if (!doc || typeof doc !== 'object') {
+          throw new Error(
+            'Area: the `doc` prop must be an existing doc or widget object.'
+          );
+        }
+        if (typeof name !== 'string') {
+          throw new Error('Area: the `name` prop must be a string.');
+        }
+        if (!name.match(/^\w+$/)) {
+          throw new Error(
+            'Area: area names must consist only of letters, digits, and underscores.'
+          );
+        }
+        let area = doc[name];
+        if (!area) {
+          // Same stub-into-db logic as the {% area %} tag, so that newly
+          // added schema fields get a persistent `_id` on first render.
+          area = {
+            metaType: 'area',
+            _id: self.apos.util.generateId(),
+            items: []
+          };
+          doc[name] = area;
+          const docId = doc._docId || ((doc.metaType === 'doc') ? doc._id : null);
+          if (docId) {
+            let mainDoc = await self.apos.doc.db.findOne({ _id: docId });
+            if (!mainDoc) {
+              throw self.apos.error('notfound');
+            }
+            let docDotPath;
+            try {
+              docDotPath = (doc._id === docId)
+                ? ''
+                : self.apos.util.findNestedObjectAndDotPathById(mainDoc, doc._id).dotPath;
+            } catch (e) {
+              throw self.apos.error('notfound');
+            }
+            const areaDotPath = docDotPath ? `${docDotPath}.${name}` : name;
+            await self.apos.doc.db.updateOne({
+              _id: docId,
+              [areaDotPath]: { $eq: null }
+            }, {
+              $set: {
+                [areaDotPath]: self.apos.util.clonePermanent(area)
+              }
+            });
+            mainDoc = await self.apos.doc.db.findOne({ _id: docId });
+            area._id = self.apos.util.get(mainDoc, areaDotPath)._id;
+          }
+        }
+        const manager = self.apos.util.getManagerOf(doc);
+        const field = manager && manager.schema.find(f => f.name === name);
+        if (!field) {
+          throw new Error(
+            `Area: the doc of type ${doc.type} with the slug ${doc.slug} ` +
+            `has no field named ${name}.`
+          );
+        }
+        area._fieldId = field._id;
+        area._docId = doc._docId || ((doc.metaType === 'doc') ? doc._id : null);
+        area._edit = area._edit || doc._edit;
+        self.apos.area.prepForRender(area, doc, name);
+        const html = await self.apos.area.renderArea(req, area, ctx);
+        return new Raw(html);
+      })();
+    },
+
+    // Implementation of `<Component module="..." name="..." {...props} />`.
+    // Looks up the named async component, awaits it, then renders the
+    // component's matching template via the existing module render path.
+    jsxComponent(req, props) {
+      const {
+        module: moduleName, name, children, ...rest
+      } = props || {};
+      return (async () => {
+        if (typeof moduleName !== 'string' || typeof name !== 'string') {
+          throw new Error(
+            'Component: both `module` and `name` props must be strings.'
+          );
+        }
+        const target = self.apos.modules[moduleName];
+        if (!target) {
+          throw new Error(
+            `Component: module "${moduleName}" does not exist. ` +
+            'It must be a real, instantiated module, not a base class.'
+          );
+        }
+        if (!(target.components && target.components[name])) {
+          throw new Error(
+            `Component: ${moduleName}:${name} is not a registered async component.`
+          );
+        }
+        // Components receive plain data: any JSX nodes passed as props
+        // (including `children`) need to be flattened to HTML strings
+        // first so the underlying Nunjucks/JSX component template can
+        // safely render them.
+        const inputProps = await self.flattenJsxProps({
+          ...rest,
+          children
+        });
+        const result = await self.apos.util.recursionGuard(
+          req,
+          `component:${moduleName}:${name}`,
+          async () => {
+            const input = await target.components[name](req, inputProps);
+            return target.render(req, name, input);
+          }
+        );
+        if (result === undefined) {
+          // Recursion guard kicked in.
+          return new Raw('');
+        }
+        return new Raw(result);
+      })();
+    },
+
+    // Implementation of `<Widget widget={..} options={..} with={..} />`.
+    // Mirrors the Nunjucks `{% widget %}` tag, intended only for users
+    // reimplementing `area.html` in JSX.
+    jsxWidget(req, props) {
+      const {
+        widget, options, with: contextOptions
+      } = props || {};
+      return (async () => {
+        if (!widget) {
+          self.apos.util.warn('a null widget was encountered.');
+          return new Raw('');
+        }
+        const opts = options || {};
+        let ctxOpts = {};
+        if (contextOptions && typeof contextOptions === 'object' && contextOptions[widget.type]) {
+          ctxOpts = (typeof contextOptions[widget.type] === 'object')
+            ? contextOptions[widget.type]
+            : {};
+        }
+        const manager = self.apos.area.getWidgetManager(widget.type);
+        if (!manager) {
+          self.apos.area.warnMissingWidgetType(widget.type);
+          return new Raw('');
+        }
+        const html = await manager.output(req, widget, opts, ctxOpts);
+        return new Raw(html);
+      })();
+    },
+
+    // Shared implementation of `Template` and `Extend`. The rules:
+    //
+    // * Strip `templateName`/`name` per the spec — `templateName` always
+    //   wins as the file selector, otherwise `name` is the file selector
+    //   AND is *not* passed through as a data prop.
+    // * Resolve the file. JSX targets receive the props (plus ambient
+    //   data) and `children` natively; Nunjucks targets receive props
+    //   as block overrides (`extend` mode) or as data (`include` mode
+    //   when called via `Template` against a Nunjucks file).
+    jsxInvoke(req, callerModule, props, { mode, ambientData }) {
+      const {
+        templateName, name, ...rest
+      } = props || {};
+      let targetName;
+      const dataProps = { ...rest };
+      if (templateName !== undefined) {
+        targetName = templateName;
+        // Per spec: `name` is forwarded as a normal prop only when
+        // `templateName` is also present.
+        if (name !== undefined) {
+          dataProps.name = name;
+        }
+      } else {
+        targetName = name;
+      }
+      if (typeof targetName !== 'string') {
+        throw new Error(
+          'Template/Extend: pass a string to the `templateName` prop ' +
+          '(or `name` when no other prop named `name` is needed).'
+        );
+      }
+      return (async () => {
+        const resolved = self.resolveTemplate(callerModule, targetName);
+        if (!resolved) {
+          throw new Error(`Template/Extend: could not resolve template "${targetName}".`);
+        }
+        if (resolved.kind === 'jsx') {
+          // For JSX targets both Template and Extend behave the same:
+          // the props (with the parent's ambient data underneath) are
+          // passed straight through. JSX values like `children` flow as
+          // node trees — they are flattened only when the target template
+          // emits them.
+          const targetModule = self.apos.modules[resolved.moduleName];
+          const merged = {
+            ...(ambientData || {}),
+            ...dataProps
+          };
+          const html = await self.renderJsxTemplate(req, resolved, merged, targetModule);
+          return new Raw(html);
+        }
+        // Nunjucks target.
+        if (mode === 'extend') {
+          return self.renderNunjucksWithBlocks(
+            req, resolved, dataProps, ambientData
+          );
+        }
+        // mode === 'include': render the Nunjucks template with our
+        // props merged on top of ambient data, the same way a Nunjucks
+        // `{% include %}` would inherit data.
+        const flatProps = await self.flattenJsxProps(dataProps);
+        const targetModule = self.apos.modules[resolved.moduleName];
+        const data = {
+          ...(ambientData || {}),
+          ...flatProps
+        };
+        const html = await targetModule.render(req, resolved.relativeName, data);
+        return new Raw(html);
+      })();
+    },
+
+    // Invoke a Nunjucks template via `extends` so that JSX-supplied props
+    // become `{% block %}` overrides. The synthetic Nunjucks template
+    // declares one block per prop, each emitting the matching string
+    // marked safe so already-rendered HTML survives.
+    async renderNunjucksWithBlocks(req, resolved, props, ambientData) {
+      const targetModule = self.apos.modules[resolved.moduleName];
+      const blocks = {};
+      for (const key of Object.keys(props)) {
+        const html = await flattenToHtml(props[key]);
+        blocks[key] = html;
+      }
+      const blockNames = Object.keys(blocks);
+      const targetRef = `${resolved.moduleName}:${resolved.relativeName}`;
+      const lines = [ `{% extends ${JSON.stringify(targetRef)} %}` ];
+      for (const blockName of blockNames) {
+        if (!/^[A-Za-z_][\w]*$/.test(blockName)) {
+          throw new Error(
+            'Template/Extend: prop names used as block overrides must be ' +
+            `valid identifiers (got "${blockName}").`
+          );
+        }
+        lines.push(
+          `{% block ${blockName} %}{{ data.aposJsxBlocks[${JSON.stringify(blockName)}] | safe }}{% endblock %}`
+        );
+      }
+      const synthetic = lines.join('\n');
+      // Layer ambient page data underneath so the Nunjucks layout has
+      // access to `data.outerLayout`, `data.page`, etc.; our blocks
+      // override only what they explicitly name.
+      const data = {
+        ...(ambientData || {}),
+        aposJsxBlocks: blocks
+      };
+      const html = await targetModule.renderString(req, synthetic, data);
+      return new Raw(html);
+    },
+
+    // Walk a props object, flattening any JSX node values to HTML strings
+    // so they can cross into Nunjucks (which can't deal with our internal
+    // node arrays). Plain primitive props pass through unchanged.
+    async flattenJsxProps(props) {
+      const out = {};
+      for (const key of Object.keys(props)) {
+        const value = props[key];
+        if (value === undefined) {
+          continue;
+        }
+        if (isJsxNode(value)) {
+          out[key] = self.safe(await flatten(value));
+        } else {
+          out[key] = value;
+        }
+      }
+      return out;
+    }
+  };
+};
+
+// Decide whether a value should be flattened by the JSX runtime before
+// being handed to Nunjucks. Arrays, Raw markers, and thenables produced
+// by our helpers all need flattening; everything else (strings, numbers,
+// docs, options objects) is forwarded as-is.
+function isJsxNode(value) {
+  if (value == null) {
+    return false;
+  }
+  if (Array.isArray(value)) {
+    return true;
+  }
+  if (value instanceof Raw) {
+    return true;
+  }
+  if (typeof value === 'object' && typeof value.then === 'function') {
+    return true;
+  }
+  return false;
+}
+
+// Convenience wrapper used when a JSX-supplied prop becomes a Nunjucks
+// block override: regardless of input type, produce the final HTML string
+// that the synthesized template will emit via the `safe` filter.
+async function flattenToHtml(value) {
+  if (value == null || value === false) {
+    return '';
+  }
+  if (isJsxNode(value)) {
+    return await flatten(value);
+  }
+  return String(value);
+}
+
+// Annotate exceptions thrown out of a JSX template with the file path so
+// the error log clearly identifies which template failed. Source maps
+// (installed by `jsxLoader`) take care of accurate line/column info.
+function decorateJsxError(error, file) {
+  if (!error || typeof error !== 'object') {
+    return error;
+  }
+  if (!error.aposJsxFile) {
+    error.aposJsxFile = file;
+    error.message = `[JSX template ${file}] ${error.message}`;
+  }
+  return error;
+}
diff --git a/packages/apostrophe/modules/@apostrophecms/template/lib/jsxRuntime.js b/packages/apostrophe/modules/@apostrophecms/template/lib/jsxRuntime.js
new file mode 100644
index 0000000000..915a11900c
--- /dev/null
+++ b/packages/apostrophe/modules/@apostrophecms/template/lib/jsxRuntime.js
@@ -0,0 +1,276 @@
+// JSX runtime used by Apostrophe `.jsx` templates. The classic Babel
+// transform (`@babel/plugin-transform-react-jsx`) compiles `<Tag a={x}>...</Tag>`
+// into `h(Tag, { a: x }, ...children)` and `<>...</>` into
+// `h(Fragment, null, ...children)`. The `h` function and `Fragment` symbol
+// are injected into every compiled module by `jsxLoader.js`.
+//
+// Output model: `h` returns a nested array of strings, `Raw` markers,
+// promises, and arrays. The array is flattened by `flatten()` which awaits
+// every promise, escapes plain string values, and joins everything into a
+// final HTML string. This array+promise model is what allows JSX templates
+// to call asynchronous helpers (`Area`, `Component`, `Template`, `Extend`)
+// directly inside markup without wrapping them in `await`.
+
+const voidElements = require('void-elements');
+
+const Fragment = Symbol('AposJsxFragment');
+
+// Marker class for already-rendered raw HTML. Anything wrapped in a `Raw`
+// is emitted into the final output without any additional escaping.
+class Raw {
+  constructor(html) {
+    this.html = (html == null) ? '' : String(html);
+  }
+}
+
+// Compatibility hook: Nunjucks `SafeString` instances (returned by Apostrophe
+// helpers like `apos.area.html()` and the `safe` filter) need to flow through
+// JSX templates without being escaped a second time. `template/index.js`
+// registers Nunjucks's `SafeString` class via `registerSafeClass()`; any
+// instance of a registered class is treated as raw HTML.
+const safeClasses = [];
+
+function registerSafeClass(cls) {
+  if (cls && !safeClasses.includes(cls)) {
+    safeClasses.push(cls);
+  }
+}
+
+function isSafeInstance(value) {
+  if (value == null || typeof value !== 'object') {
+    return false;
+  }
+  for (const cls of safeClasses) {
+    if (value instanceof cls) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function escapeAttr(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+// Build the JSX node for an element, function component, or fragment.
+// For function types (including the runtime helpers `Area`, `Component`,
+// `Template`, `Extend`, `Widget`) we invoke the function with a single
+// `props` object that includes `children`, matching React conventions.
+function h(type, props, ...children) {
+  props = props || {};
+  if (type === Fragment) {
+    return children;
+  }
+  if (typeof type === 'function') {
+    const finalProps = { ...props };
+    if (children.length > 0) {
+      finalProps.children = (children.length === 1) ? children[0] : children;
+    }
+    return type(finalProps);
+  }
+  if (typeof type !== 'string') {
+    throw new Error(`Invalid JSX element type: ${typeof type}`);
+  }
+  return buildElement(type, props, children);
+}
+
+function buildElement(tag, props, children) {
+  let attrs = '';
+  let dangerous = null;
+  for (const key of Object.keys(props)) {
+    if (key === 'children' || key === 'key' || key === 'ref') {
+      continue;
+    }
+    if (key === 'dangerouslySetInnerHTML') {
+      const v = props[key];
+      if (v && typeof v.__html === 'string') {
+        dangerous = v.__html;
+      } else if (v && v.__html != null) {
+        dangerous = String(v.__html);
+      }
+      continue;
+    }
+    const value = props[key];
+    if (value == null || value === false) {
+      continue;
+    }
+    const attrName = jsxAttrName(key);
+    if (value === true) {
+      attrs += ` ${attrName}`;
+    } else {
+      attrs += ` ${attrName}="${escapeAttr(value)}"`;
+    }
+  }
+
+  if (dangerous != null) {
+    return [
+      new Raw(`<${tag}${attrs}>`),
+      new Raw(dangerous),
+      new Raw(`</${tag}>`)
+    ];
+  }
+
+  if (voidElements[tag] && children.length === 0) {
+    return [ new Raw(`<${tag}${attrs} />`) ];
+  }
+
+  return [
+    new Raw(`<${tag}${attrs}>`),
+    ...children,
+    new Raw(`</${tag}>`)
+  ];
+}
+
+// Match React's friendly attribute names to standard HTML/SVG attribute
+// names. `data-*` and `aria-*` props pass through verbatim; SVG presentation
+// attributes (`strokeWidth`, `fillRule`, etc.) are converted to the
+// kebab-case form actually understood by browsers when the document is
+// parsed as text/html. The handful of SVG attributes that are *natively*
+// camelCase (e.g. `viewBox`, `preserveAspectRatio`) stay as-is.
+const svgAttrMap = {
+  // Stroke
+  strokeWidth: 'stroke-width',
+  strokeLinecap: 'stroke-linecap',
+  strokeLinejoin: 'stroke-linejoin',
+  strokeDasharray: 'stroke-dasharray',
+  strokeDashoffset: 'stroke-dashoffset',
+  strokeMiterlimit: 'stroke-miterlimit',
+  strokeOpacity: 'stroke-opacity',
+  // Fill
+  fillOpacity: 'fill-opacity',
+  fillRule: 'fill-rule',
+  // Clip / mask
+  clipPath: 'clip-path',
+  clipRule: 'clip-rule',
+  // Text
+  textAnchor: 'text-anchor',
+  textDecoration: 'text-decoration',
+  alignmentBaseline: 'alignment-baseline',
+  baselineShift: 'baseline-shift',
+  dominantBaseline: 'dominant-baseline',
+  fontFamily: 'font-family',
+  fontSize: 'font-size',
+  fontStyle: 'font-style',
+  fontVariant: 'font-variant',
+  fontWeight: 'font-weight',
+  letterSpacing: 'letter-spacing',
+  wordSpacing: 'word-spacing',
+  // Generic
+  colorInterpolation: 'color-interpolation',
+  colorInterpolationFilters: 'color-interpolation-filters',
+  colorProfile: 'color-profile',
+  colorRendering: 'color-rendering',
+  fillRendering: 'fill-rendering',
+  imageRendering: 'image-rendering',
+  shapeRendering: 'shape-rendering',
+  textRendering: 'text-rendering',
+  pointerEvents: 'pointer-events',
+  unicodeBidi: 'unicode-bidi',
+  vectorEffect: 'vector-effect',
+  writingMode: 'writing-mode',
+  enableBackground: 'enable-background',
+  floodColor: 'flood-color',
+  floodOpacity: 'flood-opacity',
+  glyphOrientationHorizontal: 'glyph-orientation-horizontal',
+  glyphOrientationVertical: 'glyph-orientation-vertical',
+  lightingColor: 'lighting-color',
+  markerEnd: 'marker-end',
+  markerMid: 'marker-mid',
+  markerStart: 'marker-start',
+  overflowWrap: 'overflow-wrap',
+  paintOrder: 'paint-order',
+  stopColor: 'stop-color',
+  stopOpacity: 'stop-opacity',
+  // Linked references
+  xlinkHref: 'xlink:href',
+  xlinkRole: 'xlink:role',
+  xlinkTitle: 'xlink:title',
+  xlinkType: 'xlink:type',
+  xlinkArcrole: 'xlink:arcrole',
+  xlinkActuate: 'xlink:actuate',
+  xlinkShow: 'xlink:show',
+  xmlBase: 'xml:base',
+  xmlLang: 'xml:lang',
+  xmlSpace: 'xml:space',
+  xmlnsXlink: 'xmlns:xlink'
+};
+
+function jsxAttrName(name) {
+  if (name === 'className') {
+    return 'class';
+  }
+  if (name === 'htmlFor') {
+    return 'for';
+  }
+  const svg = svgAttrMap[name];
+  if (svg) {
+    return svg;
+  }
+  return name;
+}
+
+// Walk the tree of strings, Raw markers, promises, and arrays, awaiting
+// every promise and producing a final HTML string. Plain strings/numbers
+// are escaped; Raw and Nunjucks SafeString values are not.
+async function flatten(node) {
+  const out = [];
+  await walk(node, out);
+  return out.join('');
+}
+
+async function walk(node, out) {
+  if (node == null || node === false || node === true) {
+    return;
+  }
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      await walk(item, out);
+    }
+    return;
+  }
+  if (node instanceof Raw) {
+    out.push(node.html);
+    return;
+  }
+  if (isSafeInstance(node)) {
+    out.push(node.toString());
+    return;
+  }
+  if (typeof node === 'object' && typeof node.then === 'function') {
+    const resolved = await node;
+    await walk(resolved, out);
+    return;
+  }
+  if (typeof node === 'string') {
+    out.push(escapeHtml(node));
+    return;
+  }
+  if (typeof node === 'number' || typeof node === 'bigint') {
+    out.push(escapeHtml(String(node)));
+    return;
+  }
+  // Anything else (objects without a known handler) is coerced to string
+  // and escaped, mirroring how React stringifies unexpected children.
+  out.push(escapeHtml(String(node)));
+}
+
+module.exports = {
+  h,
+  Fragment,
+  Raw,
+  flatten,
+  escapeHtml,
+  escapeAttr,
+  registerSafeClass
+};
diff --git a/packages/apostrophe/modules/@apostrophecms/template/lib/nunjucksLoader.js b/packages/apostrophe/modules/@apostrophecms/template/lib/nunjucksLoader.js
index 3bfe99801b..38c0bd133f 100644
--- a/packages/apostrophe/modules/@apostrophecms/template/lib/nunjucksLoader.js
+++ b/packages/apostrophe/modules/@apostrophecms/template/lib/nunjucksLoader.js
@@ -7,23 +7,26 @@
 // Note that if @apostrophecms/template has a project-level override
 // of outerLayout.html, that will be loaded instead. This is
 // intentional.
+//
+// File watching and cache invalidation are deliberately NOT handled here:
+// the template module wires up `viewWatcher.js` once for both Nunjucks and
+// JSX, and clears every loader's `cache` (read by Nunjucks itself) when a
+// view file changes.
 
 const fs = require('fs');
 const path = require('path');
 const _ = require('lodash');
 const { stripIndent } = require('common-tags');
-const chokidar = require('chokidar');
 
 module.exports = function(moduleName, searchPaths, noWatch, templates, options) {
 
   const self = this;
-  self.watches = [];
   options = options || {};
   const extensions = options.extensions || [ 'njk', 'html' ];
   self.moduleName = moduleName;
   self.templates = templates;
 
-  self.init = function(searchPaths, noWatch) {
+  self.init = function(searchPaths) {
     self.pathsToNames = {};
     if (searchPaths) {
       searchPaths = Array.isArray(searchPaths) ? searchPaths : [ searchPaths ];
@@ -32,34 +35,6 @@ module.exports = function(moduleName, searchPaths, noWatch, templates, options)
     } else {
       self.searchPaths = [];
     }
-    // Unless and until chokidar declares this a supported config,
-    // no watching in WSL (it doesn't work without chokidar either)
-    if ((!noWatch) && (!require('is-wsl'))) {
-      _.each(self.searchPaths, function(p) {
-        if (fs.existsSync(p)) {
-          try {
-            const watcher = chokidar.watch(p);
-            watcher.on('change', (path, stats) => {
-              // Just blow the whole cache if anything is modified. Much
-              // simpler, avoids several false negatives, and works well for a
-              // CMS in dev. -Tom
-              self.cache = {};
-            });
-            self.watches.push(watcher);
-          } catch (e) {
-            if (!self.firstWatchFailure) {
-              // Don't crash in broken environments (not sure if any are left
-              // thanks to chokidar, but still a useful warning to have if it
-              // comes up)
-              self.firstWatchFailure = true;
-              self.templates.apos.util.warn('WARNING: fs.watch does not work on this system. That is OK but you\n' +
-                'will have to restart to see any template changes take effect.');
-            }
-            self.templates.apos.util.error(e);
-          }
-        }
-      });
-    }
   };
 
   self.isRelative = function(filename) {
@@ -183,11 +158,11 @@ module.exports = function(moduleName, searchPaths, noWatch, templates, options)
     }
   };
 
-  self.destroy = async () => {
-    for (const watch of self.watches) {
-      await watch.close();
-    }
-  };
+  // Retained for backwards compatibility — file watching now lives in
+  // `viewWatcher.js`, owned by the template module itself, so there is
+  // nothing for the loader to dispose of. Callers (Apostrophe internals
+  // and tests) may still invoke `destroy()` and that must keep working.
+  self.destroy = async () => {};
 
   self.init(searchPaths, noWatch);
 };
diff --git a/packages/apostrophe/modules/@apostrophecms/template/lib/viewWatcher.js b/packages/apostrophe/modules/@apostrophecms/template/lib/viewWatcher.js
new file mode 100644
index 0000000000..5442f71432
--- /dev/null
+++ b/packages/apostrophe/modules/@apostrophecms/template/lib/viewWatcher.js
@@ -0,0 +1,108 @@
+// File-watching for view directories shared by Nunjucks and JSX.
+//
+// Owns one chokidar watcher per directory and dispatches change events to
+// any number of registered handlers. The template module wires this up at
+// init time with two handlers: clear every Nunjucks loader's cache, and
+// invalidate compiled `.jsx` modules so the next render reloads them.
+//
+// WSL safety: chokidar's underlying file events are unreliable on WSL, so
+// we deliberately skip watching there — same behavior as the previous
+// in-loader code. Developers running on WSL will need to restart to pick
+// up template edits, but the rest of Apostrophe still functions.
+//
+// Returns a methods mixin compatible with `@apostrophecms/module`'s
+// `methods` factory pattern, the same way `bundlesLoader` and `jsxRender`
+// are mixed in.
+
+const fs = require('fs');
+const chokidar = require('chokidar');
+const isWsl = require('is-wsl');
+
+module.exports = (self) => {
+  // Lazily-allocated state. Lives on `self` so it survives across method
+  // calls and can be inspected by tests if needed.
+  if (!self._viewWatchers) {
+    self._viewWatchers = [];
+  }
+  if (!self._viewWatchedDirs) {
+    self._viewWatchedDirs = new Set();
+  }
+  if (!self._viewChangeHandlers) {
+    self._viewChangeHandlers = [];
+  }
+
+  return {
+    // Begin watching the supplied directories for change events. Idempotent
+    // per absolute path: subsequent calls with the same dir do not create
+    // duplicate watchers. Honors the WSL skip flag and the loader's
+    // `noWatch` option (templates module exposes this via
+    // `options.loader.noWatch`).
+    watchViewFolders(dirs) {
+      if (self.options.loader && self.options.loader.noWatch) {
+        return;
+      }
+      // chokidar's recursive watching is not reliable on WSL; preserve the
+      // historical behavior of skipping watch setup entirely there.
+      if (isWsl) {
+        return;
+      }
+      for (const dir of dirs) {
+        if (self._viewWatchedDirs.has(dir)) {
+          continue;
+        }
+        if (!fs.existsSync(dir)) {
+          continue;
+        }
+        self._viewWatchedDirs.add(dir);
+        try {
+          const watcher = chokidar.watch(dir);
+          watcher.on('change', (filePath) => {
+            for (const handler of self._viewChangeHandlers) {
+              try {
+                handler(filePath);
+              } catch (e) {
+                self.apos.util.error(e);
+              }
+            }
+          });
+          self._viewWatchers.push(watcher);
+        } catch (e) {
+          // Don't crash in broken environments. Warn at most once so the
+          // logs don't get spammed for every dir we fail to watch.
+          if (!self._viewFirstWatchFailure) {
+            self._viewFirstWatchFailure = true;
+            self.apos.util.warn(
+              'WARNING: fs.watch does not work on this system. That is OK but you\n' +
+              'will have to restart to see any template changes take effect.'
+            );
+          }
+          self.apos.util.error(e);
+        }
+      }
+    },
+
+    // Register a callback invoked with the absolute path of the changed
+    // file every time chokidar reports a `change` event. Handlers run in
+    // registration order. Errors thrown by a handler are logged but never
+    // stop other handlers from running.
+    onViewChange(handler) {
+      self._viewChangeHandlers.push(handler);
+    },
+
+    // Tear down every chokidar watcher created via `watchViewFolders`.
+    // Called from the `apostrophe:destroy` handler so a process that
+    // builds and tears down multiple Apostrophe instances (tests, the
+    // multisite harness) doesn't leak file descriptors.
+    async closeViewWatchers() {
+      const watchers = self._viewWatchers.splice(0, self._viewWatchers.length);
+      self._viewWatchedDirs.clear();
+      for (const watcher of watchers) {
+        try {
+          await watcher.close();
+        } catch (e) {
+          self.apos.util.error(e);
+        }
+      }
+    }
+  };
+};
diff --git a/packages/apostrophe/package.json b/packages/apostrophe/package.json
index 850b2c9d12..94c83a7382 100644
--- a/packages/apostrophe/package.json
+++ b/packages/apostrophe/package.json
@@ -39,6 +39,9 @@
   "dependencies": {
     "@apostrophecms/db-connect": "workspace:^",
     "@apostrophecms/vue-material-design-icons": "^1.0.0",
+    "@babel/core": "^7.29.0",
+    "@babel/plugin-transform-modules-commonjs": "^7.28.0",
+    "@babel/plugin-transform-react-jsx": "^7.28.0",
     "@ctrl/tinycolor": "^4.1.0",
     "@floating-ui/dom": "^1.5.3",
     "@opentelemetry/api": "^1.9.0",
@@ -126,6 +129,7 @@
     "sluggo": "^1.0.0",
     "sortablejs": "^1.15.0",
     "sortablejs-vue3": "^1.2.11",
+    "source-map-support": "^0.5.21",
     "tiny-emitter": "^2.1.0",
     "tough-cookie": "^4.0.0",
     "underscore.string": "^3.3.4",
diff --git a/packages/apostrophe/test/add-missing-schema-fields-project/test.js b/packages/apostrophe/test/add-missing-schema-fields-project/test.js
index 819a96c445..9d84f01341 100644
--- a/packages/apostrophe/test/add-missing-schema-fields-project/test.js
+++ b/packages/apostrophe/test/add-missing-schema-fields-project/test.js
@@ -16,7 +16,12 @@ describe('Apostrophe - add-missing-schema-fields task', function() {
   const projectCwd = path.resolve(process.cwd(), 'test/add-missing-schema-fields-project/');
   const testDbUri = t.getTestDbUri('add-missing-schema-fields-project');
   const execEnv = testDbUri
-    ? { env: { ...process.env, APOS_DB_URI: testDbUri } }
+    ? {
+      env: {
+        ...process.env,
+        APOS_DB_URI: testDbUri
+      }
+    }
     : {};
 
   before(async function() {
@@ -33,7 +38,10 @@ describe('Apostrophe - add-missing-schema-fields task', function() {
   it('should not run migrations when running the task', async function() {
     await util.promisify(exec)(
       'node app.js @apostrophecms/migration:add-missing-schema-fields',
-      { cwd: projectCwd, ...execEnv }
+      {
+        cwd: projectCwd,
+        ...execEnv
+      }
     );
 
     apos = await t.create({
@@ -72,7 +80,10 @@ describe('Apostrophe - add-missing-schema-fields task', function() {
   it('should run migrations when running @apostrophecms/migration:migrate task', async function() {
     await util.promisify(exec)(
       'node app.js @apostrophecms/migration:migrate',
-      { cwd: projectCwd, ...execEnv }
+      {
+        cwd: projectCwd,
+        ...execEnv
+      }
     );
 
     apos = await t.create({
diff --git a/packages/apostrophe/test/modules/jsx-area-test/index.js b/packages/apostrophe/test/modules/jsx-area-test/index.js
new file mode 100644
index 0000000000..e750c729b2
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-area-test/index.js
@@ -0,0 +1,23 @@
+module.exports = {
+  extend: '@apostrophecms/piece-type',
+  options: {
+    alias: 'jsxAreaTest',
+    name: 'jsx-area-test',
+    label: 'JSX Area Test'
+  },
+  fields: {
+    add: {
+      main: {
+        type: 'area',
+        label: 'Main',
+        options: {
+          widgets: {
+            '@apostrophecms/rich-text': {},
+            'jsx-async': {},
+            'jsx-ctx': {}
+          }
+        }
+      }
+    }
+  }
+};
diff --git a/packages/apostrophe/test/modules/jsx-area-test/views/bad-area.jsx b/packages/apostrophe/test/modules/jsx-area-test/views/bad-area.jsx
new file mode 100644
index 0000000000..d9ce539fec
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-area-test/views/bad-area.jsx
@@ -0,0 +1,7 @@
+export default function (data, { Area }) {
+  return (
+    <main>
+      <Area doc={data.piece} name='nope' />
+    </main>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-area-test/views/with-area-ctx.jsx b/packages/apostrophe/test/modules/jsx-area-test/views/with-area-ctx.jsx
new file mode 100644
index 0000000000..da3cb9b266
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-area-test/views/with-area-ctx.jsx
@@ -0,0 +1,13 @@
+export default function (data, { Area }) {
+  return (
+    <main>
+      <Area
+        doc={data.piece}
+        name='main'
+        with={{
+          'jsx-ctx': { tag: 'from-area-with' }
+        }}
+      />
+    </main>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-area-test/views/with-area.jsx b/packages/apostrophe/test/modules/jsx-area-test/views/with-area.jsx
new file mode 100644
index 0000000000..99a1985f53
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-area-test/views/with-area.jsx
@@ -0,0 +1,7 @@
+export default function (data, { Area }) {
+  return (
+    <main>
+      <Area doc={data.piece} name='main' />
+    </main>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-area-test/views/with-widget-ctx.jsx b/packages/apostrophe/test/modules/jsx-area-test/views/with-widget-ctx.jsx
new file mode 100644
index 0000000000..17aedd9bd5
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-area-test/views/with-widget-ctx.jsx
@@ -0,0 +1,12 @@
+export default function (data, { Widget }) {
+  return (
+    <section class='wrapper'>
+      <Widget
+        widget={data.widget}
+        with={{
+          'jsx-ctx': { tag: 'from-widget-with' }
+        }}
+      />
+    </section>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-area-test/views/with-widget.jsx b/packages/apostrophe/test/modules/jsx-area-test/views/with-widget.jsx
new file mode 100644
index 0000000000..a1e801e38b
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-area-test/views/with-widget.jsx
@@ -0,0 +1,7 @@
+export default function (data, { Widget }) {
+  return (
+    <section class='wrapper'>
+      <Widget widget={data.widget} />
+    </section>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-async-widget/index.js b/packages/apostrophe/test/modules/jsx-async-widget/index.js
new file mode 100644
index 0000000000..6c4bdf2899
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-async-widget/index.js
@@ -0,0 +1,6 @@
+module.exports = {
+  extend: '@apostrophecms/widget-type',
+  options: {
+    label: 'JSX Async Widget'
+  }
+};
diff --git a/packages/apostrophe/test/modules/jsx-async-widget/views/widget.jsx b/packages/apostrophe/test/modules/jsx-async-widget/views/widget.jsx
new file mode 100644
index 0000000000..9ad8ce16e8
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-async-widget/views/widget.jsx
@@ -0,0 +1,11 @@
+export default function (data, { Component }) {
+  return (
+    <div class='async-widget'>
+      <Component
+        module='jsx-component-test'
+        name='greet'
+        who={data.widget.who}
+      />
+    </div>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-bridge-test/index.js b/packages/apostrophe/test/modules/jsx-bridge-test/index.js
new file mode 100644
index 0000000000..f053ebf797
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-bridge-test/index.js
@@ -0,0 +1 @@
+module.exports = {};
diff --git a/packages/apostrophe/test/modules/jsx-bridge-test/views/cross-module.jsx b/packages/apostrophe/test/modules/jsx-bridge-test/views/cross-module.jsx
new file mode 100644
index 0000000000..f80d7e44fb
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-bridge-test/views/cross-module.jsx
@@ -0,0 +1,7 @@
+export default function (data, { Template }) {
+  return (
+    <div>
+      <Template name='jsx-mixed-test:partial' item='from-cross-module' />
+    </div>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-bridge-test/views/disambig-name-only.jsx b/packages/apostrophe/test/modules/jsx-bridge-test/views/disambig-name-only.jsx
new file mode 100644
index 0000000000..53e3b52420
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-bridge-test/views/disambig-name-only.jsx
@@ -0,0 +1,7 @@
+export default function (data, { Template }) {
+  return (
+    <div>
+      <Template name='disambig-target' foo='bar' />
+    </div>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-bridge-test/views/disambig-target.jsx b/packages/apostrophe/test/modules/jsx-bridge-test/views/disambig-target.jsx
new file mode 100644
index 0000000000..1f35c9e439
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-bridge-test/views/disambig-target.jsx
@@ -0,0 +1,8 @@
+export default function (data) {
+  return (
+    <p
+      data-name={String(data.name)}
+      data-template-name={String(data.templateName)}
+    />
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-bridge-test/views/disambig-with-template-name.jsx b/packages/apostrophe/test/modules/jsx-bridge-test/views/disambig-with-template-name.jsx
new file mode 100644
index 0000000000..446f868793
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-bridge-test/views/disambig-with-template-name.jsx
@@ -0,0 +1,7 @@
+export default function (data, { Template }) {
+  return (
+    <div>
+      <Template templateName='disambig-target.jsx' name='forwarded-value' />
+    </div>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-bridge-test/views/include-html.jsx b/packages/apostrophe/test/modules/jsx-bridge-test/views/include-html.jsx
new file mode 100644
index 0000000000..d613cb472b
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-bridge-test/views/include-html.jsx
@@ -0,0 +1,7 @@
+export default function (data, { Template }) {
+  return (
+    <div>
+      <Template templateName='include-target.html' content='prop-content' />
+    </div>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-bridge-test/views/include-target.html b/packages/apostrophe/test/modules/jsx-bridge-test/views/include-target.html
new file mode 100644
index 0000000000..3ab7c0dfa9
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-bridge-test/views/include-target.html
@@ -0,0 +1,4 @@
+<section class="include-target">
+  <p class="block-output">{% block content %}default-block{% endblock %}</p>
+  <p class="data-output">{{ data.content }}</p>
+</section>
diff --git a/packages/apostrophe/test/modules/jsx-bridge-test/views/jsx-extends-via-extend.jsx b/packages/apostrophe/test/modules/jsx-bridge-test/views/jsx-extends-via-extend.jsx
new file mode 100644
index 0000000000..6a8b61aa27
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-bridge-test/views/jsx-extends-via-extend.jsx
@@ -0,0 +1,9 @@
+export default function (data, { Extend }) {
+  return (
+    <Extend templateName='jsx-layout.jsx' title='Extend-against-JSX'>
+      <main>
+        <p>{data.message}</p>
+      </main>
+    </Extend>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-bridge-test/views/jsx-extends.jsx b/packages/apostrophe/test/modules/jsx-bridge-test/views/jsx-extends.jsx
new file mode 100644
index 0000000000..8c642524d3
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-bridge-test/views/jsx-extends.jsx
@@ -0,0 +1,9 @@
+export default function (data, { Template }) {
+  return (
+    <Template templateName='jsx-layout.jsx' title='JSX-in-JSX'>
+      <main>
+        <p>{data.message}</p>
+      </main>
+    </Template>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-bridge-test/views/jsx-layout.jsx b/packages/apostrophe/test/modules/jsx-bridge-test/views/jsx-layout.jsx
new file mode 100644
index 0000000000..3e6c04ed89
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-bridge-test/views/jsx-layout.jsx
@@ -0,0 +1,14 @@
+export default function (data) {
+  return (
+    <html>
+      <head>
+        <title>{data.title || 'default title'}</title>
+      </head>
+      <body>
+        <header>shared header</header>
+        {data.children}
+        <footer>shared footer</footer>
+      </body>
+    </html>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-bridge-test/views/njk-extends.jsx b/packages/apostrophe/test/modules/jsx-bridge-test/views/njk-extends.jsx
new file mode 100644
index 0000000000..88f504ca76
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-bridge-test/views/njk-extends.jsx
@@ -0,0 +1,14 @@
+export default function (data, { Extend }) {
+  return (
+    <Extend
+      templateName='njk-layout.html'
+      title='A JSX page'
+      main={
+        <main>
+          <h1>I am from JSX</h1>
+          <p>{data.message}</p>
+        </main>
+      }
+    />
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-bridge-test/views/njk-layout.html b/packages/apostrophe/test/modules/jsx-bridge-test/views/njk-layout.html
new file mode 100644
index 0000000000..f509141d36
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-bridge-test/views/njk-layout.html
@@ -0,0 +1,9 @@
+<!doctype html>
+<html>
+  <head>
+    <title>{% block title %}default title{% endblock %}</title>
+  </head>
+  <body data-page="{{ data.pageSlug }}">
+    {% block main %}default body{% endblock %}
+  </body>
+</html>
diff --git a/packages/apostrophe/test/modules/jsx-bridge-test/views/short-form.jsx b/packages/apostrophe/test/modules/jsx-bridge-test/views/short-form.jsx
new file mode 100644
index 0000000000..c8d5823009
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-bridge-test/views/short-form.jsx
@@ -0,0 +1,7 @@
+export default function (data, { Template }) {
+  return (
+    <div>
+      <Template name='short-target' message='from-short' />
+    </div>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-bridge-test/views/short-target.jsx b/packages/apostrophe/test/modules/jsx-bridge-test/views/short-target.jsx
new file mode 100644
index 0000000000..384131e230
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-bridge-test/views/short-target.jsx
@@ -0,0 +1,3 @@
+export default function (data) {
+  return <p>short:{data.message}</p>;
+}
diff --git a/packages/apostrophe/test/modules/jsx-component-test/index.js b/packages/apostrophe/test/modules/jsx-component-test/index.js
new file mode 100644
index 0000000000..56f0a6954a
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-component-test/index.js
@@ -0,0 +1,15 @@
+const Promise = require('bluebird');
+
+module.exports = {
+  components(self) {
+    return {
+      async greet(req, input) {
+        await Promise.delay(20);
+        return {
+          who: input.who,
+          afterDelay: true
+        };
+      }
+    };
+  }
+};
diff --git a/packages/apostrophe/test/modules/jsx-component-test/views/greet.html b/packages/apostrophe/test/modules/jsx-component-test/views/greet.html
new file mode 100644
index 0000000000..4c474f3a02
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-component-test/views/greet.html
@@ -0,0 +1 @@
+<span class="greet">Hello {{ data.who }}{% if data.afterDelay %} (after delay){% endif %}</span>
diff --git a/packages/apostrophe/test/modules/jsx-component-test/views/uses-component.jsx b/packages/apostrophe/test/modules/jsx-component-test/views/uses-component.jsx
new file mode 100644
index 0000000000..fa69353369
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-component-test/views/uses-component.jsx
@@ -0,0 +1,8 @@
+export default function (data, { Component }) {
+  return (
+    <section>
+      <h1>Welcome</h1>
+      <Component module='jsx-component-test' name='greet' who={data.name} />
+    </section>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-ctx-widget/index.js b/packages/apostrophe/test/modules/jsx-ctx-widget/index.js
new file mode 100644
index 0000000000..01514397ea
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-ctx-widget/index.js
@@ -0,0 +1,6 @@
+module.exports = {
+  extend: '@apostrophecms/widget-type',
+  options: {
+    label: 'JSX Ctx Widget'
+  }
+};
diff --git a/packages/apostrophe/test/modules/jsx-ctx-widget/views/widget.jsx b/packages/apostrophe/test/modules/jsx-ctx-widget/views/widget.jsx
new file mode 100644
index 0000000000..96f722dc86
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-ctx-widget/views/widget.jsx
@@ -0,0 +1,4 @@
+export default function (data) {
+  const tag = (data.contextOptions && data.contextOptions.tag) || 'no-tag';
+  return <span class='ctx-widget' data-tag={tag}>{tag}</span>;
+}
diff --git a/packages/apostrophe/test/modules/jsx-mixed-test/index.js b/packages/apostrophe/test/modules/jsx-mixed-test/index.js
new file mode 100644
index 0000000000..fe1a8f98db
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-mixed-test/index.js
@@ -0,0 +1,9 @@
+module.exports = {
+  init(self) {
+    self.addHelpers({
+      safeBold(text) {
+        return self.apos.template.safe(`<b>${self.apos.util.escapeHtml(text)}</b>`);
+      }
+    });
+  }
+};
diff --git a/packages/apostrophe/test/modules/jsx-mixed-test/views/apos-full.jsx b/packages/apostrophe/test/modules/jsx-mixed-test/views/apos-full.jsx
new file mode 100644
index 0000000000..1673075f72
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-mixed-test/views/apos-full.jsx
@@ -0,0 +1,21 @@
+export default async function (data, { apos, helpers }) {
+  const id = apos.util.generateId();
+  // apos.doc.find returns a real cursor we can await. apos.doc here is the
+  // doc-module instance from self.apos, not a helper bag.
+  const docs = await apos.doc.find(data.req, { type: '@apostrophecms/global' }).toArray();
+  // The doc module instance has methods (e.g. find) that the helper bag
+  // does not — and the two `modules` collections are different objects.
+  const aposDocIsModule = typeof apos.doc.find === 'function';
+  const helpersDocIsHelperBag = (apos.doc !== helpers.modules['@apostrophecms/doc']);
+  const aposModulesIsNotHelpersModules = (apos.modules !== helpers.modules);
+  return (
+    <div
+      data-id-length={String(id.length)}
+      data-global-count={String(docs.length)}
+      data-distinct={String(apos !== helpers)}
+      data-apos-doc-is-module={String(aposDocIsModule)}
+      data-helpers-doc-is-helper-bag={String(helpersDocIsHelperBag)}
+      data-modules-distinct={String(aposModulesIsNotHelpersModules)}
+    />
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-mixed-test/views/async-list.jsx b/packages/apostrophe/test/modules/jsx-mixed-test/views/async-list.jsx
new file mode 100644
index 0000000000..e465170c8b
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-mixed-test/views/async-list.jsx
@@ -0,0 +1,12 @@
+async function bullet(value) {
+  await new Promise((resolve) => setTimeout(resolve, 5));
+  return <li>{value}</li>;
+}
+
+export default async function (data) {
+  return (
+    <ul>
+      {data.items.map((item) => bullet(item))}
+    </ul>
+  );
+}
diff --git a/packages/apostrophe/test/modules/jsx-mixed-test/views/lib/format.js b/packages/apostrophe/test/modules/jsx-mixed-test/views/lib/format.js
new file mode 100644
index 0000000000..1d9221e5cb
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-mixed-test/views/lib/format.js
@@ -0,0 +1,3 @@
+module.exports = function format(value) {
+  return `[${value}]`;
+};
diff --git a/packages/apostrophe/test/modules/jsx-mixed-test/views/localized.jsx b/packages/apostrophe/test/modules/jsx-mixed-test/views/localized.jsx
new file mode 100644
index 0000000000..79cd34235a
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-mixed-test/views/localized.jsx
@@ -0,0 +1,3 @@
+export default function (data, { __t }) {
+  return <p>{__t('apostrophe:notFoundPageTitle')}</p>;
+}
diff --git a/packages/apostrophe/test/modules/jsx-mixed-test/views/partial.jsx b/packages/apostrophe/test/modules/jsx-mixed-test/views/partial.jsx
new file mode 100644
index 0000000000..caf556703a
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-mixed-test/views/partial.jsx
@@ -0,0 +1,3 @@
+export default function (data) {
+  return <p class='partial'>partial:{data.item}</p>;
+}
diff --git a/packages/apostrophe/test/modules/jsx-mixed-test/views/safe-helper.jsx b/packages/apostrophe/test/modules/jsx-mixed-test/views/safe-helper.jsx
new file mode 100644
index 0000000000..d4c6c9d55b
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-mixed-test/views/safe-helper.jsx
@@ -0,0 +1,3 @@
+export default function (data, { helpers }) {
+  return <div>{helpers.modules['jsx-mixed-test'].safeBold('hello & <world>')}</div>;
+}
diff --git a/packages/apostrophe/test/modules/jsx-mixed-test/views/syntax-error.jsx b/packages/apostrophe/test/modules/jsx-mixed-test/views/syntax-error.jsx
new file mode 100644
index 0000000000..a53f7e7e06
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-mixed-test/views/syntax-error.jsx
@@ -0,0 +1,3 @@
+export default function () {
+  return <div>missing closing tag<;
+}
diff --git a/packages/apostrophe/test/modules/jsx-mixed-test/views/throws.jsx b/packages/apostrophe/test/modules/jsx-mixed-test/views/throws.jsx
new file mode 100644
index 0000000000..c0340fa0ef
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-mixed-test/views/throws.jsx
@@ -0,0 +1,5 @@
+export default function () {
+  // intentionally accesses a property of undefined to trigger an error
+  const data = undefined;
+  return <p>{data.boom}</p>;
+}
diff --git a/packages/apostrophe/test/modules/jsx-mixed-test/views/uses-import.jsx b/packages/apostrophe/test/modules/jsx-mixed-test/views/uses-import.jsx
new file mode 100644
index 0000000000..3f89e3a336
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-mixed-test/views/uses-import.jsx
@@ -0,0 +1,5 @@
+import format from './lib/format.js';
+
+export default function (data) {
+  return <span>{format(data.value)}</span>;
+}
diff --git a/packages/apostrophe/test/modules/jsx-mixed-test/views/uses-require.jsx b/packages/apostrophe/test/modules/jsx-mixed-test/views/uses-require.jsx
new file mode 100644
index 0000000000..d7f9b66710
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-mixed-test/views/uses-require.jsx
@@ -0,0 +1,5 @@
+const format = require('./lib/format.js');
+
+export default function (data) {
+  return <span>{format(data.value)}</span>;
+}
diff --git a/packages/apostrophe/test/modules/jsx-watcher-cross-test/index.js b/packages/apostrophe/test/modules/jsx-watcher-cross-test/index.js
new file mode 100644
index 0000000000..2292fa9997
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-watcher-cross-test/index.js
@@ -0,0 +1,5 @@
+module.exports = {
+  options: {
+    ignoreNoCodeWarning: true
+  }
+};
diff --git a/packages/apostrophe/test/modules/jsx-watcher-cross-test/views/cross-template.jsx b/packages/apostrophe/test/modules/jsx-watcher-cross-test/views/cross-template.jsx
new file mode 100644
index 0000000000..477abbac39
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-watcher-cross-test/views/cross-template.jsx
@@ -0,0 +1,3 @@
+export default function () {
+  return <h1>cross-original</h1>;
+}
diff --git a/packages/apostrophe/test/modules/jsx-watcher-test/index.js b/packages/apostrophe/test/modules/jsx-watcher-test/index.js
new file mode 100644
index 0000000000..2292fa9997
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-watcher-test/index.js
@@ -0,0 +1,5 @@
+module.exports = {
+  options: {
+    ignoreNoCodeWarning: true
+  }
+};
diff --git a/packages/apostrophe/test/modules/jsx-watcher-test/views/watcher-test.jsx b/packages/apostrophe/test/modules/jsx-watcher-test/views/watcher-test.jsx
new file mode 100644
index 0000000000..c65b67c3ac
--- /dev/null
+++ b/packages/apostrophe/test/modules/jsx-watcher-test/views/watcher-test.jsx
@@ -0,0 +1,3 @@
+export default function () {
+  return <h1>own-original</h1>;
+}
diff --git a/packages/apostrophe/test/modules/template-jsx-options-test/index.js b/packages/apostrophe/test/modules/template-jsx-options-test/index.js
new file mode 100644
index 0000000000..125f464c5d
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-options-test/index.js
@@ -0,0 +1,12 @@
+module.exports = {
+  options: {
+    spiffiness: 'nifty'
+  },
+  init(self) {
+    self.addHelpers({
+      test(a) {
+        return a * 2;
+      }
+    });
+  }
+};
diff --git a/packages/apostrophe/test/modules/template-jsx-options-test/views/options-test.jsx b/packages/apostrophe/test/modules/template-jsx-options-test/views/options-test.jsx
new file mode 100644
index 0000000000..1c16191123
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-options-test/views/options-test.jsx
@@ -0,0 +1,9 @@
+export default function (data, { helpers }) {
+  return (
+    <>
+      {helpers.modules['template-jsx-options-test'].options.spiffiness}
+      {' '}
+      {helpers.modules['template-jsx-options-test'].test(2)}
+    </>
+  );
+}
diff --git a/packages/apostrophe/test/modules/template-jsx-subclass-test/index.js b/packages/apostrophe/test/modules/template-jsx-subclass-test/index.js
new file mode 100644
index 0000000000..f1b210e9b5
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-subclass-test/index.js
@@ -0,0 +1,3 @@
+module.exports = {
+  extend: 'template-jsx-test'
+};
diff --git a/packages/apostrophe/test/modules/template-jsx-subclass-test/views/override-test.jsx b/packages/apostrophe/test/modules/template-jsx-subclass-test/views/override-test.jsx
new file mode 100644
index 0000000000..d18fd57240
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-subclass-test/views/override-test.jsx
@@ -0,0 +1,3 @@
+export default function () {
+  return <h1>I am overridden</h1>;
+}
diff --git a/packages/apostrophe/test/modules/template-jsx-test/index.js b/packages/apostrophe/test/modules/template-jsx-test/index.js
new file mode 100644
index 0000000000..142b6a6cef
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-test/index.js
@@ -0,0 +1,9 @@
+module.exports = {
+  options: {
+    templateData: {
+      age: 30,
+      multiline: 'first line\nsecond line\n<a href="javascript:alert(\'oh no\')">CSRF attempt</a>',
+      multilineSafe: 'first line\nsecond line\n<a href="http://niceurl.com">This is okay</a>'
+    }
+  }
+};
diff --git a/packages/apostrophe/test/modules/template-jsx-test/views/boolean-attrs.jsx b/packages/apostrophe/test/modules/template-jsx-test/views/boolean-attrs.jsx
new file mode 100644
index 0000000000..3cc760bcc2
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-test/views/boolean-attrs.jsx
@@ -0,0 +1,11 @@
+export default function () {
+  return (
+    <input
+      type='checkbox'
+      checked
+      disabled={false}
+      data-extra={null}
+      data-undefined={undefined}
+    />
+  );
+}
diff --git a/packages/apostrophe/test/modules/template-jsx-test/views/class-and-for.jsx b/packages/apostrophe/test/modules/template-jsx-test/views/class-and-for.jsx
new file mode 100644
index 0000000000..a1000bd8fa
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-test/views/class-and-for.jsx
@@ -0,0 +1,7 @@
+export default function () {
+  return (
+    <label className='form-label' htmlFor='username'>
+      Username
+    </label>
+  );
+}
diff --git a/packages/apostrophe/test/modules/template-jsx-test/views/dangerously-set.jsx b/packages/apostrophe/test/modules/template-jsx-test/views/dangerously-set.jsx
new file mode 100644
index 0000000000..59149483a9
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-test/views/dangerously-set.jsx
@@ -0,0 +1,3 @@
+export default function (data) {
+  return <div dangerouslySetInnerHTML={{ __html: data.html }} />;
+}
diff --git a/packages/apostrophe/test/modules/template-jsx-test/views/escape-attr.jsx b/packages/apostrophe/test/modules/template-jsx-test/views/escape-attr.jsx
new file mode 100644
index 0000000000..e8f0229b4f
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-test/views/escape-attr.jsx
@@ -0,0 +1,3 @@
+export default function (data) {
+  return <a href={data.url} title={data.title}>link</a>;
+}
diff --git a/packages/apostrophe/test/modules/template-jsx-test/views/escape-body.jsx b/packages/apostrophe/test/modules/template-jsx-test/views/escape-body.jsx
new file mode 100644
index 0000000000..14ae199807
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-test/views/escape-body.jsx
@@ -0,0 +1,3 @@
+export default function (data) {
+  return <p>{data.html}</p>;
+}
diff --git a/packages/apostrophe/test/modules/template-jsx-test/views/inherit-test.jsx b/packages/apostrophe/test/modules/template-jsx-test/views/inherit-test.jsx
new file mode 100644
index 0000000000..90ec61c4b9
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-test/views/inherit-test.jsx
@@ -0,0 +1,3 @@
+export default function () {
+  return <h1>I am inherited</h1>;
+}
diff --git a/packages/apostrophe/test/modules/template-jsx-test/views/list.jsx b/packages/apostrophe/test/modules/template-jsx-test/views/list.jsx
new file mode 100644
index 0000000000..873439439c
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-test/views/list.jsx
@@ -0,0 +1,7 @@
+export default function (data) {
+  return (
+    <ul>
+      {data.items.map((item) => <li key={item}>{item}</li>)}
+    </ul>
+  );
+}
diff --git a/packages/apostrophe/test/modules/template-jsx-test/views/override-test.jsx b/packages/apostrophe/test/modules/template-jsx-test/views/override-test.jsx
new file mode 100644
index 0000000000..42dd8e3e1d
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-test/views/override-test.jsx
@@ -0,0 +1,3 @@
+export default function () {
+  return <h1>I am a bug</h1>;
+}
diff --git a/packages/apostrophe/test/modules/template-jsx-test/views/svg-attrs.jsx b/packages/apostrophe/test/modules/template-jsx-test/views/svg-attrs.jsx
new file mode 100644
index 0000000000..fbf373f0c8
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-test/views/svg-attrs.jsx
@@ -0,0 +1,27 @@
+// Verifies that camelCase SVG presentation attributes are emitted in
+// the kebab-case form expected by browsers parsing text/html, and that
+// natively camelCase SVG attributes (viewBox, preserveAspectRatio) are
+// preserved.
+
+export default function () {
+  return (
+    <svg
+      xmlns='http://www.w3.org/2000/svg'
+      viewBox='0 0 24 24'
+      preserveAspectRatio='xMidYMid meet'
+      fill='none'
+      stroke='currentColor'
+      strokeWidth='2'
+      strokeLinecap='round'
+      strokeLinejoin='round'
+      strokeDasharray='4 2'
+      strokeOpacity='0.5'
+      fillRule='evenodd'
+      clipRule='evenodd'
+      pointerEvents='none'
+      textAnchor='middle'
+    >
+      <path d='M0 0L24 24' />
+    </svg>
+  );
+}
diff --git a/packages/apostrophe/test/modules/template-jsx-test/views/test.jsx b/packages/apostrophe/test/modules/template-jsx-test/views/test.jsx
new file mode 100644
index 0000000000..d814ee317f
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-test/views/test.jsx
@@ -0,0 +1,3 @@
+export default function (data) {
+  return <h1>{data.age}</h1>;
+}
diff --git a/packages/apostrophe/test/modules/template-jsx-test/views/void-elements.jsx b/packages/apostrophe/test/modules/template-jsx-test/views/void-elements.jsx
new file mode 100644
index 0000000000..89b9f4bc76
--- /dev/null
+++ b/packages/apostrophe/test/modules/template-jsx-test/views/void-elements.jsx
@@ -0,0 +1,9 @@
+export default function () {
+  return (
+    <>
+      <hr />
+      <input type='text' name='email' />
+      <br />
+    </>
+  );
+}
diff --git a/packages/apostrophe/test/templates-jsx-watcher.js b/packages/apostrophe/test/templates-jsx-watcher.js
new file mode 100644
index 0000000000..9acda7957c
--- /dev/null
+++ b/packages/apostrophe/test/templates-jsx-watcher.js
@@ -0,0 +1,135 @@
+const t = require('../test-lib/test.js');
+const assert = require('assert/strict');
+const fs = require('fs');
+const path = require('path');
+const isWsl = require('is-wsl');
+
+describe('Templates: JSX watcher', function () {
+
+  let apos;
+  this.timeout(t.timeout);
+
+  // Two fixture modules. `jsx-watcher-test` is the simple case: render its
+  // own template directly. `jsx-watcher-cross-test` is the realistic-page
+  // case: another module renders this one's template via the qualified
+  // `module:template` form (mirroring how `@apostrophecms/page` renders
+  // `@apostrophecms/home-page:page` in the wild). The first surfaces a
+  // bug where renderBody never arms a watcher for JSX renders; the second
+  // surfaces a bug where the watcher was armed against the caller's views
+  // instead of the resolved module's views.
+  const ownModule = 'jsx-watcher-test';
+  const ownTemplate = 'watcher-test';
+  const ownPath = path.join(
+    __dirname, 'modules', ownModule, 'views', `${ownTemplate}.jsx`
+  );
+  const ownOriginal = 'export default function () {\n  return <h1>own-original</h1>;\n}\n';
+  const ownChanged = 'export default function () {\n  return <h1>own-changed</h1>;\n}\n';
+
+  const crossModule = 'jsx-watcher-cross-test';
+  const crossTemplate = 'cross-template';
+  const crossPath = path.join(
+    __dirname, 'modules', crossModule, 'views', `${crossTemplate}.jsx`
+  );
+  const crossOriginal = 'export default function () {\n  return <h1>cross-original</h1>;\n}\n';
+  const crossChanged = 'export default function () {\n  return <h1>cross-changed</h1>;\n}\n';
+
+  before(async function () {
+    // Defend against poisoned fixtures from a prior failed run.
+    fs.writeFileSync(ownPath, ownOriginal);
+    fs.writeFileSync(crossPath, crossOriginal);
+    apos = await t.create({
+      root: module,
+      modules: {
+        [ownModule]: {},
+        [crossModule]: {}
+      }
+    });
+  });
+
+  after(async function () {
+    try {
+      fs.writeFileSync(ownPath, ownOriginal);
+    } catch (e) {
+      // best-effort restore
+    }
+    try {
+      fs.writeFileSync(crossPath, crossOriginal);
+    } catch (e) {
+      // best-effort restore
+    }
+    return t.destroy(apos);
+  });
+
+  // Wait for chokidar's initial scan to complete on every watcher the
+  // template module has registered. If the JSX render path failed to arm
+  // any watcher for our views directory, no `change` event would ever
+  // fire and the caller's `waitForChange` would time out.
+  async function waitForWatchersReady() {
+    await Promise.all(
+      (apos.template._viewWatchers || []).map(watcher => {
+        if (watcher._readyEmitted) {
+          return Promise.resolve();
+        }
+        return new Promise(resolve => watcher.on('ready', resolve));
+      })
+    );
+  }
+
+  function waitForChange(absolutePath) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error(`No view-change event was observed for ${absolutePath}.`)),
+        5000
+      );
+      apos.template.onViewChange(filePath => {
+        if (filePath && path.resolve(filePath) === path.resolve(absolutePath)) {
+          clearTimeout(timer);
+          resolve();
+        }
+      });
+    });
+  }
+
+  it('should pick up edits to a .jsx template rendered through its own module', async function () {
+    if (isWsl) {
+      this.skip();
+      return;
+    }
+    const req = apos.task.getAnonReq();
+    const initial = await apos.modules[ownModule].render(req, ownTemplate);
+    assert.match(initial, /own-original/);
+
+    await waitForWatchersReady();
+    const sawChange = waitForChange(ownPath);
+    fs.writeFileSync(ownPath, ownChanged);
+    await sawChange;
+
+    const after = await apos.modules[ownModule].render(req, ownTemplate);
+    assert.match(after, /own-changed/);
+    assert.doesNotMatch(after, /own-original/);
+  });
+
+  it('should pick up edits when one module renders another module\'s .jsx via `module:template`', async function () {
+    if (isWsl) {
+      this.skip();
+      return;
+    }
+    const req = apos.task.getAnonReq();
+    // The caller is `ownModule`, but the template lives in `crossModule`.
+    // This is the shape that breaks if the watcher is armed against the
+    // caller's view chain instead of the resolved file's module.
+    const qualified = `${crossModule}:${crossTemplate}`;
+    const initial = await apos.modules[ownModule].render(req, qualified);
+    assert.match(initial, /cross-original/);
+
+    await waitForWatchersReady();
+    const sawChange = waitForChange(crossPath);
+    fs.writeFileSync(crossPath, crossChanged);
+    await sawChange;
+
+    const after = await apos.modules[ownModule].render(req, qualified);
+    assert.match(after, /cross-changed/);
+    assert.doesNotMatch(after, /cross-original/);
+  });
+
+});
diff --git a/packages/apostrophe/test/templates-jsx.js b/packages/apostrophe/test/templates-jsx.js
new file mode 100644
index 0000000000..d128e1eb98
--- /dev/null
+++ b/packages/apostrophe/test/templates-jsx.js
@@ -0,0 +1,537 @@
+const t = require('../test-lib/test.js');
+const assert = require('assert/strict');
+
+describe('Templates: JSX', function() {
+
+  let apos;
+
+  this.timeout(t.timeout);
+
+  after(async function() {
+    return t.destroy(apos);
+  });
+
+  before(async function() {
+    apos = await t.create({
+      root: module,
+      modules: {
+        'express-test': {},
+        'template-jsx-test': {
+          options: {
+            ignoreNoCodeWarning: true
+          }
+        },
+        'template-jsx-subclass-test': {
+          options: {
+            ignoreNoCodeWarning: true
+          }
+        },
+        'template-jsx-options-test': {},
+        'jsx-component-test': {},
+        'jsx-bridge-test': {
+          options: {
+            ignoreNoCodeWarning: true
+          }
+        },
+        'jsx-mixed-test': {},
+        'jsx-area-test': {},
+        'jsx-async-widget': {},
+        'jsx-ctx-widget': {}
+      }
+    });
+  });
+
+  // ---- Equivalents of the existing Nunjucks template tests ----
+
+  it('should render a JSX template relative to a module', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['template-jsx-test'].render(req, 'test', { age: 50 });
+    assert.equal(result.trim(), '<h1>50</h1>');
+  });
+
+  it('should respect templateData at module level for JSX templates', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['template-jsx-test'].render(req, 'test');
+    assert.equal(result.trim(), '<h1>30</h1>');
+  });
+
+  it('should respect JSX template overrides in subclasses', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['template-jsx-subclass-test'].render(req, 'override-test');
+    assert.equal(result.trim(), '<h1>I am overridden</h1>');
+  });
+
+  it('should inherit JSX templates in the absence of overrides', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['template-jsx-subclass-test'].render(req, 'inherit-test');
+    assert.equal(result.trim(), '<h1>I am inherited</h1>');
+  });
+
+  it('should expose module options and helpers to JSX via the helpers second argument', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['template-jsx-options-test'].render(req, 'options-test');
+    assert.match(result, /nifty/);
+    assert.match(result, /\b4\b/);
+  });
+
+  // ---- Auto-escape and dangerouslySetInnerHTML ----
+
+  it('should auto-escape strings in element bodies', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['template-jsx-test'].render(req, 'escape-body', {
+      html: '<script>alert("xss")</script>'
+    });
+    assert.match(result, /&lt;script&gt;alert\("xss"\)&lt;\/script&gt;/);
+    assert.doesNotMatch(result, /<script>/i);
+  });
+
+  it('should auto-escape attribute values, including quotes', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['template-jsx-test'].render(req, 'escape-attr', {
+      url: 'javascript:alert("hi")',
+      title: 'evil "quotes" & <tags>'
+    });
+    assert.match(result, /href="javascript:alert\(&quot;hi&quot;\)"/);
+    assert.match(result, /title="evil &quot;quotes&quot; &amp; &lt;tags&gt;"/);
+  });
+
+  it('should emit raw HTML via dangerouslySetInnerHTML without escaping', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['template-jsx-test'].render(req, 'dangerously-set', {
+      html: '<strong>raw</strong> & <em>html</em>'
+    });
+    assert.match(result, /<strong>raw<\/strong> & <em>html<\/em>/);
+  });
+
+  it('should rewrite className to class and htmlFor to for', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['template-jsx-test'].render(req, 'class-and-for');
+    assert.match(result, /class="form-label"/);
+    assert.match(result, /for="username"/);
+    assert.doesNotMatch(result, /className=/);
+    assert.doesNotMatch(result, /htmlFor=/);
+  });
+
+  it('should rewrite camelCase SVG presentation attrs to kebab-case', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['template-jsx-test'].render(req, 'svg-attrs');
+    // Kebab-case conversions
+    assert.match(result, /stroke-width="2"/);
+    assert.match(result, /stroke-linecap="round"/);
+    assert.match(result, /stroke-linejoin="round"/);
+    assert.match(result, /stroke-dasharray="4 2"/);
+    assert.match(result, /stroke-opacity="0.5"/);
+    assert.match(result, /fill-rule="evenodd"/);
+    assert.match(result, /clip-rule="evenodd"/);
+    assert.match(result, /pointer-events="none"/);
+    assert.match(result, /text-anchor="middle"/);
+    // Native camelCase preserved
+    assert.match(result, /viewBox="0 0 24 24"/);
+    assert.match(result, /preserveAspectRatio="xMidYMid meet"/);
+    // No camelCase forms leaked through
+    assert.doesNotMatch(result, /strokeWidth=/);
+    assert.doesNotMatch(result, /fillRule=/);
+  });
+
+  it('should self-close void elements', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['template-jsx-test'].render(req, 'void-elements');
+    assert.match(result, /<hr \/>/);
+    assert.match(result, /<input type="text" name="email" \/>/);
+    assert.match(result, /<br \/>/);
+  });
+
+  it('should handle boolean attributes and skip null/undefined/false attribute values', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['template-jsx-test'].render(req, 'boolean-attrs');
+    assert.match(result, /<input/);
+    assert.match(result, / checked/);
+    assert.doesNotMatch(result, /checked="true"/);
+    assert.doesNotMatch(result, /disabled/);
+    assert.doesNotMatch(result, /data-extra/);
+    assert.doesNotMatch(result, /data-undefined/);
+  });
+
+  it('should render arrays of nodes (e.g. lists from .map())', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['template-jsx-test'].render(req, 'list', {
+      items: [ 'a', 'b', 'c' ]
+    });
+    assert.match(result, /<ul>/);
+    assert.match(result, /<li>a<\/li>/);
+    assert.match(result, /<li>b<\/li>/);
+    assert.match(result, /<li>c<\/li>/);
+  });
+
+  // ---- Async <Component> ----
+
+  it('should await async components inline within JSX', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-component-test'].render(req, 'uses-component', {
+      name: 'World'
+    });
+    assert.match(result, /<section>/);
+    assert.match(result, /<h1>Welcome<\/h1>/);
+    assert.match(
+      result,
+      /<span class="greet">Hello World \(after delay\)<\/span>/
+    );
+  });
+
+  // ---- <Area> ----
+
+  it('should render a doc area inline via the Area helper', async function() {
+    const req = apos.task.getAnonReq();
+    const piece = {
+      _id: 'jsx-area-piece-1',
+      metaType: 'doc',
+      type: 'jsx-area-test',
+      title: 'Area Host',
+      slug: 'area-host',
+      main: {
+        _id: 'jsx-area-1',
+        metaType: 'area',
+        items: [
+          {
+            _id: 'jsx-area-widget-1',
+            metaType: 'widget',
+            type: '@apostrophecms/rich-text',
+            content: '<p>area body</p>'
+          }
+        ]
+      }
+    };
+    const result = await apos.modules['jsx-area-test'].render(req, 'with-area', { piece });
+    assert.match(result, /<main>/);
+    assert.match(result, /class="apos-area"/);
+    assert.match(result, /<div data-rich-text>/);
+    assert.match(result, /<p>area body<\/p>/);
+  });
+
+  it('Area helper should reject calls with a missing or invalid name', async function() {
+    const req = apos.task.getAnonReq();
+    const piece = {
+      _id: 'jsx-area-piece-2',
+      metaType: 'doc',
+      type: 'jsx-area-test',
+      title: 'Bad Area',
+      slug: 'bad-area',
+      // No `nope` field exists in the schema
+      nope: {
+        _id: 'jsx-area-nope-1',
+        metaType: 'area',
+        items: []
+      }
+    };
+    let caught;
+    try {
+      await apos.modules['jsx-area-test'].render(req, 'bad-area', { piece });
+    } catch (e) {
+      caught = e;
+    }
+    assert(caught, 'expected the render to throw');
+    assert.match(caught.message, /no field named nope/);
+  });
+
+  // ---- <Widget> ----
+
+  it('should render a single widget via the Widget helper', async function() {
+    const req = apos.task.getAnonReq();
+    const widget = {
+      _id: 'jsx-widget-direct-1',
+      metaType: 'widget',
+      type: '@apostrophecms/rich-text',
+      content: '<p>just a widget</p>'
+    };
+    const result = await apos.modules['jsx-area-test'].render(req, 'with-widget', { widget });
+    assert.match(result, /<section class="wrapper">/);
+    assert.match(result, /<div data-rich-text>/);
+    assert.match(result, /<p>just a widget<\/p>/);
+    // Widget should NOT add the surrounding apos-area wrapper.
+    assert.doesNotMatch(result, /class="apos-area"/);
+  });
+
+  it('Widget helper should silently skip a null widget', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-area-test'].render(req, 'with-widget', { widget: null });
+    assert.match(result, /<section class="wrapper"><\/section>/);
+  });
+
+  // ---- `with={...}` context options on Area and Widget ----
+
+  it('Area should pass `with={...}` context options through to the widget', async function() {
+    const req = apos.task.getAnonReq();
+    const piece = {
+      _id: 'jsx-ctx-area-piece-1',
+      metaType: 'doc',
+      type: 'jsx-area-test',
+      title: 'Ctx Host',
+      slug: 'ctx-host',
+      main: {
+        _id: 'jsx-ctx-area-1',
+        metaType: 'area',
+        items: [
+          {
+            _id: 'jsx-ctx-widget-1',
+            metaType: 'widget',
+            type: 'jsx-ctx'
+          }
+        ]
+      }
+    };
+    const result = await apos.modules['jsx-area-test'].render(req, 'with-area-ctx', { piece });
+    assert.match(result, /data-tag="from-area-with"/);
+    assert.match(result, /<span class="ctx-widget"[^>]*>from-area-with<\/span>/);
+  });
+
+  it('Widget should pass `with={...}` context options through to the widget', async function() {
+    const req = apos.task.getAnonReq();
+    const widget = {
+      _id: 'jsx-ctx-widget-direct-1',
+      metaType: 'widget',
+      type: 'jsx-ctx'
+    };
+    const result = await apos.modules['jsx-area-test'].render(req, 'with-widget-ctx', { widget });
+    assert.match(result, /data-tag="from-widget-with"/);
+    assert.match(result, /<span class="ctx-widget"[^>]*>from-widget-with<\/span>/);
+  });
+
+  // Exercises the full render-time async pipeline: a page JSX template calls
+  // <Area>, the area renders each widget via its widget.jsx, and the widget.jsx
+  // itself invokes <Component> which runs an async component that delays before
+  // returning. If any await is missing along that path — page → Area → widget.jsx
+  // → Component — the deferred output ("(after delay)") will not appear in the
+  // rendered HTML.
+  it('a JSX widget.jsx that calls an async <Component> should resolve through the full render pipeline', async function() {
+    const req = apos.task.getAnonReq();
+    const piece = {
+      _id: 'jsx-async-host',
+      metaType: 'doc',
+      type: 'jsx-area-test',
+      title: 'Async Host',
+      slug: 'async-host',
+      main: {
+        _id: 'jsx-async-area',
+        metaType: 'area',
+        items: [
+          {
+            _id: 'jsx-async-widget-instance',
+            metaType: 'widget',
+            type: 'jsx-async',
+            who: 'World'
+          }
+        ]
+      }
+    };
+    const result = await apos.modules['jsx-area-test'].render(req, 'with-area', { piece });
+    assert.match(result, /<div class="async-widget">/);
+    assert.match(
+      result,
+      /<span class="greet">Hello World \(after delay\)<\/span>/
+    );
+  });
+
+  // ---- JSX → Nunjucks bridge via Extend ----
+
+  it('should let JSX extend a Nunjucks layout, mapping props to {% block %} overrides', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-bridge-test'].render(req, 'njk-extends', {
+      message: 'hello & <world>',
+      pageSlug: '/test'
+    });
+    assert.match(result, /<title>A JSX page<\/title>/);
+    assert.match(result, /<body data-page="\/test">/);
+    assert.match(result, /<main>/);
+    assert.match(result, /<h1>I am from JSX<\/h1>/);
+    // Auto-escape applies to ordinary string children inside JSX, even when
+    // the surrounding output ends up in a Nunjucks block override.
+    assert.match(result, /<p>hello &amp; &lt;world&gt;<\/p>/);
+    assert.doesNotMatch(result, /default body/);
+    assert.doesNotMatch(result, /default title/);
+  });
+
+  // ---- JSX → JSX layout via Template + children ----
+
+  it('should let JSX extend a JSX layout, passing children through', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-bridge-test'].render(req, 'jsx-extends', {
+      message: 'inside the jsx layout'
+    });
+    assert.match(result, /<title>JSX-in-JSX<\/title>/);
+    assert.match(result, /<header>shared header<\/header>/);
+    assert.match(result, /<main>/);
+    assert.match(result, /<p>inside the jsx layout<\/p>/);
+    assert.match(result, /<footer>shared footer<\/footer>/);
+  });
+
+  // ---- <Extend> against a .jsx target behaves like <Template> ----
+
+  it('Extend against a .jsx target should behave like Template (props + children)', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-bridge-test'].render(req, 'jsx-extends-via-extend', {
+      message: 'inside via extend'
+    });
+    assert.match(result, /<title>Extend-against-JSX<\/title>/);
+    assert.match(result, /<header>shared header<\/header>/);
+    assert.match(result, /<p>inside via extend<\/p>/);
+    assert.match(result, /<footer>shared footer<\/footer>/);
+  });
+
+  // ---- <Template> against a .html target: include semantics ----
+
+  it('Template against a .html target should pass props as data and NOT override blocks', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-bridge-test'].render(req, 'include-html');
+    // Block content is the default — Template did NOT override it.
+    assert.match(result, /<p class="block-output">default-block<\/p>/);
+    // The JSX prop arrived as data.content in Nunjucks.
+    assert.match(result, /<p class="data-output">prop-content<\/p>/);
+  });
+
+  // ---- Template short-form `name=` (no `templateName`) ----
+
+  it('Template `name=` short form should resolve and pass other props as data', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-bridge-test'].render(req, 'short-form');
+    assert.match(result, /<p>short:from-short<\/p>/);
+  });
+
+  // ---- Cross-module `module:file` ----
+
+  it('Template should resolve `module:file` cross-module references', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-bridge-test'].render(req, 'cross-module');
+    assert.match(result, /<p class="partial">partial:from-cross-module<\/p>/);
+  });
+
+  // ---- templateName/name disambiguation rule ----
+
+  it('Template with both `templateName` and `name` should forward `name` as a prop and not `templateName`', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-bridge-test'].render(req, 'disambig-with-template-name');
+    // `name` is forwarded as data.name when `templateName` is also present.
+    assert.match(result, /data-name="forwarded-value"/);
+    // `templateName` itself is never forwarded as a data prop.
+    assert.match(result, /data-template-name="undefined"/);
+  });
+
+  it('Template with only `name=` should use it as the selector and not forward it as data', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-bridge-test'].render(req, 'disambig-name-only');
+    // `name` was the selector (resolved disambig-target.jsx), not a prop.
+    assert.match(result, /data-name="undefined"/);
+    // The target rendered, proving `name` selected it.
+    assert.match(result, /data-template-name="undefined"/);
+  });
+
+  // ---- import / require inside .jsx ----
+
+  it('should support `import` inside .jsx files', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-mixed-test'].render(req, 'uses-import', {
+      value: 'imported'
+    });
+    assert.match(result, /<span>\[imported\]<\/span>/);
+  });
+
+  it('should support `require` inside .jsx files', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-mixed-test'].render(req, 'uses-require', {
+      value: 'required'
+    });
+    assert.match(result, /<span>\[required\]<\/span>/);
+  });
+
+  // ---- Async JSX with promise-returning helpers in arrays ----
+
+  it('should await promises returned from inside arrays', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-mixed-test'].render(req, 'async-list', {
+      items: [ 'one', 'two', 'three' ]
+    });
+    assert.match(result, /<ul><li>one<\/li><li>two<\/li><li>three<\/li><\/ul>/);
+  });
+
+  // ---- Nunjucks SafeString interop ----
+
+  it('should not double-escape Nunjucks SafeString values returned by helpers', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-mixed-test'].render(req, 'safe-helper');
+    // Helper escapes its input itself, returns SafeString. JSX must not
+    // re-escape the resulting <b> tag, but the inner text was escaped by
+    // the helper.
+    assert.match(result, /<div><b>hello &amp; &lt;world&gt;<\/b><\/div>/);
+  });
+
+  // ---- Full self.apos exposure ----
+
+  it('should expose full self.apos as `apos` and templateApos as `helpers` (distinct objects)', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-mixed-test'].render(req, 'apos-full', { req });
+    // apos.util.generateId() lives on self.apos.util, not on templateApos.
+    assert.match(result, /data-id-length="\d+"/);
+    // apos.doc.find(req, ...) returns a real cursor we can await.
+    assert.match(result, /data-global-count="\d+"/);
+    // apos and helpers must be different objects, not aliases.
+    assert.match(result, /data-distinct="true"/);
+    // apos.doc is the doc-module instance, with module methods like .find().
+    assert.match(result, /data-apos-doc-is-module="true"/);
+    // It is a different object than the helper bag for @apostrophecms/doc.
+    assert.match(result, /data-helpers-doc-is-helper-bag="true"/);
+    // The `modules` collections on the two objects are distinct.
+    assert.match(result, /data-modules-distinct="true"/);
+  });
+
+  // ---- Localization helper ----
+
+  it('should expose __t as the localization helper', async function() {
+    const req = apos.task.getAnonReq();
+    const result = await apos.modules['jsx-mixed-test'].render(req, 'localized');
+    assert.match(result, /<p>404 - Page not found<\/p>/);
+  });
+
+  // ---- Resolution: prefer .jsx when it exists alongside .html ----
+
+  it('resolveTemplate should prefer .jsx over .html in the same directory', function() {
+    const module = apos.modules['template-jsx-test'];
+    const resolved = apos.template.resolveTemplate(module, 'test');
+    assert.equal(resolved.kind, 'jsx');
+    assert.equal(resolved.ext, 'jsx');
+  });
+
+  it('resolveTemplate should still find .html templates when no .jsx exists', function() {
+    // template-test only has .html, not .jsx
+    const module = apos.modules['@apostrophecms/template'];
+    const resolved = apos.template.resolveTemplate(module, 'outerLayout');
+    assert.equal(resolved.kind, 'nunjucks');
+    assert.equal(resolved.ext, 'html');
+  });
+
+  // ---- Error handling ----
+
+  it('should annotate runtime errors thrown by JSX templates with the file path', async function() {
+    const req = apos.task.getAnonReq();
+    let caught;
+    try {
+      await apos.modules['jsx-mixed-test'].render(req, 'throws');
+    } catch (e) {
+      caught = e;
+    }
+    assert(caught, 'expected the render to throw');
+    assert.match(caught.message, /\[JSX template .*throws\.jsx\]/);
+    assert.equal(caught.aposJsxFile.endsWith('throws.jsx'), true);
+  });
+
+  it('should report JSX compile errors with the file path and a clear code', async function() {
+    const req = apos.task.getAnonReq();
+    let caught;
+    try {
+      await apos.modules['jsx-mixed-test'].render(req, 'syntax-error');
+    } catch (e) {
+      caught = e;
+    }
+    assert(caught, 'expected the render to throw');
+    assert.match(caught.message, /syntax-error\.jsx/);
+  });
+
+});
diff --git a/packages/db-connect/adapters/postgres.js b/packages/db-connect/adapters/postgres.js
index 7e99980a21..f3b81cd231 100644
--- a/packages/db-connect/adapters/postgres.js
+++ b/packages/db-connect/adapters/postgres.js
@@ -7,9 +7,6 @@ const {
   serializeValue,
   serializeDocument,
   deserializeDocument,
-  getNestedField,
-  setNestedField,
-  deepEqual,
   applyProjection,
   applyUpdate,
   extractAnchoredLiteralPrefix,
diff --git a/packages/db-connect/adapters/sqlite.js b/packages/db-connect/adapters/sqlite.js
index dbece06df6..af05dc2390 100644
--- a/packages/db-connect/adapters/sqlite.js
+++ b/packages/db-connect/adapters/sqlite.js
@@ -12,7 +12,6 @@ const {
   deserializeDocument,
   getNestedField,
   setNestedField,
-  deepEqual,
   applyProjection,
   applyUpdate,
   extractAnchoredLiteralPrefix,
@@ -636,7 +635,6 @@ function buildOrderBy(sort, options = {}) {
   return `ORDER BY ${clauses.join(', ')}`;
 }
 
-
 // =============================================================================
 // Parse SQLite index definitions from sqlite_master
 // =============================================================================
@@ -672,7 +670,7 @@ function parseIndexDef(sql) {
   for (const expr of exprs) {
     // Strip outer parentheses that SQLite adds around expression indexes.
     // e.g. "(json_extract(data, '$.slug')) ASC" → "json_extract(data, '$.slug') ASC"
-    let trimmed = stripOuterParens(expr.trim());
+    const trimmed = stripOuterParens(expr.trim());
 
     if (/^_id\b/.test(trimmed)) {
       const direction = /\bDESC\b/i.test(trimmed) ? -1 : 1;
diff --git a/packages/db-connect/lib/dump.js b/packages/db-connect/lib/dump.js
index 3551fa8d8e..69e62b9dfa 100644
--- a/packages/db-connect/lib/dump.js
+++ b/packages/db-connect/lib/dump.js
@@ -14,7 +14,7 @@ const BATCH_SIZE = 100;
 // Accept either a URI string or an already-connected db object. When a
 // db object is passed, the caller owns the connection lifecycle; when a
 // URI is passed, this module connects and closes the client on its own.
-async function *dump(uriOrDb) {
+async function * dump(uriOrDb) {
   let db;
   let client;
   if (typeof uriOrDb === 'string') {
diff --git a/packages/db-connect/test/adapter.test.js b/packages/db-connect/test/adapter.test.js
index 3d00f00122..6f6b9f1ac0 100644
--- a/packages/db-connect/test/adapter.test.js
+++ b/packages/db-connect/test/adapter.test.js
@@ -1492,15 +1492,24 @@ describe(`Database Adapter (${ADAPTER})`, function() {
       await db.collection('test').insertMany([
         {
           _id: 'dobj1',
-          updatedBy: { _id: 'user1', title: 'Alice' }
+          updatedBy: {
+            _id: 'user1',
+            title: 'Alice'
+          }
         },
         {
           _id: 'dobj2',
-          updatedBy: { _id: 'user2', title: 'Bob' }
+          updatedBy: {
+            _id: 'user2',
+            title: 'Bob'
+          }
         },
         {
           _id: 'dobj3',
-          updatedBy: { _id: 'user1', title: 'Alice' }
+          updatedBy: {
+            _id: 'user1',
+            title: 'Alice'
+          }
         }
       ]);
       const values = await db.collection('test').distinct('updatedBy');
diff --git a/packages/db-connect/test/shared.test.js b/packages/db-connect/test/shared.test.js
index e0fd78e962..b626006231 100644
--- a/packages/db-connect/test/shared.test.js
+++ b/packages/db-connect/test/shared.test.js
@@ -1,5 +1,5 @@
 /* global describe, it */
-/* eslint-disable no-unused-expressions */
+
 const { expect } = require('chai');
 const {
   extractAnchoredLiteralPrefix,

From 1fa59e4769e861a706bdca51c6808ba094dc2a77 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 3 Jun 2026 08:50:34 -0400
Subject: [PATCH 39/56] no watch in prod (#5439)

---
 .../modules/@apostrophecms/template/lib/viewWatcher.js       | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/apostrophe/modules/@apostrophecms/template/lib/viewWatcher.js b/packages/apostrophe/modules/@apostrophecms/template/lib/viewWatcher.js
index 5442f71432..3492b8021c 100644
--- a/packages/apostrophe/modules/@apostrophecms/template/lib/viewWatcher.js
+++ b/packages/apostrophe/modules/@apostrophecms/template/lib/viewWatcher.js
@@ -41,6 +41,11 @@ module.exports = (self) => {
       if (self.options.loader && self.options.loader.noWatch) {
         return;
       }
+      // In production the file tree is static and watching only burns
+      // file descriptors. Honor NODE_ENV unconditionally.
+      if (process.env.NODE_ENV === 'production') {
+        return;
+      }
       // chokidar's recursive watching is not reliable on WSL; preserve the
       // historical behavior of skipping watch setup entirely there.
       if (isWsl) {

From 34dca7aba1504fffddaa36224d420a8a88dca6b9 Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Wed, 3 Jun 2026 18:06:30 +0300
Subject: [PATCH 40/56] Fix new schema areas in existing documents (Astro) Part
 II (#5440)

* Prevent data corruption when stubbing areas for Astro

* Fix false positive orphan area warnings

* Guard against corrupt area items
---
 .../components/AposArea.astro                 |  27 +-
 .../modules/@apostrophecms/area/index.js      |  94 ++++--
 .../area/lib/custom-tags/area.js              |  29 +-
 .../modules/@apostrophecms/template/index.js  |  49 ++--
 packages/apostrophe/test/external-front.js    | 272 ++++++++++++++++++
 5 files changed, 394 insertions(+), 77 deletions(-)

diff --git a/packages/apostrophe-astro/components/AposArea.astro b/packages/apostrophe-astro/components/AposArea.astro
index 94b6c27f8e..a790b34bbb 100644
--- a/packages/apostrophe-astro/components/AposArea.astro
+++ b/packages/apostrophe-astro/components/AposArea.astro
@@ -13,13 +13,22 @@ const {
 
 let attributes = {};
 
-// The backend sets `field` only on areas still in the schema; a missing or
-// orphaned area lacks it and renders nothing.
-const isArea = Boolean(area?.field);
+// Enough structure to render as an area at all (hardens against malformed
+// data — never crash the render).
+const renderable = area?.metaType === "area" && Array.isArray(area?.items);
 
-const widgets: Record<string, any>[] = area?.items || [];
+const isOrphan = Boolean(area?._isOrphan);
+const isArea = renderable && !isOrphan;
 
-const isEdit = isArea && area?._edit && Astro.url.searchParams.get("aposEdit");
+const hasField = Boolean(area?.field);
+
+// Defensive: a corrupt item (null/typeless) must never crash the render.
+const widgets: Record<string, any>[] = (area?.items || []).filter(
+  (item: any) => item && item.type,
+);
+
+const isEdit =
+  hasField && area?._edit && Astro.url.searchParams.get("aposEdit");
 const forceWrapper = aposAttributes || aposStyle || aposClassName;
 
 const WidgetComponent = widgetComponent ?? AposWidget;
@@ -84,10 +93,12 @@ function getWidgetOptions(options: any = {}) {
       })}
     </Wrapper>
   ) : (
-    // Orphaned area. Dev-only diagnostic: `import.meta.env.DEV` is replaced
-    // with `false` in production, so this branch is dead-code eliminated.
+    // Genuine orphan only. Dev-only diagnostic: `import.meta.env.DEV` is
+    // replaced with `false` in production, so this branch is dead-code
+    // eliminated. Un-annotated (e.g. REST-delivered) areas never reach here —
+    // they render above.
     (import.meta as any).env.DEV &&
-    area?.metaType === "area" && (
+    isOrphan && (
       <div
         data-apos-area-error
         role="alert"
diff --git a/packages/apostrophe/modules/@apostrophecms/area/index.js b/packages/apostrophe/modules/@apostrophecms/area/index.js
index 5d74add608..4ec664f70e 100644
--- a/packages/apostrophe/modules/@apostrophecms/area/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/area/index.js
@@ -140,7 +140,7 @@ module.exports = {
               // so this logic is reproduced partially
               self.apos.doc.walk(area, (o, k, v) => {
                 if (v && v.metaType === 'area') {
-                  const manager = self.apos.util.getManagerOf(o);
+                  const manager = self.apos.util.getManagerOf(o, { log: false });
                   if (!manager) {
                     self.apos.util.warnDevOnce(
                       'noManagerForDocInExternalFront',
@@ -285,37 +285,95 @@ module.exports = {
           self.missingWidgetTypes[name] = true;
         }
       },
-      // Build an empty area and attach it to `parent[name]`. When `parent`
-      // is doc-backed (has `_docId`, or is itself a doc) and `areaDotPath`
-      // is provided, also persist the area at that dot-path. The write is
-      // idempotent via `$eq: null`, so concurrent renders won't clobber each
-      // other. Returns the area.
+      // Build an empty area and attach it to `parent[name]`. When the area's
+      // location can be resolved inside the *persisted* document, also stub it
+      // into the database so the backend recognizes it for later edits.
+      // Returns the area.
       //
-      // Used by the `{% area %}` tag and the external front annotator as a
+      // Options:
+      // - `throwIfNotFound` (default `false`): when `parent` is doc-backed but
+      //   the document or the container cannot be located in the database,
+      //   throw a `notfound` error instead of returning an in-memory-only
+      //   stub. The `{% area %}` tag opts in to preserve its historical
+      //   behavior; the external front annotator leaves it off so a render is
+      //   never brought down by such a case.
+      //
+      // Used by the `{% area %}` tag and the external front annotator as the
       // single source of truth for stubbing schema areas that have no value
       // yet.
-      async addMissingArea(parent, name, areaDotPath) {
+      async addMissingArea(parent, name, { throwIfNotFound = false } = {}) {
         const area = {
           metaType: 'area',
           _id: self.apos.util.generateId(),
           items: []
         };
         parent[name] = area;
+
         const docId = parent._docId ??
           (parent.metaType === 'doc' ? parent._id : null);
-        if (docId && areaDotPath) {
-          await self.apos.doc.db.updateOne(
-            {
-              _id: docId,
-              [areaDotPath]: { $eq: null }
-            },
-            {
-              $set: { [areaDotPath]: self.apos.util.clonePermanent(area) }
-            }
-          );
+        const areaDotPath = await self.resolvePersistedAreaDotPath(parent, name);
+        if (!areaDotPath) {
+          if (throwIfNotFound && docId) {
+            throw self.apos.error('notfound');
+          }
+          return area;
+        }
+
+        const result = await self.apos.doc.db.updateOne(
+          {
+            _id: docId,
+            // Idempotent and race-safe: only write when still absent.
+            [areaDotPath]: { $eq: null }
+          },
+          {
+            $set: { [areaDotPath]: self.apos.util.clonePermanent(area) }
+          }
+        );
+        if (result.modifiedCount === 0) {
+          // Another request stubbed it first (or it already existed): adopt
+          // the persisted `_id` so we render the same area.
+          const refreshed = await self.apos.doc.db.findOne({ _id: docId });
+          const persisted = refreshed && self.apos.util.get(refreshed, areaDotPath);
+          if (persisted?._id) {
+            area._id = persisted._id;
+          }
         }
         return area;
       },
+
+      // Resolve the MongoDB dot-path at which `parent[name]` should be stored,
+      // computed from the *persisted* document so it always reflects real
+      // storage (not the in-memory graph with its loaded relationships). The
+      // `parent` object is located inside the freshly read document by its
+      // `_id`. Returns the dot-path string, or `null` when the area cannot be
+      // safely persisted (no doc id, doc not in the database, or `parent` is
+      // not part of the persisted document, e.g. loaded relationship data).
+      async resolvePersistedAreaDotPath(parent, name) {
+        const docId = parent._docId ??
+          (parent.metaType === 'doc' ? parent._id : null);
+        if (!docId) {
+          return null;
+        }
+        const mainDoc = await self.apos.doc.db.findOne({ _id: docId });
+        if (!mainDoc) {
+          return null;
+        }
+        if (parent._id === docId) {
+          return name;
+        }
+        if (!parent._id) {
+          return null;
+        }
+        const found = self.apos.util.findNestedObjectAndDotPathById(
+          mainDoc,
+          parent._id,
+          { ignoreDynamicProperties: true }
+        );
+        if (!found) {
+          return null;
+        }
+        return `${found.dotPath}.${name}`;
+      },
       prepForRender(area, context, fieldName) {
         const manager = self.apos.util.getManagerOf(context);
         const field = manager.schema.find(field => field.name === fieldName);
diff --git a/packages/apostrophe/modules/@apostrophecms/area/lib/custom-tags/area.js b/packages/apostrophe/modules/@apostrophecms/area/lib/custom-tags/area.js
index c9e5615ad1..865bd68a7b 100644
--- a/packages/apostrophe/modules/@apostrophecms/area/lib/custom-tags/area.js
+++ b/packages/apostrophe/modules/@apostrophecms/area/lib/custom-tags/area.js
@@ -59,34 +59,7 @@ module.exports = function(self) {
       }
       area = doc[name];
       if (!area) {
-        // Problem: area is in schema but that doesn't guarantee it
-        // has a value, for instance the field could be new in the schema.
-        // But we need an area _id. Stub it into the db on the fly
-        // without race conditions
-        const docId = doc._docId || ((doc.metaType === 'doc') ? doc._id : null);
-        let areaDotPath;
-        if (docId) {
-          const mainDoc = await self.apos.doc.db.findOne({ _id: docId });
-          if (!mainDoc) {
-            throw self.apos.error('notfound');
-          }
-          let docDotPath;
-          try {
-            docDotPath = (doc._id === docId) ? '' : self.apos.util.findNestedObjectAndDotPathById(mainDoc, doc._id).dotPath;
-          } catch (e) {
-            // Race condition: someone removed the area's parent object.
-            // Unlikely thanks to advisory locking
-            throw self.apos.error('notfound');
-          }
-          areaDotPath = docDotPath ? `${docDotPath}.${name}` : name;
-        }
-        area = await self.apos.area.addMissingArea(doc, name, areaDotPath);
-        if (docId) {
-          // Race-safety: re-read the persisted _id in case another request
-          // wrote first (our $eq: null write was a no-op in that case).
-          const refreshed = await self.apos.doc.db.findOne({ _id: docId });
-          area._id = self.apos.util.get(refreshed, areaDotPath)._id;
-        }
+        area = await self.apos.area.addMissingArea(doc, name, { throwIfNotFound: true });
       }
       const manager = self.apos.util.getManagerOf(doc);
       const field = manager.schema.find(field => field.name === name);
diff --git a/packages/apostrophe/modules/@apostrophecms/template/index.js b/packages/apostrophe/modules/@apostrophecms/template/index.js
index 5cd51cadd5..925a25932c 100644
--- a/packages/apostrophe/modules/@apostrophecms/template/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/template/index.js
@@ -1352,19 +1352,18 @@ module.exports = {
       async annotateDocForExternalFront(doc, { scene } = {}) {
         const handled = new WeakSet();
         const missingAreas = [];
-        self.apos.doc.walk(doc, (o, k, v, __dotPath) => {
+        self.apos.doc.walk(doc, (o, k, v) => {
           if (o._edit === true && !handled.has(o)) {
             handled.add(o);
-            // `__dotPath` is the path to `v` (= o[k]); the container `o` lives
-            // one segment up — '' for the top-level doc.
-            const dot = __dotPath.lastIndexOf('.');
-            const containerDotPath = dot === -1 ? '' : __dotPath.substring(0, dot);
             for (const field of self.missingSchemaAreas(o)) {
-              missingAreas.push([ o, field, containerDotPath ]);
+              missingAreas.push([ o, field ]);
             }
           }
           if (v && v.metaType === 'area') {
-            const manager = self.apos.util.getManagerOf(o);
+            // A missing manager here is expected (e.g. an area reached on a
+            // container without a manager) and handled below, so suppress the
+            // low-level per-call log and rely on the once-per-process warning.
+            const manager = self.apos.util.getManagerOf(o, { log: false });
             if (!manager) {
               self.apos.util.warnDevOnce(
                 'noManagerForDocInExternalFront',
@@ -1374,6 +1373,7 @@ module.exports = {
             }
             const field = manager.schema.find(f => f.name === k);
             if (!field) {
+              v._isOrphan = true;
               self.apos.util.warnDevOnce(
                 'noSchemaFieldForAreaInExternalFront',
                 `Area ${k} has no matching schema field in ${o.metaType} ${o.type || ''}`
@@ -1385,15 +1385,8 @@ module.exports = {
         });
         // Materialize every missing area, after the walk so we never add keys
         // to an object while it is being traversed.
-        for (const [ o, field, containerDotPath ] of missingAreas) {
-          const areaDotPath = containerDotPath
-            ? `${containerDotPath}.${field.name}`
-            : field.name;
-          const area = await self.apos.area.addMissingArea(
-            o,
-            field.name,
-            areaDotPath
-          );
+        for (const [ o, field ] of missingAreas) {
+          const area = await self.apos.area.addMissingArea(o, field.name);
           area._edit = true;
           area._docId = o._docId ?? (o.metaType === 'doc' ? o._id : null);
           self.annotateAreaForExternalFront(field, area, { scene });
@@ -1406,6 +1399,7 @@ module.exports = {
       // at least as an empty array.
 
       annotateAreaForExternalFront(field, area, { scene } = {}) {
+        area._aposAnnotated = true;
         area.field = field;
         area.options = field.options;
         // Really widget configurations, but the method name is already set in
@@ -1420,23 +1414,32 @@ module.exports = {
           };
         }).filter(choice => !!choice);
 
-        area.items ||= [];
+        // Drop corrupt items (null, or not a widget).
+        area.items = (area.items || []).filter((item) => {
+          const valid = item && item.metaType === 'widget' && item.type;
+          if (!valid) {
+            self.apos.util.warnDevOnce(
+              'corruptAreaItemInExternalFront',
+              `Dropping malformed item in area ${area._id || ''}`
+            );
+          }
+          return valid;
+        });
+
         for (const item of area.items) {
           // Add _docId if area has one
           if (area._docId) {
             item._docId = area._docId;
           }
 
-          // Annotate each individual widget with its options
-          // Each widget must elect into this by creating an
-          // `annotateWidgetForExternalFront() method.
+          // Annotate each individual widget with its options. Each widget must
+          // elect into this by creating an `annotateWidgetForExternalFront()`
+          // method.
           const manager = self.apos.area.getWidgetManager(item.type);
           if (manager) {
-            const widgetOptions = manager.annotateWidgetForExternalFront(item, { scene });
-            item._options = widgetOptions;
+            item._options = manager.annotateWidgetForExternalFront(item, { scene });
           } else {
             self.apos.area.warnMissingWidgetType(item.type);
-            throw self.apos.error('invalid', 'Missing widget type');
           }
         }
       },
diff --git a/packages/apostrophe/test/external-front.js b/packages/apostrophe/test/external-front.js
index b49424cfe7..e12e5157c1 100644
--- a/packages/apostrophe/test/external-front.js
+++ b/packages/apostrophe/test/external-front.js
@@ -88,6 +88,9 @@ describe('External Front', function() {
     // Existing area still annotated, unchanged behavior
     assert(doc.main.field && doc.main.field.name === 'main');
     assert(doc.main.options);
+    // Carries the provenance signal, and is never flagged as orphan
+    assert.strictEqual(doc.main._aposAnnotated, true);
+    assert.strictEqual(doc.main._isOrphan, undefined);
 
     // Missing area added as an empty, editable, annotated area
     assert(doc.extra, 'extra area was materialized');
@@ -99,6 +102,59 @@ describe('External Front', function() {
     assert(doc.extra.field && doc.extra.field.name === 'extra');
     assert(doc.extra.options, 'annotated with options');
     assert(Array.isArray(doc.extra.choices));
+    assert.strictEqual(doc.extra._aposAnnotated, true);
+    assert.strictEqual(doc.extra._isOrphan, undefined);
+  });
+
+  it('flags a genuine orphan area, leaves valid areas alone, and never persists the flag', async function() {
+    // Insert a doc with an area whose field is no longer in the schema.
+    const docId = 'orphan-test:en:draft';
+    await apos.doc.db.deleteOne({ _id: docId });
+    await apos.doc.db.insertOne({
+      _id: docId,
+      type: 'product',
+      metaType: 'doc',
+      aposMode: 'draft',
+      aposDocId: 'orphan-test',
+      aposLocale: 'en:draft',
+      title: 'Orphan Test',
+      slug: 'orphan-test',
+      main: {
+        metaType: 'area',
+        _id: 'orphan-main',
+        items: []
+      },
+      // `ghost` is not a field in the product schema (simulates a removed field)
+      ghost: {
+        metaType: 'area',
+        _id: 'orphan-ghost',
+        items: []
+      }
+    });
+
+    const doc = await apos.doc.db.findOne({ _id: docId });
+    doc._edit = true;
+    doc.main._edit = true;
+    doc.ghost._edit = true;
+
+    await apos.template.annotateDocForExternalFront(doc);
+
+    // The annotator owns the doc, so the orphan is flagged — and has no field.
+    // It is NOT marked `_aposAnnotated` (that signals a fully annotated area).
+    assert.strictEqual(doc.ghost._isOrphan, true, 'orphan flagged');
+    assert.strictEqual(doc.ghost.field, undefined, 'orphan has no schema field');
+    assert.strictEqual(doc.ghost._aposAnnotated, undefined, 'orphan is not _aposAnnotated');
+    // The valid area is annotated normally and never flagged orphan.
+    assert(doc.main.field && doc.main._isOrphan === undefined);
+    assert.strictEqual(doc.main._aposAnnotated, true);
+
+    // Neither flag is written to the database.
+    const persisted = await apos.doc.db.findOne({ _id: docId });
+    assert.strictEqual(persisted.ghost._isOrphan, undefined, 'flag not persisted');
+    assert.strictEqual(persisted.main._isOrphan, undefined, 'flag not persisted');
+    assert.strictEqual(persisted.main._aposAnnotated, undefined, 'signal not persisted');
+
+    await apos.doc.db.deleteOne({ _id: docId });
   });
 
   it('annotateDocForExternalFront leaves missing areas alone on a non-editable doc', async function() {
@@ -169,6 +225,222 @@ describe('External Front', function() {
     await apos.doc.db.deleteOne({ _id: docId });
   });
 
+  it('does not write missing areas at an in-memory path when a relationship target needs one (regression)', async function() {
+    // The editor's in-memory graph contains loaded relationship data. A widget
+    // in the host doc relates to a SEPARATE editable doc that is missing a
+    // schema area (added after it was created). The area must be stubbed at the
+    // related doc's OWN path — never at a path derived from the host's
+    // in-memory traversal, which would write into the wrong document and pad
+    // arrays with nulls. This reproduces the production corruption that left
+    // null items and stray fragments in published docs.
+    const hostId = 'reg-host:en:draft';
+    const relatedId = 'reg-related:en:draft';
+    await apos.doc.db.deleteMany({ _id: { $in: [ hostId, relatedId ] } });
+
+    // Host has both areas filled (nothing missing of its own) and a single
+    // rich-text widget in `main`.
+    await apos.doc.db.insertOne({
+      _id: hostId,
+      type: 'product',
+      metaType: 'doc',
+      aposMode: 'draft',
+      aposDocId: 'reg-host',
+      aposLocale: 'en:draft',
+      title: 'Host',
+      slug: 'reg-host',
+      main: {
+        metaType: 'area',
+        _id: 'reg-host-main',
+        items: [
+          {
+            _id: 'reg-host-widget',
+            metaType: 'widget',
+            type: '@apostrophecms/rich-text',
+            content: '<p>hi</p>'
+          }
+        ]
+      },
+      extra: {
+        metaType: 'area',
+        _id: 'reg-host-extra',
+        items: []
+      }
+    });
+    // Related has `main` but no `extra` (field added to the schema later).
+    await apos.doc.db.insertOne({
+      _id: relatedId,
+      type: 'product',
+      metaType: 'doc',
+      aposMode: 'draft',
+      aposDocId: 'reg-related',
+      aposLocale: 'en:draft',
+      title: 'Related',
+      slug: 'reg-related',
+      main: {
+        metaType: 'area',
+        _id: 'reg-related-main',
+        items: []
+      }
+    });
+
+    const hostStored = await apos.doc.db.findOne({ _id: hostId });
+
+    // Build the in-memory graph: the host widget carries a loaded relationship
+    // to the related doc, which is editable and missing `extra`.
+    const related = await apos.doc.db.findOne({ _id: relatedId });
+    related._edit = true;
+    related._docId = relatedId;
+    related.main._edit = true;
+    delete related.extra;
+
+    const host = await apos.doc.db.findOne({ _id: hostId });
+    host._edit = true;
+    host._docId = hostId;
+    host.main._edit = true;
+    host.main.items[0]._docId = hostId;
+    host.main.items[0]._related = [ related ];
+
+    await apos.template.annotateDocForExternalFront(host);
+
+    // Related doc: `extra` stubbed at its OWN top-level path, clean, and its
+    // existing `main` is untouched (no host-relative path leaked in).
+    const relatedAfter = await apos.doc.db.findOne({ _id: relatedId });
+    assert(relatedAfter.extra, 'extra stubbed on the related doc');
+    assert.strictEqual(relatedAfter.extra.metaType, 'area');
+    assert.deepStrictEqual(relatedAfter.extra.items, []);
+    assert.strictEqual(relatedAfter.extra._id, related.extra._id, 'same _id as in memory');
+    assert.strictEqual(relatedAfter.main.items.length, 0, 'related main not padded');
+    assert.ok(!Object.prototype.hasOwnProperty.call(relatedAfter, '0'), 'no numeric-key fragment');
+
+    // Host doc: completely untouched in the database.
+    const hostAfter = await apos.doc.db.findOne({ _id: hostId });
+    assert.strictEqual(hostAfter.main.items.length, 1, 'host main.items not extended');
+    assert(
+      hostAfter.main.items.every(i => i && i.metaType === 'widget'),
+      'no null/typeless items in host'
+    );
+    assert.deepStrictEqual(hostAfter, hostStored, 'host doc unchanged in the DB');
+
+    await apos.doc.db.deleteMany({ _id: { $in: [ hostId, relatedId ] } });
+  });
+
+  it('annotateAreaForExternalFront drops corrupt items so they never reach the front end', function() {
+    const field = {
+      name: 'main',
+      options: {
+        widgets: { '@apostrophecms/rich-text': {} }
+      }
+    };
+    const area = {
+      metaType: 'area',
+      _id: 'guard-area',
+      _docId: 'guard-doc:en:published',
+      items: [
+        {
+          _id: 'w1',
+          metaType: 'widget',
+          type: '@apostrophecms/rich-text',
+          content: '<p>ok</p>'
+        },
+        // The two shapes the production corruption produced. A `null` left in
+        // place would crash the Astro area renderer (`...item._options`).
+        null,
+        {
+          _id: 'frag',
+          foo: 'bar'
+        }
+      ]
+    };
+
+    assert.doesNotThrow(() => {
+      apos.template.annotateAreaForExternalFront(field, area, { scene: 'apos' });
+    });
+
+    // Corrupt items are removed; only the valid, annotated widget remains.
+    assert.strictEqual(area.items.length, 1, 'corrupt items dropped');
+    assert.strictEqual(area.items[0]._id, 'w1');
+    assert(area.items[0]._options, 'valid widget annotated');
+    assert.strictEqual(area.items[0]._docId, area._docId, 'valid widget got _docId');
+  });
+
+  it('annotateAreaForExternalFront keeps an unknown widget type un-annotated instead of throwing', function() {
+    const field = {
+      name: 'main',
+      options: {
+        widgets: { '@apostrophecms/rich-text': {} }
+      }
+    };
+    const area = {
+      metaType: 'area',
+      _id: 'unknown-area',
+      _docId: 'unknown-doc:en:published',
+      items: [
+        {
+          _id: 'w1',
+          metaType: 'widget',
+          type: '@apostrophecms/rich-text',
+          content: '<p>ok</p>'
+        },
+        // A real widget whose module is not registered (e.g. `custom-layout`).
+        {
+          _id: 'w2',
+          metaType: 'widget',
+          type: 'definitely-not-a-registered-widget'
+        }
+      ]
+    };
+
+    // No throw — a missing widget module must not 500 the whole render.
+    assert.doesNotThrow(() => {
+      apos.template.annotateAreaForExternalFront(field, area, { scene: 'apos' });
+    });
+
+    // The unknown widget is preserved (so its content survives a save) but left
+    // un-annotated; the front end skips it.
+    assert.strictEqual(area.items.length, 2, 'unknown-type item preserved');
+    assert(area.items[0]._options, 'valid widget annotated');
+    assert.strictEqual(area.items[1].type, 'definitely-not-a-registered-widget');
+    assert.strictEqual(area.items[1]._options, undefined, 'unknown widget not annotated');
+  });
+
+  it('addMissingArea honors throwIfNotFound (tag behavior) and defaults to graceful (annotator)', async function() {
+    // Doc-backed parent whose document is not in the database (the missing-doc
+    // race the `{% area %}` tag historically treated as notfound).
+    const ghost = {
+      _id: 'ghost:en:published',
+      metaType: 'doc',
+      type: 'product'
+    };
+
+    // Opt-in (tag): throws notfound rather than persisting nothing silently.
+    await assert.rejects(
+      () => apos.area.addMissingArea(ghost, 'extra', { throwIfNotFound: true }),
+      err => err && err.name === 'notfound'
+    );
+    // The in-memory stub is still attached for the caller.
+    assert(ghost.extra && ghost.extra.metaType === 'area');
+
+    // Default (annotator): degrades to an in-memory stub, never throws.
+    const ghost2 = {
+      _id: 'ghost2:en:published',
+      metaType: 'doc',
+      type: 'product'
+    };
+    const area = await apos.area.addMissingArea(ghost2, 'extra');
+    assert.strictEqual(area.metaType, 'area');
+    assert(area._id, 'in-memory stub has an _id');
+    assert.deepStrictEqual(area.items, []);
+    assert.strictEqual(ghost2.extra, area, 'stub attached to the parent');
+
+    // A parent with no docId is never an error, even with throwIfNotFound.
+    const unsaved = {
+      metaType: 'doc',
+      type: 'product'
+    };
+    const unsavedArea = await apos.area.addMissingArea(unsaved, 'extra', { throwIfNotFound: true });
+    assert.strictEqual(unsavedArea.metaType, 'area');
+  });
+
   it('fetch home with external front', async function() {
     const data = await await apos.http.get('/', {
       headers: {

From 4be7e008849a4e215586c1eec345f1aed5e5e6ec Mon Sep 17 00:00:00 2001
From: Dipanshu singh <161134993+Dipanshusinghh@users.noreply.github.com>
Date: Thu, 4 Jun 2026 17:46:45 +0530
Subject: [PATCH 41/56] Fix raw-text sanitization bypass vulnerability and add
 regression tests (#5432)

---
 packages/sanitize-html/index.js     |  4 +--
 packages/sanitize-html/test/test.js | 56 +++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+), 2 deletions(-)

diff --git a/packages/sanitize-html/index.js b/packages/sanitize-html/index.js
index 6a67683868..b5da859f7e 100644
--- a/packages/sanitize-html/index.js
+++ b/packages/sanitize-html/index.js
@@ -566,13 +566,13 @@ function sanitizeHtml(html, options, _recursing) {
 
       if (options.disallowedTagsMode === 'completelyDiscard' && !tagAllowed(tag)) {
         text = '';
-      } else if ((options.disallowedTagsMode === 'discard' || options.disallowedTagsMode === 'completelyDiscard') && ((tag === 'script') || (tag === 'style'))) {
+      } else if (tag && tagAllowed(tag) && (options.disallowedTagsMode === 'discard' || options.disallowedTagsMode === 'completelyDiscard') && ((tag === 'script') || (tag === 'style'))) {
         // htmlparser2 gives us these as-is. Escaping them ruins the content. Allowing
         // script tags is, by definition, game over for XSS protection, so if that's
         // your concern, don't allow them. The same is essentially true for style tags
         // which have their own collection of XSS vectors.
         result += text;
-      } else if ((options.disallowedTagsMode === 'discard' || options.disallowedTagsMode === 'completelyDiscard') && (tag === 'textarea' || tag === 'xmp')) {
+      } else if (tag && tagAllowed(tag) && (options.disallowedTagsMode === 'discard' || options.disallowedTagsMode === 'completelyDiscard') && (tag === 'textarea' || tag === 'xmp')) {
         // htmlparser2 treats <textarea> and <xmp> as raw text elements and
         // does NOT decode entities inside them. The text is already properly
         // encoded, so pass it through without additional escaping to avoid
diff --git a/packages/sanitize-html/test/test.js b/packages/sanitize-html/test/test.js
index 5bd342e530..f757d7f286 100644
--- a/packages/sanitize-html/test/test.js
+++ b/packages/sanitize-html/test/test.js
@@ -1931,4 +1931,60 @@ describe('sanitizeHtml', function() {
       ), '!<xmp>&lt;/xmp&gt;&lt;svg/onload=prompt`xs`&gt;</xmp>!'
     );
   });
+
+  describe('CVE-2026-44990 regression and raw-text edge cases', function() {
+    it('should escape raw-text inner content when xmp tag is disallowed and discarded under custom nonTextTags', function() {
+      assert.strictEqual(
+        sanitizeHtml('<xmp><script>alert(1)</script></xmp>', {
+          nonTextTags: ['script', 'style']
+        }),
+        '&lt;script&gt;alert(1)&lt;/script&gt;'
+      );
+    });
+
+    it('should escape raw-text inner content when script tag is disallowed and discarded under empty nonTextTags', function() {
+      assert.strictEqual(
+        sanitizeHtml('<script><svg onload=alert(1)></script>', {
+          nonTextTags: []
+        }),
+        '&lt;svg onload=alert(1)&gt;'
+      );
+    });
+
+    it('should escape raw-text inner content when textarea tag is disallowed and discarded', function() {
+      assert.strictEqual(
+        sanitizeHtml('<textarea><script>alert(1)</script></textarea>', {
+          nonTextTags: []
+        }),
+        '&lt;script&gt;alert(1)&lt;/script&gt;'
+      );
+    });
+
+    it('should escape raw-text inner content when style tag is disallowed and discarded', function() {
+      assert.strictEqual(
+        sanitizeHtml('<style><a onload=alert(1)></style>', {
+          nonTextTags: []
+        }),
+        '&lt;a onload=alert(1)&gt;'
+      );
+    });
+
+    it('should handle malformed or unclosed raw-text tags correctly', function() {
+      assert.strictEqual(
+        sanitizeHtml('<xmp><script>alert(1)', {
+          nonTextTags: ['script', 'style']
+        }),
+        '&lt;script&gt;alert(1)'
+      );
+    });
+
+    it('should handle sibling raw-text elements correctly without leaking states', function() {
+      assert.strictEqual(
+        sanitizeHtml('<noembed><script>alert(1)</script></noembed><noscript><style>body{}</style></noscript>', {
+          nonTextTags: []
+        }),
+        'alert(1)body{}'
+      );
+    });
+  });
 });

From 862d7606839622d6bf22e61b6be7ed15dd84dcbc Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Thu, 4 Jun 2026 08:51:31 -0400
Subject: [PATCH 42/56] changeset for singh contribution (#5442)

---
 .changeset/new-doors-turn.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/new-doors-turn.md

diff --git a/.changeset/new-doors-turn.md b/.changeset/new-doors-turn.md
new file mode 100644
index 0000000000..b7aa9e76ab
--- /dev/null
+++ b/.changeset/new-doors-turn.md
@@ -0,0 +1,5 @@
+---
+"sanitize-html": patch
+---
+
+Address a potential vulnerability when nonTextTags is configured in a nonstandard way. While it is never a good idea to remove known non-text tags from the standard list e.g. script, styles, etc., this change ensures that doing so does not result in nested tags being passed through without sanitization when they are not expressly allowed. (ApostropheCMS would never trigger this situation.) Thanks to [Dipanshu singh](https://github.com/Dipanshusinghh) for pointing out the issue and contributing the fix.

From 7ce629621de93f8359bd2eca1a276d242a751cba Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Fri, 5 Jun 2026 15:31:33 +0300
Subject: [PATCH 43/56] Fix relationship select scrolling issue (#5445)

* Fix relationship select scrolling issue

* Prevent same scrolling bugs to appear in media manager
---
 .changeset/smart-kids-rest.md                                | 5 +++++
 .../image/ui/apos/components/AposMediaUploader.vue           | 3 +++
 .../@apostrophecms/ui/ui/apos/scss/global/_inputs.scss       | 2 ++
 3 files changed, 10 insertions(+)
 create mode 100644 .changeset/smart-kids-rest.md

diff --git a/.changeset/smart-kids-rest.md b/.changeset/smart-kids-rest.md
new file mode 100644
index 0000000000..ce014a1952
--- /dev/null
+++ b/.changeset/smart-kids-rest.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": patch
+---
+
+Selecting an item in a relationship "browse" dialog no longer scrolls the title and Cancel/Select buttons out of view when the item is far down the list.
diff --git a/packages/apostrophe/modules/@apostrophecms/image/ui/apos/components/AposMediaUploader.vue b/packages/apostrophe/modules/@apostrophecms/image/ui/apos/components/AposMediaUploader.vue
index 9ba38df9e4..4041ccd6ea 100644
--- a/packages/apostrophe/modules/@apostrophecms/image/ui/apos/components/AposMediaUploader.vue
+++ b/packages/apostrophe/modules/@apostrophecms/image/ui/apos/components/AposMediaUploader.vue
@@ -252,6 +252,9 @@ export default {
     @include apos-transition();
 
     & {
+      // Contain the visually hidden (`.apos-sr-only`, position: absolute)
+      // file input so focusing it does not scroll a distant ancestor.
+      position: relative;
       display: flex;
       box-sizing: border-box;
       align-items: center;
diff --git a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/scss/global/_inputs.scss b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/scss/global/_inputs.scss
index 60dcd1b43c..36d857504c 100644
--- a/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/scss/global/_inputs.scss
+++ b/packages/apostrophe/modules/@apostrophecms/ui/ui/apos/scss/global/_inputs.scss
@@ -372,6 +372,8 @@
   @include type-base;
 
   & {
+    // Do not remove - it fixes unintended `sr-only` side effect.
+    position: relative;
     display: flex;
     align-items: center;
     color: var(--a-base-2);

From 97e9d56df10bf95217bc5e50e60301ec4d37e923 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Fri, 5 Jun 2026 09:34:43 -0400
Subject: [PATCH 44/56] jsx changeset (#5446)

---
 .changeset/violet-windows-draw.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/violet-windows-draw.md

diff --git a/.changeset/violet-windows-draw.md b/.changeset/violet-windows-draw.md
new file mode 100644
index 0000000000..755e3cde7d
--- /dev/null
+++ b/.changeset/violet-windows-draw.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": minor
+---
+
+JSX support for templates within ApostropheCMS. JSX is now co-equal with Nunjucks, with a gradual migration strategy. Anyone who is familiar with React will be very comfortable writing JSX templates, which also offer a superior debugging experience, and templates can be migrated gradually. JSX is a great option for those who don't wish to create parallel Astro and ApostropheCMS projects, but still prefer a modern syntax. For more information, see the new [JSX templates guide](https://apostrophecms.com/docs/guide/jsx-templates.html).

From e38ffe8a85c5dd76c8886183ef6ba394d749842e Mon Sep 17 00:00:00 2001
From: Miro Yovchev <2827783+myovchev@users.noreply.github.com>
Date: Mon, 8 Jun 2026 16:51:25 +0300
Subject: [PATCH 45/56] Ensure install of the project root for astro projects
 (#5449)

---
 .../src/core/steps/install.js                 | 10 +++++--
 .../test/core/install.test.js                 | 30 +++++++++++++++++++
 2 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/packages/create-apostrophe/src/core/steps/install.js b/packages/create-apostrophe/src/core/steps/install.js
index b860e49a53..4539916a21 100644
--- a/packages/create-apostrophe/src/core/steps/install.js
+++ b/packages/create-apostrophe/src/core/steps/install.js
@@ -1,6 +1,9 @@
 // Step: install dependencies with npm. Standalone installs once in the app
-// root; an external-frontend project installs in backend/ and frontend/.
-// A non-npm manager is rejected up front. Failure → 'dependency_install'.
+// root; an external-frontend project installs in backend/ and frontend/, and
+// — if the project root ships its own package.json — also at the root (some
+// Astro kits put orchestration deps like `concurrently` there to power a
+// single `npm run dev`). A non-npm manager is rejected up front. Failure →
+// 'dependency_install'.
 
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
@@ -41,6 +44,9 @@ export async function install(
     if (existsSync(frontendDir)) {
       dirs.push(frontendDir);
     }
+    if (existsSync(join(projectDir, 'package.json'))) {
+      dirs.push(projectDir);
+    }
   }
 
   for (const cwd of dirs) {
diff --git a/packages/create-apostrophe/test/core/install.test.js b/packages/create-apostrophe/test/core/install.test.js
index 7204634ab6..7c84d8b78c 100644
--- a/packages/create-apostrophe/test/core/install.test.js
+++ b/packages/create-apostrophe/test/core/install.test.js
@@ -88,6 +88,36 @@ describe('core/steps/install', function () {
     ]);
   });
 
+  it('external frontend + root package.json: backend → frontend → root', async function () {
+    // Newer Astro kits ship a root package.json with orchestration deps
+    // (concurrently) so a single `npm run dev` runs both apps. Without
+    // installing the root, `npm run dev` fails with "concurrently: not found".
+    const projectDir = join(dir, 'proj');
+    const appRoot = join(projectDir, 'backend');
+    mkdirSync(appRoot, { recursive: true });
+    mkdirSync(join(projectDir, 'frontend'), { recursive: true });
+    writeFileSync(join(projectDir, 'package.json'), '{}');
+
+    const calls = [];
+    await install(
+      {
+        projectDir,
+        appRoot,
+        frontend: 'astro',
+        packageManager: 'npm'
+      },
+      { run: fakeRunFactory(calls) }
+    );
+
+    // Root install runs LAST so its (potentially redundant) recursion into
+    // workspaces hits an already-warm cache.
+    assert.deepEqual(calls.map((c) => [ c.command, c.cwd ]), [
+      [ 'npm', appRoot ],
+      [ 'npm', join(projectDir, 'frontend') ],
+      [ 'npm', projectDir ]
+    ]);
+  });
+
   it('unknown pm runs npm, reports \'unknown\'', async function () {
     const projectDir = join(dir, 'proj');
     mkdirSync(projectDir, { recursive: true });

From a70541a55826d0e371139ca4eae386542cf273b0 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Mon, 8 Jun 2026 14:34:14 -0400
Subject: [PATCH 46/56] test node 26 (#5450)

* test node 26

* support node 26 by bumping the better-sqlite3 version

* node 22 requirement
---
 .github/workflows/monorepo.yml                      | 2 +-
 packages/create-apostrophe/README.md                | 3 +--
 packages/create-apostrophe/bin/create-apostrophe.js | 6 +++---
 packages/create-apostrophe/package.json             | 2 +-
 packages/db-connect/package.json                    | 2 +-
 5 files changed, 7 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/monorepo.yml b/.github/workflows/monorepo.yml
index 4276a83fe0..8cf21c4887 100644
--- a/.github/workflows/monorepo.yml
+++ b/.github/workflows/monorepo.yml
@@ -4,7 +4,7 @@ permissions:
 
 env:
   # Define supported runtime versions for matrix expansion once for the workflow.
-  NODE_VERSIONS_JSON: "[20,22,24]"
+  NODE_VERSIONS_JSON: "[22,24,26]"
   MONGODB_VERSIONS_JSON: '["7","8"]'
   REDIS_VERSION: "7"
   POSTGRES_VERSION: "16"
diff --git a/packages/create-apostrophe/README.md b/packages/create-apostrophe/README.md
index c563a35c4d..73bb0e003b 100644
--- a/packages/create-apostrophe/README.md
+++ b/packages/create-apostrophe/README.md
@@ -28,8 +28,7 @@ npm create apostrophe@latest -- --help
 > Everything after `--` is forwarded to the installer; npm swallows args without it.
 > Run `-- --help` any time for the full flag list.
 
-Requires **Node 20+** and **npm** (pnpm and yarn aren't supported yet - running
-under either is rejected up front).
+Requires **Node 22+** and **npm** (pnpm and yarn aren't by this CLI yet, but they work fine with apostrophe).
 
 ## Architecture
 
diff --git a/packages/create-apostrophe/bin/create-apostrophe.js b/packages/create-apostrophe/bin/create-apostrophe.js
index e86700a3a2..6d6056c2c2 100755
--- a/packages/create-apostrophe/bin/create-apostrophe.js
+++ b/packages/create-apostrophe/bin/create-apostrophe.js
@@ -5,11 +5,11 @@
 
 const nodeVersion = process && process.versions && process.versions.node;
 const major = nodeVersion ? parseInt(nodeVersion.split('.')[0], 10) : NaN;
-if (Number.isFinite(major) && major < 20) {
+if (Number.isFinite(major) && major < 22) {
   process.stderr.write(
-    'Node.js 20 or newer is required. ' +
+    'Node.js 22 or newer is required. ' +
     'You are running Node ' + nodeVersion + '.\n' +
-    'Please upgrade Node (https://nodejs.org) and try again.\n'
+    'Please upgrade Node (https://nodejs.org) to a current LTS release and try again.\n'
   );
   process.exit(1);
 }
diff --git a/packages/create-apostrophe/package.json b/packages/create-apostrophe/package.json
index 107b907b81..4234de6356 100644
--- a/packages/create-apostrophe/package.json
+++ b/packages/create-apostrophe/package.json
@@ -4,7 +4,7 @@
   "description": "Guided installer for ApostropheCMS — npm create apostrophe@latest",
   "type": "module",
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "bin": {
     "create-apostrophe": "bin/create-apostrophe.js"
diff --git a/packages/db-connect/package.json b/packages/db-connect/package.json
index 37150cddfe..fcfeaa4de9 100644
--- a/packages/db-connect/package.json
+++ b/packages/db-connect/package.json
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@apostrophecms/emulate-mongo-3-driver": "workspace:^",
-    "better-sqlite3": "^11.0.0",
+    "better-sqlite3": "^12.10.0",
     "pg": "^8.11.3"
   }
 }

From 8d084b60a7bf3e93aacb9a2f541924d88a0e6440 Mon Sep 17 00:00:00 2001
From: Robert Means <robert@apostrophecms.com>
Date: Tue, 9 Jun 2026 10:49:09 -0400
Subject: [PATCH 47/56] Add link for telemetry policy (#5455)

---
 packages/create-apostrophe/src/ui/links.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/create-apostrophe/src/ui/links.js b/packages/create-apostrophe/src/ui/links.js
index bcbd2ff7aa..2839d0255f 100644
--- a/packages/create-apostrophe/src/ui/links.js
+++ b/packages/create-apostrophe/src/ui/links.js
@@ -5,7 +5,7 @@
 // without each call site remembering to do it.
 
 const LINKS = Object.freeze({
-  telemetryPolicy: '[link to telemetry policy]',
+  telemetryPolicy: 'https://apostrophecms.com/telemetry-policy?utm_source=cli',
   docs: 'https://docs.apostrophecms.com',
   discord: 'https://discord.gg/apostrophe',
   demoSite: 'https://demo.apostrophecms.com',

From afbceea85fe3eefa05cf480331e5faf0d45db9d3 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Tue, 9 Jun 2026 12:27:14 -0400
Subject: [PATCH 48/56] remove absent options (#5456)

---
 packages/cli/README.md | 9 ---------
 1 file changed, 9 deletions(-)

diff --git a/packages/cli/README.md b/packages/cli/README.md
index 1a61f5fe6e..fd3cf0ba10 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -27,15 +27,6 @@ apos create <shortname-without-spaces>
 
 This will create a local copy of the [ApostropheCMS public demo](https://github.com/apostrophecms/public-demo).
 
-### options
-
-#### `--starter`
-
-Run `create` with a `--starter` flag to start from a Github repository other than the standard starters. For example, `apos create <shortname-without-spaces> --starter=https://github.com/apostrophecms/apostrophe-open-museum.git` would create a project using the [Open Museum](https://github.com/apostrophecms/apostrophe-open-museum) demo. The `--starter` flag also accepts shortened names for any of the [existing starter kits](https://github.com/orgs/apostrophecms/repositories?q=starter-kit&type=all) that consists of the name of the repo with the `starter-kit-` prefix removed. For example, `apos create <shortname-without-spaces> --starter=ecommerce` for the `starter-kit-ecommerce` repo. Finally, if you are using a personal or organizational repo, you can prefix your repo with it's location followed by the name to automatically add `https://github.com/`. For example, `apos create <shortname-without-spaces> --starter=mycoolcompany/my-starter`.
-
-#### `--mongodb-uri`
-If you are not using a locally hosted MongoDB server, you can provide a connection string with the `--mongodb-uri` flag. For the standard Atlas connection string, you will need to add quotes around the connection string due to the query parameters. This allows for the creation of an admin user during project creation. **Note**: this will not add your connection string to the project. It needs to be included through the `APOS_MONGODB_URI` environment variable, potentially through a `.env` file.
-
 ### Astro projects
 
 Hybrid ApostropheCMS + Astro projects are automatically detected by the presence of a `backend/` directory. When detected, the CLI will:

From c82451431d3ce2ca6e4770469f7da3c30367a429 Mon Sep 17 00:00:00 2001
From: Robert Means <robert@apostrophecms.com>
Date: Wed, 10 Jun 2026 05:33:43 -0400
Subject: [PATCH 49/56] Remove consumed 4.30.0 changesets from main (#5454)

---
 .changeset/a11y-admin-nav.md            |  5 -----
 .changeset/a11y-context-title.md        |  5 -----
 .changeset/a11y-locale-switcher.md      |  5 -----
 .changeset/a11y-recently-edited-icon.md |  5 -----
 .changeset/a11y-sr-only.md              |  5 -----
 .changeset/a11y-tray-aria.md            |  5 -----
 .changeset/busy-spies-enter.md          |  5 -----
 .changeset/clean-actors-laugh.md        |  5 -----
 .changeset/cozy-wombats-burn.md         |  5 -----
 .changeset/fiery-lights-fetch.md        |  5 -----
 .changeset/fifty-hornets-follow.md      |  7 -------
 .changeset/full-symbols-obey.md         |  5 -----
 .changeset/open-garlics-smile.md        |  7 -------
 .changeset/pink-buckets-write.md        |  7 -------
 .changeset/quick-guests-join.md         |  5 -----
 .changeset/seven-emus-vanish.md         |  6 ------
 .changeset/solid-boats-send.md          | 10 ----------
 .changeset/stale-shirts-read.md         |  5 -----
 .changeset/upset-ties-cough.md          |  5 -----
 .changeset/wild-forks-fetch.md          | 15 ---------------
 .changeset/wild-lies-film.md            |  5 -----
 21 files changed, 127 deletions(-)
 delete mode 100644 .changeset/a11y-admin-nav.md
 delete mode 100644 .changeset/a11y-context-title.md
 delete mode 100644 .changeset/a11y-locale-switcher.md
 delete mode 100644 .changeset/a11y-recently-edited-icon.md
 delete mode 100644 .changeset/a11y-sr-only.md
 delete mode 100644 .changeset/a11y-tray-aria.md
 delete mode 100644 .changeset/busy-spies-enter.md
 delete mode 100644 .changeset/clean-actors-laugh.md
 delete mode 100644 .changeset/cozy-wombats-burn.md
 delete mode 100644 .changeset/fiery-lights-fetch.md
 delete mode 100644 .changeset/fifty-hornets-follow.md
 delete mode 100644 .changeset/full-symbols-obey.md
 delete mode 100644 .changeset/open-garlics-smile.md
 delete mode 100644 .changeset/pink-buckets-write.md
 delete mode 100644 .changeset/quick-guests-join.md
 delete mode 100644 .changeset/seven-emus-vanish.md
 delete mode 100644 .changeset/solid-boats-send.md
 delete mode 100644 .changeset/stale-shirts-read.md
 delete mode 100644 .changeset/upset-ties-cough.md
 delete mode 100644 .changeset/wild-forks-fetch.md
 delete mode 100644 .changeset/wild-lies-film.md

diff --git a/.changeset/a11y-admin-nav.md b/.changeset/a11y-admin-nav.md
deleted file mode 100644
index e6025193a8..0000000000
--- a/.changeset/a11y-admin-nav.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"apostrophe": patch
----
-
-Accessibility: corrected ARIA semantics on the top admin navigation bar. 
diff --git a/.changeset/a11y-context-title.md b/.changeset/a11y-context-title.md
deleted file mode 100644
index 344cf6fa7b..0000000000
--- a/.changeset/a11y-context-title.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"apostrophe": patch
----
-
-Accessibility: improvements to the document context title (admin bar middle group) and the underlying `AposContextMenu` machinery.
diff --git a/.changeset/a11y-locale-switcher.md b/.changeset/a11y-locale-switcher.md
deleted file mode 100644
index ec687d8c7d..0000000000
--- a/.changeset/a11y-locale-switcher.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"apostrophe": patch
----
-
-Accessibility: improve the locale switcher (`AposLocalePicker`).
diff --git a/.changeset/a11y-recently-edited-icon.md b/.changeset/a11y-recently-edited-icon.md
deleted file mode 100644
index 8c6a04567c..0000000000
--- a/.changeset/a11y-recently-edited-icon.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"apostrophe": patch
----
-
-Accessibility: the Recently Edited Documents tray icon (admin bar) now exposes its action through `aria-label`.
diff --git a/.changeset/a11y-sr-only.md b/.changeset/a11y-sr-only.md
deleted file mode 100644
index 193a4cf5ec..0000000000
--- a/.changeset/a11y-sr-only.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"apostrophe": patch
----
-
-Accessibility: fix `.apos-sr-only` so screen-reader-only content is exposed to the accessibility tree.
diff --git a/.changeset/a11y-tray-aria.md b/.changeset/a11y-tray-aria.md
deleted file mode 100644
index 4f39003b28..0000000000
--- a/.changeset/a11y-tray-aria.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"apostrophe": patch
----
-
-Accessibility: icon-only context-utility buttons in the admin bar tray (e.g. the global settings cog) now expose their action through `aria-label`.
diff --git a/.changeset/busy-spies-enter.md b/.changeset/busy-spies-enter.md
deleted file mode 100644
index cc922b7b1c..0000000000
--- a/.changeset/busy-spies-enter.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"apostrophe": patch
----
-
-Security fix: the password reset request feature will refuse to operate unless the baseUrl option or the APOS_BASE_URL environment variable has been set (note that this is automatic in multisite projects). This fix is necessary to prevent a vulnerability that can be used to convince ApostropheCMS to send emails containing links to other sites. It is only a vulnerability if you have enabled the passwordReset: true option for the login module. Thanks to [SPIDY](https://github.com/Mujahidkhan525) for reporting the issue.
diff --git a/.changeset/clean-actors-laugh.md b/.changeset/clean-actors-laugh.md
deleted file mode 100644
index 5d78fab358..0000000000
--- a/.changeset/clean-actors-laugh.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"apostrophe": patch
----
-
-Fix illegal HTML id attribute values generated by the admin UI
diff --git a/.changeset/cozy-wombats-burn.md b/.changeset/cozy-wombats-burn.md
deleted file mode 100644
index a484ecded0..0000000000
--- a/.changeset/cozy-wombats-burn.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@apostrophecms/cli": patch
----
-
-Security: bump and clean up dependencies. This closes vulnerabilities in `uuid` and `fast-xml-parser` although they were not used in a sensitive or vulnerable way within ApostropheCMS. This also closes a vulnerability in `shelljs` which ould only be exploited if the developer could be convinced to enter malicious commands as part of their CLI input.
diff --git a/.changeset/fiery-lights-fetch.md b/.changeset/fiery-lights-fetch.md
deleted file mode 100644
index 3bcf8c1da7..0000000000
--- a/.changeset/fiery-lights-fetch.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@apostrophecms/cli": patch
----
-
-Security: passwords and starter kit URLs containing intentionally malicious punctuation cannot be used to run arbitrary shell commands. Because the CLI is only used by developers, this would always have been an "own goal" situation, however this does make the CLI more robust for scripted use. Thanks to [Nitro13urn](https://github.com/VadlaReddySai) for reporting the issue.
diff --git a/.changeset/fifty-hornets-follow.md b/.changeset/fifty-hornets-follow.md
deleted file mode 100644
index d698950dad..0000000000
--- a/.changeset/fifty-hornets-follow.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-"apostrophe": patch
----
-
-- Removed duplicate <meta charset> tag from `outerLayoutBase.html`
-- Standardized charset to utf-8 (the legacy configuration option is now ignored). Per the spec this is the only legal setting, so we classify this as a bug fix
-- Altered unused/legacy i18n template helper to return `utf-8`, ensuring backwards compatibility
diff --git a/.changeset/full-symbols-obey.md b/.changeset/full-symbols-obey.md
deleted file mode 100644
index 903395756e..0000000000
--- a/.changeset/full-symbols-obey.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"apostrophe": patch
----
-
-Keyboard shortcuts for widget operations (copy, cut, paste, duplicate, remove) no longer block the browser's native clipboard behavior when no widget is focused. Previously, selecting and copying text on a page while logged in was prevented by the admin UI intercepting those shortcuts unconditionally.
diff --git a/.changeset/open-garlics-smile.md b/.changeset/open-garlics-smile.md
deleted file mode 100644
index 610ece378e..0000000000
--- a/.changeset/open-garlics-smile.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-"apostrophe": patch
----
-
-Security: a malicious full name containing HTML was executed as HTML in the tooltip displayed with an "i" icon next to the title of the current page, creating an
-XSS attack risk versus other users. Since most projects permit users to change their full name (the "title" property), All projects with multiple users should be
-updated promptly to close this vulnerability. Thanks to [Muhammad Uwais](https://github.com/MuhammadUwais) for reporting the issue.
diff --git a/.changeset/pink-buckets-write.md b/.changeset/pink-buckets-write.md
deleted file mode 100644
index 9333df426d..0000000000
--- a/.changeset/pink-buckets-write.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-"sanitize-html": patch
-"apostrophe": patch
-"launder": patch
----
-
-Security: launder now uses and exports the best available naughtyHref function for detecting malicious URLs. sanitize-html now depends on it, and apostrophe now uses type: 'url' for the link URL field of image widgets, which leverages it. Prior to this fix, it was possible for any user with editing privileges, including a contributor, to trigger arbitrary JavaScript via a javascript: URL in the link URL field of an image widget. A migration has been included to strip any such malicious URLs already present in the database. All users of apostrophe are encouraged to upgrade to get this security fix. Thanks to [Muhammad Uwais](https://github.com/MuhammadUwais) for reporting the issue.
diff --git a/.changeset/quick-guests-join.md b/.changeset/quick-guests-join.md
deleted file mode 100644
index 8bab7b0384..0000000000
--- a/.changeset/quick-guests-join.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"apostrophe": minor
----
-
-Fix layout widget not regaining full focus on switching back to Edit content mode.
diff --git a/.changeset/seven-emus-vanish.md b/.changeset/seven-emus-vanish.md
deleted file mode 100644
index 564a10e231..0000000000
--- a/.changeset/seven-emus-vanish.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-"@apostrophecms/apostrophe-astro": minor
-"apostrophe": minor
----
-
-Editors can now control the layout-widget gap through the styles system, both site-wide via a global `layoutGap` preset and per widget via a `gap` styles field. New Layout widget option `className` allows for additional CSS class names to be added to the widget Grid container.
diff --git a/.changeset/solid-boats-send.md b/.changeset/solid-boats-send.md
deleted file mode 100644
index d0f848873f..0000000000
--- a/.changeset/solid-boats-send.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-"apostrophe": patch
----
-
-Security: the HTML import feature of the rich text widget no longer permits images to be fetched
-from arbitrary hosts. This could be used to probe internal networks, and to exfiltrate images from
-internal hosts if their URLs were known. Instead, the `imageImportAllowedHostnames` option of the
-`@apostrophecms/rich-text-widget` must be configured to opt into that feature.
-
-Thanks to [Yiğit Şengezer](https://github.com/yigitsengezer) and [Sainithin0309](https://github.com/Sainithin0309) for reporting this issue.
diff --git a/.changeset/stale-shirts-read.md b/.changeset/stale-shirts-read.md
deleted file mode 100644
index 271cd86872..0000000000
--- a/.changeset/stale-shirts-read.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"apostrophe": patch
----
-
-fixes issue where orderable table array items drag the entire floating window
diff --git a/.changeset/upset-ties-cough.md b/.changeset/upset-ties-cough.md
deleted file mode 100644
index 6795e47545..0000000000
--- a/.changeset/upset-ties-cough.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"sanitize-html": patch
----
-
-Security vulnerability: the xmp tag could be used to pass forbidden markup through sanitize-html, even when xmp itself is not explicitly allowed All users of sanitize-html should update immediately. Thanks to [Vincenzo Turturro](https://github.com/sushi-gif) for reporting the vulnerability.
diff --git a/.changeset/wild-forks-fetch.md b/.changeset/wild-forks-fetch.md
deleted file mode 100644
index a175167488..0000000000
--- a/.changeset/wild-forks-fetch.md
+++ /dev/null
@@ -1,15 +0,0 @@
----
-"apostrophe": patch
----
-
-apostrophe and oembetter have been updated to eliminate a number of services that formerly supported
-oembed for the general public, but no longer do so. While there is no security risk today, removing
-these ensures that if these domains are ever allowed to lapse, they do not become an XSS
-attack vector in the future.
-
-Because oembed responses are not always iframes, it is important that this list be maintained
-over time. In addition, developers always have the option to prune it on their own by setting
-the new minimumAllowlist and minimumEndpoints options of the @apostrophecms/oembed module.
-
-Thanks to [Sainithin0309](https://github.com/Sainithin0309) for pointing out the potential
-long-term security concern.
diff --git a/.changeset/wild-lies-film.md b/.changeset/wild-lies-film.md
deleted file mode 100644
index 3b608070dd..0000000000
--- a/.changeset/wild-lies-film.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@apostrophecms/apostrophe-astro": minor
----
-
-Log aposResponse errors server side in the Astro process. Thanks to [Harouna Traore](https://github.com/haroun).

From 874582f6ba204e039bae43cb0b18af96cbb3c917 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 10 Jun 2026 08:59:35 -0400
Subject: [PATCH 50/56] cli links that are correct, or will be post publish
 (#5458)

---
 packages/create-apostrophe/src/ui/links.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/create-apostrophe/src/ui/links.js b/packages/create-apostrophe/src/ui/links.js
index 2839d0255f..9e119897d2 100644
--- a/packages/create-apostrophe/src/ui/links.js
+++ b/packages/create-apostrophe/src/ui/links.js
@@ -7,9 +7,9 @@
 const LINKS = Object.freeze({
   telemetryPolicy: 'https://apostrophecms.com/telemetry-policy?utm_source=cli',
   docs: 'https://docs.apostrophecms.com',
-  discord: 'https://discord.gg/apostrophe',
+  discord: 'https://chat.apostrophecms.com',
   demoSite: 'https://demo.apostrophecms.com',
-  dbGuide: 'https://apostrophecms.com/guides/choosing-a-db'
+  dbGuide: 'https://apostrophecms.com/docs/guide/choosing-a-database.html'
 });
 
 /** Per-kit "get oriented" guides. `*-demo` and `*-demo-data` share a guide. */

From 203ff2648c8f22e8206dad62b9b57fe4cf129442 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 10 Jun 2026 09:38:58 -0400
Subject: [PATCH 51/56] release db connect to solve chicken and egg problem in
 cypress-tools (#5459)

---
 packages/db-connect/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/db-connect/package.json b/packages/db-connect/package.json
index fcfeaa4de9..3413e92507 100644
--- a/packages/db-connect/package.json
+++ b/packages/db-connect/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@apostrophecms/db-connect",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Database connection library and dump/restore tools for ApostropheCMS",
   "license": "MIT",
   "main": "index.js",

From 6a11a08b2c530f86703165b99feef3b93cf61bd7 Mon Sep 17 00:00:00 2001
From: Robert Means <robert@apostrophecms.com>
Date: Wed, 10 Jun 2026 09:51:07 -0400
Subject: [PATCH 52/56] Corrects documentation links (#5457)

* Corrects documentation links

* correct `guides` -> `guide`
---
 packages/create-apostrophe/src/ui/links.js | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/create-apostrophe/src/ui/links.js b/packages/create-apostrophe/src/ui/links.js
index 9e119897d2..43cd409af6 100644
--- a/packages/create-apostrophe/src/ui/links.js
+++ b/packages/create-apostrophe/src/ui/links.js
@@ -14,12 +14,12 @@ const LINKS = Object.freeze({
 
 /** Per-kit "get oriented" guides. `*-demo` and `*-demo-data` share a guide. */
 const KIT_GUIDES = Object.freeze({
-  'apostrophe-astro-essentials': 'https://apostrophecms.com/guides/astro-essentials-overview',
-  'apostrophe-astro-demo': 'https://apostrophecms.com/guides/astro-demo-overview',
-  'apostrophe-astro-demo-data': 'https://apostrophecms.com/guides/astro-demo-overview',
-  'apostrophe-essentials': 'https://apostrophecms.com/guides/apostrophe-standalone-essentials-overview',
-  'apostrophe-demo': 'https://apostrophecms.com/guides/apostrophe-demo-overview',
-  'apostrophe-demo-data': 'https://apostrophecms.com/guides/apostrophe-demo-overview'
+  'apostrophe-astro-essentials': 'https://apostrophecms.com/docs/guide/astro-essentials-overview.html',
+  'apostrophe-astro-demo': 'https://apostrophecms.com/docs/guide/astro-demo-overview.html',
+  'apostrophe-astro-demo-data': 'https://apostrophecms.com/docs/guide/astro-demo-overview.html',
+  'apostrophe-essentials': 'https://apostrophecms.com/docs/guide/apostrophe-standalone-essentials-overview.html',
+  'apostrophe-demo': 'https://apostrophecms.com/docs/guides/apostrophe-demo-overview.html',
+  'apostrophe-demo-data': 'https://apostrophecms.com/docs/guide/apostrophe-demo-overview.html'
 });
 
 /** @typedef {keyof typeof LINKS} LinkName */

From ef817dd82bebf012842ddbe2bb370bb1ad1b5ff3 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 10 Jun 2026 11:45:37 -0400
Subject: [PATCH 53/56] Merge commit from fork

---
 .changeset/proud-moons-guard.md               |   5 +
 .../modules/@apostrophecms/util/index.js      |  17 +++
 packages/apostrophe/test/utils.js             | 103 ++++++++++++++++++
 3 files changed, 125 insertions(+)
 create mode 100644 .changeset/proud-moons-guard.md

diff --git a/.changeset/proud-moons-guard.md b/.changeset/proud-moons-guard.md
new file mode 100644
index 0000000000..ea5449c194
--- /dev/null
+++ b/.changeset/proud-moons-guard.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": patch
+---
+
+Security fix: server-side prototype pollution (CWE-1321) via dot-notation paths. `apos.util.set()` and `apos.util.get()` now refuse to traverse `__proto__`, `constructor` and `prototype` path segments. Previously an authenticated editor could send a PATCH REST API request whose patch operators (for example `$pullAll` with a key of `__proto__.publicApiProjection`) wrote to `Object.prototype`. A polluted `publicApiProjection` defeated the `publicApiCheck()` authorization gate on piece-type REST endpoints for subsequent unauthenticated requests, for the lifetime of the Node.js process. All users should update. Thanks to [tonghuaroot](https://github.com/tonghuaroot), [H3xV0rT3x](https://github.com/H3xV0rT3x), and [5h1kh4r](https://github.com/5h1kh4r) for reporting the vulnerability.
diff --git a/packages/apostrophe/modules/@apostrophecms/util/index.js b/packages/apostrophe/modules/@apostrophecms/util/index.js
index 38b9e54527..24e4d18df3 100644
--- a/packages/apostrophe/modules/@apostrophecms/util/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/util/index.js
@@ -35,6 +35,13 @@ const util = require('util');
 const { stripIndent } = require('common-tags');
 const glob = require('../../../lib/glob.js');
 
+// Dot-path segments that must never be traversed when walking a
+// user-supplied path in `apos.util.get` and `apos.util.set`. Following any
+// of these reaches the prototype chain and enables server-side prototype
+// pollution (CWE-1321), e.g. a PATCH `$pullAll` key of
+// `__proto__.publicApiProjection`.
+const unsafePathSegments = new Set([ '__proto__', 'constructor', 'prototype' ]);
+
 module.exports = {
   options: {
     alias: 'util',
@@ -755,6 +762,10 @@ module.exports = {
             if (o == null) {
               return undefined;
             }
+            if (unsafePathSegments.has(p)) {
+              // Never read through the prototype chain (CWE-1321)
+              return undefined;
+            }
             o = o[p];
           }
         }
@@ -819,6 +830,12 @@ module.exports = {
           }
         }
         path = path.split('.');
+        for (p of path) {
+          if (unsafePathSegments.has(p)) {
+            // Refuse to write through the prototype chain (CWE-1321)
+            throw self.apos.error('invalid', `Unsafe property name "${p}" in dot path`);
+          }
+        }
         for (i = 0; (i < (path.length - 1)); i++) {
           p = path[i];
           o = o[p];
diff --git a/packages/apostrophe/test/utils.js b/packages/apostrophe/test/utils.js
index 7de7bcb225..5a59e8c14c 100644
--- a/packages/apostrophe/test/utils.js
+++ b/packages/apostrophe/test/utils.js
@@ -372,6 +372,109 @@ describe('Utils', async function() {
       assert(data.shoes[0].size === 8);
     });
 
+    // Server-Side Prototype Pollution (CWE-1321) regression coverage.
+    // apos.util.set and apos.util.get traverse user-supplied dot-notation
+    // paths. A segment of `__proto__`, `constructor` or `prototype` must
+    // never be followed, or an authenticated editor could write to
+    // Object.prototype (for example via the $pullAll patch operator) and
+    // poison authorization checks process-wide. See GHSA-6h5j-32cf-4253.
+
+    it('utils.set must reject a __proto__ segment instead of polluting Object.prototype', function() {
+      const data = {};
+      try {
+        assert.throws(() => {
+          apos.util.set(data, '__proto__.polluted', 'yes');
+        }, { name: 'invalid' });
+        assert.strictEqual({}.polluted, undefined);
+        assert.strictEqual(data.polluted, undefined);
+      } finally {
+        // Belt and suspenders: if the guard ever regresses, do not leak a
+        // polluted prototype into the rest of the suite.
+        delete Object.prototype.polluted;
+      }
+    });
+
+    it('utils.set must reject a constructor.prototype segment', function() {
+      const data = {};
+      try {
+        assert.throws(() => {
+          apos.util.set(data, 'constructor.prototype.polluted', 'yes');
+        }, { name: 'invalid' });
+        assert.strictEqual({}.polluted, undefined);
+      } finally {
+        delete Object.prototype.polluted;
+      }
+    });
+
+    it('utils.set must reject a trailing __proto__ segment rather than replacing the prototype', function() {
+      const data = {};
+      assert.throws(() => {
+        apos.util.set(data, '__proto__', { polluted: 'yes' });
+      }, { name: 'invalid' });
+      assert.strictEqual(Object.getPrototypeOf(data), Object.prototype);
+      assert.strictEqual(data.polluted, undefined);
+    });
+
+    it('utils.set must reject a dangerous segment exposed after an @ reference', function() {
+      const data = {
+        items: [
+          {
+            _id: 'abc',
+            sub: {}
+          }
+        ]
+      };
+      try {
+        assert.throws(() => {
+          apos.util.set(data, '@abc.__proto__.polluted', 'yes');
+        }, { name: 'invalid' });
+        assert.strictEqual({}.polluted, undefined);
+      } finally {
+        delete Object.prototype.polluted;
+      }
+    });
+
+    it('utils.get must not traverse into the prototype chain via __proto__', function() {
+      // Without the guard this returns Object.prototype.toString (a function).
+      assert.strictEqual(apos.util.get({ a: 1 }, '__proto__.toString'), undefined);
+      assert.strictEqual(apos.util.get({ a: 1 }, '__proto__'), undefined);
+    });
+
+    it('implementPatchOperators must not let a $pullAll key pollute Object.prototype', function() {
+      // The reported attack vector: an authenticated editor PATCH body of
+      // { $pullAll: { '__proto__.publicApiProjection': [] } } reached
+      // apos.util.set with a fully attacker-controlled key.
+      const patch = {
+        $pullAll: {
+          '__proto__.publicApiProjection': []
+        }
+      };
+      try {
+        assert.throws(() => {
+          apos.schema.implementPatchOperators(patch, {});
+        }, { name: 'invalid' });
+        assert.strictEqual({}.publicApiProjection, undefined);
+      } finally {
+        delete Object.prototype.publicApiProjection;
+      }
+    });
+
+    it('implementPatchOperators must not let a direct dot-notation key pollute Object.prototype', function() {
+      // The second documented entry point: a top-level dotted key whose value
+      // is fully attacker-controlled.
+      const patch = {
+        '__proto__.publicApiProjection': { title: 1 }
+      };
+      try {
+        assert.throws(() => {
+          apos.schema.implementPatchOperators(patch, {});
+        }, { name: 'invalid' });
+        assert.strictEqual({}.publicApiProjection, undefined);
+      } finally {
+        delete Object.prototype.publicApiProjection;
+      }
+    });
+
     it('should slugify', function () {
       // Basic
       assert.equal(

From b3981ec7473111bff7f2911a74b1c002fe252351 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 10 Jun 2026 11:46:07 -0400
Subject: [PATCH 54/56] Merge commit from fork

---
 .changeset/seo-analytics-xss.md |   5 +
 packages/seo/lib/nodes.js       |  32 ++++--
 packages/seo/test/unit-tests.js | 176 ++++++++++++++++++++++++++++++++
 3 files changed, 204 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/seo-analytics-xss.md

diff --git a/.changeset/seo-analytics-xss.md b/.changeset/seo-analytics-xss.md
new file mode 100644
index 0000000000..e9b1f65d3b
--- /dev/null
+++ b/.changeset/seo-analytics-xss.md
@@ -0,0 +1,5 @@
+---
+"@apostrophecms/seo": patch
+---
+
+Security: the Google Analytics tracking ID (`seoGoogleTrackingId`) and Google Tag Manager ID (`seoGoogleTagManager`) global SEO fields were interpolated directly into the bodies of inline `<script>` tags without escaping. Any user permitted to edit the global document, including editors and contributors (if their submission were approved), could set these fields to a value that broke out of the surrounding script and executed arbitrary JavaScript for every visitor on every page (stored XSS). These values are now emitted as escaped `json` nodes, matching the JSON-LD handling, so they can no longer terminate the `<script>` element or escape the string literal they sit in. All projects using `@apostrophecms/seo` with untrusted editors should upgrade promptly to close this vulnerability. Thanks to [H3xV0rT3x](https://github.com/H3xV0rT3x) and [hibrian827](https://github.com/hibrian827) for reporting the issue.
diff --git a/packages/seo/lib/nodes.js b/packages/seo/lib/nodes.js
index 01731cfcae..b83ba5e373 100644
--- a/packages/seo/lib/nodes.js
+++ b/packages/seo/lib/nodes.js
@@ -214,14 +214,21 @@ function getMetaHead(data, options) {
     });
     nodes.push({
       name: 'script',
-      body: [ {
-        raw: `
+      // seoGoogleTrackingId is editor-controlled, so it is emitted as a `json`
+      // node (escaped by renderNodes via safeJsonForScript) rather than
+      // interpolated raw into the script body, which would be stored XSS.
+      // See the JSON-LD note below.
+      body: [
+        {
+          raw: `
   window.dataLayer = window.dataLayer || [];
   function gtag(){dataLayer.push(arguments);}
   gtag('js', new Date());
-  gtag('config', '${global.seoGoogleTrackingId}');
-`
-      } ]
+  gtag('config', `
+        },
+        { json: global.seoGoogleTrackingId },
+        { raw: ');\n' }
+      ]
     });
   }
 
@@ -294,13 +301,20 @@ function getTagManagerHead(data) {
 
     nodes.push({
       name: 'script',
-      body: [ {
-        raw: `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
+      // seoGoogleTagManager is editor-controlled, so it is emitted as a `json`
+      // node (escaped by renderNodes via safeJsonForScript) rather than
+      // interpolated raw into the script body, which would be stored XSS.
+      body: [
+        {
+          raw: `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
   new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
   j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
   'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
-  })(window,document,'script','dataLayer','${global.seoGoogleTagManager}');`
-      } ]
+  })(window,document,'script','dataLayer',`
+        },
+        { json: global.seoGoogleTagManager },
+        { raw: ');' }
+      ]
     });
 
     nodes.push({
diff --git a/packages/seo/test/unit-tests.js b/packages/seo/test/unit-tests.js
index 095d82077f..e581c69a46 100644
--- a/packages/seo/test/unit-tests.js
+++ b/packages/seo/test/unit-tests.js
@@ -1716,6 +1716,182 @@ describe('@apostrophecms/seo', function () {
     });
   });
 
+  describe('XSS prevention in analytics scripts', function () {
+    const safeJsonForScript = require('apostrophe/lib/safe-json-script');
+
+    // Breaks out of the single-quoted JS string literal AND closes the
+    // surrounding <script> element under the old raw interpolation.
+    const payload = 'G-FAKE\'); alert(document.cookie); </script><script>alert(1)//';
+
+    it('should emit seoGoogleTrackingId as a json node, not raw interpolation', function () {
+      const { getMetaHead } = require('../lib/nodes');
+
+      const data = {
+        page: { _url: 'https://example.com/' },
+        global: { seoGoogleTrackingId: payload },
+        req: {}
+      };
+
+      const nodes = getMetaHead(data, {});
+
+      // The inline gtag() config script (a body array, not the async src
+      // loader, and not the application/ld+json block).
+      const inlineScript = nodes.find(n =>
+        n.name === 'script' &&
+        Array.isArray(n.body) &&
+        n.attrs?.type !== 'application/ld+json'
+      );
+      assert(inlineScript, 'inline gtag config script node should exist');
+
+      // The tracking id must be a json node so renderNodes escapes it, not a
+      // raw string with the id interpolated in.
+      const jsonSegment = inlineScript.body.find(seg => seg.json != null);
+      assert(jsonSegment, 'tracking id must be emitted as a json node');
+      assert.strictEqual(jsonSegment.json, payload);
+
+      const rawWithPayload = inlineScript.body.find(
+        seg => seg.raw != null && seg.raw.includes(payload)
+      );
+      assert(!rawWithPayload, 'tracking id must not be interpolated into a raw segment');
+
+      // Once rendered, the payload cannot terminate the <script> element.
+      const rendered = safeJsonForScript(jsonSegment.json);
+      assert(
+        !/<\/script/i.test(rendered),
+        'rendered tracking id must not contain an unescaped </script> sequence'
+      );
+    });
+
+    it('should emit seoGoogleTagManager as a json node, not raw interpolation', function () {
+      const { getTagManagerHead } = require('../lib/nodes');
+
+      const data = {
+        global: { seoGoogleTagManager: payload },
+        req: {}
+      };
+
+      const nodes = getTagManagerHead(data);
+
+      const script = nodes.find(n =>
+        n.name === 'script' && Array.isArray(n.body)
+      );
+      assert(script, 'GTM loader script node should exist');
+
+      const jsonSegment = script.body.find(seg => seg.json != null);
+      assert(jsonSegment, 'GTM id must be emitted as a json node');
+      assert.strictEqual(jsonSegment.json, payload);
+
+      const rawWithPayload = script.body.find(
+        seg => seg.raw != null && seg.raw.includes(payload)
+      );
+      assert(!rawWithPayload, 'GTM id must not be interpolated into a raw segment');
+
+      const rendered = safeJsonForScript(jsonSegment.json);
+      assert(
+        !/<\/script/i.test(rendered),
+        'rendered GTM id must not contain an unescaped </script> sequence'
+      );
+    });
+  });
+
+  describe('analytics scripts with valid IDs', function () {
+    const safeJsonForScript = require('apostrophe/lib/safe-json-script');
+
+    // Render a script body the same way apos.template.renderNodes does: raw
+    // segments pass through verbatim, json segments go through the safe
+    // encoder. This lets us assert on the real rendered output (and prove the
+    // escaping fix did not break the normal, working snippet) without booting
+    // a full Apostrophe instance.
+    function renderBody(body) {
+      return body
+        .map(seg => {
+          if (seg.raw != null) {
+            return seg.raw;
+          }
+          if (seg.json != null) {
+            return safeJsonForScript(seg.json);
+          }
+          return '';
+        })
+        .join('');
+    }
+
+    it('should emit a working gtag config call when seoGoogleTrackingId is a normal id', function () {
+      const { getMetaHead } = require('../lib/nodes');
+
+      const trackingId = 'G-ABC1234567';
+
+      const data = {
+        page: { _url: 'https://example.com/' },
+        global: { seoGoogleTrackingId: trackingId },
+        req: {}
+      };
+
+      const nodes = getMetaHead(data, {});
+
+      // The async gtag.js loader carries the id in its src.
+      const loader = nodes.find(n =>
+        n.name === 'script' &&
+        n.attrs?.src?.startsWith('https://www.googletagmanager.com/gtag/js')
+      );
+      assert(loader, 'gtag.js loader script should exist');
+      assert.strictEqual(
+        loader.attrs.src,
+        `https://www.googletagmanager.com/gtag/js?id=${trackingId}`
+      );
+
+      // The inline config script carries the id as a json node.
+      const inlineScript = nodes.find(n =>
+        n.name === 'script' &&
+        Array.isArray(n.body) &&
+        n.attrs?.type !== 'application/ld+json'
+      );
+      assert(inlineScript, 'inline gtag config script node should exist');
+
+      const jsonSegment = inlineScript.body.find(seg => seg.json != null);
+      assert(jsonSegment, 'tracking id should be emitted as a json node');
+      assert.strictEqual(jsonSegment.json, trackingId);
+
+      // Rendered, the snippet is valid, working JS that configures gtag with
+      // the exact id as a quoted string: gtag('config', "G-ABC1234567");
+      const rendered = renderBody(inlineScript.body);
+      assert(
+        rendered.includes(`gtag('config', "${trackingId}");`),
+        'rendered gtag config should call gtag with the exact id as a quoted string'
+      );
+    });
+
+    it('should emit a working GTM loader call when seoGoogleTagManager is a normal id', function () {
+      const { getTagManagerHead } = require('../lib/nodes');
+
+      const containerId = 'GTM-ABCD123';
+
+      const data = {
+        global: { seoGoogleTagManager: containerId },
+        req: {}
+      };
+
+      const nodes = getTagManagerHead(data);
+
+      const script = nodes.find(n =>
+        n.name === 'script' && Array.isArray(n.body)
+      );
+      assert(script, 'GTM loader script node should exist');
+
+      const jsonSegment = script.body.find(seg => seg.json != null);
+      assert(jsonSegment, 'GTM id should be emitted as a json node');
+      assert.strictEqual(jsonSegment.json, containerId);
+
+      // Rendered, the IIFE receives the exact id as a quoted string:
+      // ...,'dataLayer',"GTM-ABCD123");
+      const rendered = renderBody(script.body);
+      assert(
+        rendered.includes(`'dataLayer',"${containerId}");`),
+        'rendered GTM snippet should pass the exact id as a quoted string'
+      );
+    });
+  });
+
   describe('Schema Validation', function () {
 
     it('should validate Article schema requirements', function () {

From c91b6c72407f6d89cc8b6bc63d1ae1ffb4273cbc Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 10 Jun 2026 11:46:23 -0400
Subject: [PATCH 55/56] Merge commit from fork

---
 .../file-pretty-url-host-header-ssrf.md       |  5 ++++
 .../modules/@apostrophecms/file/index.js      | 17 +++++------
 packages/apostrophe/test/files.js             | 28 +++++++++++++++++++
 3 files changed, 42 insertions(+), 8 deletions(-)
 create mode 100644 .changeset/file-pretty-url-host-header-ssrf.md

diff --git a/.changeset/file-pretty-url-host-header-ssrf.md b/.changeset/file-pretty-url-host-header-ssrf.md
new file mode 100644
index 0000000000..e071a14d9e
--- /dev/null
+++ b/.changeset/file-pretty-url-host-header-ssrf.md
@@ -0,0 +1,5 @@
+---
+"apostrophe": patch
+---
+
+Security: when `@apostrophecms/file` pretty URLs are enabled (`prettyUrls: true`), the upstream request used to serve the file is no longer built from the incoming `Host` header. The self-request is now resolved against the site's configured `baseUrl` (via `req.baseUrl`), falling back to the request host only when no `baseUrl` is configured. This closes a server-side request forgery (SSRF) vector in which the `Host` header could steer the proxied fetch at another host. The real-world risk was low: the path is constrained to an existing attachment's `/uploads/attachments/<cuid>-<slug>.<ext>`, and cuids are unique and immutable, so any reachable content was already public via the front door. Thanks to [EchoSkorJjj](https://github.com/EchoSkorJjj) for reporting the issue.
diff --git a/packages/apostrophe/modules/@apostrophecms/file/index.js b/packages/apostrophe/modules/@apostrophecms/file/index.js
index ec6866c3d9..c3f156b39b 100644
--- a/packages/apostrophe/modules/@apostrophecms/file/index.js
+++ b/packages/apostrophe/modules/@apostrophecms/file/index.js
@@ -248,14 +248,15 @@ module.exports = {
             const uglyUrl = self.apos.attachment.url(file.attachment, {
               prettyUrl: false
             });
-            // For relative URLs (local uploadfs, not CDN), resolve
-            // against the current server's origin so the proxy can
-            // make the self-request.  During static builds
-            // `attachment.url()` may return only a path.
-            const proxyUrl = uglyUrl.startsWith('/')
-              ? `${req.protocol}://${req.get('host')}${uglyUrl}`
-              : uglyUrl;
-            return await streamProxy(req, proxyUrl, { error: self.apos.util.error });
+            // `uglyUrl` may be relative (local uploadfs) or absolute
+            // (S3/CDN). For the relative case `streamProxy` resolves it
+            // against `req.baseUrl`, which reflects the configured
+            // `baseUrl` (or locale hostname) and only falls back to the
+            // request host when the site has none. We deliberately do
+            // not build the upstream URL from the raw `Host` header
+            // here, as that is attacker-controlled and would allow the
+            // self-request to be redirected to an arbitrary host (SSRF).
+            return await streamProxy(req, uglyUrl, { error: self.apos.util.error });
           } catch (e) {
             self.apos.util.error('Error in pretty URL route:', e);
             return res.status(500).send('error');
diff --git a/packages/apostrophe/test/files.js b/packages/apostrophe/test/files.js
index f2b2e48959..a35d5adebf 100644
--- a/packages/apostrophe/test/files.js
+++ b/packages/apostrophe/test/files.js
@@ -132,6 +132,34 @@ describe('Files', function() {
     }
   });
 
+  it('should ignore a spoofed Host header when proxying the pretty URL (SSRF regression)', async function() {
+    const req = apos.task.getAnonReq();
+    try {
+      apos.file.options.prettyUrls = true;
+      const files = await apos.file.find(req).toArray();
+      assert.strictEqual(files.length, 1);
+      const file = files[0];
+      const attachment = apos.attachment.first(file);
+      const url = apos.attachment.url(attachment);
+      assert(url);
+      // Send an attacker-controlled Host header (e.g. the cloud metadata
+      // address from the advisory). The upstream fetch must be resolved
+      // against the server-trusted baseUrl, not this header, so the
+      // legitimate content is still served and the request is never
+      // steered at the spoofed host.
+      const response = await apos.http.get(url, {
+        headers: {
+          Host: '169.254.169.254'
+        },
+        fullResponse: true
+      });
+      assert.strictEqual(response.status, 200);
+      assert.strictEqual(response.body, attachment.data);
+    } finally {
+      apos.file.options.prettyUrls = false;
+    }
+  });
+
 });
 
 describe('Files with i18n locale prefixes', function() {

From 75f680c6b0dd2d1f294635b610b2778f485a34a7 Mon Sep 17 00:00:00 2001
From: Tom Boutell <tom@apostrophecms.com>
Date: Wed, 10 Jun 2026 11:49:59 -0400
Subject: [PATCH 56/56] Merge commit from fork

* Security: added a number of new attributes to be protected against unsafe URLs, e.g. javascript: and similar. None of these are used in the default configuration of sanitize-html or apostrophe or likely to be used there, and some attributes, like an action for a form, are inherently unsafe to allow if XSS protection is your goal. Nevertheless it makes sense to block certain URL types where they are not appropriate. Thanks to [crattack](https://github.com/crattack) for reporting the vulnerability.

* changeset

* removed duplicate changeset

* patch the right module
---
 .changeset/boozy-manual-severaltoms.md |  5 ++
 packages/sanitize-html/README.md       |  9 ++-
 packages/sanitize-html/index.js        | 13 +++-
 packages/sanitize-html/test/test.js    | 92 ++++++++++++++++++++++++++
 4 files changed, 115 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/boozy-manual-severaltoms.md

diff --git a/.changeset/boozy-manual-severaltoms.md b/.changeset/boozy-manual-severaltoms.md
new file mode 100644
index 0000000000..7b2e41169b
--- /dev/null
+++ b/.changeset/boozy-manual-severaltoms.md
@@ -0,0 +1,5 @@
+---
+"sanitize-html": patch
+---
+
+Security: added a number of new attributes to be protected against unsafe URLs, e.g. `javascript:` and similar. None of these are used in the default configuration of `sanitize-html` or `apostrophe` or likely to be used there, and some attributes, like an `action` for a `form`, are inherently unsafe to allow if XSS protection is your goal. Nevertheless it makes sense to block certain URL types where they are not appropriate. Some attributes are not supported at all by modern browsers but are included for completeness. Thanks to [crattack](https://github.com/crattack) for reporting the vulnerability.
diff --git a/packages/sanitize-html/README.md b/packages/sanitize-html/README.md
index fca839f93d..2dfefb4504 100644
--- a/packages/sanitize-html/README.md
+++ b/packages/sanitize-html/README.md
@@ -182,7 +182,14 @@ selfClosing: [ 'img', 'br', 'hr', 'area', 'base', 'basefont', 'input', 'link', '
 // URL schemes we permit
 allowedSchemes: [ 'http', 'https', 'ftp', 'mailto', 'tel' ],
 allowedSchemesByTag: {},
-allowedSchemesAppliedToAttributes: [ 'href', 'src', 'cite' ],
+allowedSchemesAppliedToAttributes: [
+  'href', 'src', 'cite',
+  'action', 'formaction', 'data', 'xlink:href',
+  'poster', 'background', 'ping',
+  'longdesc', 'usemap', 'codebase', 'classid', 'archive',
+  'profile', 'manifest', 'itemid',
+  'dynsrc', 'lowsrc'
+],
 allowProtocolRelative: true,
 enforceHtmlBoundary: false,
 parseStyleAttributes: true
diff --git a/packages/sanitize-html/index.js b/packages/sanitize-html/index.js
index b5da859f7e..7a616cca60 100644
--- a/packages/sanitize-html/index.js
+++ b/packages/sanitize-html/index.js
@@ -440,11 +440,11 @@ function sanitizeHtml(html, options, _recursing) {
                 return;
               }
             }
-            if (a === 'srcset') {
+            if (a === 'srcset' || a === 'imagesrcset') {
               try {
                 let parsed = parseSrcset(value);
                 parsed.forEach(function(value) {
-                  if (naughtyHref('srcset', value.url)) {
+                  if (naughtyHref(a, value.url)) {
                     value.evil = true;
                   }
                 });
@@ -957,7 +957,14 @@ sanitizeHtml.defaults = {
   // URL schemes we permit
   allowedSchemes: [ 'http', 'https', 'ftp', 'mailto', 'tel' ],
   allowedSchemesByTag: {},
-  allowedSchemesAppliedToAttributes: [ 'href', 'src', 'cite' ],
+  allowedSchemesAppliedToAttributes: [
+    'href', 'src', 'cite',
+    'action', 'formaction', 'data', 'xlink:href',
+    'poster', 'background', 'ping',
+    'longdesc', 'usemap', 'codebase', 'classid', 'archive',
+    'profile', 'manifest', 'itemid',
+    'dynsrc', 'lowsrc'
+  ],
   allowProtocolRelative: true,
   enforceHtmlBoundary: false,
   parseStyleAttributes: true,
diff --git a/packages/sanitize-html/test/test.js b/packages/sanitize-html/test/test.js
index f757d7f286..db3d877f5e 100644
--- a/packages/sanitize-html/test/test.js
+++ b/packages/sanitize-html/test/test.js
@@ -969,6 +969,98 @@ describe('sanitizeHtml', function() {
       '<img src="fallback.jpg" srcset="/upload/f_auto,q_auto:eco,c_fit,w_1460,h_2191/abc.jpg 1460w, /upload/f_auto,q_auto:eco,c_fit,w_1360,h_2041/abc.jpg" />'
     );
   });
+  it('should drop javascript: in form action', function() {
+    assert.equal(
+      sanitizeHtml('<form action="javascript:alert(1)"><button>x</button></form>', {
+        allowedTags: [ 'form', 'button' ],
+        allowedAttributes: { form: [ 'action' ] }
+      }),
+      '<form><button>x</button></form>'
+    );
+  });
+  it('should allow http(s) in form action', function() {
+    assert.equal(
+      sanitizeHtml('<form action="https://example.com/submit"><button>x</button></form>', {
+        allowedTags: [ 'form', 'button' ],
+        allowedAttributes: { form: [ 'action' ] }
+      }),
+      '<form action="https://example.com/submit"><button>x</button></form>'
+    );
+  });
+  it('should drop javascript: in button formaction', function() {
+    assert.equal(
+      sanitizeHtml('<button formaction="javascript:alert(1)">x</button>', {
+        allowedTags: [ 'button' ],
+        allowedAttributes: { button: [ 'formaction' ] }
+      }),
+      '<button>x</button>'
+    );
+  });
+  it('should allow http(s) in button formaction', function() {
+    assert.equal(
+      sanitizeHtml('<button formaction="https://example.com/submit">x</button>', {
+        allowedTags: [ 'button' ],
+        allowedAttributes: { button: [ 'formaction' ] }
+      }),
+      '<button formaction="https://example.com/submit">x</button>'
+    );
+  });
+  it('should drop javascript: in object data', function() {
+    assert.equal(
+      sanitizeHtml('<object data="javascript:alert(1)"></object>', {
+        allowedTags: [ 'object' ],
+        allowedAttributes: { object: [ 'data' ] }
+      }),
+      '<object></object>'
+    );
+  });
+  it('should allow http(s) in object data', function() {
+    assert.equal(
+      sanitizeHtml('<object data="https://example.com/file.pdf"></object>', {
+        allowedTags: [ 'object' ],
+        allowedAttributes: { object: [ 'data' ] }
+      }),
+      '<object data="https://example.com/file.pdf"></object>'
+    );
+  });
+  it('should drop javascript: in SVG xlink:href', function() {
+    assert.equal(
+      sanitizeHtml('<svg><a xlink:href="javascript:alert(1)"><text>x</text></a></svg>', {
+        allowedTags: [ 'svg', 'a', 'text' ],
+        allowedAttributes: { a: [ 'xlink:href' ] }
+      }),
+      '<svg><a><text>x</text></a></svg>'
+    );
+  });
+  it('should allow http(s) in SVG xlink:href', function() {
+    assert.equal(
+      sanitizeHtml('<svg><a xlink:href="https://example.com/"><text>x</text></a></svg>', {
+        allowedTags: [ 'svg', 'a', 'text' ],
+        allowedAttributes: { a: [ 'xlink:href' ] }
+      }),
+      '<svg><a xlink:href="https://example.com/"><text>x</text></a></svg>'
+    );
+  });
+  it('should drop bogus imagesrcset', function() {
+    assert.equal(
+      sanitizeHtml('<link rel="preload" as="image" imagesrcset="foo.jpg 1x, javascript:alert(1) 2x" />', {
+        allowedTags: [ 'link' ],
+        allowedAttributes: { link: [ 'rel', 'as', 'imagesrcset' ] },
+        selfClosing: [ 'link' ]
+      }),
+      '<link rel="preload" as="image" imagesrcset="foo.jpg 1x" />'
+    );
+  });
+  it('should accept valid imagesrcset', function() {
+    assert.equal(
+      sanitizeHtml('<link rel="preload" as="image" imagesrcset="foo.jpg 1x, bar.jpg 2x" />', {
+        allowedTags: [ 'link' ],
+        allowedAttributes: { link: [ 'rel', 'as', 'imagesrcset' ] },
+        selfClosing: [ 'link' ]
+      }),
+      '<link rel="preload" as="image" imagesrcset="foo.jpg 1x, bar.jpg 2x" />'
+    );
+  });
 
   it('text from transformTags should not specify tags', function() {
     const input = '<input value="&lt;script&gt;alert(1)&lt;/script&gt;">';