用途：mdsql 对一棵 markdown 文件树的 YAML frontmatter 运行 SQL。每个文件是 docs 表中的一行（每个 frontmatter 键为一列），文件的正文内容不会被查询，只查询 frontmatter。无需运行中的应用，磁盘文件是唯一数据来源。
安装与准备：先确认已安装，可用 mdsql --list 或 which mdsql 检查；若缺失可执行 npm install -g mdsql。同时需要存在配置。发现机制会从当前工作目录向上查找 mdsql.config.json，类似 git 查找 .git，因此无需先 cd 到项目根目录；--config <path> 可完全绕过该发现机制。若被查询的目录树中还没有配置，可在其根目录运行 mdsql init 生成起始配置，再按需调整查询。
查看与运行：mdsql --list 打印配置中定义的命名查询（已排序）；需要看 SQL 本身可直接读取该文件。运行方式为 mdsql <name> [params...] --format json。作为 agent 消费输出时优先使用 --format json，结构清晰且免于解析带填充的文本表格；--format table 为默认格式，适合终端中人工查看。命名查询可含 ? 占位符，查询名后的位置参数按顺序绑定；参数个数会被严格校验，数量不对属于用法错误（退出码 2），不会静默返回空结果。示例：mdsql by-tag urgent --format json。
has() 语义：这是唯一的自定义 SQL 函数，用于数组或自由文本类型的 frontmatter 字段。若字段为 JSON 数组（如 tags），表示数组成员匹配；若为字符串，表示子串匹配；若为 NULL（键缺失），始终为 false。
添加命名查询：直接编辑 mdsql.config.json，它是普通 JSON。示例结构为 scan.include 指定如 **/*.md，queries 中定义查询，如 SELECT path, title FROM docs WHERE has(tags, ?) ORDER BY path。scan.include 的 glob 与查询结果都相对于配置文件所在目录，与当前工作目录无关。保留列（不可用作 frontmatter 键名）：path、_mtime、_size。
退出码：0 成功；1 真实错误（配置错误或 SQL 错误，SQLite 消息原样打印）；2 用法错误（缺少查询名、未知查询名、参数个数错误）。
结果疑似过期时：mdsql rebuild 会删除本地 .mdsql/ 缓存并从头重新抓取所有文件。每次查询在打开时已把缓存与文件系统对账，因此通常很少需要；若怀疑缓存，用它重建即可，而不必调试。mdsql status 显示文档数量、数据库路径，以及后台 mdsql watch 进程是否在运行（watch 只是可选的预热器，不影响正确性）。