用途：让 Alpaca CLI 与上游 OpenAPI 规范保持同步。流程按阶段顺序执行，每阶段通过后再进入下一阶段。
主要能力与用法：
- 拉取规范：make spec-update 需要网络访问（会请求 docs.alpaca.markets），从 docs.alpaca.markets/openapi/ 下载 trading-api.json 与 market-data-api.json 到 api/specs/。之后用 git diff --stat api/specs/ 查看变更；若无变化可跳到第 4 阶段验证生成代码是否仍是最新。
- 生成代码：make generate 运行 go run ./cmd/generate，生成 internal/api/trading_types.gen.go、trading_client.gen.go、marketdata_types.gen.go、marketdata_client.gen.go、descriptions.gen.go 以及 internal/cmd/commands.gen.go。禁止直接编辑 *.gen.go 文件。
- 修复生成失败：生成器强制穷尽性，规范中每个 operationId 必须出现在 cmd/generate/commands.go 的 cmdRegistry 或 cmdSkip 中。注册新命令需提供 parent（须为 cmdParents 的键）、use（kebab-case）、examples（必填）等；可加 defaults、bodyAliases、bodyHook/bodySkipFields、configureFunc、normalize。命令即父级时用 self: true 并省略 use。跳过操作需在 cmdSkip 中写明原因。新增父组需加入 cmdParents，嵌套组设 parent；顶层父组还需在 internal/cmd/root.go 的 addGroup() 中接线，否则不会出现在 --help 中。
- 更新 golden 文件：go test ./internal/cmd -run TestCommandTreeGolden -update 与 go test ./internal/cmd -run TestOpsGolden -update。
- 运行全部检查：make check（golangci-lint、go test -race ./...、go build）。
- 验证完整性：git diff --stat 检查 specs、生成文件、golden、注册表、root.go 及 test/integration/。新增命令需按 AGENTS.md 规则补集成测试；命令或标志变动需同步文档。
限制与反模式：不得直接编辑 *.gen.go 或 api/specs/ 中的规范文件；生成后不得跳过 make check；更新 golden 前须审阅 diff；cmdRegistry 条目必须有 examples；cmdSkip 必须写原因。集成测试 make test-integration 需要 API 密钥。