draftgo-cli 4.0.1 → 4.0.23

package/resources/skill/references/methods.md

@@ -0,0 +1,189 @@
+---
+read_when: 不确定 DraftGo 任务应使用 API/MCP 还是 checkout；需要 AIHub、数据、内容、自定义服务、诊断或交付的最短正确命令链时
+---
+
+# 极简方法指南
+
+只使用本页列出的真实 CLI 命令。动态 operation、字段、权限和响应以当前服务器为准；不知道精确契约时统一执行：
+
+```bash
+draftgo api search "<能力或资源>"
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+```
+
+已有准确 `operation_id` 且缓存 revision 未变化时可跳过 search；describe 不完整时停止，不猜字段、operation ID 或 URL。`request.json` 必须是 UTF-8 JSON object，并按 describe 使用 `path`、`query`、`body` 或 `multipart` 容器。
+
+所有 `--output json` 命令都将单一 UTF-8 JSON 写到 stdout，诊断写入 stderr。先选择摘要、精确筛选或分页，避免用终端截断处理大结果。
+
+## AIHub
+
+适用场景：查询或管理 Agent、模型、供应商、路由、Skill、Prompt，或验证一次 AI 调用。
+
+```bash
+draftgo api search "AIHub <agent|model|provider|route>"
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+draftgo api search "AI run logs"
+```
+
+关键约束与失败定位：AIHub 是结构化远端资源，不 checkout；只传 describe 允许的字段。不得把 API Key、Authorization、供应商 header 或上游地址写入文件和日志。401/403 查登录、`aihub:*` 权限和资源调用策略；503 查模型路由、适配器与凭据是否就绪。
+
+完成条件：写入后的目标 ID 可由 get/list operation 回读；任务涉及调用时，调用成功且 run 能按入口 Agent/模型或 request ID 定位。完整字段和编排规则再读 `aihub.md`。
+
+## 知识库与记忆
+
+适用场景：知识库、文档、Chunk、检索/重建，以及 Agent 长期记忆和作用域配置。
+
+```bash
+draftgo api search "knowledge base"
+draftgo api search "agent memory"
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+```
+
+关键约束与失败定位：知识库保存可检索资料，记忆保存运行时提炼结果，不能互相替代。知识库操作使用独立的 `knowledge:*`，不会继承 `aihub:*`。上传、检索、重建和记忆字段均以 describe 为准；没有专用 CLI 子命令。检索为空时依次核对文档状态、索引/重建结果、作用域和调用权限。
+
+完成条件：目标资源可回读；任务涉及检索或记忆召回时，最小验证调用能返回预期范围的数据，且运行日志可关联。
+
+## 统一权限与数据范围
+
+适用场景：设计角色、组织授权、动态 DB CRUD、知识库或自定义服务的资源归属。
+
+```text
+Role          = 无作用域的权限模板
+AccessGrant       = 主体在哪个 platform/space 范围获得 Role
+WorkspaceMember  = 加入根工作区的关系，本身不授权
+ResourceOwnership = 资源持久化归属，服务端最终判定边界
+DataRange     = 作用域内记录策略：none / own / all
+```
+
+platform AccessGrant 可跨空间，但只覆盖角色中显式列出的权限；space Grant 只能覆盖同根的 self/subtree。请求 header 只是候选上下文。
+创建、读取、更新、删除都必须由服务端同时校验动作权限、持久化 ResourceOwnership 和 DataRange。
+
+### 空间化最短流程
+
+开始前只运行一次 `draftgo status` 确认连接健康和 API Key 当前范围；需要选择空间时再运行 `draftgo space list`。目标 operation 仍须以实时 `describe` 的 `permission`、`supported_scopes` 和 `ownership_mode` 为准。
+
+| 场景 | 最短正确做法 |
+|---|---|
+| 单空间 | 固定使用该业务空间；调用输入传 `scope_type=space` 和目标 `space_id`。不为“方便”创建 platform Grant、子空间或用户组。 |
+| 多空间 | 每次先确定目标空间，再以该 `space_id` 调用；切换空间后重新读取目标资源。不要缓存一个空间的资源 ID 后在另一个空间复用。 |
+| 平台跨空间 | 仅当 operation 的实时契约支持 `platform`，且当前用户的 platform AccessGrant 明确包含所需 permission 时传 `scope_type=platform`。普通空间写入仍选择具体空间。 |
+| 超级管理员普通使用 | 与普通用户相同，选择当前业务空间并传 `scope_type=space`。管理员身份不把资源改成 platform 归属，也不绕过 Authorizer、DataRange 或持久化 ownership。 |
+
+空间调用输入只增加实时 MCP 支持的范围字段，其余容器仍按 `describe` 填写：
+
+```json
+{"scope_type":"space","space_id":120,"path":{},"query":{},"body":{}}
+```
+
+平台调用使用 `{"scope_type":"platform", ...}` 且不传 `space_id`。对已有资源的按 ID 操作，客户端选择的范围不能覆盖服务端已保存的 ResourceOwnership；403 时进入 `diagnostics.md`，不要改 ID 或扩大范围反复试探。
+
+## 页面、导航与内容
+
+适用场景：修改已有 page/navigation/article 完整正文，或创建后继续编辑正文。
+
+```bash
+draftgo map --type pages --route /admin/channel-ops --output json
+draftgo checkout pages <id>
+draftgo diff pages <id> --stat
+draftgo verify pages <id>
+draftgo commit pages <id>
+```
+
+导航将 `pages` 换为 `nav`，文档文章换为 `docs`。`--route` 与 `--title` 均为精确匹配，同时给出时取交集；CLI 会先用资源搜索缩小候选，再在本地判定精确结果。只需确认范围、数量和 checkout 状态时使用 `map --summary`；必须浏览时使用 `--limit <1-100>`（默认 20），并仅在单一 `--type` 下用返回的 `--cursor <opaque>` 请求下一页。`map --summary` 不含 project overview、资源列表或 hash。`diff --stat` 显示文件与增删行数，`diff --summary` 显示资源、版本和变化概览；只有需要审查正文时才运行不带这两个参数的 `diff`。新资源先发现创建契约并取得 ID：
+
+```bash
+draftgo api search "create <page|navigation|article>"
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+draftgo checkout <pages|nav|docs> <id>
+```
+
+关键约束与失败定位：checkout 只处理已存在资源的完整正文，不负责创建。409/412 时停止提交，使用 `draftgo conflicts` 和 `draftgo conflict show <type> <id>` 检查保留的 base/local/remote；不要 force、覆盖或自动合并。
+
+完成条件：commit 返回新版本/哈希，随后 `draftgo check --remote --output json` 显示本地基线与远端一致。正文和冲突细节再读 `checkout.md`，页面运行规则再读 `frontend.md`。
+
+## 动态数据
+
+适用场景：管理 `db_meta` schema、权限、关系，或查询/写入动态 DB 记录。
+
+```bash
+draftgo api search "db meta"
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+draftgo api search "dynamic db record"
+```
+
+关键约束与失败定位：schema 和记录都是结构化远端资源，不 checkout。创建或更新 schema 后先回读目标 `type`，再按实时记录 operation 做最小 CRUD。400 优先核对 searchable、filter 操作符和字段容器；403 核对 `db_meta` permission 与记录 owner；列表不完整先核对分页，不用超大 page size 假装全量。
+
+完成条件：schema 可按 `type` 回读，目标角色的最小 CRUD/筛选符合预期；批量写入还需验证失败时整批回滚。字段和关系规则再读 `data.md`。
+
+## 自定义服务
+
+适用场景：编写、保存、验证、试运行或发布 Go 自定义服务。
+
+```bash
+draftgo api search "custom service create"
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+draftgo checkout custom-services <id>
+draftgo diff custom-services <id>
+draftgo commit custom-services <id>
+draftgo validate custom-services <id>
+draftgo test custom-services <id> --source draft --handler route:POST:/path --input request.json
+draftgo publish custom-services <id>
+```
+
+关键约束与失败定位：自定义服务只有一种 Go `Register` 形态；后端从 `Register` 自动发现 Route/Event/Scheduled handler，不需要配置服务模式或 `triggers` 字段。worktree 只含 `service.go` 和 `service.json`，`go.mod/go.sum` 由 Runner 管理。`commit custom-services` 自动完成提交、验证和发布。余额、权益、支付和订阅使用 `ctx.Billing` / `ctx.Admin.Billing`，精确签名读 checkout 后的 `.draftgo-sdk/billing.go`，不要用动态 DB 自建账本。试运行默认拒绝副作用；真实写入必须显式使用 `--side-effect-policy live --test-write`。validate 失败查编译/Register/依赖；test 失败按 execution/request ID 查运行日志；revision 冲突停止重试。
+
+完成条件：`commit custom-services` 返回 published 且 validate passed；需要运行行为证据时再要求 test success。完整 SDK、handler selector 和依赖规则再读 `custom-services.md`。
+
+## MCP 与实时契约
+
+适用场景：首次连接、宿主配置变化、工具不可用，或不知道 operation/schema。
+
+```bash
+draftgo mcp status
+draftgo mcp test
+draftgo api search "<业务能力>"
+draftgo api describe <operation_id>
+```
+
+关键约束与失败定位：已配置且健康时不必每个任务重复 setup/status/test。宿主配置只运行 `draftgo mcp serve`，不得保存 API Key。401/403 查用户 API Key 和 grant；session/uninitialized 重新建立连接；operation 不唯一时继续缩小 search；describe 缺字段、风险或响应契约时停止。
+
+完成条件：initialize、tools/list、关键 tools/call 可用，目标 operation schema 已确认且可回读一次无副作用结果。完整缓存、风险和 multipart 规则再读 `mcp.md`。
+
+## 运行诊断
+
+适用场景：连接失败、API 调用失败、checkout 状态异常，或需要定位 AI/custom-service run。
+
+```bash
+draftgo mcp status
+draftgo mcp test
+draftgo map --type pages --summary --output json
+draftgo check --remote --output json
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+```
+
+关键约束与失败定位：只运行与故障层级相关的命令。保留脱敏的 `operation_id`、`status_code`、`server_code`、`request_id`；非幂等写失败后先回读状态，不自动重试。连接问题看 mcp test，正文版本看 check/conflicts，AI 与服务运行问题再 search 对应日志 operation。
+
+完成条件：故障被定位到连接、契约、权限、资源版本、Runner 或业务运行中的一层，并有 request ID/run 等可关联证据。完整分流再读 `diagnostics.md`。
+
+## 交付验收
+
+适用场景：准备提交、发布、交付或关闭 worklog 项目。
+
+```bash
+draftgo verify
+draftgo check --remote --output json
+draftgo work complete <ref> --note "<结果与证据>"
+```
+
+正文资源在 complete 前还必须成功执行 `diff -> commit`；结构化资源必须 call 后回读；自定义服务按任务要求追加 validate/test/publish。默认不启动浏览器，只有用户明确要求视觉验收时才使用 `draftgo verify --url <url> --screenshot always`，需要 DOM/交互时再加 `--ui always`。
+
+关键约束与失败定位：本地验证通过不等于已提交或已发布。任何 verify、commit、MCP 写入、必要 test/publish、回读或视觉验收失败时，工作项保持 active。
+
+完成条件：全部目标远端状态可回读，正文版本/哈希或结构化状态符合预期，任务要求的运行/视觉证据齐全且不含凭据，然后才 complete。

package/resources/skill/references/modules.md

@@ -11,22 +11,43 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 | 页面 | 数据库 HTML（`page.value.html`） | 已有页面由 MCP 定位后 `checkout pages` / `commit pages`；新页面先按实时 API 契约创建并取得 ID |
 | 导航栏 | 数据库 HTML（`navigation.html`） | MCP 定位，`checkout nav` / `commit nav` 编辑正文 |
 | 动态 DB | db_meta 定义 schema 并操作结构化记录 | MCP `api_search` / `api_describe` / `api_call` |
-| 自定义服务 | Go `Register` 服务，支持 route/event/scheduled 混合注册 | MCP 实时 API；不创建本地镜像 |
+| 文件资产 | 文件夹、文件元数据、绑定、下载、回收站和对象存储 | MCP 实时 API；文件字节不进入普通 tool result |
+| 自定义服务 | 单一 Go `Register` 服务；后端从注册代码自动发现 Route/Event/Scheduled handler | MCP 定位/创建；正文用 `checkout custom-services` / `commit custom-services` |
 | AIHub | 配置 AI Agent（模型/编排/能力/子智能体/记忆）；页面对话使用 `<dg-chat>`，图片模式使用 `DraftGoAI.images`；见 `references/chat-sdk.md` 与 `references/aihub.md` | MCP 实时 API；不创建本地镜像 |
 | 文档中心 | Markdown/HTML 文章 + 分类树 | 正文用 `checkout docs` / `commit docs`；分类用 MCP |
 | 系统配置 | KV 存储，含全局前端层槽位 | MCP 实时 API；不创建本地镜像 |
+| 商业与计费 | 账本、余额、权益、支付订单、退款、套餐、订阅和 AI 计费 | 管理任务用 MCP 实时 API；自定义服务用 `ctx.Billing` / `ctx.Admin.Billing`；不要用动态 DB 重建金钱状态 |
 
 ## 平台内置模块（开箱即用，不需实现）
 
 | 模块 | 能力 | 调用方式 |
 |---|---|---|
 | 认证 | 注册/登录/刷新/找回密码/微信登录/手机邮箱验证 | 页面使用 `App`；服务端操作通过 MCP 实时描述接口 |
-| 角色权限 | 多角色 RBAC，页面/DB/API 均支持角色级权限 | `App.isAdmin` / `App.currentUser.role_code` |
+| 角色权限 | 无作用域 Role 模板 + 带 `platform` / `space` 范围的 AccessGrant | 页面可用 `App.permissions` 辅助显隐；服务端按资源授权 |
+| 工作区与空间 | 根工作区成员、用户组和递归 Space；成员关系本身不授权 | `App.scopeContext` + MCP space/group/grant operations；资源保存直接归属 |
+| 动态数据范围 | `DataRange=none|own|all`，限制空间内的记录级访问 | db_meta 的记录策略；不替代 ResourceOwnership 或 AccessGrant |
 | 通知公告 | 发布公告，支持类型/状态/分页 | MCP 实时 API |
 | 工单反馈 | 用户提交问题，支持类型/状态跟踪 | MCP 实时 API |
 | 备份恢复 | 完整/选择性备份，JSON/.dgbak 格式，支持 dry-run | MCP 实时 API |
 | 系统管理 | 系统配置 KV、存储健康、全局前端层、通知测试 | MCP 实时 API |
 
+`App.currentUser.role_code` 是展示投影，不是用户表中的可写字段。真正的资源/API 授权由服务端根据 ResourceOwnership 与有效 AccessGrant 决定；platform Grant 也只能使用角色中显式声明的权限。
+
+用户 API Key 只是一种用户认证方式；它不改变 AccessGrant、ResourceOwnership、DataRange 或管理员边界。服务身份是平台运行时主体。
+
+## 新模块权限接入检查表
+
+AI 新建或扩展受保护模块时，按以下最小闭环逐项确认；缺少任一项都不能用页面显隐、角色名或调用来源补洞：
+
+- [ ] 在统一 Permission Catalog 注册每个 `resource:action`，声明支持的 `platform` / `space` 范围以及是否使用 DataRange；不在模块内另建权限字符串或角色分支。
+- [ ] 顶层资源持久化 canonical ResourceOwnership：platform，或完整的 `ownership_type=space + workspace_id + space_id`；需要 own/all 时同时保存 `owner_user_id`。子资源只能通过不可变父键继承归属。
+- [ ] 创建和列表只接受服务端验证后的范围上下文；读取、更新、删除及其他按 ID 操作先加载持久化 ownership，忽略客户端提交的 workspace、space、owner 或调用者替代值。
+- [ ] 使用统一 Authorizer 校验真实 Principal、Catalog permission 和持久化 ResourceOwnership；执行记录级操作时继续应用返回的 DataRange，不能把 `all` 解释为跨工作区。
+- [ ] HTTP、MCP、SDK、Route、Event、Schedule 和 worker 等所有实际入口复用同一授权路径；TokenScope 只能对最终权限取交集并收窄。
+- [ ] 保留最小拒绝证据：无 Grant、space Grant 跨根、伪造归属；支持 own/all 时再覆盖他人记录拒绝。不要为同一规则复制一套测试框架。
+
+实现位置和具体 API 以目标 DraftGo 服务端仓库的现有 Catalog、ResourceOwnership 与 WorkspaceAuthorizer 模式为准；本 Skill 不复制服务端动态 schema。
+
 ## 模块选型决策
 
 ```
@@ -34,20 +55,27 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
   → 有固定结构 → 动态 DB（db_meta 定义 schema）
   → 仅需 KV → sys_config（category 自定义）
 
+要保存文件？
+  → 文件夹、上传、下载、回收站或业务绑定 → 文件资产模块；不要把文件字节塞进动态 DB
+
+要做余额、支付、会员或订阅？
+  → 管理操作走 money/payment/subscription/billing 的 MCP 实时契约；自定义服务读 `.draftgo-sdk/billing.go` 并使用 Billing SDK，不自行实现账本或扣费一致性
+
 要调用 AI？
   → 聊天/问答 UI → AIHub + `<dg-chat>`（自动隔离 thread/session）
   → 无 UI 的旧代码文本调用 → AIHub + DraftGoAI.chat()（兼容门面）
   → 图片生成 → AIHub + DraftGoAI.images()
+  → Responses、Embedding、Rerank、TTS、ASR 或 Video → AIHub capability 与 provider readiness；先确认模型的 canonical capability 和 transport
   → 需要工具/子智能体/记忆/结构化输出/多模态 → 都是 Agent spec 开关，见 references/aihub.md
 
 要调用第三方服务？
-  → 自定义服务（用 `draftgo.HTTP` 请求；需要时可用 route/event/scheduled 加工）
+  → 自定义服务（用 `ctx.HTTP` 请求；在同一 Go 服务中按需注册 Route/Event/Scheduled handler）
 
 要展示内容文档？
   → 文档中心（Markdown + 分类树）
 
 要做定时任务或事件响应？
-  → 自定义服务（mode: scheduled / event）
+  → 自定义服务（用 `app.Schedule` / `app.On` 注册；后端自动识别定时任务和事件 handler）
 
 要做后台管理页？
   → 业务页面 + 动态 DB + 角色权限
@@ -56,11 +84,11 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 ## 自定义服务边界
 
 - 新服务使用 Go `Register(app *sdk.App)` 自动注册路由、事件和定时任务；完整语言、`draftgo` 和 SDK 契约见 `references/custom-services.md`。
-- `route`：对外暴露 HTTP 端点；同一 Go 服务可用多个 `app.Route(method, path, handler)` 注册多个端点，实际路径通过 MCP 实时发现，保存或发布后要真实请求验证。
-- `event`：响应平台事件，如 `db.created` / `db.updated` / `user.registered`；用 `app.On(event, handler)` 注册，可为同一事件注册多个 handler。
-- `scheduled`：用 `app.Schedule("分 时 日 月 周", handler)` 注册 cron；同一服务可声明多个定时 handler。
+- `Route`：对外暴露 HTTP 端点；同一 Go 服务可用多个 `app.Route(method, path, handler)` 注册多个端点，实际路径通过 MCP 实时发现，草稿行为先用 `draftgo test custom-services` 验证。
+- `Event`：响应平台事件，如 `db.created` / `db.updated` / `user.registered`；用 `app.On(event, handler)` 注册，可为同一事件注册多个 handler。
+- `Scheduled`：用 `app.Schedule("分 时 日 月 周", handler)` 注册 cron；同一服务可声明多个定时 handler。
 - 新 Go 服务的 `Register` 是唯一触发器事实来源；旧 `triggers` 字段不参与注册。
-- 管理面由角色 RBAC 的 `scripts:*` 动作控制；Route 调用面继续由每个服务的 `permission` / `route_security` 独立控制，不要把两层权限混为一谈。
+- 管理面由角色 RBAC 的 `scripts:*` 动作控制；Route 不再读取服务级 `permission`，由宿主认证、持久化 ownership 和 `scripts:execute` AccessGrant 统一控制。
 - Go 服务在独立子进程中构建/运行；只有可信角色才能获得 `scripts:create` / `scripts:update`。
 - 自定义服务适合服务端加工、鉴权后聚合、第三方回调、定时任务和事件响应；普通 CRUD 管理界面优先用“页面 + 动态 DB”，不要把所有业务后台都塞进 route 脚本。
-- 脚本内读动态 DB 用 `draftgo.DB.Query(type, sdk.QueryOptions{...})`；返回 `sdk.QueryResult`，分页和筛选见 `references/custom-services.md`。
+- 脚本内读动态 DB 用 `ctx.DB.Query(type, sdk.QueryOptions{...})`；返回 `sdk.QueryResult`，分页和筛选见 `references/custom-services.md`。

package/resources/skill/references/runtime.md

@@ -35,7 +35,7 @@ read_when: 需要理解运行时机制时 · 处理 token/路由/事件相关问
 
 壳层将 `app` 对象赋值给 `window.App`，页面通过 `window.parent.App` 访问。
 
-`app` 组成：`api.js`（请求）+ `feedback.js`（弹窗/Toast）+ `runtime.js`（路由/主题）+ `i18n.js`（国际化）+ state（currentUser/isAdmin/config/theme）
+`app` 组成：`api.js`（请求）+ `feedback.js`（弹窗/Toast）+ `runtime.js`（路由/主题/作用域）+ `i18n.js`（国际化）+ state（currentUser/isAdmin/config/theme/scopeContext）
 
 完整 API 见 `references/app-api.md`
 
@@ -103,3 +103,25 @@ registry revision 变化时 `draftgo_api_describe`，再用 `draftgo_api_call`
 
 页面管理中 Toast 时长以秒输入，`sys_config` 中仍以毫秒存储。例如 UI 中
 `错误 Toast 时长(s) = 4.5` 对应 `frontend_global_toast_duration_error.config_value = 4500`。
+
+## 统一作用域
+
+DraftGo 的资源归属和授权范围只有 `platform`、`space`。`Role` 是无作用域权限模板；`AccessGrant`
+定义 user/group/service 主体在哪个范围拥有该角色。工作区成员与用户组成员关系本身不授予权限。
+
+`platform` Grant 可跨全部空间，但只能使用 Role 中显式列出的权限。`space` Grant 仅覆盖同一根工作区内的
+目标空间或 subtree；所有授权为 allow-only 并集，DataRange 使用 `all > own > none`。
+
+页面需要切换工作范围时使用 `App.getScopeContext()`、`App.setScopeContext(context)`，不要把
+space id 当作自定义权限判断。上下文只是请求意图，服务端仍以持久化 `ResourceOwnership` 和有效 AccessGrant 为准。
+API 请求只使用 `X-DraftGo-Scope-Type` 与 `X-DraftGo-Space-Id`；workspace_id 由服务端推导。
+
+动态 DB 的 `DataRange`（数据库元数据中的记录策略）是另一层：`none` 拒绝动作，`owner` 仅允许当前
+所有者记录，`all` 允许当前 ResourceOwnership 内全部记录。它不能扩大 `platform` / `space` 范围；
+不要把 `all` 解释成跨工作区。记录的 `userid` 是当前兼容实现的所有者字段，`created_by` / 独立
+`owner_user_id` 只有在服务端契约明确提供后才能使用。
+
+认证边界：交互式 CLI、MCP 和普通 HTTP API 使用当前用户的 API Key；该凭据始终代表该用户，权限来自
+用户及用户组的 AccessGrant，TokenScope 只能收窄，不能变成管理员或服务身份。CI、定时任务和共享服务等
+无人值守自动化使用平台的独立服务凭据通道；service principal 由平台内部注入，CLI 不生成、导出或伪造
+服务身份凭据。

package/src/cli.js

@@ -8,6 +8,7 @@ const VALUE_FLAGS = new Set([
   'target',
   'server',
   'mcp-url',
+  'api-key',
   'token',
   'output',
   'url',
@@ -29,12 +30,35 @@ const VALUE_FLAGS = new Set([
   'params',
   'input',
   'type',
+  'route',
+  'title',
+  'limit',
+  'cursor',
   'date',
   'handler',
+  'source',
   'headers',
   'user',
   'side-effect-policy',
+  'page',
+  'instance',
   'note',
+  'file',
+  'library',
+  'name',
+  'slug',
+  'category',
+  'description',
+  'tags',
+  'source-type',
+  'status',
+  'scope-type',
+  'space-id',
+  'module',
+  'resource-type',
+  'method',
+  'risk',
+  'permission',
 ]);
 
 function parse(argv) {

package/src/commandRegistry.js

@@ -6,7 +6,7 @@ const commands = [
   { name: 'init', run: (dir, args, flags) => require('./commands/init')(dir, args, flags) },
   { name: 'update', run: (dir, args, flags) => require('./commands/update')(dir, args, flags) },
   { name: 'uninstall', run: (dir, args, flags) => require('./commands/uninstall')(dir, args, flags) },
-  { name: 'status', run: (dir) => require('./commands/status')(dir) },
+  { name: 'status', run: (dir, args, flags) => require('./commands/status')(dir, args, flags) },
   { name: 'work', run: (dir, args, flags) => require('./commands/worklog')(dir, args, flags) },
   { name: 'clean', run: (dir, args, flags) => require('./commands/clean')(dir, args, flags) },
   { name: 'map', run: (dir, _args, flags) => require('./commands/map')(dir, flags) },
@@ -24,12 +24,20 @@ const commands = [
   { name: 'conflicts', run: (dir, args, flags) => require('./commands/conflicts')(dir, args, flags) },
   { name: 'conflict', run: (dir, args, flags) => require('./commands/conflict')(dir, args, flags) },
   { name: 'api', run: (dir, args, flags) => require('./commands/api')(dir, args, flags) },
+  { name: 'space', run: (dir, args, flags) => require('./commands/space')(dir, args, flags) },
+  { name: 'group', run: (dir, args, flags) => require('./commands/group')(dir, args, flags) },
+  { name: 'grant', run: (dir, args, flags) => require('./commands/grant')(dir, args, flags) },
+  { name: 'api-key', run: (dir, args, flags) => require('./commands/apiKey')(dir, args, flags) },
+  { name: 'role', run: (dir, args, flags) => require('./commands/role')(dir, args, flags) },
+  { name: 'data-range', run: (dir, args, flags) => require('./commands/dataRange')(dir, args, flags) },
   { name: 'delete', run: (dir, args, flags) => require('./commands/delete')(dir, args, flags) },
   { name: 'deploy', run: (dir, args, flags) => require('./commands/deploy')(dir, args, flags) },
   { name: 'auto-push', run: (dir, args, flags) => require('./commands/autoPush')(dir, args, flags) },
   { name: 'local', run: (dir, args, flags) => require('./commands/local')(dir, args, flags) },
   { name: 'list-targets', run: () => require('./commands/listTargets')() },
   { name: 'connect', run: (dir, args, flags) => require('./commands/connect')(dir, args, flags) },
+  { name: 'components', run: (dir, args, flags) => require('./commands/components')(dir, args, flags) },
+  { name: 'capabilities', run: (dir, args, flags) => require('./commands/capabilities')(dir, args, flags) },
 ];
 
 const aliases = new Map();

package/src/commands/api.js

@@ -5,8 +5,15 @@ const path = require('path');
 const log = require('../logger');
 const { confirm } = require('../prompt');
 const { loadProjectConfig } = require('../projectConfig');
-const { TOOL_NAMES, openToolSession, callStructured } = require('../mcp/tools');
+const { TOOL_NAMES, openToolSession, callStructured, configuredScope } = require('../mcp/tools');
 const { cachedDescription, normalizeDescription, storeDescription } = require('../apiContractCache');
+const {
+  isContractCompatibilityError,
+  isHardContractIncompatibility,
+  isDangerousOperation,
+  sameOperationContract,
+  incompatibleOperationError,
+} = require('../contractCompatibility');
 
 function readCallInput(projectDir, flags) {
   const raw = flags.input
@@ -81,8 +88,8 @@ async function callOperation(projectDir, operationId, flags = {}) {
   } catch (error) {
     return printCallError(operationId, error, flags);
   }
-  const destructive = description.operation.destructive === true;
-  if (destructive && !flags.yes && !flags.y) {
+  const dangerous = isDangerousOperation(description);
+  if (dangerous && !flags.yes && !flags.y) {
     const approved = await confirm(`Call destructive DraftGo operation ${operationId}?`, { default: false });
     if (!approved) return 0;
   }
@@ -90,21 +97,25 @@ async function callOperation(projectDir, operationId, flags = {}) {
   try {
     const invoke = (contract, confirmed) => callStructured(session, TOOL_NAMES.apiCall, {
       ...input, operation_id: operationId, registry_revision: contract.registry_revision,
+      ...configuredScope(config, contract),
       ...(confirmed ? { confirm: true } : {}),
     });
     try {
-      result = await invoke(description, destructive);
+      result = await invoke(description, dangerous);
     } catch (error) {
-      if (error.code !== 'CONTRACT_CHANGED') throw error;
+      if (!isContractCompatibilityError(error)) throw error;
+      if (isHardContractIncompatibility(error)) {
+        throw incompatibleOperationError(operationId, error);
+      }
+      const previousDescription = description;
       const described = await callStructured(session, TOOL_NAMES.apiDescribe, { operation_id: operationId });
       description = storeDescription(projectDir, config.server, described) || normalizeDescription(described);
       if (!description) throw new Error('DraftGo API description is missing contract revision metadata.');
-      const changedDestructive = description.operation.destructive === true;
-      if (changedDestructive && !destructive && !flags.yes && !flags.y) {
-        const approved = await confirm(`Call destructive DraftGo operation ${operationId}?`, { default: false });
-        if (!approved) return 0;
+      const changedDangerous = isDangerousOperation(description);
+      if ((dangerous || changedDangerous) && !sameOperationContract(previousDescription, description)) {
+        throw incompatibleOperationError(operationId, error);
       }
-      result = await invoke(description, changedDestructive);
+      result = await invoke(description, changedDangerous);
     }
   } catch (error) {
     return printCallError(operationId, error, flags);

package/src/commands/apiKey.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const log = require('../logger');
+const { callOperation } = require('./api');
+
+const OPERATIONS = Object.freeze({
+  status: 'getCurrentUserAPIKey',
+  create: 'createCurrentUserAPIKey',
+  update: 'updateCurrentUserAPIKey',
+  delete: 'deleteCurrentUserAPIKey',
+  rotate: 'rotateCurrentUserAPIKey',
+  reset: 'resetCurrentUserAPIKey',
+  enable: 'enableCurrentUserAPIKey',
+  disable: 'disableCurrentUserAPIKey',
+});
+
+function operationKey(value) {
+  const action = String(value || 'status').trim().toLowerCase();
+  return OPERATIONS[action] ? action : '';
+}
+
+async function apiKeyCommand(projectDir, positional, flags = {}) {
+  const action = operationKey(positional[0]);
+  if (!action) {
+    log.err('Usage: draftgo api-key status|create|update|delete|rotate|reset|enable|disable [--input <json-file>]');
+    return 1;
+  }
+  if (action === 'reset') log.warn('api-key reset is deprecated; prefer rotate.');
+  return callOperation(projectDir, OPERATIONS[action], flags);
+}
+
+module.exports = apiKeyCommand;
+module.exports.OPERATIONS = OPERATIONS;
+module.exports.operationKey = operationKey;

package/src/commands/capabilities.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const log = require('../logger');
+const { loadProjectConfig } = require('../projectConfig');
+const { TOOL_NAMES, openToolSession, callStructured } = require('../mcp/tools');
+
+function itemsOf(value) {
+  if (Array.isArray(value)) return value;
+  return value && Array.isArray(value.items) ? value.items : [];
+}
+
+function nextCursorOf(value) {
+  return value && (value.next_cursor ?? value.nextCursor) || null;
+}
+
+function print(value, flags, title) {
+  if (flags.output === 'json') console.log(JSON.stringify(value, null, 2));
+  else {
+    log.title(title);
+    if (Array.isArray(value)) value.forEach(item => log.plain(`  ${item.operation_id || item.name || JSON.stringify(item)}`));
+    else console.log(JSON.stringify(value, null, 2));
+  }
+}
+
+function searchArguments(query, flags, cursor) {
+  const input = { limit: Math.min(100, Math.max(1, Number(flags.limit) || 100)) };
+  if (query) input.query = query;
+  if (flags.module) input.module = String(flags.module);
+  if (flags['resource-type'] || flags.type) input.resource_type = String(flags['resource-type'] || flags.type);
+  if (flags.method) input.method = String(flags.method).toUpperCase();
+  if (flags.risk) input.risk = String(flags.risk);
+  if (flags.permission) input.permission = String(flags.permission);
+  if (cursor) input.cursor = cursor;
+  return input;
+}
+
+async function collect(session, query, flags, allPages) {
+  const result = [];
+  let cursor = flags.cursor || null;
+  const seen = new Set();
+  do {
+    const page = await callStructured(session, TOOL_NAMES.apiSearch, searchArguments(query, flags, cursor));
+    result.push(...itemsOf(page));
+    cursor = nextCursorOf(page);
+    if (!allPages || !cursor) break;
+    if (seen.has(cursor)) throw new Error('DraftGo capability search repeated a cursor.');
+    seen.add(cursor);
+  } while (true);
+  return { items: result, next_cursor: cursor };
+}
+
+async function capabilities(projectDir, positional = [], flags = {}) {
+  const action = String(positional[0] || 'list').toLowerCase();
+  const config = loadProjectConfig(projectDir);
+  if (action === 'show') {
+    const operationID = String(positional[1] || '').trim();
+    if (!operationID) throw new Error('Usage: draftgo capabilities show <operation_id>');
+    const session = await openToolSession(config, [TOOL_NAMES.apiDescribe]);
+    const result = await callStructured(session, TOOL_NAMES.apiDescribe, { operation_id: operationID });
+    print(result, flags, `DraftGo capability ${operationID}`);
+    return 0;
+  }
+  if (action === 'audit') {
+    const session = await openToolSession(config, [TOOL_NAMES.projectOverview, TOOL_NAMES.apiSearch]);
+    const overview = await callStructured(session, TOOL_NAMES.projectOverview, {});
+    const catalog = await collect(session, '', flags, true);
+    const registry = overview && (overview.operation_registry || overview.registry) || {};
+    const result = {
+      server: config.server,
+      registry_revision: registry.registry_revision || overview.registry_revision || null,
+      mapped_operations: registry.mapped_operations ?? registry.mapped ?? catalog.items.length,
+      excluded_operations: registry.excluded_operations ?? registry.excluded ?? null,
+      total_operations: registry.total_operations ?? registry.total ?? null,
+      discovered_operations: catalog.items.length,
+      complete: (registry.mapped_operations ?? registry.mapped ?? catalog.items.length) === catalog.items.length,
+    };
+    print(result, flags, 'DraftGo capability audit');
+    return result.complete ? 0 : 1;
+  }
+  if (action !== 'list' && action !== 'search') throw new Error('Usage: draftgo capabilities list|search|show|audit');
+  const query = action === 'search' ? positional.slice(1).join(' ').trim() : '';
+  if (action === 'search' && !query && !flags.module && !flags.type && !flags.method && !flags.risk && !flags.permission) {
+    throw new Error('Capability search needs a query or filter.');
+  }
+  const session = await openToolSession(config, [TOOL_NAMES.apiSearch]);
+  const result = await collect(session, query, flags, action === 'list' && !flags.cursor);
+  print(flags.output === 'json' ? result : result.items, flags, action === 'search' ? `DraftGo capabilities: ${query || 'filtered'}` : 'DraftGo capabilities');
+  return 0;
+}
+
+module.exports = capabilities;
+module.exports.searchArguments = searchArguments;
+module.exports.itemsOf = itemsOf;

package/src/commands/checkout.js

@@ -6,7 +6,7 @@ const { checkoutResources } = require('../worktree');
 async function checkout(projectDir, positional, flags = {}) {
   const [resourceType, ...ids] = positional;
   if (!resourceType || !ids.length) {
-    log.err('Usage: draftgo checkout <pages|nav|docs> <id...>');
+    log.err('Usage: draftgo checkout <pages|nav|docs|custom-services> <id...>');
     return 1;
   }
   if (require('./customService').isServiceType(resourceType)) {

package/src/commands/commit.js

@@ -6,7 +6,7 @@ const { commitResources } = require('../worktree');
 async function commit(projectDir, positional, flags = {}) {
   const [resourceType, ...ids] = positional;
   if (!resourceType || !ids.length) {
-    log.err('Usage: draftgo commit <pages|nav|docs> <id...>');
+    log.err('Usage: draftgo commit <pages|nav|docs|custom-services> <id...>');
     return 1;
   }
   if (require('./customService').isServiceType(resourceType)) {