@carllee1983/dbcli 1.51.0 → 1.51.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.51.0",
+  "version": "1.51.2",
   "description": "Database CLI skill and command reference for AI agents.",
   "author": {
     "name": "Carl Lee",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.51.0",
+  "version": "1.51.2",
   "description": "Database CLI skill and command reference for AI agents",
   "author": {
     "name": "Carl Lee",

package/.cursor/rules/dbcli.mdc

@@ -82,6 +82,40 @@ warnings) go to stderr so stdout stays parseable — when piping JSON into a par
 use `2>/dev/null` or leave stderr alone. **Never `2>&1`**: it merges those lines back
 into stdout and the parse fails.
 
+**Intent confirmation:** Treat `auto`, `confirm`, and `guided` as conversational
+preferences for the current request, not as dbcli flags or persistent configuration.
+Do not ask the user a meta-question about whether they want questions.
+
+- `auto` (default): autonomously use governed semantic context and schema discovery.
+  If unresolved ambiguity would materially change the result, ask one compact batch of
+  questions before querying; otherwise state the assumptions and proceed.
+- `confirm`: first state the proposed interpretation and wait for the user's approval
+  before issuing the task's data query.
+- `guided`: resolve the request through short, focused questions, carrying confirmed
+  answers forward rather than asking again.
+
+For business requests, material ambiguity includes the requested result shape or grain,
+metric definition, time boundary and timezone, inclusion/exclusion rules (such as order
+status or refunds), grouping, or selected connection. Example: for “yesterday's sales,”
+do not guess whether the user needs a total or detail, which timezone defines yesterday,
+or whether cancelled and refunded orders count. Summarize the candidate interpretation
+and ask only the unresolved, result-changing questions.
+
+When the user explicitly says to decide without further questions, proceed in `auto`
+mode and disclose the material assumptions. This never bypasses blacklist, schema,
+permission, dry-run, production-selection, or write-confirmation gates; an agent must
+still stop where those gates require human confirmation.
+
+**Business-language discovery:** When a user uses a business alias, metric, recurring
+term, or relationship/join intent instead of a physical table or field name, first run
+`dbcli skill context --format json`. If it includes `semantic`, treat that reviewed
+section as the governed vocabulary; use `dbcli semantic search <terms> --format json`
+to look up a specific term. If no semantic section exists or search returns no result,
+fall back to `blacklist` → `schema` mapping and tell the user that optional
+`dbcli.semantic.json` can make future requests consistent. Never create, update, or
+migrate that file without an explicit human request; semantic vocabulary never replaces
+schema confirmation or the normal query/write safety gates.
+
 ## Agent Task Packs
 
 When the user asks for a database workflow ("diagnose this slow query", "audit
@@ -552,7 +586,7 @@ schema. Raw `query` / `export` invocations render a sortable table only.
 - **Health / growth:** `check --all` (huge tables skipped unless `--include-large`); consult schema `sizeCategory` before ad-hoc queries.
 - **Codegen from live DB:** `schema --format json` to drive an ORM; cross-check once with `dbcli query`.
 - **Integration truth:** `query` before → run app → `query` after. Unit-test mocks are not a substitute.
-- **Natural language requests** (e.g. "update order to shipped"): pick `query` vs DML, map terms → columns via `schema` (and enum values in data), respect blacklist and `sizeCategory`, **always `--dry-run` writes first**.
+- **Natural language requests** (e.g. "update order to shipped"): follow **Business-language discovery** first when the request uses business terminology; then pick `query` vs DML, map terms → columns via `schema` (and enum values in data), respect blacklist and `sizeCategory`, **always `--dry-run` writes first**.
 
 ## Notes
 

package/.cursor/skills/dbcli/reference.md

@@ -2197,6 +2197,14 @@ project root. It supplies business names and descriptions to an agent, but is
 not a query language: these commands are offline, read-only, and never execute
 SQL or contact an LLM.
 
+When an agent receives a business term, metric, alias, or relationship/join intent,
+it should first inspect `dbcli skill context --format json`. If that output includes
+`semantic`, use the reviewed vocabulary and use `semantic search <terms>` for a
+specific lookup. When the section is absent or search has no result, fall back to the
+blacklist-filtered schema and tell the user that `dbcli.semantic.json` is an optional
+way to make future terminology consistent. Do not create, update, or migrate the file
+without an explicit human request.
+
 ```bash
 dbcli semantic validate
 dbcli semantic validate --format json

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "dbcli-agent",
   "displayName": "dbcli Agent",
   "description": "Database CLI skill and command reference for AI agents.",
-  "version": "1.51.0",
+  "version": "1.51.2",
   "author": {
     "name": "Carl Lee",
     "url": "https://github.com/CarlLee1983"

package/.github/skills/dbcli/SKILL.md

@@ -82,6 +82,40 @@ warnings) go to stderr so stdout stays parseable — when piping JSON into a par
 use `2>/dev/null` or leave stderr alone. **Never `2>&1`**: it merges those lines back
 into stdout and the parse fails.
 
+**Intent confirmation:** Treat `auto`, `confirm`, and `guided` as conversational
+preferences for the current request, not as dbcli flags or persistent configuration.
+Do not ask the user a meta-question about whether they want questions.
+
+- `auto` (default): autonomously use governed semantic context and schema discovery.
+  If unresolved ambiguity would materially change the result, ask one compact batch of
+  questions before querying; otherwise state the assumptions and proceed.
+- `confirm`: first state the proposed interpretation and wait for the user's approval
+  before issuing the task's data query.
+- `guided`: resolve the request through short, focused questions, carrying confirmed
+  answers forward rather than asking again.
+
+For business requests, material ambiguity includes the requested result shape or grain,
+metric definition, time boundary and timezone, inclusion/exclusion rules (such as order
+status or refunds), grouping, or selected connection. Example: for “yesterday's sales,”
+do not guess whether the user needs a total or detail, which timezone defines yesterday,
+or whether cancelled and refunded orders count. Summarize the candidate interpretation
+and ask only the unresolved, result-changing questions.
+
+When the user explicitly says to decide without further questions, proceed in `auto`
+mode and disclose the material assumptions. This never bypasses blacklist, schema,
+permission, dry-run, production-selection, or write-confirmation gates; an agent must
+still stop where those gates require human confirmation.
+
+**Business-language discovery:** When a user uses a business alias, metric, recurring
+term, or relationship/join intent instead of a physical table or field name, first run
+`dbcli skill context --format json`. If it includes `semantic`, treat that reviewed
+section as the governed vocabulary; use `dbcli semantic search <terms> --format json`
+to look up a specific term. If no semantic section exists or search returns no result,
+fall back to `blacklist` → `schema` mapping and tell the user that optional
+`dbcli.semantic.json` can make future requests consistent. Never create, update, or
+migrate that file without an explicit human request; semantic vocabulary never replaces
+schema confirmation or the normal query/write safety gates.
+
 ## Agent Task Packs
 
 When the user asks for a database workflow ("diagnose this slow query", "audit
@@ -552,7 +586,7 @@ schema. Raw `query` / `export` invocations render a sortable table only.
 - **Health / growth:** `check --all` (huge tables skipped unless `--include-large`); consult schema `sizeCategory` before ad-hoc queries.
 - **Codegen from live DB:** `schema --format json` to drive an ORM; cross-check once with `dbcli query`.
 - **Integration truth:** `query` before → run app → `query` after. Unit-test mocks are not a substitute.
-- **Natural language requests** (e.g. "update order to shipped"): pick `query` vs DML, map terms → columns via `schema` (and enum values in data), respect blacklist and `sizeCategory`, **always `--dry-run` writes first**.
+- **Natural language requests** (e.g. "update order to shipped"): follow **Business-language discovery** first when the request uses business terminology; then pick `query` vs DML, map terms → columns via `schema` (and enum values in data), respect blacklist and `sizeCategory`, **always `--dry-run` writes first**.
 
 ## Notes
 

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

@@ -2197,6 +2197,14 @@ project root. It supplies business names and descriptions to an agent, but is
 not a query language: these commands are offline, read-only, and never execute
 SQL or contact an LLM.
 
+When an agent receives a business term, metric, alias, or relationship/join intent,
+it should first inspect `dbcli skill context --format json`. If that output includes
+`semantic`, use the reviewed vocabulary and use `semantic search <terms>` for a
+specific lookup. When the section is absent or search has no result, fall back to the
+blacklist-filtered schema and tell the user that `dbcli.semantic.json` is an optional
+way to make future terminology consistent. Do not create, update, or migrate the file
+without an explicit human request.
+
 ```bash
 dbcli semantic validate
 dbcli semantic validate --format json

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.51.2] - 2026-08-07 - Intent confirmation for business requests
+
+### Added
+
+- **Per-request agent intent confirmation.** Installed dbcli skills now support `auto` (default), `confirm`, and `guided` conversational preferences for business-language database requests. Agents ask only result-changing questions, carry confirmed answers forward, and disclose material assumptions when explicitly asked to decide without further questions. These preferences are not persistent CLI configuration and never bypass schema, blacklist, permission, dry-run, production-selection, or write-confirmation gates.
+
+## [1.51.1] - 2026-08-07 - Proactive semantic context discovery
+
+### Changed
+
+- **Agent skills now surface semantic context before users have to discover it.** When a request uses business aliases, metrics, recurring terminology, or relationship/join intent, installed dbcli skills first check `skill context`; they use validated semantic vocabulary when available, otherwise fall back to the blacklist-filtered schema and explain that `dbcli.semantic.json` is an optional way to keep future requests consistent. Skills never create, update, or migrate the file without explicit human instruction.
+
+### Fixed
+
+- **Release formatting gate.** Remove an extra closing brace from the static guides stylesheet so Prettier can parse the repository and the release gate can run.
+
 ## [1.51.0] - 2026-08-07 - Local semantic context and offline query-draft validation
 
 ### Added

package/assets/SKILL.md

@@ -82,6 +82,40 @@ warnings) go to stderr so stdout stays parseable — when piping JSON into a par
 use `2>/dev/null` or leave stderr alone. **Never `2>&1`**: it merges those lines back
 into stdout and the parse fails.
 
+**Intent confirmation:** Treat `auto`, `confirm`, and `guided` as conversational
+preferences for the current request, not as dbcli flags or persistent configuration.
+Do not ask the user a meta-question about whether they want questions.
+
+- `auto` (default): autonomously use governed semantic context and schema discovery.
+  If unresolved ambiguity would materially change the result, ask one compact batch of
+  questions before querying; otherwise state the assumptions and proceed.
+- `confirm`: first state the proposed interpretation and wait for the user's approval
+  before issuing the task's data query.
+- `guided`: resolve the request through short, focused questions, carrying confirmed
+  answers forward rather than asking again.
+
+For business requests, material ambiguity includes the requested result shape or grain,
+metric definition, time boundary and timezone, inclusion/exclusion rules (such as order
+status or refunds), grouping, or selected connection. Example: for “yesterday's sales,”
+do not guess whether the user needs a total or detail, which timezone defines yesterday,
+or whether cancelled and refunded orders count. Summarize the candidate interpretation
+and ask only the unresolved, result-changing questions.
+
+When the user explicitly says to decide without further questions, proceed in `auto`
+mode and disclose the material assumptions. This never bypasses blacklist, schema,
+permission, dry-run, production-selection, or write-confirmation gates; an agent must
+still stop where those gates require human confirmation.
+
+**Business-language discovery:** When a user uses a business alias, metric, recurring
+term, or relationship/join intent instead of a physical table or field name, first run
+`dbcli skill context --format json`. If it includes `semantic`, treat that reviewed
+section as the governed vocabulary; use `dbcli semantic search <terms> --format json`
+to look up a specific term. If no semantic section exists or search returns no result,
+fall back to `blacklist` → `schema` mapping and tell the user that optional
+`dbcli.semantic.json` can make future requests consistent. Never create, update, or
+migrate that file without an explicit human request; semantic vocabulary never replaces
+schema confirmation or the normal query/write safety gates.
+
 ## Agent Task Packs
 
 When the user asks for a database workflow ("diagnose this slow query", "audit
@@ -552,7 +586,7 @@ schema. Raw `query` / `export` invocations render a sortable table only.
 - **Health / growth:** `check --all` (huge tables skipped unless `--include-large`); consult schema `sizeCategory` before ad-hoc queries.
 - **Codegen from live DB:** `schema --format json` to drive an ORM; cross-check once with `dbcli query`.
 - **Integration truth:** `query` before → run app → `query` after. Unit-test mocks are not a substitute.
-- **Natural language requests** (e.g. "update order to shipped"): pick `query` vs DML, map terms → columns via `schema` (and enum values in data), respect blacklist and `sizeCategory`, **always `--dry-run` writes first**.
+- **Natural language requests** (e.g. "update order to shipped"): follow **Business-language discovery** first when the request uses business terminology; then pick `query` vs DML, map terms → columns via `schema` (and enum values in data), respect blacklist and `sizeCategory`, **always `--dry-run` writes first**.
 
 ## Notes
 

package/assets/SKILL.zh-TW.md

@@ -64,6 +64,31 @@ legacy 單檔 `.dbcli`。若要防護同一 OS 使用者的惡意 process，host
 stdout 保持可解析——把 JSON 導進 parser 時請用 `2>/dev/null` 或不要動 stderr。
 **絕對不要用 `2>&1`**：那會把那些訊息併回 stdout，解析必定失敗。
 
+**意圖確認：**將 `auto`、`confirm` 與 `guided` 視為**當次請求**的對話偏好，而不是 dbcli
+旗標或持久化設定。不要先用後設問題詢問使用者「要不要讓我提問」。
+
+- `auto`（預設）：自主使用受治理的 semantic context 與 schema 探索。若尚未解決的歧義會
+  實質改變結果，先用一小批精簡問題確認；否則說明假設後繼續。
+- `confirm`：先說明預計採用的解讀，等待使用者核准後，才發出該任務的資料查詢。
+- `guided`：以短而聚焦的問題逐步釐清請求；已確認的答案必須延續使用，不可重複詢問。
+
+對業務請求而言，會實質改變結果的歧義包括所需結果的形狀或粒度、指標定義、時間邊界與
+時區、納入／排除規則（例如訂單狀態或退款）、分組方式與選用連線。例如「昨天的銷售資料」
+不能猜測使用者要總額或明細、哪個時區定義昨天，或取消與退款訂單是否計入。先摘要候選解讀，
+只詢問尚未解決且會改變結果的問題。
+
+當使用者明確要求自行判斷、不要再問時，以 `auto` 模式繼續並說明重要假設。這絕不繞過
+blacklist、schema、permission、dry-run、production 選取或寫入確認閘門；只要閘門要求人類
+確認，agent 仍必須停止。
+
+**業務語言探索：** 當使用者以業務別名、metric、反覆出現的術語或 relationship/join 意圖，
+而非實體 table 或 field 名稱提出需求時，先執行 `dbcli skill context --format json`。若輸出含有
+`semantic`，將該已檢閱的區塊視為受治理詞彙；需查找特定術語時，用
+`dbcli semantic search <terms> --format json`。若沒有 semantic 區塊，或搜尋沒有結果，就退回
+`blacklist` → `schema` 對照，並告知使用者可選用的 `dbcli.semantic.json` 能讓後續需求保持一致。
+除非人類明確要求，絕不可建立、更新或 migrate 此檔案；語意詞彙不能取代 schema 確認或正常的
+query/write 安全閘門。
+
 ## Agent Task Packs
 
 當使用者要求一個資料庫工作流（例如「診斷這個慢查詢」、「審計權限」、「審視長時間執行的操作」），**優先選用已發布的任務模板，而非憑記憶自行組合步驟。**
@@ -421,7 +446,7 @@ dbcli export "SELECT * FROM orders" --format html --output orders.html
 - **健康 / 成長：** `check --all`（除非加 `--include-large`，否則略過巨大表）；做 ad-hoc query 前先看 schema 的 `sizeCategory`。
 - **從活線 DB 產生程式：** `schema --format json` 餵給 ORM；再用 `dbcli query` 交叉驗證一次。
 - **整合事實：** 前 `query` → 跑應用 → 後 `query`。單元測試 mock 不能替代。
-- **自然語言請求**（如「把訂單更新為 shipped」）：先決定要 `query` 還是 DML，透過 `schema` 把詞彙映到欄位（值用 enum 資料），尊重 blacklist 與 `sizeCategory`，**寫入永遠先 `--dry-run`**。
+- **自然語言請求**（如「把訂單更新為 shipped」）：若需求使用業務術語，先遵循**業務語言探索**；接著決定要 `query` 還是 DML，透過 `schema` 把詞彙映到欄位（值用 enum 資料），尊重 blacklist 與 `sizeCategory`，**寫入永遠先 `--dry-run`**。
 
 ## 備註
 

package/assets/reference.md

@@ -2197,6 +2197,14 @@ project root. It supplies business names and descriptions to an agent, but is
 not a query language: these commands are offline, read-only, and never execute
 SQL or contact an LLM.
 
+When an agent receives a business term, metric, alias, or relationship/join intent,
+it should first inspect `dbcli skill context --format json`. If that output includes
+`semantic`, use the reviewed vocabulary and use `semantic search <terms>` for a
+specific lookup. When the section is absent or search has no result, fall back to the
+blacklist-filtered schema and tell the user that `dbcli.semantic.json` is an optional
+way to make future terminology consistent. Do not create, update, or migrate the file
+without an explicit human request.
+
 ```bash
 dbcli semantic validate
 dbcli semantic validate --format json

package/dist/cli.mjs

@@ -52,7 +52,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@carllee1983/dbcli",
-    version: "1.51.0",
+    version: "1.51.2",
     description: "Database CLI for AI agents",
     type: "module",
     publishConfig: {

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.51.0",
+  "version": "1.51.2",
   "description": "Database CLI skill and command reference for AI agents.",
   "contextFileName": "AGENTS.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "1.51.0",
+  "version": "1.51.2",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {

package/plugins/dbcli-agent/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.51.0",
+  "version": "1.51.2",
   "description": "Database CLI skill and command reference for AI agents",
   "author": {
     "name": "Carl Lee",

package/plugins/dbcli-agent/skills/dbcli/SKILL.md

@@ -82,6 +82,40 @@ warnings) go to stderr so stdout stays parseable — when piping JSON into a par
 use `2>/dev/null` or leave stderr alone. **Never `2>&1`**: it merges those lines back
 into stdout and the parse fails.
 
+**Intent confirmation:** Treat `auto`, `confirm`, and `guided` as conversational
+preferences for the current request, not as dbcli flags or persistent configuration.
+Do not ask the user a meta-question about whether they want questions.
+
+- `auto` (default): autonomously use governed semantic context and schema discovery.
+  If unresolved ambiguity would materially change the result, ask one compact batch of
+  questions before querying; otherwise state the assumptions and proceed.
+- `confirm`: first state the proposed interpretation and wait for the user's approval
+  before issuing the task's data query.
+- `guided`: resolve the request through short, focused questions, carrying confirmed
+  answers forward rather than asking again.
+
+For business requests, material ambiguity includes the requested result shape or grain,
+metric definition, time boundary and timezone, inclusion/exclusion rules (such as order
+status or refunds), grouping, or selected connection. Example: for “yesterday's sales,”
+do not guess whether the user needs a total or detail, which timezone defines yesterday,
+or whether cancelled and refunded orders count. Summarize the candidate interpretation
+and ask only the unresolved, result-changing questions.
+
+When the user explicitly says to decide without further questions, proceed in `auto`
+mode and disclose the material assumptions. This never bypasses blacklist, schema,
+permission, dry-run, production-selection, or write-confirmation gates; an agent must
+still stop where those gates require human confirmation.
+
+**Business-language discovery:** When a user uses a business alias, metric, recurring
+term, or relationship/join intent instead of a physical table or field name, first run
+`dbcli skill context --format json`. If it includes `semantic`, treat that reviewed
+section as the governed vocabulary; use `dbcli semantic search <terms> --format json`
+to look up a specific term. If no semantic section exists or search returns no result,
+fall back to `blacklist` → `schema` mapping and tell the user that optional
+`dbcli.semantic.json` can make future requests consistent. Never create, update, or
+migrate that file without an explicit human request; semantic vocabulary never replaces
+schema confirmation or the normal query/write safety gates.
+
 ## Agent Task Packs
 
 When the user asks for a database workflow ("diagnose this slow query", "audit
@@ -552,7 +586,7 @@ schema. Raw `query` / `export` invocations render a sortable table only.
 - **Health / growth:** `check --all` (huge tables skipped unless `--include-large`); consult schema `sizeCategory` before ad-hoc queries.
 - **Codegen from live DB:** `schema --format json` to drive an ORM; cross-check once with `dbcli query`.
 - **Integration truth:** `query` before → run app → `query` after. Unit-test mocks are not a substitute.
-- **Natural language requests** (e.g. "update order to shipped"): pick `query` vs DML, map terms → columns via `schema` (and enum values in data), respect blacklist and `sizeCategory`, **always `--dry-run` writes first**.
+- **Natural language requests** (e.g. "update order to shipped"): follow **Business-language discovery** first when the request uses business terminology; then pick `query` vs DML, map terms → columns via `schema` (and enum values in data), respect blacklist and `sizeCategory`, **always `--dry-run` writes first**.
 
 ## Notes
 

package/plugins/dbcli-agent/skills/dbcli/reference.md

@@ -2197,6 +2197,14 @@ project root. It supplies business names and descriptions to an agent, but is
 not a query language: these commands are offline, read-only, and never execute
 SQL or contact an LLM.
 
+When an agent receives a business term, metric, alias, or relationship/join intent,
+it should first inspect `dbcli skill context --format json`. If that output includes
+`semantic`, use the reviewed vocabulary and use `semantic search <terms>` for a
+specific lookup. When the section is absent or search has no result, fall back to the
+blacklist-filtered schema and tell the user that `dbcli.semantic.json` is an optional
+way to make future terminology consistent. Do not create, update, or migrate the file
+without an explicit human request.
+
 ```bash
 dbcli semantic validate
 dbcli semantic validate --format json

package/skills/dbcli/SKILL.md

@@ -82,6 +82,40 @@ warnings) go to stderr so stdout stays parseable — when piping JSON into a par
 use `2>/dev/null` or leave stderr alone. **Never `2>&1`**: it merges those lines back
 into stdout and the parse fails.
 
+**Intent confirmation:** Treat `auto`, `confirm`, and `guided` as conversational
+preferences for the current request, not as dbcli flags or persistent configuration.
+Do not ask the user a meta-question about whether they want questions.
+
+- `auto` (default): autonomously use governed semantic context and schema discovery.
+  If unresolved ambiguity would materially change the result, ask one compact batch of
+  questions before querying; otherwise state the assumptions and proceed.
+- `confirm`: first state the proposed interpretation and wait for the user's approval
+  before issuing the task's data query.
+- `guided`: resolve the request through short, focused questions, carrying confirmed
+  answers forward rather than asking again.
+
+For business requests, material ambiguity includes the requested result shape or grain,
+metric definition, time boundary and timezone, inclusion/exclusion rules (such as order
+status or refunds), grouping, or selected connection. Example: for “yesterday's sales,”
+do not guess whether the user needs a total or detail, which timezone defines yesterday,
+or whether cancelled and refunded orders count. Summarize the candidate interpretation
+and ask only the unresolved, result-changing questions.
+
+When the user explicitly says to decide without further questions, proceed in `auto`
+mode and disclose the material assumptions. This never bypasses blacklist, schema,
+permission, dry-run, production-selection, or write-confirmation gates; an agent must
+still stop where those gates require human confirmation.
+
+**Business-language discovery:** When a user uses a business alias, metric, recurring
+term, or relationship/join intent instead of a physical table or field name, first run
+`dbcli skill context --format json`. If it includes `semantic`, treat that reviewed
+section as the governed vocabulary; use `dbcli semantic search <terms> --format json`
+to look up a specific term. If no semantic section exists or search returns no result,
+fall back to `blacklist` → `schema` mapping and tell the user that optional
+`dbcli.semantic.json` can make future requests consistent. Never create, update, or
+migrate that file without an explicit human request; semantic vocabulary never replaces
+schema confirmation or the normal query/write safety gates.
+
 ## Agent Task Packs
 
 When the user asks for a database workflow ("diagnose this slow query", "audit
@@ -552,7 +586,7 @@ schema. Raw `query` / `export` invocations render a sortable table only.
 - **Health / growth:** `check --all` (huge tables skipped unless `--include-large`); consult schema `sizeCategory` before ad-hoc queries.
 - **Codegen from live DB:** `schema --format json` to drive an ORM; cross-check once with `dbcli query`.
 - **Integration truth:** `query` before → run app → `query` after. Unit-test mocks are not a substitute.
-- **Natural language requests** (e.g. "update order to shipped"): pick `query` vs DML, map terms → columns via `schema` (and enum values in data), respect blacklist and `sizeCategory`, **always `--dry-run` writes first**.
+- **Natural language requests** (e.g. "update order to shipped"): follow **Business-language discovery** first when the request uses business terminology; then pick `query` vs DML, map terms → columns via `schema` (and enum values in data), respect blacklist and `sizeCategory`, **always `--dry-run` writes first**.
 
 ## Notes
 

package/skills/dbcli/reference.md

@@ -2197,6 +2197,14 @@ project root. It supplies business names and descriptions to an agent, but is
 not a query language: these commands are offline, read-only, and never execute
 SQL or contact an LLM.
 
+When an agent receives a business term, metric, alias, or relationship/join intent,
+it should first inspect `dbcli skill context --format json`. If that output includes
+`semantic`, use the reviewed vocabulary and use `semantic search <terms>` for a
+specific lookup. When the section is absent or search has no result, fall back to the
+blacklist-filtered schema and tell the user that `dbcli.semantic.json` is an optional
+way to make future terminology consistent. Do not create, update, or migrate the file
+without an explicit human request.
+
 ```bash
 dbcli semantic validate
 dbcli semantic validate --format json