@follenfang/wowdata 0.0.1 → 0.0.3

package/LICENSE

@@ -1,10 +1,10 @@
-GNU AFFERO GENERAL PUBLIC LICENSE
-Version 3, 19 November 2007
-
-Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
-Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
-
-wowdata is licensed under the GNU Affero General Public License version 3 or any later version.
-
-Full license text:
-https://www.gnu.org/licenses/agpl-3.0.txt
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+
+wowdata is licensed under the GNU Affero General Public License version 3 or any later version.
+
+Full license text:
+https://www.gnu.org/licenses/agpl-3.0.txt

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,50 +78,90 @@ 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. 完成查询并返回最终结果。
-
-准备和下载进度写入 stderr，最终结构化结果写入 stdout JSON。多个独立 CDN 对象和清单默认使用 4 个 worker 并发下载；可以通过 `wowdata cache config --workers N` 调整。
-
-## 发现与提前准备
+4. 执行查询并返回最终 JSON。
 
-查看某个区域当前提供的真实产品和 Build 组合：
+只有需要提前准备数据时，才显式运行：
 
 ```bash
-wowdata casc products --source remote --region cn
+wowdata warmup --source remote --region cn \
+  --product wow --build latest --locale zhCN
+```
+
+独立 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": []
+}
 ```
 
-需要提前下载时再显式使用 `warmup`：
+- 成功：stdout 返回 `"ok": true`，退出码为 `0`。
+- 业务错误：stdout 返回 `"ok": false` 和结构化错误，退出码为 `1`。
+- 下载、缓存准备等进度只写入 stderr。
+- 参数解析错误写入 stderr，退出码为 `1`。
+
+普通 Shell 可以直接同时使用退出码和 JSON：
 
 ```bash
-wowdata warmup \
-  --source remote \
-  --region cn \
-  --product wow \
-  --build latest \
-  --locale zhCN
+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
 ```
 
-## 本地目录
+### 缓存与本地目录
 
 ```text
 ~/.wowdata/
@@ -89,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
@@ -110,66 +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
+```
+
+Save frequently used targets as Profiles:
+
+```bash
+wowdata profile set retail-cn \
+  --source remote \
+  --region cn \
+  --product wow \
+  --build latest \
+  --locale zhCN
+
+wowdata spell info --spell-id 123 --profile retail-cn
+```
+
+Discover the products and Builds currently available in a region:
+
+```bash
+wowdata casc products --source remote --region cn
 ```
 
-Go 负责数据解析和命令执行；Node.js 只负责 npm 安装、启动桥接和包生命周期，所有脚本都在 `npm/` 中可审计。
+### 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
+```
 
-推送语义版本 tag 会触发 GitHub Actions：
+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
-git tag v1.2.3
-git push origin v1.2.3
+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": []
+}
 ```
 
-工作流会测试 Go 和 npm、构建五个平台、生成 `SHA256SUMS`、创建 GitHub Release，并发布同版本 `@follenfang/wowdata`。
+- 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
+```
+
+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.
+
+---
 
 ## License
 
-AGPL-3.0-or-later
+[AGPL-3.0-or-later](LICENSE)

package/dist/SHA256SUMS

@@ -0,0 +1,5 @@
+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.1",
+  "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,39 +1,36 @@
 ---
 name: wowdata
-description: Use the wowdata CLI for World of Warcraft CASC, DB2, file, icon, spell, encounter, item, creature, decor, video, Build, cache, and diagnostic tasks.
+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
 
-CLI only. Run `wowdata` from PATH. Do not look for a bundled executable and do not use any server transport.
+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.
 
-## Target Contract
+## Choose the command
 
-Every data command must receive a complete target or an explicit `--profile`.
+- 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. Preserve source, path, region, product, Build, and locale when the user states them.
-2. For an unspecified remote region, Build, or locale, explicitly pass `--source remote --region cn --build latest --locale zhCN`.
-3. Product has no default. Resolve it from the user's words or the current conversation only when there is one unambiguous product. Otherwise ask the user which product they mean before running the CLI.
-4. Never rely on CLI defaults. The CLI intentionally has none.
+## Resolve the target
 
-Read [clients.yaml](references/clients.yaml) for stable product aliases and [locales.yaml](references/locales.yaml) for language aliases. Do not store a current Build number in this Skill.
+Resolve the target before reading CASC or DB2 data.
 
-## Atomic Use
+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.
 
-Call the business command directly. The CLI checks Build identity and cache integrity, downloads missing data, reports preparation on stderr, then returns the final JSON on stdout. Do not run `warmup` before ordinary queries.
+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.
 
-Use `casc products` only when the user asks which combinations exist. Use `warmup` only when the user explicitly asks to download data ahead of time. Use `doctor` when a command reports an environment, cache, target, or network problem.
+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.
 
-```powershell
-wowdata db2 rows SpellName --id 123 --source remote --region cn --product wow --build latest --locale zhCN
-wowdata spell info --spell-id 123 --source remote --region cn --product wow_classic --build latest --locale zhCN
-wowdata icon export --file-data-id 134400 --format png --output output/icon.png --source remote --region cn --product wow --build latest --locale zhCN
-wowdata casc products --source remote --region cn
-wowdata doctor
-```
+## Execute and report
 
-Read [commands.md](references/commands.md) before composing unfamiliar commands and [tables.yaml](references/tables.yaml) when mapping a semantic task to DB2 tables. Keep exported files in the user's requested directory or the current workspace.
+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.
 
-## Output
+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.
 
-Preparation and download progress is stderr. The final structured result is stdout JSON. Preserve product, resolved Build, region, locale, table, fileDataID, output path, and diagnostics in the answer so the result stays 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.1
+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 through the wowdata CLI.
-  default_prompt: Use wowdata atomic CLI commands with a complete explicit target. Default remote region/build/locale to cn/latest/zhCN in the Skill, and ask when product is unclear.
+  display_name: "wowdata"
+  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/clients.yaml

@@ -2,12 +2,28 @@ schema: wowdata.clients.v1
 clients:
   retail: wow
   ptr: wowt
+  正式服测试服: wowt
+  "正式服 PTR": wowt
   ptr2: wowxptr
   beta: wow_beta
   classic: wow_classic
+  怀旧服: wow_classic
   classic-ptr: wow_classic_ptr
+  "怀旧服 PTR": wow_classic_ptr
+  怀旧服测试服: wow_classic_ptr
   classic-beta: wow_classic_beta
   classic-era: wow_classic_era
+  怀中怀: wow_classic_era
+  "60级": wow_classic_era
+  香草服: wow_classic_era
   classic-era-ptr: wow_classic_era_ptr
   classic-anniversary: wow_anniversary
   classic-titan: wow_classic_titan
+  泰坦服: wow_classic_titan
+  泰坦重铸: wow_classic_titan
+  时光服: wow_classic_titan
+contextualAliases:
+  硬核服:
+    type: realm-rule
+    products: [wow_classic_era, wow_anniversary]
+    instruction: Do not treat as a product. Resolve the underlying classic-era or anniversary product from context; ask which one when unclear.

package/skill/wowdata/references/commands.md

@@ -1,24 +1,85 @@
 # Command Reference
 
-Run `wowdata <command> --help` when a flag is uncertain. Every data command needs either `--profile <name>` or a complete target.
+Run `wowdata <command> --help` when a flag is uncertain.
 
-| Intent | Atomic command |
+For commands that read CASC or DB2, append either:
+
+```text
+--profile <name>
+```
+
+or a complete target:
+
+```text
+--source remote --region <region> --product <product> --build <latest|version|build-id|config-key> --locale <locale>
+```
+
+Use `--source local --path <client>` plus explicit region, product, Build, and locale for a local client.
+
+## Discovery And Preparation
+
+| Intent | Command |
+| --- | --- |
+| List remote product/Build/locale combinations | `casc products --source remote --region <region>` |
+| List local client combinations | `casc products --source local --path <client>` |
+| Inspect resolved CASC and Build state | `casc info <target>` |
+| Diagnose CDN, root, encoding, archive, cache, and TACT state | `casc diagnose <target>` |
+| Download ahead of time | `warmup <target>` |
+
+Ordinary queries prepare their own dependencies. Do not call `warmup` as a prerequisite.
+
+## DB2 And Domain Queries
+
+| Intent | Command |
 | --- | --- |
-| Discover products and Builds | `casc products` |
-| Prepare data ahead of time | `warmup` |
-| DB2 schema, rows, text search, relations, stream | `db2 schema/rows/search/foreign-key/stream` |
-| Spell details, auras, summons | `spell info/auras/summons` |
-| Encounter tree | `encounter get` |
-| File lookup, search, type, fetch, existence, encoding, export | `file lookup/search/extension/get/exists/encoding/export` |
-| Export BLP icon | `icon export` |
-| Build and CASC state | `casc info/products/diagnose` |
-| Item data and assets | `item get/models/geosets/textures` |
-| Creature display and model | `creature display/model` |
-| Decor data | `decor list/get` |
-| Video container | `video demux` |
-| Named complete targets | `profile list/show/set/remove` |
-| Cache lifecycle | `cache status/verify/prune/clear/config` |
-| Installation diagnosis | `doctor` |
-| Package maintenance | `update`, `uninstall` |
-
-Do not use the obsolete `query rows` spelling. The command is `db2 rows`.
+| Inspect table fields and row count | `db2 schema <table> <target>` |
+| Read rows by ID | `db2 rows <table> --id <id[,id...]> [--fields <field,...>] <target>` |
+| Read multiple IDs | `db2 rows <table> --ids <id,...> <target>` |
+| Filter rows | `db2 rows <table> --filter <field=value> [--limit N] <target>` |
+| Search localized or text fields | `db2 search <table> --field <field> --query <text> [--limit N] <target>` |
+| Follow a numeric relation | `db2 foreign-key <table> --field <field> --value <id> <target>` |
+| Stream a large table | `db2 stream <table> [--fields <field,...>] [--filter <field=value>] [--limit N] [--format jsonl|json] <target>` |
+| Inspect spell relationships | `spell info --spell-id <id> [--max-depth N] <target>` |
+| Detect spell aura behavior | `spell auras --spell-id <id> <target>` |
+| Detect summoned NPCs | `spell summons --spell-id <id> [--npc-id <id>] <target>` |
+| Read an encounter section tree | `encounter get --journal-encounter-id <id> <target>` |
+| Read item metadata | `item get --item-id <id> <target>` |
+| Read item model and texture IDs | `item models --item-id <id> [--race-id N] [--gender 0|1] <target>` |
+| Read item geosets | `item geosets --item-id <id> <target>` |
+| Read item textures | `item textures --item-id <id> <target>` |
+| Read a creature display | `creature display (--display-id <id>|--file-data-id <id>) <target>` |
+| Find displays for a creature model | `creature model --file-data-id <id> <target>` |
+| List decor | `decor list [--limit N] <target>` |
+| Read decor | `decor get (--id <id>|--model-file-data-id <id>) <target>` |
+
+Never translate a semantic label such as "name", "description", or "model" directly into a guessed DB2 field. When exact field names are not supplied, run `db2 schema` first and use the returned names. Then use `--fields` to keep large row responses focused.
+
+## Files And Media
+
+| Intent | Command |
+| --- | --- |
+| Resolve a fileDataID | `file lookup --file-data-id <id> <target>` |
+| Search names in the listfile | `file search --query <text> [--limit N] <target>` |
+| List by extension | `file extension --extension <ext> [--limit N] <target>` |
+| Read file size and hash | `file get (--file-data-id <id>|--filename <name>) <target>` |
+| Read or write a raw file | `file get (--file-data-id <id>|--filename <name>) --output <path> <target>` |
+| Test existence | `file exists (--file-data-id <id>|--filename <name>) <target>` |
+| Inspect content/encoding keys | `file encoding --file-data-id <id> <target>` |
+| Export a raw file | `file export (--file-data-id <id>|--filename <name>) --output <path> <target>` |
+| Decode a BLP texture | `icon export --file-data-id <id> --format png|webp --output <path> [--mipmap N] [--mask N] <target>` |
+| Inspect a local VP9 AVI container | `video demux --input <file> [--output <directory>]` |
+
+`file get` without `--output` returns metadata, not raw bytes in JSON. Use `file export` or `file get --output` when the user needs an artifact.
+
+## Profiles, Cache, And Maintenance
+
+| Intent | Command |
+| --- | --- |
+| Manage complete targets | `profile list`, `profile show <name>`, `profile set <name> <target>`, `profile remove <name>` |
+| Inspect or verify cache | `cache status`, `cache verify` |
+| Manage cache | `cache prune`, `cache clear`, `cache config [--max-gb N] [--workers N]` |
+| Diagnose installation | `doctor` |
+| Update package | `update [--version latest|x.y.z]` |
+| Uninstall | `uninstall [--keep-data]` |
+
+Profile flags and explicit target flags are mutually exclusive. Treat cache clearing, Profile removal, update, and uninstall as explicit user actions.

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.