@carllee1983/dbcli 9.1.2 → 10.0.0

package/.github/skills/dbcli/reference.md

@@ -119,24 +119,24 @@ dbcli query '{}' --collection events --format json 2>/dev/null | jq '.rows | len
 Initialize `.dbcli` configuration file. Typically run manually by the developer — avoid running on behalf of the user unless explicitly requested.
 
 ```bash
-dbcli init                                              # Single connection (v1 format)
-dbcli init --system mysql --host localhost --port 3306 --user root --name mydb
+dbcli init                                              # Prompt for a name; create named v2
+dbcli init --conn-name local --system mysql --host localhost --port 3306 --user root --name mydb
 dbcli init --use-env-refs                               # Store env var references
-dbcli init --no-interactive --force                     # Non-interactive mode
+dbcli init --conn-name local --no-interactive --force    # Non-interactive; credentials from environment
 
 # MongoDB — field-by-field (primary path, same shape as SQL)
-dbcli init --system mongodb --host localhost --port 27017 --user admin --password secret --auth-source admin --name mydb
-dbcli init --system mongodb --host localhost --port 27017 --name mydb  # No auth
+dbcli init --conn-name local --system mongodb --host localhost --port 27017 --user admin --password secret --auth-source admin --name mydb
+dbcli init --conn-name local --system mongodb --host localhost --port 27017 --name mydb  # No auth
 # MongoDB — full URI (advanced fallback: multi-host, non-standard driver options)
-dbcli init --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
+dbcli init --conn-name local --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
 
 # Redis (database = logical DB index)
-dbcli init --system redis --host localhost --port 6379
-dbcli init --system redis --host localhost --port 6379 --password secret --name 0
+dbcli init --conn-name local --system redis --host localhost --port 6379
+dbcli init --conn-name local --system redis --host localhost --port 6379 --password secret --name 0
 
 # Elasticsearch
-dbcli init --system elasticsearch --host localhost --port 9200 --user elastic --password changeme
-dbcli init --system elasticsearch --cloud-id "myCluster:dXMtZWFzdC0xLmF3..." --api-key "<base64>"
+dbcli init --conn-name local --system elasticsearch --host localhost --port 9200 --user elastic --password changeme
+dbcli init --conn-name local --system elasticsearch --cloud-id "myCluster:dXMtZWFzdC0xLmF3..." --api-key "<base64>"
 
 # Multi-connection (v2 format)
 dbcli init --conn-name staging --env-file .env.staging   # Named connection with custom env file
@@ -151,6 +151,12 @@ dbcli --global init --conn-name shared --system postgresql --host db.example.com
 dbcli --global use --list
 ```
 
+Every new or additional connection needs a nonblank connection name. Pass `--conn-name <name>`, or run `dbcli init` in an interactive terminal to be asked for one. The name prompt has no suggested `default`; empty or whitespace-only answers explain the requirement and prompt again. Cancelling or ending the name prompt stops before any connection test or configuration/credential write. An explicit nonblank `--conn-name` skips this prompt, and `--conn-name default` is valid. An explicitly blank `--conn-name` is an error in every mode, before connection tests or writes. `--name` still means the database name (the logical DB index for Redis), never the connection name.
+
+Without a TTY, with `--no-interactive`, or when `--use-env-refs` plus all five `--env-*` options automatically disables interaction, a missing or blank `--conn-name` fails with guidance to supply it, before database access or configuration/credential writes. Complete credentials, `--name`, `--env-file`, and `--force` do not supply a connection name.
+
+New initialization always creates named v2 configuration, including plain `init` and explicit `--config` paths; it no longer creates an unnamed v1 configuration. Existing v1 configurations remain readable and their established named v2 import is retained. The first explicitly named connection is still the default in a new registry; adding a connection preserves an existing registry's default or no-default state. An explicitly chosen duplicate name still requires interactive overwrite confirmation or `--force`; a noninteractive duplicate without `--force`, or a declined confirmation, leaves files untouched. `--remove` and `--rename` do not ask for a new connection name.
+
 **Key options:** `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
@@ -161,7 +167,27 @@ dbcli --global use --list
 
 **Redis note:** the `database` (or `--name`) field is the logical DB index (`"0"` … `"15"`), not a database name.
 
-**Multi-connection:** Using `--conn-name` or `--env-file` creates a v2 config with named connections. Each connection can have its own env file and permission level. Existing v1 configs are automatically imported as the `default` connection when upgrading.
+**Multi-connection:** Every newly created connection uses v2 with an explicitly supplied or interactively entered name. Each connection can have its own env file and permission level; `--env-file` does not replace the name requirement. Existing v1 configs are automatically imported as the `default` connection when upgrading.
+
+V2 may omit the top-level `default` field; if supplied, it must be a nonempty
+string naming an existing connection. `null`, `""`, and nonexistent names are
+invalid. The first explicitly named connection defaults a new registry; adding
+another preserves the existing default or no-default state. Existing v1 reads
+and named v1 imports remain supported; neither configuration version changes.
+
+Legacy project configuration compatibility: adding a connection cannot import a
+direct-project v2 registry when an existing connection uses an `envFile` other
+than `.env.local`. `init` refuses before writing and retains the existing config
+and env files. An administrator must migrate the registry and custom env files
+to supported home storage before retrying. Bound/home-storage v2 configs and
+direct-project v2 configs with no `envFile` or only `.env.local` remain supported.
+
+`init --remove <name>` clears `default` and reports that change when removing its
+connection; it never chooses another connection. Removing a non-default keeps
+the saved default, and removing a connection from a no-default config keeps that
+state. The public `removeConnection` helper follows the same rules. Deleting
+the last connection is rejected without changing the config. Renaming preserves
+the no-default state, or updates the default name when renaming that connection.
 
 Use root-level `--global` with `init`, `use`, `status`, `query`, or any other command to read or mutate the user-global v2 registry at `~/.config/dbcli/config.json`. Without it, the current project binding remains the source of truth. The global registry uses the same private file mode and integrity record as project home storage.
 
@@ -169,11 +195,12 @@ Use root-level `--global` with `init`, `use`, `status`, `query`, or any other co
 
 ### use
 
-Switch or display the default database connection (v2 multi-connection config).
+Set, clear, or display the default database connection (v2 multi-connection config).
 
 ```bash
-dbcli use                   # Show current default connection
+dbcli use                   # Show the current default, or describe no default
 dbcli use staging           # Switch default to 'staging'
+dbcli use --unset            # Clear the saved default; connections are unchanged
 dbcli use --list            # List all connections (* marks default)
 dbcli use --list --format json # Credential-free connection identity inventory
 ```
@@ -188,17 +215,43 @@ Cloud ID-only Elasticsearch connections also return `null` instead of default
 placeholders. It deliberately excludes user names, passwords, URIs, Cloud IDs,
 API keys, and env variable names.
 Misspelled selectors suggest nearby configured connection names.
+Without a default, text inventory marks no connection as default and every JSON
+item has `isDefault: false`. Inventory remains usable, and `doctor` accepts an
+omitted default as valid v2 configuration. Its connection checks still require
+an explicit selector, for example `dbcli --use staging doctor`.
 
-Any command can also use `--use <name>` to temporarily select a connection without changing the default:
+Any command can also use root-level `--use <name>` before the command to
+temporarily select a connection without changing the default. `query`, `schema`,
+`list`, `export`, and `check` also accept it after the command:
 
 ```bash
 dbcli query --use staging "SELECT * FROM users LIMIT 10"
 dbcli list --use prod
 ```
 
+Selection precedence is explicit `--use`, then `DBCLI_CONNECTION`, then the
+saved default. Conflicting root-level and command-level selectors are an error;
+blank CLI selectors are invalid, while a blank environment selector is ignored.
+Without a default, connection-dependent commands require an explicit `--use` or
+`DBCLI_CONNECTION` selection. Otherwise they fail before database access with
+an error naming both selectors and listing available connection names, never
+endpoints or credentials. No caller selects the first connection automatically.
+Unknown names and production targets retain their validation and explicit
+selection safeguards.
+
+`use --unset` removes only the persisted v2 `default` field and reports that it
+was cleared. It also succeeds when the field is already absent without changing
+connections. It rejects a connection name, `--list`, `--confirm-production`, or
+`--format json` in the same invocation before writing, and never converts or
+overwrites v1. It uses the existing approved, integrity-protected configuration
+write path and is blocked under `DBCLI_AGENT_MODE=1`. To set a default again, use
+`dbcli use <name>`; production defaults still require the exact name repeated in
+`--confirm-production <name>`, and production database access still requires an
+explicit selector even if that connection is the saved default.
+
 **Requires v2 config** (created with `dbcli init --conn-name`).
 
-**Options:** `--list`, `--format <text|json>`, `--confirm-production <name>` (required when explicitly selecting a production connection as the default).
+**Options:** `--list`, `--unset`, `--format <text|json>`, `--confirm-production <name>` (required when explicitly selecting a production connection as the default).
 
 ### password
 
@@ -3591,7 +3644,7 @@ Parser behaviour (`src/core/saved-queries/parser.ts::normaliseVisual`):
 
 MongoDB connections use a JSON-based query model instead of SQL. Treat MongoDB support as a narrower document-database path, not as a full SQL feature equivalent.
 
-`init --system mongodb` defaults to a field-by-field wizard (`host`, `srv`, `port`, `user`, `password` + `authSource`, then optional `replicaSet` / `tls`); a full `uri` is an explicit advanced choice in the interactive flow and the unchanged non-interactive path via `--uri`. Optional fields `authSource`, `replicaSet`, `tls`, and `srv` express what previously required embedding options in the `uri` query string. Atlas-style `mongodb+srv://` URIs are supported both as a full `uri` and via the per-field `srv: true` option. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
+`init --system mongodb` defaults to a field-by-field wizard (`host`, `srv`, `port`, `user`, `password` + `authSource`, then optional `replicaSet` / `tls`); a full `uri` is an explicit advanced choice in the interactive flow and the non-interactive path via `--uri` (with the required `--conn-name`). Optional fields `authSource`, `replicaSet`, `tls`, and `srv` express what previously required embedding options in the `uri` query string. Atlas-style `mongodb+srv://` URIs are supported both as a full `uri` and via the per-field `srv: true` option. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
 
 The 5000ms default server-selection timeout is often too tight for a connection over a VPN or to Atlas. Set a `timeout` field (ms) in the connection config, or override it per invocation with root-level `--timeout`, e.g. `dbcli --timeout 20000 --use <conn> list`.
 
@@ -3617,10 +3670,10 @@ The 5000ms default server-selection timeout is often too tight for a connection
 
 ```bash
 # 1. Initialize — field-by-field (primary path)
-dbcli init --system mongodb --host localhost --port 27017 \
+dbcli init --conn-name local --system mongodb --host localhost --port 27017 \
   --user admin --password '<secret>' --auth-source admin --name mydb
 # ...or a full URI (advanced fallback, e.g. Atlas SRV clusters)
-dbcli init --system mongodb --uri "mongodb+srv://user:pass@cluster.example.mongodb.net/mydb"
+dbcli init --conn-name local --system mongodb --uri "mongodb+srv://user:pass@cluster.example.mongodb.net/mydb"
 
 # 2. List collections
 dbcli list --format json

package/CHANGELOG.md

@@ -5,6 +5,113 @@ All notable changes to dbcli are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [10.0.0] - 2026-10-13
+
+這次發布整合 npm 9.1.2 之後合併的變更：明確命名連線、可不設預設連線、Bun 1.4.0
+最低版本、PostgreSQL schema 修正、帶期限的 audit 豁免，以及實錄的 agent 操作影片。
+9.2.0 曾完成發布準備，但未發布到 npm；原本的 9.2.0 與 Unreleased 更新紀錄合併於此。
+
+版本為 **10.0.0**。新連線不再自動取名，刪除預設連線也不再自動改選另一條；這兩項
+行為會影響既有腳本，所以採用 major 版本。
+
+### Breaking changes and upgrade notes
+
+- **非互動式初始化必須指定 `--conn-name <連線名稱>`。** 適用於非 TTY、
+  `--no-interactive` 與完整 env-reference 自動非互動模式；互動模式會詢問名稱。
+  `--name` 仍表示資料庫名稱，不能拿它代替 `--conn-name`。原先依賴自動命名的腳本
+  須補上連線名稱；明確指定 `--conn-name default` 仍合法。
+- **升級 Bun 至 1.4.0 以上。** 仍使用 1.3.x 的環境須先升級，原因與相依套件細節見下方。
+- **既有 v1 設定讀取與具名匯入仍保留。** 單純 `init` 與明確 `--config` 新建連線
+  改用具名 v2；全新 registry 的第一條具名連線仍會成為預設，追加連線則保留既有的
+  default/no-default 狀態，不會偷偷建立或替換預設。
+- **預設連線可以清除，刪除後不再自動補選。** 使用 `dbcli use --unset` 清除預設；
+  刪除預設連線也會留下無預設狀態，而不是選取下一條。之後須透過 `--use` 或
+  `DBCLI_CONNECTION` 選取，或以 `dbcli use <連線名稱>` 明確設定新預設；仍禁止刪除
+  最後一條連線。
+- **帶自訂 `envFile` 的直接專案 v2 設定須先遷移。** 若新增連線需要匯入舊版直接
+  專案 v2 設定，而它的 `envFile` 不是 `.env.local`，`init` 會在寫入前拒絕並保留
+  原檔。須先由管理員完成 home storage 遷移，再新增連線。
+
+### Added
+
+- **介紹頁與 README 加上一段實錄的 agent 操作影片。** 一段真實的 Claude Code session
+  對著一個用完即丟的 PostgreSQL 操作：agent 透過 dbcli 讀資料，被列入黑名單的
+  `password_hash` 欄位帶著 dbcli 的安全提示被略去，它在 query-only 連線上的寫入被拒絕。
+  影片放在兩個語系介紹頁的 #safety 區，兩份 README 各以縮圖連到自己語系的頁面。
+  `scripts/demo/` 保留 seed、設定、錄製與剪輯腳本，CLI 輸出改變時可以重錄。
+
+### Changed
+
+- **新建或新增連線必須明確命名。** `init` 未提供 `--conn-name` 時會在互動式
+  終端機主動詢問名稱，不再代填 `default`；空白回答會說明並再次詢問，取消或
+  結束提示不會寫入；明確傳入空白名稱則在任何模式都報錯。非 TTY、
+  `--no-interactive` 或完整 env-reference 自動非互動
+  模式缺少名稱時，會在連線測試、設定及憑證寫入前報錯。`--name` 仍是資料庫名，
+  明確指定 `--conn-name default` 仍合法。單純 `init` 與明確 `--config` 都改用
+  具名 v2 新建，既有 v1 讀取與具名匯入保留。全新 registry 仍以第一條具名連線
+  為預設，追加連線保留既有 default/no-default；同名覆寫確認及 `--force` 保護
+  維持不變（#212）。
+
+- **v2 可以不設定預設連線。** 省略 `default` 即可要求每次透過 `--use` 或
+  `DBCLI_CONNECTION` 明確選取；未選取時會在連線前失敗，列出可用名稱而不洩漏
+  端點或憑證。新增 `dbcli use --unset`，透過既有核准與 integrity record 保護
+  流程清除預設值，重複執行也安全。刪除預設連線會清除預設值，不再依 JSON
+  順序改選另一條；仍禁止刪除最後一條連線。清單與 doctor 支援無預設狀態，
+  初始化與 v1 遷移建立預設值的方式、selector 優先序與正式環境防護不變（#212）。
+  若新增連線會匯入帶有自訂 `envFile`（非 `.env.local`）的舊版直接專案 v2
+  設定，`init` 會在寫入前拒絕並保留原檔，須先由管理員完成 home storage 遷移。
+
+- **Bun 最低版本從 1.3.3 提高到 1.4.0。** `mongodb@7.2.0` 依賴 `bson: "^7.2.0"`，
+  不帶 lockfile 的使用者安裝會解析到 bson 7.3+。bson 7.3.0 起，`ObjectId` 載入時會呼叫
+  `v8.startupSnapshot.isBuildingSnapshot()`，Bun 1.3.x 對此丟出
+  `NotImplementedError: node:v8 isBuildingSnapshot is not yet implemented in Bun.`，
+  任何碰到 MongoDB 的指令都會失敗。實測 Bun 1.3.3 與 1.3.10–1.3.14 都會失敗，
+  1.4.0–1.4.3 都正常。本 repo 的 `bun.lock` 把 bson 鎖在 7.2.0，所以 CI 的 1.3.3 那一列
+  從來沒碰到這個問題。`engines.bun`、CI 最低版本、postinstall 提示、`doctor` 的預設值與
+  使用者文件都改為 1.4.0。
+
+- **audit gate 可以帶有期限、附理由的豁免。** `scripts/audit-exemptions.json` 逐筆列出
+  GHSA id、套件、理由與 UTC 到期日。未到期的項目轉成 `bun audit --ignore` 參數，每次執行
+  都印出來；過期或格式錯誤的項目讓 gate 失敗，所以豁免不會悄悄變成永久。第一筆豁免
+  GHSA-vfj7-8cjw-p6xm（`braces` <= 3.0.3，沒有修正版，只經由建置期的 tailwindcss 引入）
+  到 2026-11-30。決定記在 ADR-0042。
+
+- **發布流程改由版本 tag 驅動。** 合併發布準備 PR 後才在 `main` 建立 `vX.Y.Z`；
+  工作流程核對版本與來源、啟動測試資料庫並執行 `make verify`，通過後等待
+  `npm-publish` 環境審批，再透過 npm trusted publishing 發布附 provenance 的套件，
+  最後從本檔對應版本章節建立 GitHub Release。須先完成 trusted publisher 與審批環境
+  設定（#214）。
+
+### Fixed
+
+- **Elasticsearch 整合驗證不再把未執行的 roundtrip 算成通過。** 測試的 DOM preload
+  同時保留 Bun 的 `fetch`、`AbortController` 與 `AbortSignal`，避免混用不同實作而在
+  HTTP 送出前失敗。有服務時的連線／初始化錯誤會讓測試失敗；只有明確停用整合測試，
+  或本機未要求必備服務且 TCP 端點不存在時，才記為真正的 skip。CI 必須實跑建立索引、
+  寫入、refresh、查詢、schema 斷言與清理，完成後才輸出 roundtrip 驗證紀錄。
+  這是測試基礎設施修正，沒有改變發布套件的 adapter 行為。
+
+- **PostgreSQL 的 schema 重新回報主鍵、索引與外鍵欄位。** 對 `pg_attribute.attname` 做
+  `array_agg` 得到的是 `name[]`，node-postgres 把它當字串回傳，schema 因此丟掉了這些欄位，
+  寫入閘門也就拒絕了每一筆結構化寫入。改為先轉成 `text`。
+
+- **PostgreSQL 的 enum 欄位重新回報 `enumValues`。** `pg_enum.enumlabel` 的 `array_agg`
+  同樣是 `name[]`，以相同方式修正。
+
+- **SQL 引擎的 `update` 先檢查權限等級再連線。** 與 Redis、MongoDB 分支以及 `delete`
+  一致：query-only 連線現在因為權限不足被拒，而不是被寫入閘門擋下；權限檢查也排在
+  executor 的黑名單檢查之前。
+
+### Security
+
+- **兩筆開發依賴的安全公告。** `source-map-js` 1.2.1 → 1.2.2（high，GHSA-68fv-2mgg-jv7q），
+  修正版在 `postcss` 的 `^1.2.1` 範圍內，只更新 lockfile。`postcss-selector-parser`
+  （moderate，GHSA-rj75-hqrm-r3gf）只在 7.1.6 修正，但 `tailwindcss@3.4.19` 與
+  `postcss-nested@6.2.0` 都要求 6.x，因此依 ADR-0042 在 `scripts/audit-exemptions.json`
+  豁免到 2026-11-30：它只在建置時解析本 repo 自己的樣式表，執行期與使用者輸入都碰不到。
+
 ## [9.1.2] - 2026-10-01
 
 一個開發依賴的安全公告、工作規格協定從 ForgeFlow 換成 Warrant，以及三個讓測試與建置

package/README.dev.md

@@ -6,7 +6,7 @@ Scoped package: **`@carllee1983/dbcli`**. All `npm` / `npx` examples below use t
 
 ### Pre-Publication Checklist
 
-Before running `npm publish`:
+Before tagging a release (the tag triggers `npm publish` in CI):
 
 1. **Verify build is clean:**
    ```bash
@@ -34,7 +34,7 @@ Before running `npm publish`:
 
 3. **Update version in package.json:**
    ```bash
-   npm version minor   # bumps version + creates git tag (in this repo)
+   npm version minor --no-git-tag-version   # bumps version without creating a tag
    # OR edit the "version" field in package.json by hand
    ```
 
@@ -53,13 +53,26 @@ Before running `npm publish`:
 
 ### Publication
 
-Publication uses the `prepublishOnly` script in `package.json`:
+Publication is tag-driven. After the release PR is merged, tag `main` and push the tag:
 
 ```bash
-npm publish
+git checkout main && git pull
+git tag vX.Y.Z
+git push origin vX.Y.Z
 ```
 
-What runs (conceptually):
+`.github/workflows/release.yml` then runs `check-tag` (tag equals `v` + `package.json` version, commit is an ancestor of `origin/main`), `verify` (`docker-compose.test.yml` databases, `bun run services:check`, `make verify`, attestation artifact), `publish` (waits for approval in the `npm-publish` environment, then `npm publish` through npm trusted publishing with provenance, no stored token), and `github-release` (GitHub Release whose notes are the `## [X.Y.Z]` section of `CHANGELOG.md`, extracted by `scripts/changelog-section.ts`).
+
+**One-time owner setup:**
+
+- On npmjs.com, add a trusted publisher for `@carllee1983/dbcli`: owner `CarlLee1983`, repository `dbcli`, workflow `release.yml`, environment `npm-publish`, allowed action `npm publish`. npm expires a configuration that has not published within 2 days.
+- In GitHub repository Settings → Environments, create `npm-publish` with a required reviewer, and set "Deployment branches and tags" to "Selected branches and tags" with only a tag rule `v*.*.*`.
+
+**Recovery:** if `check-tag` or `verify` fails, nothing was published; fix the cause, delete the tag remotely and locally (`git push origin :refs/tags/vX.Y.Z` and `git tag -d vX.Y.Z`), and tag again. If `publish` succeeded but `github-release` failed, use "Re-run failed jobs", not "Re-run all jobs" (which would fail at `npm publish` because the version exists). Only plain `vX.Y.Z` tags are accepted; pre-release and build tags are rejected.
+
+**Emergency fallback only** (workflow cannot run): from a clean checkout of the tagged commit on `main`, `npm login` and `npm publish` locally. That ships without provenance.
+
+What `npm publish` does (in CI or locally):
 
 1. **`prepublishOnly`:** `bun run build` — rebuilds `dist/cli.mjs` from `src/cli.ts` via `scripts/build.ts`.
 2. **Tarball** — paths from the **`files`** field in `package.json`, further filtered by **`.npmignore`**. (Some npm versions also merge in extra root `README*` files; use dry-run to see exactly what will ship.)
@@ -106,7 +119,7 @@ Then ship a patch version with the fix. Prefer **deprecate** over **unpublish**
 
 - **`files` (in `package.json`):** Publishes `dist/`, `assets/`, `README.md`, `CHANGELOG.md`, `LICENSE`. The `assets/` tree is required for `dbcli skill` to copy bundled `SKILL.md` / `reference.md` from the installed package.
 - **`prepublishOnly`:** `bun run build` so `dist/cli.mjs` matches current source.
-- **`engines`:** Declares `bun >= 1.3.3` only. `node` was removed because the published bundles cannot run on Node: `dist/cli.mjs` dynamic-imports the extensionless `./cli-runtime` (Bun's resolver appends `.mjs`, Node's does not) and `dist/core.mjs` calls Bun globals. `tests/integration/runtime-contract.test.ts` fails if `engines.node` comes back without the bundles being fixed to match, and if `dist/agent-core.mjs` — the one entry point that is Node-importable — regresses. See `docs/adr/ADR-0008-dbcli-is-a-bun-program-and-engines-says-so.md`.
+- **`engines`:** Declares `bun >= 1.4.0` only. `node` was removed because the published bundles cannot run on Node: `dist/cli.mjs` dynamic-imports the extensionless `./cli-runtime` (Bun's resolver appends `.mjs`, Node's does not) and `dist/core.mjs` calls Bun globals. `tests/integration/runtime-contract.test.ts` fails if `engines.node` comes back without the bundles being fixed to match, and if `dist/agent-core.mjs` — the one entry point that is Node-importable — regresses. See `docs/adr/ADR-0008-dbcli-is-a-bun-program-and-engines-says-so.md`.
 - **Shebang:** `scripts/build.ts` prepends `#!/usr/bin/env bun` to `dist/cli.mjs`; the `bin` field in `package.json` points at that file.
 - **`exports`:** `./core` and `./agent-core` only — there is deliberately no `.` entry. It used to point at `dist/cli.mjs`, and `src/cli-runtime.ts` calls `outputHelp()` and `parseAsync(process.argv)` at module top level, so importing the package ran the CLI against the host's argv and never returned. `bin` does not resolve through `exports`, so the executable is unaffected. `tests/integration/runtime-contract.test.ts` pins both the absence of `.` and the side effect that justifies it.
 - **`postinstall`:** `scripts/postinstall-check-bun.mjs` reports a missing Bun — npm ignores `engines.bun`, so this is the only signal an npm-only machine gets before `dbcli` refuses to start. The command is `bun … || node …` so it runs under whichever runtime is present: Bun-only machines have no `node` to invoke it with, and a hard `node` dependency there would break the primary install path. It must **not** end in `|| exit 0`; v1.55.0 shipped with that mask and npm, which hides lifecycle output unless a script fails, therefore showed nothing at all. On a global install (`npm_config_global === 'true'`) a missing Bun exits 1, so the reason is printed and npm rolls the `bin` back; a dependency install only warns, because that is the `./agent-core` consumer. Both outcomes are pinned in `tests/integration/runtime-contract.test.ts`.

package/README.md

@@ -6,6 +6,10 @@ A unified database CLI tool that enables AI agents (Claude Code, Gemini, Copilot
 
 **Core Value:** AI agents can safely and intelligently access project databases through a single, permission-controlled CLI tool with sensitive data protection.
 
+[![Watch a Claude Code agent use dbcli: the blacklisted column is omitted and a write on a query-only connection is refused](docs/assets/demo/dbcli-agent-demo-thumb.webp)](https://carllee1983.github.io/dbcli/dbcli-intro.en.html#safety)
+
+*Watch a real session (42 s): the blacklist hides a sensitive column, and the agent's write is refused on a query-only connection.*
+
 > **Security update:** `dbcli init` now writes only a small project binding stub into `./.dbcli/config.json`. The full connection configuration is stored under `~/.config/dbcli/projects/<project-id>/config.json`, so sensitive settings do not live inside the project workspace by default.
 
 ## Internationalization (i18n)
@@ -43,7 +47,7 @@ bun install -g @carllee1983/dbcli
 ```
 
 **dbcli runs on Bun.** npm and npx are supported as distribution channels, but the
-installed `dbcli` executable requires Bun 1.3.3+ on your `PATH` — install it first with
+installed `dbcli` executable requires Bun 1.4.0+ on your `PATH` — install it first with
 `curl -fsSL https://bun.sh/install | bash`. Only the `./agent-core` subpath export is
 importable from a plain Node process.
 
@@ -224,7 +228,7 @@ dbcli extends its unified interface to Redis and Elasticsearch, providing consis
 
 ```bash
 # Connect to Redis
-dbcli init --system redis --host localhost --port 6379
+dbcli init --conn-name local --system redis --host localhost --port 6379
 
 # List keys (uses SCAN)
 dbcli list
@@ -241,7 +245,7 @@ dbcli query "HGETALL user:1"
 
 ```bash
 # Connect to Elasticsearch
-dbcli init --system elasticsearch --host localhost --port 9200
+dbcli init --conn-name local --system elasticsearch --host localhost --port 9200
 
 # List indices and document counts
 dbcli list
@@ -264,7 +268,13 @@ The project `.dbcli` directory now acts as a binding + cache layer. The actual c
 
 ### Initializing Named Connections
 
-To create a named connection, use the `--conn-name` option during `init`. You can also specify a custom `.env` file for that connection.
+Every new or additional connection needs a nonblank connection name. Pass `--conn-name <name>`, or run `dbcli init` in an interactive terminal to be asked for one. The name prompt has no suggested `default`; empty or whitespace-only answers explain the requirement and prompt again. Cancelling or ending the name prompt stops before any connection test or configuration/credential write. An explicit nonblank `--conn-name` skips this prompt, and `--conn-name default` is valid. An explicitly blank `--conn-name` is an error in every mode, before connection tests or writes. `--name` still means the database name (the logical DB index for Redis), never the connection name.
+
+Without a TTY, with `--no-interactive`, or when `--use-env-refs` plus all five `--env-*` options automatically disables interaction, a missing or blank `--conn-name` fails with guidance to supply it, before database access or configuration/credential writes. Complete credentials, `--name`, `--env-file`, and `--force` do not supply a connection name.
+
+New initialization always creates named v2 configuration, including plain `init` and explicit `--config` paths; it no longer creates an unnamed v1 configuration. Existing v1 configurations remain readable and their established named v2 import is retained. The first explicitly named connection is still the default in a new registry; adding a connection preserves an existing registry's default or no-default state. An explicitly chosen duplicate name still requires interactive overwrite confirmation or `--force`; a noninteractive duplicate without `--force`, or a declined confirmation, leaves files untouched. `--remove` and `--rename` do not ask for a new connection name.
+
+Use `--env-file` to specify a custom `.env` file for a named connection:
 
 ```bash
 # Add a staging connection using .env.staging
@@ -300,6 +310,9 @@ dbcli use staging
 # Show the current default connection
 dbcli use
 
+# Clear the default without removing any connection (v2)
+dbcli use --unset
+
 # Remove a connection
 dbcli init --remove staging
 
@@ -307,6 +320,21 @@ dbcli init --remove staging
 dbcli init --rename staging:production
 ```
 
+V2 configurations may omit `default`; when present, it must be a nonempty name
+of an existing connection, not `null` or `""`. Without a default, commands that
+need a connection require `--use` or `DBCLI_CONNECTION`; otherwise they fail
+before database access and list available names without endpoints or credentials.
+`dbcli use` describes this state, text lists mark no default, and JSON inventory
+uses `isDefault: false` for every connection. `doctor` accepts this configuration;
+its connection checks still require a selector, such as `dbcli --use staging doctor`.
+
+Removing the current default clears it and reports that change, without choosing
+a replacement. Other removals preserve the default or its absence; deleting the
+last connection is refused without writing. Renaming preserves a missing default
+or updates its name as needed. A new registry defaults to its first explicitly
+named connection; adding another preserves the existing default or no-default
+state. Existing v1 imports and production safeguards remain unchanged.
+
 ### Using a Specific Connection Temporarily
 
 You can use the `--use <name>` global flag, the supported command-level form, or `DBCLI_CONNECTION` to execute against a specific connection without changing the default. Selection precedence is explicit `--use`, then `DBCLI_CONNECTION`, then the configured default. A selector is rejected for legacy v1 single-connection configuration instead of being silently ignored.
@@ -350,23 +378,23 @@ dbcli init [OPTIONS]
 - `--port <port>` — Database port
 - `--user <user>` — Database user
 - `--password <pass>` — Database password
-- `--name <db>` — Database name
+- `--name <db>` — Database name, distinct from the required `--conn-name`
 - `--permission <level>` — Permission level: `query-only`, `read-write`, `data-admin`, `admin`
 - **MongoDB only:** `--uri <uri>` — full connection URI (`mongodb://…` or `mongodb+srv://…`); `--auth-source <db>` — auth database (default `admin` when using user/password)
 - `--use-env-refs` — Store environment variable references instead of actual values in config
 - `--skip-test` — Skip connection test
 - `--no-interactive` — Non-interactive mode (requires all options)
-- `--force` — Overwrite existing config without confirmation
+- `--force` — Overwrite the explicitly named existing connection without confirmation
 
 **Options (Multi-connection v2):**
-- `--conn-name <name>` — Create a named connection (e.g., `staging`, `prod`)
+- `--conn-name <name>` — Required connection name (e.g., `staging`, `prod`); prompts when omitted in an interactive terminal
 - `--env-file <path>` — Load credentials from a specific `.env` file for this connection
 - `--remove <name>` — Remove a named connection from the config
 - `--rename <old:new>` — Rename an existing connection (format: `old:new`)
 
 **Behavior:**
 - Reads `.env` file if present (auto-fills DATABASE_URL, DB_* variables)
-- Prompts for missing values (host, port, user, password, database name, permission level)
+- Obtains a nonblank connection name first; interactive terminals then prompt for missing values (host, port, user, password, database name, permission level)
 - Creates a project binding stub in `.dbcli/config.json` and stores the full config under `~/.config/dbcli/projects/<project-id>/`
 - Tests database connection before saving
 
@@ -380,7 +408,7 @@ dbcli init --conn-name staging --env-file .env.staging
 dbcli init --conn-name prod --env-file .env.production --use-env-refs
 
 # Store env var references (non-interactive)
-dbcli init --use-env-refs --system mysql \
+dbcli init --conn-name local --use-env-refs --system mysql \
   --env-host DB_HOST --env-port DB_PORT \
   --env-user DB_USER --env-password DB_PASSWORD \
   --env-database DB_DATABASE \
@@ -400,6 +428,17 @@ dbcli use [connection-name] [OPTIONS]
 
 **Options:**
 - `--list` — List all connections and show the current default
+- `--unset` — Clear the saved default; succeeds if already absent
+- `--format <text|json>` — Select inventory output format
+- `--confirm-production <name>` — Repeat the exact name to set a production default
+
+`--unset` rejects a connection name, `--list`, `--confirm-production`, or
+`--format json` in the same invocation without writing. It never converts or
+overwrites v1 and uses the same approved, integrity-protected write path as
+switching the default; it is blocked in agent mode. Selection still follows
+`--use` > `DBCLI_CONNECTION` > saved default. Conflicting root/command selectors
+and blank CLI selectors fail; blank environment selectors are ignored. See
+[Connection Management](docs/user/en/index.md#connection-management) for details.
 
 **Examples:**
 ```bash
@@ -1329,7 +1368,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 
 ### Platform-Specific Setup
 
-Every flow below assumes Bun 1.3.3+ on your `PATH`: the installed `dbcli` executable runs under Bun regardless of which package manager fetched it.
+Every flow below assumes Bun 1.4.0+ on your `PATH`: the installed `dbcli` executable runs under Bun regardless of which package manager fetched it.
 
 #### Claude Code (Anthropic)
 
@@ -1658,7 +1697,7 @@ chmod +x dist/cli.mjs
 
 ### Runtime
 
-- **Bun:** 1.3.3+ — required. The published bundles use Bun APIs and Bun module
+- **Bun:** 1.4.0+ — required. The published bundles use Bun APIs and Bun module
   resolution; `dbcli` does not run on Node.
 - **Node.js:** only for the `./agent-core` subpath export, which is Node-importable
   (18.0.0+). `npm install -g` / `npx` work as distribution channels but still shell out