@carllee1983/dbcli 1.5.2 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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).
 
+## [1.6.0] - 2026-04-23
+
+### Added
+
+- **Full MongoDB Support**: Extended all core operations to support MongoDB.
+  - Data operations: `query`, `insert`, `update`, `delete`.
+  - Safeguards: Integrated `blacklist` protection and `query-size-guard` for MongoDB commands.
+  - Discovery: Implemented schema inspection for MongoDB collections.
+  - Diagnostics: Added comprehensive MongoDB environment and connection diagnostics to `dbcli doctor`.
+- **Improved AI Skill Installation**: `dbcli skill --install` now deploys both `SKILL.md` (high-level workflow) and `reference.md` (full command syntax and examples) to target platforms (Claude Code, Gemini CLI, Copilot, Cursor).
+- **Security model enhancement**: `dbcli init` now defaults to a more secure storage model, placing sensitive connection details in `~/.config/dbcli/` rather than the local project workspace.
+
+### Changed
+
+- **Documentation Refactor**: Updated and synchronized documentation (README, README.zh-TW, SKILL.md) to reflect full MongoDB capabilities and first-step walkthroughs.
+
 ## [1.5.2] - 2026-04-22
 
 ### Fixed

package/README.dev.md

@@ -1,5 +1,7 @@
 # Development Guide
 
+Scoped package: **`@carllee1983/dbcli`**. All `npm` / `npx` examples below use this name.
+
 ## npm Publishing Process
 
 ### Pre-Publication Checklist
@@ -9,115 +11,110 @@ Before running `npm publish`:
 1. **Verify build is clean:**
    ```bash
    bun run build
-   ls -lh dist/cli.mjs  # Should be 1.0-1.5MB
+   ls -lh dist/cli.mjs   # expect a few MB (bundled CLI + dependencies)
    ```
 
-2. **Verify test suite passes:**
+2. **Verify tests pass (pick one):**
    ```bash
-   bun test --run unit/
+   # Fast path: unit + core only (matches CI-style smoke)
+   bun run test:unit
+
+   # Full suite (Bun test runner)
+   bun test
    ```
 
-   For live database integration tests, use an explicit config path if needed:
+   For live database integration tests, set an explicit config if needed:
    ```bash
    LIVE_DB_CONFIG_PATH=/path/to/.dbcli bun test tests/integration/live-db.test.ts
    ```
 
    If no live config is available, `tests/integration/live-db.test.ts` skips
-   instead of falling back to the default PostgreSQL configuration.
+   instead of falling back to the default PostgreSQL configuration. Use
+   `SKIP_INTEGRATION_TESTS=true` to skip integration tests when running a broad `bun test`.
 
 3. **Update version in package.json:**
    ```bash
-   npm version minor  # Updates package.json version + creates git tag
-   # OR manually update "version" field in package.json
+   npm version minor   # bumps version + creates git tag (in this repo)
+   # OR edit the "version" field in package.json by hand
    ```
 
 4. **Verify package contents (dry run):**
    ```bash
    npm pack --dry-run
-   # Should list only: dist/*, README.md, CHANGELOG.md, package.json
    ```
+   Expect **`dist/`** (at least `cli.mjs`), **`assets/`** (e.g. `SKILL.md`, `reference.md` for `dbcli skill`), **`README.md`**, **`CHANGELOG.md`**, **`LICENSE`**, and **`package.json`**. There must be **no** `src/`, `tests/`, or `node_modules/`. The listing may also include other root `README*.md` files (npm can still pack them even when `files` is set); dev-only readmes are listed in **`.npmignore`** — re-check with dry-run if you add or remove docs.
 
 5. **Check package size:**
    ```bash
    npm pack
-   ls -lh dbcli-*.tgz  # Must be < 5MB
-   rm dbcli-*.tgz      # Cleanup
+   ls -lh carllee1983-dbcli-*.tgz   # compressed tarball (typically well under 5MB)
+   rm carllee1983-dbcli-*.tgz       # cleanup
    ```
 
 ### Publication
 
-The publication process is automated by npm hooks:
+Publication uses the `prepublishOnly` script in `package.json`:
 
 ```bash
 npm publish
 ```
 
-This invokes (in order):
-1. `prepublishOnly` hook: Runs `bun run build` → ensures fresh dist/cli.mjs
-2. npm creates tarball with `files` whitelist → only intended files included
-3. npm applies `.npmignore` rules → additional safety layer
-4. npm publishes to registry
+What runs (conceptually):
 
-**Note:** The build CANNOT be skipped. If you try to publish with a stale dist/cli.mjs, prepublishOnly will rebuild it.
+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.)
+3. **Registry** — with `"publishConfig": { "access": "public" }`, the scoped package is published as **public**.
+
+A failed `bun run build` will fail the publish, so you should not ship a stale `dist/` from a previous local build.
 
 ### Verification (Post-Publication)
 
 After publishing:
 
-1. **Test installation globally:**
+1. **Global install:**
    ```bash
-   npm install -g dbcli
-   which dbcli  # Should show: /usr/local/bin/dbcli or similar
+   npm install -g @carllee1983/dbcli
+   which dbcli
    dbcli --version
    ```
 
-2. **Test zero-install (npx):**
+2. **Zero-install (npx / bunx):**
    ```bash
-   cd /tmp
-   mkdir test-dbcli && cd test-dbcli
-   npx dbcli --help
-   npx dbcli --version
+   cd /tmp && mkdir -p test-dbcli && cd test-dbcli
+   npx @carllee1983/dbcli --help
+   npx @carllee1983/dbcli --version
+   # or: bunx @carllee1983/dbcli --help
    ```
 
-3. **Test Windows installation (if available):**
-   - On Windows machine: `npm install -g dbcli`
-   - Verify: `dbcli --help` and `dbcli --version` work
-   - npm creates .cmd wrapper automatically; no manual .cmd needed
+3. **Windows (if available):** `npm install -g @carllee1983/dbcli`, then `dbcli --help`. npm creates the `.cmd` stub for the `bin` entry; no hand-written `.cmd` in the repo.
 
 ### Rollback (if needed)
 
-If critical bug discovered after publishing:
+If a bad release must be mitigated:
 
 ```bash
-npm unpublish dbcli@VERSION  # Remove specific version
-# OR
-npm deprecate dbcli@VERSION "Critical bug; use VERSION-1"  # Mark as deprecated
+npm unpublish @carllee1983/dbcli@<VERSION>
+# and/or
+npm deprecate @carllee1983/dbcli@<VERSION> "Reason; use <SAFE_VERSION> instead"
 ```
 
-Then publish a patch fix.
+Then ship a patch version with the fix. Prefer **deprecate** over **unpublish** when consumers may already depend on the version.
 
 ### Configuration Details
 
-- **files whitelist (package.json):** Restricts tarball to source only
-  - Includes: dist/, README.md, CHANGELOG.md, LICENSE
-  - Excludes: src/, tests/, node_modules/, .git/, docs/
-- **prepublishOnly hook:** Ensures build runs before pack
-  - Prevents stale binaries from being published
-  - Runs automatically; cannot be skipped with --no-scripts
-- **engines field:** Declares minimum Node >=18.0.0, Bun >=1.3.3
-  - npm warns if consumer's environment is too old
-- **Cross-platform support:** Shebang `#!/usr/bin/env bun` works on all platforms
-  - macOS/Linux: Direct shebang execution
-  - Windows: npm creates .cmd wrapper automatically (no manual creation needed)
-- **Live integration tests:** `tests/integration/live-db.test.ts` reads `.dbcli/config.json`
-  by default or `LIVE_DB_CONFIG_PATH` when you need to point at another config
-  directory. Set `SKIP_INTEGRATION_TESTS=true` to skip all integration tests.
+- **`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 `node >= 18.0.0` and `bun >= 1.3.3` so npm can warn on outdated runtimes.
+- **Shebang:** `scripts/build.ts` prepends `#!/usr/bin/env bun` to `dist/cli.mjs`; the `bin` field in `package.json` points at that file.
+- **Live DB tests:** `tests/integration/live-db.test.ts` uses project `.dbcli` by default or `LIVE_DB_CONFIG_PATH` when you point at another config directory. Set `SKIP_INTEGRATION_TESTS=true` to skip all integration tests.
+
+For contributor workflow and release process, see **[CONTRIBUTING.md](./CONTRIBUTING.md)** and the main **[README.md](./README.md)** Development section.
 
 ### Troubleshooting
 
-| Issue | Solution |
-|-------|----------|
-| prepublishOnly fails (build error) | Fix TypeScript errors in src/, run `bun test --run unit/`, retry `npm publish` |
-| Package size > 5MB | Run `bun build --metafile=meta.json`, analyze output, remove unused dependencies |
-| Windows installation fails | Verify shebang is `#!/usr/bin/env bun` in dist/cli.mjs; npm's .cmd wrapper will be created automatically |
-| npx hangs or times out | Run `npm cache clean --force`, retry `npx dbcli` |
+| Issue | What to do |
+|-------|------------|
+| `prepublishOnly` / build fails | Fix TypeScript or build errors, run `bun run test:unit`, then `bun run build` again. |
+| Tarball unexpectedly large or bloated | Inspect the bundle: e.g. `bun build ./src/cli.ts --outfile=dist/cli.mjs --target=bun --metafile=meta.json` and review the metafile; trim dependencies or dev-only code paths. |
+| Windows: `dbcli` not found after global install | Confirm PATH includes npm’s global `bin`; reinstall `npm i -g @carllee1983/dbcli`. |
+| `npx` download slow or cache weird | `npm cache clean --force` and retry `npx @carllee1983/dbcli --version`. |

package/README.md

@@ -6,6 +6,8 @@ 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.
 
+> **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)
 
 dbcli supports multiple languages via the `DBCLI_LANG` environment variable:
@@ -76,6 +78,9 @@ When `dbcli` is not on your `PATH`, use `bun run src/cli.ts <subcommand> ...` (s
 # Initialize project with database connection
 dbcli init
 
+# Interactive shell (SQL + dbcli commands, tab completion)
+dbcli shell
+
 # List available tables
 dbcli list
 
@@ -85,6 +90,9 @@ dbcli schema users
 # Query data
 dbcli query "SELECT * FROM users"
 
+# Preview schema DDL (dry-run by default; add --execute to apply)
+dbcli migrate create posts --column "id:serial:pk" --column "title:varchar(200):not-null"
+
 # Generate AI agent skill
 dbcli skill --install claude
 ```
@@ -112,6 +120,8 @@ For MongoDB, `list` and `query` operate on the database configured for the conne
 
 dbcli supports multiple named database connections within a single project. This is useful for managing different environments (development, staging, production) or multiple databases.
 
+The project `.dbcli` directory now acts as a binding + cache layer. The actual connection config is stored in `~/.config/dbcli/projects/<project-id>/`, which keeps sensitive settings out of the workspace by default.
+
 ### 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.
@@ -170,13 +180,14 @@ dbcli init [OPTIONS]
 ```
 
 **Options (Basic):**
-- `--system <type>` — Database system: `postgresql`, `mysql`, `mariadb`
+- `--system <type>` — Database system: `postgresql`, `mysql`, `mariadb`, `mongodb`
 - `--host <host>` — Database host
 - `--port <port>` — Database port
 - `--user <user>` — Database user
 - `--password <pass>` — Database password
 - `--name <db>` — Database 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)
@@ -191,7 +202,7 @@ dbcli init [OPTIONS]
 **Behavior:**
 - Reads `.env` file if present (auto-fills DATABASE_URL, DB_* variables)
 - Prompts for missing values (host, port, user, password, database name, permission level)
-- Creates `.dbcli` JSON config file in project root
+- 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
 
 **Examples:**
@@ -241,6 +252,8 @@ dbcli use --list
 
 > **`--use-env-refs`:** When enabled, the config stores environment variable names (e.g., `{"$env": "DB_HOST"}`) instead of actual values. This avoids writing sensitive credentials into the config file, making it suitable for multi-environment deployments and CI/CD pipelines. At connection time, dbcli automatically reads the actual values from the referenced environment variables.
 
+> **Storage model:** The project `.dbcli` directory is now a binding + cache layer, not the canonical home for secrets. If you inspect `./.dbcli/config.json`, you should only see the binding metadata; the full config lives in the home storage path shown above.
+
 ---
 
 #### `dbcli list`
@@ -489,8 +502,8 @@ dbcli skill --install cursor          # Install to Cursor IDE
 ```
 
 **Behavior:**
-- Ships a canonical **`assets/SKILL.md`** in the package (single source of truth)
-- Prints that file to **stdout**, writes it with **`--output`**, or copies it to a **platform-specific path** with **`--install`**
+- Ships canonical **`assets/SKILL.md`** + **`assets/reference.md`** (single source of truth: concise skill + long command reference)
+- Prints the skill to **stdout**, writes it with **`--output`**, or copies it to a **platform-specific path** with **`--install`**
 - Actual database access is still enforced by your `.dbcli` permission level and blacklist — the skill text describes the full CLI surface
 
 **Examples:**
@@ -592,12 +605,8 @@ dbcli check users
 dbcli check orders --checks nulls,orphans --format table
 # Scan all tables
 dbcli check --all
-```
-
----
 
-**Examples:**
-```bash
+# Table view + all-tables with selected checks
 dbcli check orders --format table
 dbcli check --all --checks nulls,duplicates --format json
 ```
@@ -690,7 +699,7 @@ dbcli upgrade --check           # Only check, do not upgrade
 
 **Background checks (stderr, skipped when `--quiet` or for `upgrade` / `skill`):**
 - **CLI version:** dbcli checks the npm registry (cached, about once per 24 hours). If a newer package exists, a one-line hint prints after normal command output.
-- **Installed skills:** If you used `dbcli skill --install <platform>`, dbcli compares each installed copy to the bundled `assets/SKILL.md`. When they differ, a short reminder lists which platforms to re-install (`dbcli skill --install <platform>`). Run `dbcli upgrade` to see the same skill status together with version info.
+- **Installed skills:** If you used `dbcli skill --install <platform>`, dbcli compares each installed primary skill file (`SKILL.md` or `dbcli.mdc`) to the bundled `assets/SKILL.md`. When they differ, a short reminder lists which platforms to re-install (`dbcli skill --install <platform>`). Run `dbcli upgrade` to see the same skill status together with version info. Re-installing also refreshes `reference.md` next to the skill.
 
 #### `dbcli shell`
 
@@ -950,7 +959,7 @@ A Query-only agent cannot write to any table, and also cannot read blacklisted t
 
 ## AI Integration Guide
 
-dbcli ships AI-consumable skill documentation (`assets/SKILL.md`) and can copy it into your favorite AI development tool directories.
+dbcli ships AI-consumable skill files (`assets/SKILL.md` and `assets/reference.md`) and can copy them into your favorite AI tool directories.
 
 ### Quick Start
 
@@ -982,7 +991,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 4. Restart Claude Code extension
 5. In Claude Code chat, ask: "Show me the database schema" or "Query active users"
 
-**Skill location:** `~/.claude/skills/dbcli/SKILL.md`
+**Skill location:** `~/.claude/skills/dbcli/` (SKILL.md + reference.md)
 
 ---
 
@@ -994,7 +1003,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 4. Start Gemini: `gemini start`
 5. In chat, request: "Query the users table" or "Show database tables"
 
-**Skill location:** `~/.gemini/skills/dbcli/SKILL.md`
+**Skill location:** `~/.gemini/skills/dbcli/` (SKILL.md + reference.md)
 
 ---
 
@@ -1006,7 +1015,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 4. Install Copilot CLI: `npm install -g @github-next/github-copilot-cli`
 5. Use copilot preview: `copilot --help` and explore dbcli integration
 
-**Skill location:** `.github/skills/dbcli/SKILL.md` under the **current working directory** when you run `dbcli skill --install copilot` (typically your project root).
+**Skill location:** `.github/skills/dbcli/` (SKILL.md + reference.md) when you run `dbcli skill --install copilot` in your project root.
 
 ---
 
@@ -1018,7 +1027,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 4. Open Cursor editor
 5. Use Cursor's Composer: "Insert a new user" or "Export user data"
 
-**Skill location:** `.cursor/rules/dbcli.mdc` under the **current working directory** when you run `dbcli skill --install cursor` (project-level Cursor rule).
+**Skill location:** `.cursor/rules/dbcli.mdc` (summary + workflows) and `.cursor/skills/dbcli/reference.md` (full command flags and examples) under the **current working directory** when you run `dbcli skill --install cursor`.
 
 ---
 
@@ -1045,7 +1054,7 @@ dbcli skill --install claude
 
 ### Updating the skill after upgrades
 
-The markdown installed by `dbcli skill` is the bundled **`assets/SKILL.md`**. It is **not** regenerated from your live config. When you **upgrade dbcli** or the bundled skill changes, re-copy it to each platform you use:
+`dbcli skill` copies the bundled **`assets/SKILL.md`** (and for `--install`, **`assets/reference.md`** next to it). It is **not** regenerated from your live config. When you **upgrade dbcli** or the bundled skill changes, re-copy it to each platform you use:
 
 ```bash
 dbcli skill --install claude
@@ -1053,7 +1062,7 @@ dbcli skill --install gemini
 # ... etc.
 ```
 
-If an installed copy is older than the bundled file, dbcli prints a **stderr reminder** after most commands (see **`dbcli upgrade`**). Changing **permission level** or **blacklist** in `.dbcli` affects what the CLI allows at runtime — keep project context (e.g. `dbcli status`, `dbcli blacklist list`) in mind for agents even though the skill text lists the full command set.
+If an installed primary skill file is older than the bundled `assets/SKILL.md`, dbcli prints a **stderr reminder** after most commands (see **`dbcli upgrade`**). Changing **permission level** or **blacklist** in `.dbcli` affects what the CLI allows at runtime — keep project context (e.g. `dbcli status`, `dbcli blacklist list`) in mind for agents even though the skill text lists the full command set.
 
 ---
 
@@ -1230,6 +1239,7 @@ chmod +x dist/cli.mjs
 - **PostgreSQL:** 12.0+
 - **MySQL:** 8.0+
 - **MariaDB:** 10.5+
+- **MongoDB:** 4.4+ (query and collection listing via `mongodb://` and `mongodb+srv://`; see **MongoDB Atlas / SRV Connections** earlier in this document)
 
 ### Runtime
 

package/README.zh-TW.md

@@ -6,6 +6,8 @@
 
 **核心價值：** AI 代理可透過單一、具權限控管的 CLI 工具，在敏感資料保護下安全且智慧地存取專案資料庫。
 
+> **安全性更新：** `dbcli init` 現在只會在 `./.dbcli/config.json` 寫入一個很小的專案綁定 stub。完整的連線設定會存放在 `~/.config/dbcli/projects/<project-id>/config.json`，因此敏感設定預設不會留在專案工作區內。
+
 ## 國際化（i18n）
 
 dbcli 透過環境變數 `DBCLI_LANG` 支援多語系：
@@ -88,8 +90,8 @@ dbcli schema users
 # 查詢資料
 dbcli query "SELECT * FROM users"
 
-# 修改結構 (DDL)
-dbcli migrate create posts --column "id:int:pk" "title:varchar(100)"
+# 預覽結構變更（DDL，預設 dry-run；實際套用請加 --execute）
+dbcli migrate create posts --column "id:serial:pk" --column "title:varchar(200):not-null"
 
 # 產生 AI 代理 skill
 dbcli skill --install claude
@@ -146,7 +148,7 @@ dbcli init --conn-name staging --env-file .env.staging
 dbcli init --conn-name prod --env-file .env.production --use-env-refs
 ```
 
-每一條具名連線可以設定不同的 **`--permission`**（例如正式環境只給 `query-only`）。同一專案下的 **schema 快取、黑名單** 等仍共用同一個 `.dbcli` 目錄；切換連線只改「連到哪一台資料庫」，不複製整份專案設定目錄。
+每一條具名連線可以設定不同的 **`--permission`**（例如正式環境只給 `query-only`）。現在專案內的 `.dbcli` 主要扮演**綁定 + 快取層**；真正的連線設定會存到使用者家目錄下的 `~/.config/dbcli/projects/<project-id>/`，避免敏感設定留在工作區。
 
 ### 管理連線（`use` / 移除 / 更名）
 
@@ -187,13 +189,14 @@ dbcli init [OPTIONS]
 ```
 
 **選項 (基本)：**
-- `--system <type>` — 資料庫系統：`postgresql`、`mysql`、`mariadb`
+- `--system <type>` — 資料庫系統：`postgresql`、`mysql`、`mariadb`、`mongodb`
 - `--host <host>` — 主機
 - `--port <port>` — 埠號
 - `--user <user>` — 使用者
 - `--password <pass>` — 密碼
 - `--name <db>` — 資料庫名稱
 - `--permission <level>` — 權限等級：`query-only`、`read-write`、`data-admin`、`admin`
+- **僅 MongoDB：** `--uri <uri>` — 完整連線 URI（`mongodb://…` 或 `mongodb+srv://…`）；`--auth-source <db>` — 驗證資料庫（使用帳密時預設為 `admin`）
 - `--use-env-refs` — 在設定檔中儲存環境變數名稱參照，而非實際值
 - `--skip-test` — 略過連線測試
 - `--no-interactive` — 非互動模式（須提供所有必要選項）
@@ -208,7 +211,7 @@ dbcli init [OPTIONS]
 **行為：**
 - 若存在 `.env` 會讀取（自動帶入 DATABASE_URL、DB_* 等變數）
 - 缺少的欄位會互動提示（主機、埠、使用者、密碼、資料庫名、權限等級）
-- 在專案根目錄建立 `.dbcli` JSON 設定檔
+- 在 `.dbcli/config.json` 建立專案綁定 stub，並將完整設定儲存在 `~/.config/dbcli/projects/<project-id>/`
 - 儲存前會測試資料庫連線
 
 **範例：**
@@ -258,6 +261,8 @@ dbcli use --list
 
 > **`--use-env-refs`：** 啟用後，設定檔會儲存環境變數名稱（例如 `{"$env": "DB_HOST"}`）而非實際值，避免將憑證寫入檔案，適合多環境與 CI/CD。連線時 dbcli 會自動從對應環境變數讀取實際值。
 
+> **儲存模型：** 專案內的 `.dbcli` 現在是綁定 + 快取層，不再是秘密資訊的最終儲存地。若你查看 `./.dbcli/config.json`，應只會看到綁定 metadata；完整設定會放在前述 home storage 路徑中。
+
 ---
 
 #### `dbcli list`
@@ -506,8 +511,8 @@ dbcli skill --install cursor          # 安裝至 Cursor IDE
 ```
 
 **行為：**
-- 套件內建唯一的 **`assets/SKILL.md`**（單一來源）
-- 可輸出至 **stdout**、以 **`--output`** 寫入檔案，或以 **`--install`** 複製到**各平台預設路徑**
+- 內建 **`assets/SKILL.md`** 與 **`assets/reference.md`**（單一來源：精簡 skill＋完整指令參考）
+- 可輸出至 **stdout**、以 **`--output`** 寫入主要 skill 檔，或以 **`--install`** 複製到**各平台預設路徑**（`--install` 時一併寫入同目錄的 `reference.md`）
 - 實際能否存取資料庫仍由 `.dbcli` 的**權限等級**與**黑名單**決定；skill 文字描述的是完整 CLI 能力
 
 **範例：**
@@ -610,6 +615,10 @@ dbcli check orders --checks nulls,orphans --format table
 
 # 掃描所有資料表
 dbcli check --all
+
+# 以表格顯示單表／掃全庫僅執行部分檢查
+dbcli check orders --format table
+dbcli check --all --checks nulls,duplicates --format json
 ```
 
 ---
@@ -700,7 +709,7 @@ dbcli upgrade --check           # 僅檢查，不安裝
 
 **背景檢查（stderr；使用 `--quiet` 或執行 `upgrade` / `skill` 時略過）：**
 - **CLI 版本：** dbcli 會查詢 npm registry（有快取，約每 24 小時一次）。若有新版，一般指令結束後會印一行提示。
-- **已安裝的 skill：** 若曾執行 `dbcli skill --install <platform>`，dbcli 會比對各平台安裝檔與套件內的 `assets/SKILL.md`；若不一致，會列出需重新安裝的平台（`dbcli skill --install <platform>`）。執行 `dbcli upgrade` 時也會一併顯示 skill 狀態與版本資訊。
+- **已安裝的 skill：** 若曾執行 `dbcli skill --install <platform>`，dbcli 會比對各平台**主 skill 檔**（`SKILL.md` 或 Cursor 的 `dbcli.mdc`）與套件內的 `assets/SKILL.md`；若不一致，會提示需重新安裝的平台（`dbcli skill --install <platform>`）。執行 `dbcli upgrade` 時也會一併顯示 skill 與版本資訊。重新安裝時也會一併更新技能旁的 `reference.md`。
 
 #### `dbcli shell`
 
@@ -956,7 +965,7 @@ Query-only 代理無法寫入任何表，也無法讀取黑名單表或欄位
 
 ## AI 整合指南
 
-dbcli 內建可供 AI 使用的 skill 文件（`assets/SKILL.md`），並可複製到常見 AI 開發工具的目錄。
+dbcli 內建供 AI 使用的 skill 文件（`assets/SKILL.md` 與 `assets/reference.md`），並可複製到常見 AI 開發工具的目錄。
 
 ### 快速開始
 
@@ -988,7 +997,7 @@ dbcli skill --install cursor
 4. 重新啟動 Claude Code 擴充
 5. 在對話中詢問：「顯示資料庫 schema」或「查詢作用中使用者」
 
-**Skill 路徑：** `~/.claude/skills/dbcli/SKILL.md`
+**Skill 路徑：** `~/.claude/skills/dbcli/`（`SKILL.md` + `reference.md`）
 
 ---
 
@@ -1000,7 +1009,7 @@ dbcli skill --install cursor
 4. 啟動 Gemini：`gemini start`
 5. 在對話中請求：「查詢 users 表」或「列出資料庫資料表」
 
-**Skill 路徑：** `~/.gemini/skills/dbcli/SKILL.md`
+**Skill 路徑：** `~/.gemini/skills/dbcli/`（`SKILL.md` + `reference.md`）
 
 ---
 
@@ -1012,7 +1021,7 @@ dbcli skill --install cursor
 4. 安裝 Copilot CLI：`npm install -g @github-next/github-copilot-cli`
 5. 使用 `copilot --help` 並探索與 dbcli 的整合
 
-**Skill 路徑：** 執行 `dbcli skill --install copilot` 時，寫入**目前工作目錄**下的 `.github/skills/dbcli/SKILL.md`（通常為專案根目錄）。
+**Skill 路徑：** 執行 `dbcli skill --install copilot` 於專案根目錄時，寫入 **`.github/skills/dbcli/`**（`SKILL.md` + `reference.md`）。
 
 ---
 
@@ -1024,7 +1033,7 @@ dbcli skill --install cursor
 4. 開啟 Cursor
 5. 在 Composer 中：「新增一筆使用者」或「匯出使用者資料」
 
-**Skill 路徑：** 執行 `dbcli skill --install cursor` 時，寫入**目前工作目錄**下的 `.cursor/rules/dbcli.mdc`（專案層級 Cursor 規則）。
+**Skill 路徑：** 在**目前工作目錄**執行 `dbcli skill --install cursor` 時，寫入 **`.cursor/rules/dbcli.mdc`**（摘要與工作流程）及 **`.cursor/skills/dbcli/reference.md`**（完整旗標與範例）。
 
 ---
 
@@ -1051,7 +1060,7 @@ dbcli skill --install claude
 
 ### 升級後更新 skill
 
-`dbcli skill` 安裝的是套件內建的 **`assets/SKILL.md`**，**不會**依你目前的設定即時重新產生。當你**升級 dbcli** 或內建 skill 內容變更時，請對各平台重新安裝：
+`dbcli skill` 會複製套件內的 **`assets/SKILL.md`**；使用 **`--install`** 時另會複製 **`assets/reference.md`** 至技能旁。**不會**依你即時的 `.dbcli` 設定重新產生內文。當**升級 dbcli** 或內建 skill 變更時，請對所使用平台重新執行：
 
 ```bash
 dbcli skill --install claude
@@ -1059,7 +1068,7 @@ dbcli skill --install gemini
 # …依需求
 ```
 
-若本機安裝檔與套件內檔案不一致，多數指令結束後會在 **stderr** 提示（見 **`dbcli upgrade`**）。**權限**或**黑名單**變更會影響 CLI 實際允許的操作 — 建議搭配 `dbcli status`、`dbcli blacklist list` 等讓代理掌握專案現況；skill 文字仍可能列出完整指令集。
+若本機**主 skill 檔**早於套件內 `assets/SKILL.md`，多數指令結束後會在 **stderr** 提醒（見 **`dbcli upgrade`**）。**權限**與**黑名單**變更會影響執行期允許的操作—建議搭配 `dbcli status`、`dbcli blacklist list` 讓代理掌握現況；skill 內文仍可能列出完整指令表。
 
 ---
 
@@ -1230,6 +1239,7 @@ chmod +x dist/cli.mjs
 - **PostgreSQL：** 12.0+
 - **MySQL：** 8.0+
 - **MariaDB：** 10.5+
+- **MongoDB：** 4.4+（`mongodb://` 與 `mongodb+srv://` 查詢與列集合；見前文 **MongoDB Atlas / SRV 連線**）
 
 ### 執行環境