@follenfang/wowdata 0.0.2 → 0.0.3

package/README.md

@@ -1,23 +1,63 @@
 # wowdata
 
-`wowdata` 是一个纯 Go 的 World of Warcraft 数据 CLI，用于查询和导出 CASC、DB2、Listfile、图标、法术、副本、物品、生物、装饰物和视频数据。
+<div align="center">
+  <strong>World of Warcraft data, from the command line.</strong>
+  <br />
+  <sub>Query CASC and DB2 data, export game assets, and keep every result scriptable.</sub>
+  <br /><br />
 
-## 安装
+  [![npm](https://img.shields.io/npm/v/@follenfang/wowdata?style=flat-square&logo=npm&label=npm)](https://www.npmjs.com/package/@follenfang/wowdata)
+  [![downloads](https://img.shields.io/npm/dm/@follenfang/wowdata?style=flat-square&label=downloads)](https://www.npmjs.com/package/@follenfang/wowdata)
+  [![CI](https://img.shields.io/github/actions/workflow/status/Follen/wowdata/ci.yml?branch=main&style=flat-square&logo=github&label=CI)](https://github.com/Follen/wowdata/actions/workflows/ci.yml)
+  [![release](https://img.shields.io/github/v/release/Follen/wowdata?style=flat-square&logo=github&label=release)](https://github.com/Follen/wowdata/releases/latest)
+  [![license](https://img.shields.io/github/license/Follen/wowdata?style=flat-square&label=license)](LICENSE)
+
+  <br />
+  <a href="#readme-zh">中文</a> · <a href="#readme-en">English</a>
+</div>
+
+---
+
+<a id="readme-zh"></a>
+
+## 中文
+
+`wowdata` 是一个 CLI-only 的魔兽世界数据工具。它直接读取本地客户端或 Blizzard CDN，查询 CASC、DB2、Listfile、法术、物品、生物和地下城手册数据，也能导出 BLP、PNG、WebP 与其他游戏文件。
+
+核心解析器使用 Go。npm 只负责跨平台安装、更新和 Skill 部署，没有隐藏的远端服务，也不需要 MCP。
+
+### 为什么用它
+
+- **直接查询**：执行目标命令即可，CLI 会自行判断缓存是否可用、是否需要下载。
+- **结果稳定**：最终结果写入 stdout JSON，下载进度写入 stderr，适合 Shell 和 Agent。
+- **缓存可控**：按 Build 保存不可变快照，支持校验、清理、容量限制和离线复用。
+- **源码可审计**：数据解析在 Go 中完成，npm 生命周期脚本集中在 `npm/`。
+- **原子命令**：CLI 只提供明确的小命令，语义理解和命令组合交给 Skill。
+
+### 安装
 
 ```bash
 npm install -g @follenfang/wowdata
 ```
 
-npm 会完成两件事：
+支持 Windows amd64、Linux amd64/arm64、macOS amd64/arm64。安装完成后：
 
-- 把当前平台的 Go CLI 安装到 `~/.wowdata/bin`，并提供全局 `wowdata` 命令。
-- 把轻量 Skill 安装到 `~/.agents/skills/wowdata`。Skill 只有说明和 Reference，不包含可执行文件。
+```bash
+wowdata --version
+wowdata doctor
+wowdata --help
+```
+
+npm 会安装：
 
-支持 Windows amd64、Linux amd64/arm64、macOS amd64/arm64。
+- `wowdata` CLI 到 `~/.wowdata/bin`，并创建全局命令。
+- `wowdata` Skill 到 `~/.agents/skills/wowdata`。
 
-## 目标必须明确
+也可以从 [GitHub Releases](https://github.com/Follen/wowdata/releases/latest) 直接下载单文件程序。
 
-CLI 没有地区、产品、Build 或语言默认值。需要游戏数据的命令必须传完整目标：
+### 快速开始
+
+CLI 不猜地区、产品、Build 或语言。涉及游戏数据时，目标必须明确：
 
 ```bash
 wowdata db2 rows SpellName --id 123 \
@@ -28,7 +68,7 @@ wowdata db2 rows SpellName --id 123 \
   --locale zhCN
 ```
 
-也可以先保存完整 Profile：
+常用目标可以保存成 Profile：
 
 ```bash
 wowdata profile set retail-cn \
@@ -38,40 +78,78 @@ wowdata profile set retail-cn \
   --build latest \
   --locale zhCN
 
-wowdata db2 rows SpellName --id 123 --profile retail-cn
+wowdata spell info --spell-id 123 --profile retail-cn
 ```
 
-Skill 的规则不同：用户没指定时，Skill 显式传入中国区 `cn`、最新 Build `latest` 和简体中文 `zhCN`；产品没有默认值，无法从用户话语或上下文确定时，Skill 会先询问用户。
+查看某个区域当前实际提供的产品和 Build：
+
+```bash
+wowdata casc products --source remote --region cn
+```
 
-## 直接查询
+### 不需要手动预热
 
-普通任务直接运行对应原子命令，不需要先执行预热：
+直接执行查询即可：
 
 ```bash
-wowdata spell info --spell-id 123 --profile retail-cn
 wowdata file lookup --file-data-id 134400 --profile retail-cn
-wowdata icon export --file-data-id 134400 --format png --output output/icon.png --profile retail-cn
+wowdata icon export --file-data-id 134400 --format png \
+  --output output/icon.png --profile retail-cn
 ```
 
-CLI 会在同一次命令中：
+每次查询时，CLI 会依次完成：
 
-1. 解析明确的产品和 Build。
-2. 检查远端内容身份与本地 SHA-256。
+1. 解析产品与 Build。
+2. 对比远端内容身份和本地 SHA-256。
 3. 复用有效缓存，下载缺失或过期内容。
-4. 完成查询并返回最终结果。
+4. 执行查询并返回最终 JSON。
 
-准备和下载进度写入 stderr，最终结构化结果写入 stdout JSON。多个独立 CDN 对象和清单默认使用 4 个 worker 并发下载；可以通过 `wowdata cache config --workers N` 调整。
+只有需要提前准备数据时，才显式运行：
 
-## 输出和退出码
+```bash
+wowdata warmup --source remote --region cn \
+  --product wow --build latest --locale zhCN
+```
 
-CLI 可以直接用于 Agent，也可以作为普通 Shell 命令组合：
+独立 CDN 对象和清单默认使用 4 个 worker 并发下载。
+
+### 命令一览
+
+| 领域 | 命令 |
+| --- | --- |
+| CASC | `casc info/products/diagnose` |
+| DB2 | `db2 schema/rows/search/foreign-key/stream` |
+| 文件 | `file lookup/search/extension/get/exists/encoding/export` |
+| 图标 | `icon export` |
+| 法术 | `spell info/auras/summons` |
+| 副本 | `encounter get` |
+| 物品 | `item get/models/geosets/textures` |
+| 生物 | `creature display/model` |
+| 装饰 | `decor list/get` |
+| 视频 | `video demux` |
+| 目标 | `profile list/show/set/remove` |
+| 缓存 | `cache status/verify/prune/clear/config` |
+| 维护 | `doctor/update/uninstall` |
+
+运行 `wowdata <command> --help` 查看参数。
+
+### 输出约定
+
+```json
+{
+  "ok": true,
+  "command": "icon export",
+  "data": {},
+  "warnings": []
+}
+```
 
-- 成功结果为 `"ok": true`，进程退出码为 `0`。
-- 业务错误为 `"ok": false`，错误详情仍是 stdout 中的 JSON，进程退出码为 `1`。
-- 准备和下载进度只写入 stderr，不会污染 stdout JSON。
-- 参数拼写错误等尚未进入命令处理器的错误写入 stderr，并返回退出码 `1`。
+- 成功：stdout 返回 `"ok": true`，退出码为 `0`。
+- 业务错误：stdout 返回 `"ok": false` 和结构化错误，退出码为 `1`。
+- 下载、缓存准备等进度只写入 stderr。
+- 参数解析错误写入 stderr，退出码为 `1`。
 
-因此脚本既可以判断退出码，也可以继续解析结构化错误：
+普通 Shell 可以直接同时使用退出码和 JSON：
 
 ```bash
 if wowdata db2 rows SpellName --id 133 \
@@ -83,26 +161,7 @@ else
 fi
 ```
 
-## 发现与提前准备
-
-查看某个区域当前提供的真实产品和 Build 组合：
-
-```bash
-wowdata casc products --source remote --region cn
-```
-
-需要提前下载时再显式使用 `warmup`：
-
-```bash
-wowdata warmup \
-  --source remote \
-  --region cn \
-  --product wow \
-  --build latest \
-  --locale zhCN
-```
-
-## 本地目录
+### 缓存与本地目录
 
 ```text
 ~/.wowdata/
@@ -110,18 +169,13 @@ wowdata warmup \
 ├── config/    用户配置
 ├── profiles/  完整数据目标
 ├── builds/    不可变 Build 快照
-├── cache/
-│   ├── casc/
-│   ├── dbd/
-│   ├── listfile/
-│   ├── tact/
-│   └── manifests/
+├── cache/     CASC、DBD、Listfile、TACT 与清单缓存
 ├── state/     安装和最近状态
 ├── tmp/       下载临时文件
 └── locks/     跨进程下载锁
 ```
 
-缓存默认上限为 20GB。每个 Profile 的当前 Build 和上一个 Build 不参与自动清理，更老的 Build 按最久未使用顺序清理。
+缓存默认上限为 20 GB。当前 Build 和上一个 Build 不参与自动清理，更早的 Build 按最久未使用顺序清理。
 
 ```bash
 wowdata cache status
@@ -131,70 +185,245 @@ wowdata cache clear
 wowdata cache config --max-gb 30 --workers 6
 ```
 
-远端不可用时，CLI 可以使用已经通过完整性校验的离线缓存；缺失、损坏和未完成的缓存不会被使用。
+远端不可用时，CLI 会复用已经通过完整性校验的缓存；损坏或未完成的内容不会被使用。
+
+### Skill 的默认规则
+
+CLI 本身没有目标默认值。随 npm 安装的 Skill 会在用户未指定时明确传入：
+
+- 地区：`cn`
+- Build：`latest`
+- 语言：`zhCN`
+
+产品没有默认值。无法从问题或上下文确定产品时，Skill 会先询问。
 
-## 诊断和维护
+### 维护
 
 ```bash
 wowdata doctor
 wowdata update
-wowdata update --version 1.2.3
+wowdata update --version 0.0.2
 wowdata uninstall
 wowdata uninstall --keep-data
 ```
 
-`doctor` 只读检查 CLI/npm、目录、Profile、缓存完整性和基础网络，不自动修改数据。
+`doctor` 是只读检查。`uninstall --keep-data` 会删除程序和托管 Skill，但保留 Profile、Build 与缓存。
 
-`uninstall` 默认删除 CLI、托管 Skill 和整个 `~/.wowdata`。使用 `--keep-data` 时保留配置、Profile、Build 和缓存。安装遇到非本包托管的旧 Skill 时会先备份，不会直接覆盖。
+### 从源码构建
 
-## 命令
+```bash
+go test ./... -count=1
+go build -trimpath -o dist/wowdata ./cmd/wowdata
+npm test
+```
 
-```text
-warmup
-db2 schema/rows/search/foreign-key/stream
-spell info/auras/summons
-encounter get
-file lookup/search/extension/get/exists/encoding/export
-icon export
-casc info/products/diagnose
-item get/models/geosets/textures
-creature display/model
-decor list/get
-video demux
-profile list/show/set/remove
-cache status/verify/prune/clear/config
-doctor
-update
-uninstall
+推送 `vX.Y.Z` tag 后，GitHub Actions 会运行测试、构建五个平台、生成 `SHA256SUMS`、创建 GitHub Release，并通过 npm Trusted Publisher OIDC 发布带 provenance 的包。
+
+---
+
+<a id="readme-en"></a>
+
+## English
+
+`wowdata` is a CLI-only toolkit for World of Warcraft data. It reads a local game installation or the Blizzard CDN to query CASC, DB2, listfiles, spells, items, creatures, and encounter data, and exports BLP, PNG, WebP, and other game files.
+
+The parser is written in Go. npm is only used for cross-platform installation, updates, and Skill deployment. There is no hosted service and no MCP runtime.
+
+### Why wowdata
+
+- **Query directly**: run the command you need; the CLI decides whether cached data can be reused or downloaded.
+- **Stable output**: final results go to stdout as JSON, while preparation progress stays on stderr.
+- **Controlled cache**: immutable Build snapshots with verification, pruning, size limits, and offline reuse.
+- **Auditable source**: data parsing lives in Go, and every npm lifecycle script is visible under `npm/`.
+- **Atomic commands**: the CLI exposes small operations; the Skill handles intent and command composition.
+
+### Install
+
+```bash
+npm install -g @follenfang/wowdata
 ```
 
-运行 `wowdata --help` 或 `wowdata <command> --help` 查看完整参数。
+Supported targets: Windows amd64, Linux amd64/arm64, and macOS amd64/arm64.
+
+```bash
+wowdata --version
+wowdata doctor
+wowdata --help
+```
+
+The npm package installs:
+
+- The `wowdata` CLI under `~/.wowdata/bin`, with a global command.
+- The `wowdata` Skill under `~/.agents/skills/wowdata`.
 
-## 从源码构建
+Standalone binaries are also available from [GitHub Releases](https://github.com/Follen/wowdata/releases/latest).
+
+### Quick start
+
+The CLI does not guess a region, product, Build, or locale. Data commands require an explicit target:
 
 ```bash
-go test ./... -count=1
-go build -trimpath -o dist/wowdata ./cmd/wowdata
-npm test
+wowdata db2 rows SpellName --id 123 \
+  --source remote \
+  --region cn \
+  --product wow \
+  --build latest \
+  --locale zhCN
 ```
 
-Go 负责数据解析和命令执行；Node.js 只负责 npm 安装、启动桥接和包生命周期，所有脚本都在 `npm/` 中可审计。
+Save frequently used targets as Profiles:
 
-## 发布
+```bash
+wowdata profile set retail-cn \
+  --source remote \
+  --region cn \
+  --product wow \
+  --build latest \
+  --locale zhCN
 
-推送语义版本 tag 会触发 GitHub Actions：
+wowdata spell info --spell-id 123 --profile retail-cn
+```
+
+Discover the products and Builds currently available in a region:
 
 ```bash
-git tag v1.2.3
-git push origin v1.2.3
+wowdata casc products --source remote --region cn
+```
+
+### Warmup is optional
+
+Run the query directly:
+
+```bash
+wowdata file lookup --file-data-id 134400 --profile retail-cn
+wowdata icon export --file-data-id 134400 --format png \
+  --output output/icon.png --profile retail-cn
 ```
 
-工作流会测试 Go 和 npm、构建五个平台、生成 `SHA256SUMS`、创建 GitHub Release，并发布同版本 `@follenfang/wowdata`。
+For each query, the CLI:
+
+1. Resolves the product and Build.
+2. Compares the remote content identity with the local SHA-256.
+3. Reuses valid cache entries and downloads missing or stale data.
+4. Executes the query and returns the final JSON result.
+
+Use `warmup` only when data must be prepared ahead of time:
+
+```bash
+wowdata warmup --source remote --region cn \
+  --product wow --build latest --locale zhCN
+```
+
+Independent CDN objects and manifests use four download workers by default.
+
+### Command map
+
+| Area | Commands |
+| --- | --- |
+| CASC | `casc info/products/diagnose` |
+| DB2 | `db2 schema/rows/search/foreign-key/stream` |
+| Files | `file lookup/search/extension/get/exists/encoding/export` |
+| Icons | `icon export` |
+| Spells | `spell info/auras/summons` |
+| Encounters | `encounter get` |
+| Items | `item get/models/geosets/textures` |
+| Creatures | `creature display/model` |
+| Decor | `decor list/get` |
+| Video | `video demux` |
+| Targets | `profile list/show/set/remove` |
+| Cache | `cache status/verify/prune/clear/config` |
+| Maintenance | `doctor/update/uninstall` |
+
+Run `wowdata <command> --help` for complete flags.
+
+### Output contract
+
+```json
+{
+  "ok": true,
+  "command": "icon export",
+  "data": {},
+  "warnings": []
+}
+```
+
+- Success: stdout contains `"ok": true`; exit code `0`.
+- Domain error: stdout contains `"ok": false` and a structured error; exit code `1`.
+- Download and cache preparation progress is written only to stderr.
+- Argument parsing errors are written to stderr and return exit code `1`.
+
+Shell scripts can rely on both the process status and JSON body:
+
+```bash
+if wowdata db2 rows SpellName --id 133 \
+  --source remote --region cn --product wow --build latest --locale zhCN \
+  >result.json; then
+  jq '.data.rows' result.json
+else
+  jq '.error' result.json
+fi
+```
+
+### Cache layout
+
+```text
+~/.wowdata/
+├── bin/       CLI binaries
+├── config/    User configuration
+├── profiles/  Complete data targets
+├── builds/    Immutable Build snapshots
+├── cache/     CASC, DBD, listfile, TACT, and manifest cache
+├── state/     Installation and recent state
+├── tmp/       Incomplete downloads
+└── locks/     Cross-process download locks
+```
+
+The default cache limit is 20 GB. The current and previous Build for each Profile are protected from automatic pruning; older Builds are removed by least-recent use.
+
+```bash
+wowdata cache status
+wowdata cache verify
+wowdata cache prune
+wowdata cache clear
+wowdata cache config --max-gb 30 --workers 6
+```
+
+When the remote source is unavailable, the CLI can reuse cache entries that already passed integrity checks. Corrupt or incomplete entries are never used.
+
+### Skill defaults
+
+The CLI itself has no target defaults. When the user does not specify them, the installed Skill explicitly supplies:
+
+- Region: `cn`
+- Build: `latest`
+- Locale: `zhCN`
+
+There is no default product. If the product cannot be inferred from the request or context, the Skill asks first.
+
+### Maintenance
+
+```bash
+wowdata doctor
+wowdata update
+wowdata update --version 0.0.2
+wowdata uninstall
+wowdata uninstall --keep-data
+```
+
+`doctor` is read-only. `uninstall --keep-data` removes the CLI and managed Skill while preserving Profiles, Builds, and cache data.
+
+### Build from source
+
+```bash
+go test ./... -count=1
+go build -trimpath -o dist/wowdata ./cmd/wowdata
+npm test
+```
 
-npm 发布使用绑定到 `Follen/wowdata` 和 `release.yml` 的 Trusted Publisher OIDC，不需要在 GitHub Secrets 中保存 `NPM_TOKEN`。发布 job 固定使用 npm `11.18.0`，并生成 npm provenance。
+Pushing a `vX.Y.Z` tag runs the test suite, builds five platforms, creates `SHA256SUMS` and a GitHub Release, then publishes the npm package through Trusted Publisher OIDC with provenance.
 
-npm 版本不可覆盖：`0.0.1` 已经发布，后续正式发布从更高的新版本 tag 开始，例如 `v0.0.2`。
+---
 
 ## License
 
-AGPL-3.0-or-later
+[AGPL-3.0-or-later](LICENSE)

package/dist/SHA256SUMS

@@ -1,5 +1,5 @@
-c518635ebf3dcdf92b39510ec9fb3f25df27e7eb0132b177553bdeae15089452  dist/wowdata-darwin-amd64
-10470811b3fb51abed29d28ff5548f272ce3939556a16321b94ae85d1736f8be  dist/wowdata-darwin-arm64
-009d40358915132df84dcdf7e9275f4fef9161a390ccc8b1beaa43763564e8ea  dist/wowdata-linux-amd64
-46528408a4ba3ba6b05e0469f7356ae1945386337e0e2305f037a26e2c96e66a  dist/wowdata-linux-arm64
-397884735b784690b01188399cf140ea05bf98494478ada7b7c57c2b31ca0d9d  dist/wowdata-windows-amd64.exe
+b44b01ae09db0b67e9f06518bdfbc3790ceb71fb4ac4bb4ac04b5be764b4c432  dist/wowdata-darwin-amd64
+c4613d552e8221417015915477fa84e69ed4df7b39a6eaa7403754cbb0daafba  dist/wowdata-darwin-arm64
+0765ff03d04ba2218d7317ece5ec85d7328f7af746a4ab58c33b25156c9bde53  dist/wowdata-linux-amd64
+ca7fc2c9739717be2992fb67de6d569c3eb40f888c6149b2a42a6ae88b9492dc  dist/wowdata-linux-arm64
+d0e575e2eea75d8ed8e6a4517b506ea3cb09bc89a6856d515618d4a179970384  dist/wowdata-windows-amd64.exe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@follenfang/wowdata",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Auditable CLI for querying World of Warcraft CASC and DB2 data",
   "license": "AGPL-3.0-or-later",
   "type": "commonjs",

package/skill/wowdata/SKILL.md

@@ -1,55 +1,36 @@
 ---
 name: wowdata
-description: Query and export World of Warcraft game data with the wowdata CLI, including CASC and DB2 schemas and rows, files, icons, textures, spells, encounters, items, creatures, decor, Builds, profiles, cache, and diagnostics. Use when a user asks to inspect or export WoW data from a local client or CDN, resolve a product/Build/locale target, or diagnose wowdata.
+description: Query and export World of Warcraft data with the wowdata CLI, including local or CDN CASC/DB2 data, read-only SQL atomic queries, independent Hotfix records, files, icons, textures, spells, encounters, items, creatures, decor, Builds, profiles, cache, and diagnostics. Use when a user asks to inspect, search, stream, decode, or export WoW data or diagnose wowdata.
 ---
 
 # wowdata
 
 Use the `wowdata` executable from `PATH`. This Skill is CLI-only: do not search for a bundled executable and do not use MCP or another server transport.
 
-## Resolve The Target
+## Choose the command
 
-Resolve the target before running a command that reads CASC or DB2 data.
+- Use `sql` for a read-only DB2 query, including joins, subqueries, CTEs, aggregates, ordering, limits, `EXPLAIN`, or `ANALYZE`. Read [sql.md](references/sql.md).
+- Use `hotfix query` for Hotfix records. Hotfix is an independent query system, not a DB2 SQL table. Read [hotfix.md](references/hotfix.md).
+- Use `db2` for schema, rows, search, foreign-key, and stream operations; use domain commands for semantic workflows; use `casc`, `file`, `icon`, `video`, `profile`, `cache`, `doctor`, or `warmup` for their named purposes. Read [commands.md](references/commands.md) when a flag or command shape is unfamiliar, and [tables.yaml](references/tables.yaml) when mapping a semantic request to DB2 tables.
 
-1. If the user gives a Profile, pass only `--profile <name>`. Do not combine a Profile with target flags.
-2. Resolve the product from the user's words or established conversation context. Read [clients.yaml](references/clients.yaml) for English and Chinese aliases. Product has no default; if it is still missing or ambiguous, ask one short product question and do not run a data command yet. Treat “硬核服” as a server rule, not a product: resolve its classic-era or anniversary product from context, or ask which one.
-3. Preserve every explicit source, path, region, product, Build, and locale value.
-4. When no source or local path is stated, use remote CDN data.
-5. For an otherwise unspecified remote target, pass `--source remote --region cn --build latest --locale zhCN` plus the resolved product.
-6. For `--source local`, require the client `--path` and complete every remaining target field explicitly. Do not replace missing local-client facts with guesses.
+## Resolve the target
 
-Never rely on CLI target defaults; the CLI intentionally has none. `--build latest` resolves at execution time, so never store a current Build number in this Skill. Read [locales.yaml](references/locales.yaml) when mapping natural-language locale names.
+Resolve the target before reading CASC or DB2 data.
 
-Commands that do not read a game target do not need the full target: `video demux`, `doctor`, `cache`, `profile`, `update`, and `uninstall`. `casc products` uses only source discovery flags such as `--source remote --region cn` or `--source local --path <client>`.
+1. If the user gives a Profile, pass only `--profile <name>`; do not combine it with target flags.
+2. Resolve product from the user's words or conversation context. Read [clients.yaml](references/clients.yaml) for aliases. Product has no default; if it remains ambiguous, ask one short product question before running a data command. Treat “硬核服” as a server rule and resolve its actual product from context.
+3. Preserve every explicit source, path, region, product, Build, and locale. Read [locales.yaml](references/locales.yaml) for locale aliases.
+4. If no source or local path is stated, use remote CDN. For an otherwise unspecified remote target, pass `--source remote --region cn --build latest --locale zhCN` plus the resolved product.
+5. For `--source local`, require `--path <client>` and complete the remaining target fields explicitly; never guess missing local-client facts.
 
-## Run Atomic Commands
+Never rely on CLI target defaults; the CLI intentionally has none. `--build latest` resolves at execution time and must not be hard-coded in this Skill.
 
-Call the business command directly. Do not run `warmup` before an ordinary query. The CLI checks Build identity and cache integrity, downloads missing data, then completes the original query in the same process.
+Commands that do not read a game target do not need the full target: `video demux`, `doctor`, `cache`, `profile`, `update`, and `uninstall`. `casc products` needs only source discovery flags.
 
-- Use `casc products` when the user asks which products or Builds exist.
-- Use `warmup` only when the user explicitly asks to download data ahead of time.
-- Use `doctor` after an environment, target, cache, or network failure needs diagnosis.
-- Read [commands.md](references/commands.md) before composing an unfamiliar command.
-- Read [tables.yaml](references/tables.yaml) when translating a semantic request into DB2 tables.
-- Never invent a DB2 field name from a natural-language label. If the user requests selected fields without giving exact schema names, run `db2 schema <table>` first, then use names returned by that schema.
-- Use `db2 rows`, never the obsolete `query rows` spelling.
-- Keep exports at the user-requested path, or in the current workspace when no path is given.
-- Do not run `cache clear`, `profile remove`, `update`, or `uninstall` unless the user explicitly requests that action.
+## Execute and report
 
-```powershell
-wowdata db2 rows SpellName --id 133 --source remote --region cn --product wow --build latest --locale zhCN
-wowdata item textures --item-id 19019 --profile retail-cn
-wowdata icon export --file-data-id 134400 --format png --output output/icon.png --source remote --region cn --product wow --build latest --locale zhCN
-```
+Call the business command directly. Do not run `warmup` before an ordinary query; the CLI prepares required dependencies in-process. Keep exports at the requested path, or the current workspace when no path is given. Do not run destructive maintenance (`cache clear`, `profile remove`, `update`, `uninstall`) unless explicitly requested.
 
-## Read Results
+Treat stdout, stderr, and exit status as one contract: progress on stderr is informational; stdout is the result. Exit `0` is success. Exit `1` with JSON stdout is a structured failure—report `error.code` and `error.message`; plain stderr indicates CLI parsing/setup failure. A successful zero-row response is valid; check ID, product, Build, and locale before changing the query.
 
-Treat the streams and exit status as one contract:
-
-- stderr contains preparation and download progress. If it reports `prepare` or `download`, let the command continue; do not start a separate warmup.
-- stdout contains the final JSON. `db2 stream` defaults to JSONL; parse it line by line or pass `--format json` when one JSON document is preferable.
-- Exit code `0` corresponds to `"ok": true`.
-- Exit code `1` with JSON stdout corresponds to `"ok": false`; report `error.code` and `error.message`. A CLI parsing error may instead be plain stderr.
-- An `"ok": true` response with zero rows is a valid empty result. Recheck the ID, product, Build, and locale before trying another query.
-
-Return the requested result, not download narration. Preserve the product, resolved Build, region, locale, table or ID, and output path/hash when present so the answer remains traceable.
+Preserve the resolved product, Build, region, locale, table/record identifiers, format, and output path/hash when present. Return requested data rather than download narration. See [errors.md](references/errors.md) for recovery decisions.

package/skill/wowdata/VERSION

@@ -1 +1 @@
-0.0.2
+0.0.3

package/skill/wowdata/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "wowdata"
-  short_description: "Query and export World of Warcraft data with the wowdata CLI"
-  default_prompt: "Use $wowdata to query or export WoW data with an explicit product and a complete target."
+  short_description: "Query WoW data with SQL, Hotfix, and CLI"
+  default_prompt: "Use $wowdata to run a targeted WoW DB2 SQL or Hotfix query with an explicit data target."

package/skill/wowdata/references/errors.md

@@ -0,0 +1,8 @@
+# Failure handling
+
+- Structured `{"ok":false,"error":{"code":...,"message":...}}` with exit `1`: report the code/message and retain the target and filters.
+- Plain stderr with a usage/flag error: read the relevant `--help`, correct only the malformed flag, and retry once.
+- Missing/ambiguous product, Build, locale, or local path: resolve from context or ask one concise question; do not guess.
+- Cache/DBD/schema mismatch: run `doctor` or `db2 schema` for the same target; do not silently switch product or Build.
+- Remote prepare/download failure: report provider and target, then retry with the same explicit target or use an explicitly requested local cache/profile. Do not launch a separate warmup unless requested.
+- Empty success: treat as valid; verify identifiers and locale before trying another source.

package/skill/wowdata/references/hotfix.md

@@ -0,0 +1,14 @@
+# Independent Hotfix queries
+
+Use `wowdata hotfix query`; do not express Hotfix lookups as DB2 SQL. The default source is Wago; select `dbcache` for a local `DBCache.bin` or `raidbots` for a recent snapshot.
+
+```powershell
+wowdata hotfix query --source dbcache --dbcache <DBCache.bin> --product <product> --build <build> --region <id> --locale <locale> --table <table> --record <id> --raw
+wowdata hotfix query --source wago --product wow_classic_titan --build 3.80.2.69137 --region 196 --locale zhCN --table SpellPowerDifficulty --latest --format json
+```
+
+Useful filters: `--table`, `--record`, `--push`, `--status`, `--search`, `--from`, `--to`, `--limit`, `--page`; `--decoded --dbd <definition>` adds decoded fields when the matching DBD is available. `--latest` returns the complete maximum-PushID batch. Output formats are `json`, `jsonl`, and `csv`; `--raw` preserves payloads.
+
+Wago `--search` is candidate acceleration, not exact filtering. The adapter must exact-filter product, Build, region, locale, table, record, and status after parsing. A zero candidate page is not proof of a complete miss. Preserve raw status and PushID ordering; report provider, filters, page/coverage, and cache provenance.
+
+Prefer local DBCache disk point lookups for immediate local data. Use Wago for remote history/complementary records and Raidbots only for recent snapshots. Do not route Hotfix through the static SQL path.

package/skill/wowdata/references/sql.md

@@ -0,0 +1,31 @@
+# wowdata-sql-v1 atomic queries
+
+Use `wowdata sql` for one read-only, atomic DB2 query. It executes against static DB2 data and emits one structured response; it does not query Hotfix records.
+
+## Input forms
+
+Provide exactly one SQL source:
+
+```powershell
+wowdata sql "SELECT ID, Name_lang FROM SpellName WHERE ID = :spell_id" --param spell_id=133 --format json <target>
+Get-Content query.sql -Raw | wowdata sql --stdin --format jsonl <target>
+wowdata sql --file query.sql --format csv <target>
+```
+
+`--param name=value` may be repeated. Parameters are named and should be used instead of interpolating user input. `--format` accepts `json` (default), `jsonl`, or `csv`.
+
+## Supported query shape
+
+The engine supports projections and aliases, predicates, `IN`, joins, scalar/subqueries, CTEs including recursive CTEs, grouping/aggregates, ordering, and limits. Use `EXPLAIN` for a plan without row reads and `EXPLAIN ANALYZE` (or `EXPLAIN ANALYZE SELECT ...`) for execution counters and timings:
+
+```sql
+EXPLAIN SELECT ID FROM SpellEffect WHERE SpellID = :spell_id;
+EXPLAIN ANALYZE SELECT se.ID, COUNT(*) AS n
+FROM SpellEffect se WHERE se.SpellID = :spell_id GROUP BY se.ID;
+```
+
+Table and field names must match the resolved Build's DBD schema. Use `wowdata db2 schema <table> <target>` first when uncertain. Keep result sets bounded with predicates and `LIMIT`; use `db2 stream` for a simple full-table stream.
+
+## Target and output rules
+
+Append a complete target or `--profile`. Local SQL regression should use `--source local --path <client>` and explicit product/Build/locale/region. SQL has no Hotfix fallback. Report the query source, parameters (redacting secrets), target, format, row count, and plan/timing fields when requested.