create-qs 0.8.26 → 0.8.29

package/README.md

@@ -6,9 +6,11 @@
 用一条命令创建全栈 Quicksilver 项目。
 
 ```bash
-npm create qs
+npm create qs@latest
 ```
 
+命令中的 `@latest` 不能省略。省略时，如果本机全局安装过 `create-qs`，或者当前目录所属的项目依赖了它，npm 会直接运行已有的那一份，不检查 registry 上是否有更新的版本。
+
 这一条命令请使用 npm，不要使用 pnpm。自 pnpm 11 起，`pnpm create` 会跳过发布不足 24 小时的版本（`minimumReleaseAge`），且不给出任何提示，当天发布的脚手架会被静默替换为较早的版本。npm 默认没有这一限制。项目创建完成后，其余操作一律使用 pnpm。
 
 脚手架发布在公网 npmjs 上，未做任何配置的机器即可直接运行。它会询问项目及其第一个模块的若干问题，然后生成一个可以直接运行的全栈项目，包括 Kotlin/Spring Boot 后端、Preact/TypeScript 前端、Gradle Wrapper，以及文件型 H2 开发数据库。
@@ -50,9 +52,11 @@ pnpm dev
 用一個指令建立全端 Quicksilver 專案。
 
 ```bash
-npm create qs
+npm create qs@latest
 ```
 
+指令中的 `@latest` 不可省略。省略時，如果本機全域安裝過 `create-qs`，或者目前目錄所屬的專案相依於它，npm 會直接執行已有的那一份，不檢查 registry 上是否有更新的版本。
+
 這一個指令請使用 npm，不要使用 pnpm。自 pnpm 11 起，`pnpm create` 會略過發布不足 24 小時的版本（`minimumReleaseAge`），且不會給出任何提示，當天發布的鷹架會被默默替換為較早的版本。npm 預設沒有這項限制。專案建立完成後，其餘操作一律使用 pnpm。
 
 鷹架發布在公開的 npmjs 上，未做任何設定的電腦即可直接執行。它會詢問專案及其第一個模組的幾個問題，然後產生一個可以直接執行的全端專案，包括 Kotlin/Spring Boot 後端、Preact/TypeScript 前端、Gradle Wrapper，以及檔案型 H2 開發資料庫。
@@ -93,9 +97,12 @@ pnpm dev
 Create a full-stack Quicksilver project with a single command.
 
 ```bash
-npm create qs
+npm create qs@latest
 ```
 
+Keep the `@latest`. Without it, npm runs any `create-qs` already installed globally or in the
+project that contains the current directory, and does not check the registry for a newer version.
+
 Use npm for this one command, not pnpm. Since pnpm 11, `pnpm create` skips any version published
 less than 24 hours ago (`minimumReleaseAge`) and does not report it, so a scaffolder released the
 same day is silently replaced by an older one. npm applies no such delay by default. Everything

package/index.js

@@ -646,6 +646,12 @@ async function inputBoolean(options, initial) {
 }
 var { Input } = enquirer;
 var TextPrompt = class extends Input {
+  async submit() {
+    if (this.options.cancelOnEmpty && String(this.value ?? "").trim() === "") {
+      return this.cancel();
+    }
+    return super.submit();
+  }
   async close() {
     try {
       await super.close();
@@ -1970,7 +1976,7 @@ async function processFiles(options) {
   variables.set("WEB_PACKAGE_NAME", options.webModulePackage);
   variables.set("API_PACKAGE", options.apiPackage);
   variables.set("API_ARTIFACT_ID", options.apiArtifactId);
-  variables.set("QUICKSILVER_VERSION", "0.8.26");
+  variables.set("QUICKSILVER_VERSION", "0.8.29");
   variables.set("MODULE_ID", randomUUID());
   variables.set("DB_PREFIX", toDbPrefix(options.name));
   variables.set("JSONS_LOCALE", options.jsonsLocale);
@@ -2033,7 +2039,7 @@ if (process.argv.some((arg) => arg === "--version" || arg === "-v")) {
   console.log(getCliVersion());
   process.exit(0);
 }
-var program = new Command().name("create-qs").description("Create a new Quicksilver application").version("0.8.26", "-v, --version").argument("[project-name]", "Name of the project").option("-c, --module-code <code>", "Full module code (e.g., power_crm.sales)").option("-d, --module-directory <directory>", "Module directory name (e.g., sales)").option("-n, --module-namespace <code>", "Prefix of unit/table, defaults to the initials of the module code (e.g., pcs)").option("-p, --api-package <package>", "JVM package for Kotlin files (e.g., com.company.crm)").option("-a, --api-artifact-id <artifactId>", "Module artifact ID in repository (e.g., power-crm-module-sales)").option("-w, --web-module-package <package>", "Web module package name (e.g., @powercrm/module-sales-web)").option("-m, --modules <codes>", "Modules to depend on, comma separated (e.g., quicksilver.org)").option("--module-menu <name>", "Create the module's top-level menu in the left nav, with this label").option("--no-module-menu", "Do not create a top-level menu").option("--jsons-locale <locale>", "Language of the display texts in data files: zh-CN or zh-TW. Changing it later means rewriting every data file").option("-y, --yes", "Skip prompts and use defaults").action(async (projectName, options) => {
+var program = new Command().name("create-qs").description("Create a new Quicksilver application").version("0.8.29", "-v, --version").argument("[project-name]", "Name of the project").option("-c, --module-code <code>", "Full module code (e.g., power_crm.sales)").option("-d, --module-directory <directory>", "Module directory name (e.g., sales)").option("-n, --module-namespace <code>", "Prefix of unit/table, defaults to the initials of the module code (e.g., pcs)").option("-p, --api-package <package>", "JVM package for Kotlin files (e.g., com.company.crm)").option("-a, --api-artifact-id <artifactId>", "Module artifact ID in repository (e.g., power-crm-module-sales)").option("-w, --web-module-package <package>", "Web module package name (e.g., @powercrm/module-sales-web)").option("-m, --modules <codes>", "Modules to depend on, comma separated (e.g., quicksilver.org)").option("--module-menu <name>", "Create the module's top-level menu in the left nav, with this label").option("--no-module-menu", "Do not create a top-level menu").option("--jsons-locale <locale>", "Language of the display texts in data files: zh-CN or zh-TW. Changing it later means rewriting every data file").option("-y, --yes", "Skip prompts and use defaults").action(async (projectName, options) => {
   applyPromptTexts();
   console.log(chalk4.cyan(`
 ${t("banner")}`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-qs",
-  "version": "0.8.26",
+  "version": "0.8.29",
   "description": "Create a full-stack Quicksilver project with a single command",
   "type": "module",
   "bin": {

package/template/default/.quicksilver/manual/en-US/00-setup.md

@@ -12,7 +12,7 @@ This chapter is committed with the project. The other chapters of the manual app
 | Node.js | **`>=22.13.0`** | The minimum version pnpm 11 requires |
 | pnpm | **11** | pnpm is required, npm and yarn are not supported. Workspaces, catalogs and `allowBuilds` all depend on pnpm.
 | Gradle | No installation needed | The project ships the Gradle Wrapper (`./gradlew`), which downloads Gradle on first run |
-| Database | No installation needed | A file-based H2 database is used by default. To use another database, see [01 Getting Started](01-getting-started.md#switching-databases) |
+| Database | No installation needed | A file-based H2 database is used by default. To use another database, see [01 Getting Started](01-getting-started.md#development-instances) |
 
 ## Basic setup
 
@@ -145,7 +145,7 @@ Keep the following two points in mind:
 
 ## Next steps
 
-After dependencies are installed, the other chapters of the manual appear in this directory. Start with the [table of contents](README.md), then read [01 Getting Started](01-getting-started.md), which explains the options chosen when creating a project, the common commands, and how to switch databases.
+After dependencies are installed, the other chapters of the manual appear in this directory. Start with the [table of contents](README.md), then read [01 Getting Started](01-getting-started.md), which explains the options chosen when creating a project, the common commands, and the development instances with their databases.
 
 On first use, run `pnpm qs sources` once. It downloads the platform's API documentation, data files and the frontend `.d.ts` files into `.quicksilver/generated/`, which later chapters of the manual refer to in many places.
 

package/template/default/.quicksilver/manual/zh-CN/00-setup.md

@@ -12,7 +12,7 @@
 | Node.js | **`>=22.13.0`** | pnpm 11 要求的最低版本 |
 | pnpm | **11** | 必须使用 pnpm，不支持 npm 与 yarn。workspace、catalog、`allowBuilds` 均依赖 pnpm。
 | Gradle | 无需安装 | 项目自带 Gradle Wrapper（`./gradlew`），首次运行时自动下载 |
-| 数据库 | 无需安装 | 默认使用文件型 H2 数据库。使用其他数据库见 [01 快速入门](01-getting-started.md#切换数据库) |
+| 数据库 | 无需安装 | 默认使用文件型 H2 数据库。使用其他数据库见 [01 快速入门](01-getting-started.md#开发实例) |
 
 ## 基础设置
 
@@ -145,7 +145,7 @@ power-crm/
 
 ## 下一步
 
-安装依赖后，本目录下会出现手册的其余章节。建议先阅读[手册目录](README.md)，再阅读 [01 快速入门](01-getting-started.md)，其中介绍创建项目时各选项的含义、常用命令以及如何切换数据库。
+安装依赖后，本目录下会出现手册的其余章节。建议先阅读[手册目录](README.md)，再阅读 [01 快速入门](01-getting-started.md)，其中介绍创建项目时各选项的含义、常用命令以及开发实例与数据库。
 
 首次使用时建议执行一次 `pnpm qs sources`，将平台的接口文档、数据文件与前端 `.d.ts` 下载到 `.quicksilver/generated/`，手册后续多处会引用其中的内容。
 

package/template/default/.quicksilver/manual/zh-TW/00-setup.md

@@ -12,7 +12,7 @@
 | Node.js | **`>=22.13.0`** | pnpm 11 要求的最低版本 |
 | pnpm | **11** | 必須使用 pnpm，不支援 npm 與 yarn。workspace、catalog、`allowBuilds` 均依賴 pnpm。
 | Gradle | 無需安裝 | 專案內建 Gradle Wrapper（`./gradlew`），首次執行時自動下載 |
-| 資料庫 | 無需安裝 | 預設使用檔案型 H2 資料庫。使用其他資料庫請參閱 [01 快速入門](01-getting-started.md#切換資料庫) |
+| 資料庫 | 無需安裝 | 預設使用檔案型 H2 資料庫。使用其他資料庫請參閱 [01 快速入門](01-getting-started.md#開發實例) |
 
 ## 基本設定
 
@@ -145,7 +145,7 @@ power-crm/
 
 ## 下一步
 
-安裝相依套件後，本目錄下會出現手冊的其餘章節。建議先閱讀[手冊目錄](README.md)，再閱讀 [01 快速入門](01-getting-started.md)，其中介紹建立專案時各選項的含義、常用指令以及如何切換資料庫。
+安裝相依套件後，本目錄下會出現手冊的其餘章節。建議先閱讀[手冊目錄](README.md)，再閱讀 [01 快速入門](01-getting-started.md)，其中介紹建立專案時各選項的含義、常用指令以及開發實例與資料庫。
 
 首次使用時建議執行一次 `pnpm qs sources`，將平台的 API 文件、資料檔與前端 `.d.ts` 下載到 `.quicksilver/generated/`，手冊後續多處會引用其中的內容。
 

package/template/default/AGENTS.md

@@ -103,9 +103,10 @@ can be started; you rarely touch it.
 Project scripts (see `scripts` in `package.json`; the database dialect scripts live there too):
 
 ```bash
-pnpm dev                    # Full dev environment (API + web), ports 6286 / 6288
-pnpm dev:h2                 # A second, isolated instance (own database and Atomikos directory)
-pnpm dev:fresh              # A separate instance (ports 6280 / 6281) whose own database is rebuilt from init and demo data at every start
+pnpm dev                    # Full dev environment (API + web), ports 6286 / 6288 in the main checkout
+pnpm dev:ai                 # The instance for AI agents, with ports and a database of its own
+pnpm dev:fresh              # An instance whose own database is rebuilt from init and demo data at every start
+pnpm qs dev --list          # Every instance of this workspace, its ports and whether it is running
 pnpm build                  # Full build (backend + frontend)
 pnpm test:api               # Backend tests
 pnpm lint                   # ESLint (pnpm lint:fix to autofix)
@@ -173,32 +174,43 @@ you are unsure what a target would actually do.
 
 ## Development servers and ports
 
-**An AI agent starts `pnpm dev:h2`, never `pnpm dev`.**
-
-`pnpm dev` (web 6286 / api 6288) belongs to the person you are working with. It may well be running
-already, and it is backed by the H2 file database `run/api/local/data/h2/dev`, which keeps
-their data between starts: with `auto-init.draft-sync: true`, every start runs the upgrade drafts that
-changed since the last one. Starting or restarting it yourself interrupts them and runs your
-half-finished drafts against their data, so taking it over does not just steal a port.
-
-`pnpm dev:h2` (6210 / 6211) is the isolated instance: its own database (`h2`), its own log
-directory and its own Atomikos directory, so it can run side by side with theirs. The other dialect
-scripts (`dev:postgresql` 6220/6221, `dev:mariadb` 6230/6231, `dev:mssql` 6240/6241, `dev:oracle`
-6250/6251) are equally isolated, but they need a real server: fill in the placeholders in
-`run/api/config/application-<dialect>.yaml` first. `pnpm dev:fresh` (6280 / 6281) is isolated in the
-same way, on the H2 database `fresh`, which it drops and rebuilds from init and demo data at every start.
-
-Two more rules:
-
-- **Port already taken?** Do not prefix the pnpm script — `pnpm dev:h2` sets `PORT` and `API_PORT`
-  itself, and a command-prefix assignment inside the script wins over the one you exported. Call the
-  CLI directly instead: `PORT=9001 API_PORT=9002 SPRING_PROFILES_ACTIVE=dev,h2 pnpm qs dev`. Pick
-  something in 9000–9999; if it is still taken, Vite fails outright — pick another.
-- **Stop the server you started.** Especially after Playwright: leaving it running holds the port
-  and the database file.
+**An AI agent starts `pnpm dev:ai`, never `pnpm dev` or `pnpm dev:fresh`.**
+
+Every workspace, the main checkout or a git worktree, runs its own development instances side by
+side, each with its own ports and its own database. `pnpm dev` and `pnpm dev:fresh` belong to the
+person you are working with, in every workspace. They may well be running already, and the dev
+database keeps their data between starts: with `auto-init.draft-sync: true`, every start runs the
+upgrade drafts that changed since the last one. Starting or restarting it yourself interrupts them
+and runs your half-finished drafts against their data, so taking it over does not just steal a port.
+
+`pnpm dev:ai` is the instance for you: ports and a database of its own, side by side with theirs.
+`pnpm qs dev --list` shows every instance of the workspace with its ports and whether it is running.
+To check a database dialect, start its instance, such as `pnpm dev:postgresql`, after filling in the
+placeholders in `run/api/config/application-<dialect>.yaml`.
+
+Rules:
+
+- **`dev:ai` ports already taken?** Another session in this workspace is using it. Do not stop that
+  process: start `pnpm dev:ai2` instead, and ask the person you work with when both are taken. Point
+  the test commands at the instance you started: `pnpm qs test verify --instance ai2`,
+  `pnpm qs test unit-smoke <unit> --instance ai2`.
+- **Add `--fresh` the first time you start `dev:ai` or `dev:ai2` in a session**, as in
+  `pnpm dev:ai --fresh`, and leave it out on later restarts. The database belongs to this workspace
+  and instance, but one workspace is used by several sessions in turn, so it may still hold what an
+  earlier session left. Restarts within the session go without `--fresh`, so that your own draft
+  changes pass through draft sync as they will for others.
+- **Treat the databases of the dialect instances as scratch.** The person you work with and you
+  share them, anyone may rebuild them at any time, so keep nothing there you need. Add `--fresh`
+  the first time you start a dialect instance in a session, as in `pnpm dev:postgresql --fresh`,
+  and again after changing its database by hand. One exception: to check a DDL command in a draft
+  (a column type change, a rename), the database has to exist from before the change, and the start
+  after editing the draft goes without `--fresh`. A fresh install runs init and skips the drafts,
+  so the command would never run.
 - **Rebuild when the database no longer matches the branch.** After switching branches, or when
   earlier experiments left the database in a state you cannot explain, start once with
-  `pnpm dev:h2 --fresh`. Draft sync never undoes a change that was taken out of a draft.
+  `pnpm dev:ai --fresh`. Draft sync never undoes a change that was taken out of a draft.
+- **Stop the server you started.** Especially after Playwright: leaving it running holds the ports
+  and the database.
 
 ## Signing in locally
 
@@ -220,13 +232,16 @@ platform's own specs and for yours under `test/e2e/scenarios/`, which start out
 ## Looking at the development data
 
 The profile file is the source of truth for where the data actually lives. Read
-`run/api/config/application-dev.yaml` (or `application-<dialect>.yaml` for whichever profile you
-started) and take the datasource from there; note that paths in it are relative to `run/api`, which
-is the working directory of the API process.
+`run/api/config/application-dev.yaml` (or `application-<dialect>.yaml` for whichever instance you
+started) and take the datasource from there. Paths in it are relative to `run/api`, which is the
+working directory of the API process. The database name then gets the suffix of the instance, which
+`pnpm qs dev --list` shows: in a git worktree and for instances such as `ai`, the name in the file is
+followed by `_worktree<slot>` and `_ai`.
 
-For the default H2 profiles that means a file — `run/api/local/data/h2/dev` for `pnpm dev`,
-`h2` for `pnpm dev:h2` — which you can open with any H2 client. For the other dialects,
-connect with your usual client using the host, port, user and password from that same file.
+For the default H2 profiles that means a file, `run/api/local/data/h2/dev` for `pnpm dev` in the main
+checkout and `dev_ai` next to it for `pnpm dev:ai`, which you can open with any H2 client. For the
+other dialects, connect with your usual client using the host, port, user and password from that
+same file.
 
 The development database is kept between starts. With `auto-init.draft-sync: true`, every start runs
 each module draft `data/upgrade/draft.jsons` that changed since the last start, and data entered by hand
@@ -256,7 +271,7 @@ installs only. Imperative commands in a draft (`@sql`,
 `$update`, `$delete` ...) run once per `$key`; to run a changed one again, give it a new `$key`.
 `$place` is the exception: it runs again whenever its draft runs. To rebuild the database from the
 data files under `data/init/` and `data/demo/`, add `--fresh` to the start command for one start
-(`pnpm dev:h2 --fresh`). It changes no config file, and the next start without it keeps the data again.
+(`pnpm dev:ai --fresh`). It changes no config file, and the next start without it keeps the data again.
 
 ## Development skills
 

package/template/default/package.json

@@ -10,15 +10,17 @@
   "scripts": {
     "// --- start dev servers -------------------------------------------": "",
     "dev": "quicksilver dev",
-    "dev:fresh": "PORT=6280 API_PORT=6281 SPRING_PROFILES_ACTIVE=dev,fresh quicksilver dev --fresh",
-    "dev:h2": "PORT=6210 API_PORT=6211 SPRING_PROFILES_ACTIVE=dev,h2 quicksilver dev",
-    "dev:postgresql": "PORT=6220 API_PORT=6221 SPRING_PROFILES_ACTIVE=dev,postgresql quicksilver dev",
-    "dev:mariadb": "PORT=6230 API_PORT=6231 SPRING_PROFILES_ACTIVE=dev,mariadb quicksilver dev",
-    "dev:mssql": "PORT=6240 API_PORT=6241 SPRING_PROFILES_ACTIVE=dev,mssql quicksilver dev",
-    "dev:oracle": "PORT=6250 API_PORT=6251 SPRING_PROFILES_ACTIVE=dev,oracle quicksilver dev",
+    "dev:fresh": "quicksilver dev --instance fresh",
+    "dev:ai": "quicksilver dev --instance ai",
+    "dev:ai2": "quicksilver dev --instance ai2",
+    "dev:h2": "quicksilver dev --instance h2",
+    "dev:postgresql": "quicksilver dev --instance postgresql",
+    "dev:mariadb": "quicksilver dev --instance mariadb",
+    "dev:mssql": "quicksilver dev --instance mssql",
+    "dev:oracle": "quicksilver dev --instance oracle",
     "dev:debug": "quicksilver dev --debug",
-    "dev:api": "quicksilver gradle :run:bootRun",
-    "dev:web": "pnpm -C run/web dev",
+    "dev:api": "quicksilver dev api",
+    "dev:web": "quicksilver dev web",
     "// --- build subprojects -------------------------------------------": "",
     "build": "pnpm build:api && pnpm build:web",
     "build:api": "quicksilver gradle build",

package/template/default/pnpm-workspace.yaml

@@ -25,13 +25,13 @@ catalogs:
   client:
     "@qs-charts/adapter-preact": "0.2.11"
     "@qs-charts/core": "0.2.11"
-    "@qs-elements/web": "1.0.163"
-    "@qs-elements/web-preact": "1.0.163"
+    "@qs-elements/web": "1.0.165"
+    "@qs-elements/web-preact": "1.0.165"
   quicksilver:
-    "@qs-platform/cli": "0.8.26"
-    "@qs-platform/preset-vite-web": "0.8.26"
-    "@qs-platform/web-module-core": "0.8.26"
-    "@qs-platform/web-module-org": "0.8.26"
+    "@qs-platform/cli": "0.8.29"
+    "@qs-platform/preset-vite-web": "0.8.29"
+    "@qs-platform/web-module-core": "0.8.29"
+    "@qs-platform/web-module-org": "0.8.29"
   tooling:
     "@types/node": "^26.4.0"
     "sass": "^1.103.1"

package/template/default/quicksilver.yaml

@@ -19,3 +19,30 @@ packaging:
   archive-name: {{PROJECT_CODE}}
   fixed-modules: [{{PLATFORM_MODULE_CODES_QUOTED}}, '{{MODULE_CODE}}']
   visible-modules:
+
+# Development instances. `pnpm dev:<name>` runs `quicksilver dev --instance <name>`. The dev instance
+# is required, `pnpm dev` starts it. port-offset gives the last two digits of the ports: web listens on
+# the base port plus it, the API on that plus 2, and plus 1 and plus 3 are reserved. profile adds
+# run/api/config/application-<profile>.yaml on top of application-dev.yaml. db-suffix is appended to
+# the database name. rebuild: always rebuilds the database from init and demo data at every start. The
+# developer manual (01-getting-started.md) describes every field, the Oracle user each instance logs in
+# as, and the base ports to choose when several projects run on one machine.
+dev:
+  # The main workspace listens on this plus the port offset: 6286 for dev.
+  main-base-port: 6200
+  # A git worktree with slot n listens on this plus n * 100 plus the port offset: 7186 for dev in
+  # worktree 1.
+  worktree-base-port: 7000
+  instances:
+    # 1x to 5x: one instance per database
+    h2:         { port-offset: 10, profile: h2 }
+    postgresql: { port-offset: 20, profile: postgresql }
+    mariadb:    { port-offset: 30, profile: mariadb }
+    mssql:      { port-offset: 40, profile: mssql }
+    oracle:     { port-offset: 50, profile: oracle }
+    # 8x: the developer
+    fresh:      { port-offset: 80, db-suffix: fresh, rebuild: always }
+    dev:        { port-offset: 86 }
+    # 9x: AI agents
+    ai:         { port-offset: 92, db-suffix: ai }
+    ai2:        { port-offset: 96, db-suffix: ai2 }

package/template/default/run/api/config/README.md

@@ -9,34 +9,75 @@ startup; nothing in this directory ships to your users.
 |---|---|
 | `application.yaml` | Base configuration: ports, CORS, cache, upload, Atomikos. **Declares no datasources** — those live in the profile files below |
 | `application-dev.yaml` | The `dev` profile, active by default. Datasources for local development, plus `auto-init` (with `draft-sync` on) and `fail-on-unregistered-data-source` |
-| `application-<dialect>.yaml` | One overlay per database dialect (`h2`, `postgresql`, `mariadb`, `mssql`, `oracle`). Each carries its own datasources, log directory and Atomikos log directory, so several can run side by side |
+| `application-<dialect>.yaml` | One overlay per database dialect (`h2`, `postgresql`, `mariadb`, `mssql`, `oracle`), each with its own datasources. `pnpm dev:<dialect>` starts the instance that uses it |
 | `application-test.yaml` | Used by `modules/*/api` tests. In-memory H2, wiped on every run |
 | `logback.xml` / `logback-test.xml` | Logging |
 
 ## Choosing a database
 
-`pnpm dev` runs on a file-based H2 database with no setup. To use another dialect, run its script
-— `pnpm dev:postgresql`, `pnpm dev:mariadb`, and so on — which sets
-`SPRING_PROFILES_ACTIVE=dev,<dialect>` and its own ports.
+`pnpm dev` runs on a file-based H2 database with no setup. To use another dialect, run its script,
+such as `pnpm dev:postgresql` or `pnpm dev:mariadb`. Each script starts the development instance of
+that name, `quicksilver dev --instance <dialect>`, which puts the dialect's profile on top of `dev`
+and gives the instance ports and a database of its own. `pnpm qs dev --list` shows every instance.
 
-The H2 profiles ship with working credentials (`sa` / `sa`) — H2 creates the database on first
+The H2 profiles ship with working credentials (`sa` / `sa`): H2 creates the database file on first
 connect, so there is nothing to change. In every other dialect file the user and `PASSWORD` are
 placeholders you must replace.
 
-**Do not drop the `dev,` prefix.** Without it `application-dev.yaml` is not loaded, and since
-`application.yaml` declares no datasources, startup fails with `Missing required datasource code`.
-That is deliberate: a missing datasource list must fail loudly rather than fall back to some
-default database.
-
-Create the databases before use — the server-based dialects only. Each of those files names its
-database after this project — a project called `power-crm` gets `power_crm_dev` — so several
-Quicksilver products can share one database server without colliding. Two files sit outside that
-rule: Oracle, whose "database" is a PDB with a name fixed by the container image (`FREEPDB1`), and
-the H2 profiles, whose databases are plain files under this project's own `local/data/h2/`
-(`dev` for `pnpm dev`, `h2` for `pnpm dev:h2`) and so have nothing to collide with. The
-datasource list is replaced as a whole, so when you change one entry, keep the other one listed
+The profile always comes from the instance. `quicksilver dev` refuses to start when
+`SPRING_PROFILES_ACTIVE` is set, because a profile from elsewhere would not match the database the
+instance is meant to use.
+
+Each server-based dialect file names its database after this project, so several Quicksilver
+products can share one database server without colliding: a project called `power-crm` gets
+`power_crm_matrix`. When you point `application-dev.yaml` at a server, name that database
+`power_crm_dev`, so that `pnpm dev` and the dialect instances never share one. Two files sit outside
+that rule. Oracle's "database" is a PDB with a name fixed by the container image (`FREEPDB1`), so
+`application-dev.yaml` and `application-oracle.yaml` are kept apart by user instead, see the next
+section. The H2 profiles keep their databases as plain files under this project's own
+`local/data/h2/` (`dev` for `pnpm dev`, `h2` for `pnpm dev:h2`) and so have nothing to collide with.
+The datasource list is replaced as a whole, so when you change one entry, keep the other one listed
 as well.
 
+## Instances, worktrees and databases
+
+Every workspace, the main checkout or a git worktree, runs its own instances side by side: `dev`,
+`fresh`, `ai`, `ai2` and one per dialect. The instance decides the ports and the database. In the
+main checkout `pnpm dev` uses web 6286 / API 6288 and the database configured here. A worktree gets
+a slot number the first time an instance starts in it, and its ports move to 7n86 / 7n88 for slot n.
+The base ports 6200 and 7000 are `main-base-port` and `worktree-base-port` in `quicksilver.yaml`.
+
+The database name gets a suffix in a worktree (`worktree<slot>`) and for instances with a
+`db-suffix` (`fresh`, `ai`, `ai2`), joined with underscores: `power_crm_dev_worktree1_ai`, or for H2
+the file `dev_worktree1_ai`. In development mode a missing database is created at startup: the log
+names it in a WARN line, and when the account may not create databases, startup fails with the
+statement to run by hand. When a suffixed database is created next to an existing configured
+database, MySQL, MariaDB and SQL Server copy its character set and collation. The first start of each
+instance in a new worktree rebuilds its database from init and demo data, and so does every start of
+`fresh`.
+
+An Oracle database is a PDB and cannot be created per instance, so the suffix goes on the user
+instead: the instance logs in as `<configured user>_<suffix>` with the configured URL and password,
+for example `pnpm dev:oracle` in worktree 1 as `system_worktree1`. In Oracle a user is its own
+schema, so each instance keeps its tables apart. In development mode a missing user is created at startup with the configured account:
+the log names it in a WARN line. The account needs the DBA role, or the system privileges
+`create profile`, `create user`, `drop user`, `grant any privilege` and `grant any role`. Without
+them startup fails with every statement a DBA has to run. The configured user must be an unquoted
+name that does not start with `C##`. Such a name belongs to a common user of the CDB, while the
+derived user is a local user created in the PDB, and local user names cannot start with `C##`.
+
+When you point `application-dev.yaml` at Oracle, give it a user other than the one in
+`application-oracle.yaml`, for example `power_crm_dev` created for development. With the same user,
+`pnpm dev` and `pnpm dev:oracle` share one schema in the main checkout, where rebuilding either with
+`--fresh` wipes the data of the other. In a worktree they derive one user, and the second of the two
+to start for the first time wipes the data of the other. No user is created when no suffix applies,
+so create this one beforehand. Besides `create session`, `create table`, `create view`,
+`select_catalog_role` and a tablespace quota, it needs the privileges above, which the instances
+whose database name gets a suffix use to create their derived users.
+
+To change the instance table, or the base ports when several projects run on one machine, see the
+developer manual (`.quicksilver/manual`, "Getting started").
+
 ## H2 URLs
 
 The two H2 parameters below are not optional. Both failures are quiet and show up far from the
@@ -52,9 +93,11 @@ configuration, so keep them when you edit an H2 URL:
 ## MySQL
 
 MySQL works, but **you have to supply the driver**: Connector/J is GPLv2, so it is not bundled.
-Add `runtimeOnly("com.mysql:mysql-connector-j")` to `run/api/build.gradle.kts`, then add a
-`application-mysql.yaml` overlay and a `dev:mysql` script of your own, modelled on the other
-dialects. Every other dialect listed above ships with its driver.
+Add `runtimeOnly("com.mysql:mysql-connector-j")` to `run/api/build.gradle.kts`, then add an
+`application-mysql.yaml` overlay modelled on the other dialects, a `mysql` instance in the
+`dev.instances` table of `quicksilver.yaml`, and a `dev:mysql` script running
+`quicksilver dev --instance mysql`. Give the new instance a port offset at least 4 away from every
+other one, for example 70. Every other dialect listed above ships with its driver.
 
 ## The dev database
 

package/template/default/run/api/config/application-dev.yaml

@@ -1,12 +1,17 @@
 #
 # Overlay for the `dev` profile. Activated by default via `spring.profiles.active` in
-# application.yaml, and by every `pnpm dev:*` script.
+# application.yaml, and by `quicksilver dev` for every instance.
 #
 spring:
   application.name: DEV
 
 quicksilver:
   datasource:
+    # `quicksilver dev` gives every instance in every workspace a database of its own, derived from
+    # the URLs below. In a git worktree, and for instances with a db-suffix such as fresh and ai, it
+    # appends a suffix to the database name: dev_worktree1, dev_fresh, dev_ai. For H2 the suffix goes
+    # on the file name. A missing database is created at startup in development mode, also when you
+    # point dev at a server-based database here.
     # Keep the quotes around passwords: special characters (# : @ ...) then paste in as is.
     items:
       - code: metadata

package/template/default/run/api/config/application-h2.yaml

@@ -1,11 +1,8 @@
 #
 # Overlay for the `h2` profile: only the keys that differ from application-dev.yaml,
-# everything else is inherited key by key. Activate with SPRING_PROFILES_ACTIVE=dev,h2
-# (or run `pnpm dev:h2`).
+# everything else is inherited key by key. `pnpm dev:h2` starts the `h2` instance with
+# it. The log and Atomikos directories are passed by `quicksilver dev` for each instance.
 #
-logging:
-  file.path: local/log/application/h2
-
 quicksilver:
   datasource:
     # Keep the quotes around passwords: special characters (# : @ ...) then paste in as is.
@@ -18,5 +15,3 @@ quicksilver:
         url: "jdbc:h2:./local/data/h2/h2;DB_CLOSE_ON_EXIT=FALSE;DATABASE_TO_UPPER=false;MODE=MySQL"
         user: sa
         password: "sa"
-    atomikos:
-      log_base_dir: local/log/atomikos/h2

package/template/default/run/api/config/application-mariadb.yaml

@@ -1,22 +1,17 @@
 #
 # Overlay for the `mariadb` profile: only the keys that differ from application-dev.yaml,
-# everything else is inherited key by key. Activate with SPRING_PROFILES_ACTIVE=dev,mariadb
-# (or run `pnpm dev:mariadb`).
+# everything else is inherited key by key. `pnpm dev:mariadb` starts the `mariadb` instance with
+# it. The log and Atomikos directories are passed by `quicksilver dev` for each instance.
 #
-logging:
-  file.path: local/log/application/mariadb
-
 quicksilver:
   datasource:
     # Keep the quotes around passwords: special characters (# : @ ...) then paste in as is.
     items:
       - code: metadata
-        url: "jdbc:mariadb://localhost:3308/{{DB_PREFIX}}_dev?characterEncoding=utf8mb4"
+        url: "jdbc:mariadb://localhost:3308/{{DB_PREFIX}}_matrix?characterEncoding=utf8mb4"
         user: root
         password: "PASSWORD"
       - code: business
-        url: "jdbc:mariadb://localhost:3308/{{DB_PREFIX}}_dev?characterEncoding=utf8mb4"
+        url: "jdbc:mariadb://localhost:3308/{{DB_PREFIX}}_matrix?characterEncoding=utf8mb4"
         user: root
         password: "PASSWORD"
-    atomikos:
-      log_base_dir: local/log/atomikos/mariadb

package/template/default/run/api/config/application-mssql.yaml

@@ -1,22 +1,17 @@
 #
 # Overlay for the `mssql` profile: only the keys that differ from application-dev.yaml,
-# everything else is inherited key by key. Activate with SPRING_PROFILES_ACTIVE=dev,mssql
-# (or run `pnpm dev:mssql`).
+# everything else is inherited key by key. `pnpm dev:mssql` starts the `mssql` instance with
+# it. The log and Atomikos directories are passed by `quicksilver dev` for each instance.
 #
-logging:
-  file.path: local/log/application/mssql
-
 quicksilver:
   datasource:
     # Keep the quotes around passwords: special characters (# : @ ...) then paste in as is.
     items:
       - code: metadata
-        url: "jdbc:sqlserver://localhost:1433;DatabaseName={{DB_PREFIX}}_dev;trustServerCertificate=true"
+        url: "jdbc:sqlserver://localhost:1433;DatabaseName={{DB_PREFIX}}_matrix;trustServerCertificate=true"
         user: sa
         password: "PASSWORD"
       - code: business
-        url: "jdbc:sqlserver://localhost:1433;DatabaseName={{DB_PREFIX}}_dev;trustServerCertificate=true"
+        url: "jdbc:sqlserver://localhost:1433;DatabaseName={{DB_PREFIX}}_matrix;trustServerCertificate=true"
         user: sa
         password: "PASSWORD"
-    atomikos:
-      log_base_dir: local/log/atomikos/mssql

package/template/default/run/api/config/application-oracle.yaml

@@ -1,11 +1,8 @@
 #
 # Overlay for the `oracle` profile: only the keys that differ from application-dev.yaml,
-# everything else is inherited key by key. Activate with SPRING_PROFILES_ACTIVE=dev,oracle
-# (or run `pnpm dev:oracle`).
+# everything else is inherited key by key. `pnpm dev:oracle` starts the `oracle` instance with
+# it. The log and Atomikos directories are passed by `quicksilver dev` for each instance.
 #
-logging:
-  file.path: local/log/application/oracle
-
 quicksilver:
   datasource:
     # Keep the quotes around passwords: special characters (# : @ ...) then paste in as is.
@@ -18,5 +15,3 @@ quicksilver:
         url: "jdbc:oracle:thin:@//localhost:1521/FREEPDB1"
         user: system
         password: "PASSWORD"
-    atomikos:
-      log_base_dir: local/log/atomikos/oracle

package/template/default/run/api/config/application-postgresql.yaml

@@ -1,22 +1,17 @@
 #
 # Overlay for the `postgresql` profile: only the keys that differ from application-dev.yaml,
-# everything else is inherited key by key. Activate with SPRING_PROFILES_ACTIVE=dev,postgresql
-# (or run `pnpm dev:postgresql`).
+# everything else is inherited key by key. `pnpm dev:postgresql` starts the `postgresql` instance with
+# it. The log and Atomikos directories are passed by `quicksilver dev` for each instance.
 #
-logging:
-  file.path: local/log/application/postgresql
-
 quicksilver:
   datasource:
     # Keep the quotes around passwords: special characters (# : @ ...) then paste in as is.
     items:
       - code: metadata
-        url: "jdbc:postgresql://127.0.0.1/{{DB_PREFIX}}_dev?stringtype=unspecified"
+        url: "jdbc:postgresql://127.0.0.1/{{DB_PREFIX}}_matrix?stringtype=unspecified"
         user: postgres
         password: "PASSWORD"
       - code: business
-        url: "jdbc:postgresql://127.0.0.1/{{DB_PREFIX}}_dev?stringtype=unspecified"
+        url: "jdbc:postgresql://127.0.0.1/{{DB_PREFIX}}_matrix?stringtype=unspecified"
         user: postgres
         password: "PASSWORD"
-    atomikos:
-      log_base_dir: local/log/atomikos/postgresql

package/template/default/run/api/config/application-fresh.yaml

@@ -1,23 +0,0 @@
-#
-# Overlay for the `fresh` profile used by `pnpm dev:fresh`: only the keys that differ from
-# application-dev.yaml, everything else is inherited key by key. It has a database of its own, which
-# the script drops and rebuilds from init and demo data at every start, so the `pnpm dev` database
-# is never touched.
-#
-logging:
-  file.path: local/log/application/fresh
-
-quicksilver:
-  datasource:
-    # Keep the quotes around passwords: special characters (# : @ ...) then paste in as is.
-    items:
-      - code: metadata
-        url: "jdbc:h2:./local/data/h2/fresh;DB_CLOSE_ON_EXIT=FALSE;DATABASE_TO_UPPER=false;MODE=MySQL"
-        user: sa
-        password: "sa"
-      - code: business
-        url: "jdbc:h2:./local/data/h2/fresh;DB_CLOSE_ON_EXIT=FALSE;DATABASE_TO_UPPER=false;MODE=MySQL"
-        user: sa
-        password: "sa"
-    atomikos:
-      log_base_dir: local/log/atomikos/fresh