@stalfh233/omc-cli 0.6.12 → 0.6.14

package/dist/cli.js

@@ -27,7 +27,7 @@ import { CLI_DEFAULT_OUTPUT_BYTES, assertSafeOutputPath, pruneArtifacts } from "
 import { artifactPathMissHint, nullProjectionHint, partialPathMissHint, projectJsonPath, projectJsonPathFanout, projectResultExtract } from "./path-projection.js";
 import { basename, join, resolve } from "node:path";
 import { buildToolRegistry } from "./tools.js";
-import { acquireWriteLock } from "./write-lock.js";
+import { acquireWriteLock, writeLockHeldFace } from "./write-lock.js";
 import { cmdCompute } from "./compute.js";
 import { cmdRuleWhen } from "./rule-when.js";
 import { cmdApprovalFlow } from "./approval-flow.js";
@@ -209,7 +209,9 @@ async function cmdDoctor(store, environment, serviceCode) {
     try {
         const resolved = store.resolveEnvironment(environment);
         steps.push(`配置      ok  环境=${resolved.name}（来源 ${resolved.source}）`);
-        steps.push(`写入      ok  写入=${environmentWritable(resolved.profile) ? "允许" : "只读"}${requiresProductionConfirmation(resolved.profile) ? "；生产环境：每笔写入需 confirmProduction" : ""}`);
+        steps.push(`远端写    ok  远端写=${environmentWritable(resolved.profile) ? "允许" : "只读"}${requiresProductionConfirmation(resolved.profile) ? "；生产环境：每笔写入需 confirmProduction" : ""}（平台侧变更）`);
+        // r29f F9：读面也会本地落盘（artifacts/usage/describe 缓存）；与远端写分开说。
+        steps.push(`本地落盘  ok  .omc/（artifacts·usage·describe 缓存；读面也会写）。重定位：OMC_CONFIG_HOME=<根>（其下 .omc/）或 OMC_ARTIFACTS_HOME=<产物目录>`);
         const removed = removedProfileKeys(resolved.profile);
         if (removed.length > 0)
             steps.push(`配置      ⚠  含已移除键（请删除）：${removed.join("、")}`);
@@ -367,8 +369,10 @@ function doctorAnchor() {
     const topics = listSkills().map((entry) => entry.name).join("、");
     return [
         "最小路径  omc next \"<目标>\"（目标→工具一步定位，不确定会明说）→ omc help omc-start-here → omc call discover_environment --env <env> --args '{}'（<env> 名以 doctor 的「环境=」或项目 .omc-env 为准，勿猜）→ omc capabilities / omc describe <tool>",
-        `方法论    omc help <topic> --sections / --section "<标题>"（按节读，随包 skills/）；topic：${topics}`,
+        `方法论    omc help <topic>（或 --topic <name>）--sections / --section "<标题>"（按节读，随包 skills/）；topic：${topics}`,
         "大输出    超预算结果只回 artifactId/sha256/fetch；用 fetch 里的 omc artifact get <id>（可加 --jq <path>）取回，勿全量读入",
+        // r29f F9：只读面不碰远端，但仍会本地落盘——写清，避免「零写入」核对误判。
+        "落盘      远端写=环境 writable 决定的平台变更；本地落盘=.omc/（artifacts/usage/describe 缓存，读面也会写）。可用 OMC_CONFIG_HOME 重定位配置根（其下 .omc/），或 OMC_ARTIFACTS_HOME 单独重定位产物目录",
     ].join("\n");
 }
 function flag0(args, name) {
@@ -509,7 +513,20 @@ async function cmdCall(store, args) {
     const positional = args.filter((token, index) => !token.startsWith("--") && (index === 0 || !args[index - 1]?.startsWith("--env") && !args[index - 1]?.startsWith("--environment") && !args[index - 1]?.startsWith("--args")));
     const toolName = positional[0];
     if (!toolName || toolName === "help" || args.includes("--help")) {
+        // r29f F3：`omc call <tool> --help` 识别具名工具时转发 describe 摘要，
+        // 并写死输出预算默认值（别只回通用 call 选项）。
+        if (toolName && toolName !== "help") {
+            const registry = buildToolRegistry();
+            const described = describeTool(registry, toolName);
+            if (described) {
+                console.error(`工具：${toolName}`);
+                console.error(`输出预算：--max-output-bytes 默认 65536（只约束最终 stdout 信封；读面 diet ~2048 独立外置 detailArtifactId）；artifact get 内联上限 8192`);
+                console.error(`投影：--jq/--extract 相对 result（不要写 result. 前缀；误写会自动剥并标 autoStripped）；先投影再判预算`);
+                return emitTransportResult({ status: "ok", ...described, helpNote: "来自 omc describe；完整面用 omc describe <tool> [--full|--param|--example]" }, { request, maxOutputBytes });
+            }
+        }
         console.error("用法：omc call <tool> [--env <环境>] [--args '<json>' | --args - (stdin) | --args-file <配置根内路径>] [--extract <path>]... [--jq [path]] [--extract-keys] [--args-list <json数组> [--preflight]]");
+        console.error("输出预算：--max-output-bytes 默认 65536（只约束最终 stdout 信封；读面 diet ~2048 独立外置 detailArtifactId）；artifact get 内联上限 8192");
         console.error("写入：由环境 writable 决定（只读环境拒写）；生产环境的写必须在 args 里带 confirmProduction:true。");
         return emit(toolName && toolName !== "help" ? "error" : "ok", {}, toolName && toolName !== "help" ? CLI_EXIT_CODES.invalidInput : 0);
     }
@@ -617,26 +634,44 @@ async function cmdCall(store, args) {
     }
     const registry = buildToolRegistry();
     const tool = registry.find((definition) => definition.name === toolName);
-    // 调用流畅性（2026-11-04，#18 的「查不到数据」同源）：读面「宽松」不等于
-    // 「无声」——`{"limt":5}` / `{"filterr":{…}}` 被 zod 剥掉后返回全量，调用方
-    // 会读成「过滤没生效 / 数据就是这么多」。读面在**不阻断**的前提下把被忽略的
-    // 键回显出来（写面仍是 fail-closed，见 parseToolInput）。
+    // r29f F7：读面未知参数默认硬拒（与写面 tool-input-unknown-keys 对齐）；
+    // 显式 `lenientArgs:true` 才回退到旧的 ignoredArgs 回显。
     //
     // F6（r27）：应用级键（appCode/applicationCode/application）静默回落会把写
     // 操作打到错误应用——这些键被忽略时直接拒绝，不进 ignoredArgs。
     const ignoredReadKeys = [];
     if (tool) {
         const schemaKeys = new Set(Object.keys(tool.inputSchema));
-        const recognized = new Set(["environment", "capability", "requestId", "dryRun"]);
+        const recognized = new Set(["environment", "capability", "requestId", "dryRun", "lenientArgs"]);
+        const lenientArgs = parsedArgs.lenientArgs === true;
         const unknownKeys = Object.keys(parsedArgs).filter((key) => !schemaKeys.has(key) && !recognized.has(key));
         const appScopeUnknown = unknownKeys.filter((key) => APP_SCOPE_ARG_KEYS.has(key));
         if (appScopeUnknown.length > 0) {
-            const canonical = schemaKeys.has("applicationCode")
-                ? "applicationCode"
-                : schemaKeys.has("appCode")
-                    ? "appCode"
-                    : "applicationCode（或 appCode，以 omc describe 为准）";
+            const hasApplicationCode = schemaKeys.has("applicationCode");
+            const hasAppCode = schemaKeys.has("appCode");
             const wrong = appScopeUnknown.join("、");
+            // r29a F7：schema 两个应用范围键都没有时，旧文案回退成
+            // 「请改用 applicationCode（或 appCode…）」——调用方传的正是它，形成死循环。
+            // 这种工具根本没有应用范围参数（如 rule.* 按 schemaCode 定位），走专用 blocker。
+            if (!hasApplicationCode && !hasAppCode) {
+                const locateBy = schemaKeys.has("schemaCode")
+                    ? "schemaCode（模型 code）"
+                    : schemaKeys.has("code")
+                        ? "code"
+                        : "本工具自己的定位键（见 omc describe）";
+                const result = {
+                    status: "refused",
+                    blocker: "tool-has-no-app-scope",
+                    tool: toolName,
+                    ignored: appScopeUnknown,
+                    locateBy,
+                    message: `本工具没有应用范围参数（不接受 applicationCode/appCode）；你传的 ${wrong} 不会生效。` +
+                        `它按 ${locateBy} 定位——应用边界请在 model.*/folder.*/app.* 面使用。` +
+                        `（\`omc describe ${toolName}\` 可确认参数表）`,
+                };
+                return emit("refused", result, CLI_EXIT_CODES.policyRefused);
+            }
+            const canonical = hasApplicationCode ? "applicationCode" : "appCode";
             const result = {
                 status: "refused",
                 blocker: "unknown-app-scope-arg",
@@ -647,10 +682,29 @@ async function cmdCall(store, args) {
             };
             return emit("refused", result, CLI_EXIT_CODES.policyRefused);
         }
-        if (tool.kind !== "write") {
-            for (const key of unknownKeys) {
-                // r25 真机：`limt:5` 被就近指到 `filter`（共享 "fi" 就够过阈值），照提示改
-                // 会把「取 5 条」变成「按条件过滤」。短键走显式缩写表，语义才不跑偏。
+        const otherUnknown = unknownKeys.filter((key) => !APP_SCOPE_ARG_KEYS.has(key));
+        if (tool.kind !== "write" && otherUnknown.length > 0) {
+            if (!lenientArgs) {
+                const suggestions = otherUnknown.map((key) => ({ key, ...suggestArgumentKey(key, [...schemaKeys]) }));
+                const pairs = suggestions.map((entry) => {
+                    if (entry.closest)
+                        return `${entry.key}→${entry.closest}`;
+                    if (entry.absentInTool)
+                        return `${entry.key}（本工具没有 ${entry.absentInTool}）`;
+                    return entry.key;
+                });
+                const result = {
+                    status: "error",
+                    blocker: "tool-input-unknown-keys",
+                    tool: toolName,
+                    unknownKeys: otherUnknown,
+                    suggestions,
+                    message: `读面不接受未知键（与写面对齐）：${pairs.join("、")}。` +
+                        `改用合法键后重试；确需宽松忽略传 lenientArgs:true。参数表：omc describe ${toolName}`,
+                };
+                return emit("error", result, CLI_EXIT_CODES.invalidInput);
+            }
+            for (const key of otherUnknown) {
                 ignoredReadKeys.push({ key, ...suggestArgumentKey(key, [...schemaKeys]) });
             }
         }
@@ -684,15 +738,16 @@ async function cmdCall(store, args) {
             if (lock.held)
                 break;
             if (Date.now() >= deadline) {
-                const conflict = {
-                    status: "refused",
-                    blocker: "write-lock-held",
+                // r31b F2: structured retryable/lockOwner/nextCommand so scripts do not
+                // invent a shell retry loop (help says use --wait; the refusal must too).
+                const conflict = writeLockHeldFace({
                     environment: lockTarget,
                     owner: lock.owner,
                     recovery: lock.recovery,
-                    message: lock.recovery[0],
-                };
-                console.error(`write lock conflict: ${JSON.stringify(lock.owner)}`);
+                    refusedTool: toolName,
+                    waitMs: waitMs > 0 ? waitMs : 30_000,
+                });
+                console.error(`write lock conflict: ${JSON.stringify({ pid: lock.owner?.pid, tool: lock.owner?.tool ?? lock.owner?.command, startedAt: lock.owner?.startedAt })}`);
                 writeEnvelope(envelope("refused", conflict, request, classifyResult(conflict).error));
                 return CLI_EXIT_CODES.policyRefused;
             }
@@ -828,6 +883,18 @@ function projectArtifactPath(value, path) {
         ? { missed: true, ...(fanout.at !== undefined ? { at: fanout.at } : {}), ...(fanout.available !== undefined ? { available: fanout.available } : {}) }
         : { missed: false, content: fanout.values, mapped: fanout.values.length, ...(fanout.missedEntries > 0 ? { missedEntries: fanout.missedEntries } : {}), nullEntries: fanout.nullEntries };
 }
+/** Preserve source completeness/count facts on every artifact projection. */
+function artifactProjectionMetadata(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return {};
+    const record = value;
+    const metadata = {};
+    for (const key of ["truncated", "truncatedKeys", "itemsCount", "total"]) {
+        if (Object.prototype.hasOwnProperty.call(record, key))
+            metadata[key] = record[key];
+    }
+    return metadata;
+}
 /**
  * T6（GitLab #17）：`mapped`/`nullEntries` 的读法要跟数据一起走，否则 `mapped:5`
  * 会被读成"取到 5 个值"。文案的单一真相源在 path-projection（与 `--extract`
@@ -883,15 +950,17 @@ async function cmdArtifactGet(id, transport, options = {}) {
                 // 一层 `projection:{path,content}`——`artifact get --jq` 与 `--summary --jq`
                 // 因此同形（顶层 path/content），换读面不用重新探根键。
                 return emitTransportResult(projected.missed
-                    ? { status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, keys, path: options.jq, content: null, pathMiss: true, missedAt: projected.at, available: projected.available, unanswered: true, hint: artifactPathMissHint(projected.at) }
+                    ? { status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, ...artifactProjectionMetadata(content), keys, path: options.jq, content: null, projections: [{ path: options.jq, content: null, pathMiss: true, missedAt: projected.at, available: projected.available }], pathMiss: true, missedAt: projected.at, available: projected.available, unanswered: true, hint: artifactPathMissHint(projected.at) }
                     : {
                         status: "ok",
                         artifactId: id,
                         sha256: artifact.sha256,
                         bytes: artifact.content.length,
+                        ...artifactProjectionMetadata(content),
                         keys,
                         path: options.jq,
                         content: projected.content ?? null,
+                        projections: [{ path: options.jq, content: projected.content ?? null, ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}), ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}) }],
                         ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}),
                         ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}),
                         ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}),
@@ -937,12 +1006,12 @@ async function cmdArtifactGet(id, transport, options = {}) {
                         ? { path, content: null, pathMiss: true, missedAt: projected.at, available: projected.available }
                         : { path, content: projected.content ?? null, ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}), ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}), ...(artifactNullHint(projected.content, projected.nullEntries) !== undefined ? { hint: artifactNullHint(projected.content, projected.nullEntries) } : {}) };
                 });
-                return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, projections, ...(projections.some((entry) => entry.pathMiss) ? { unanswered: true, hint: partialPathMissHint() } : {}) }, transport);
+                return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, ...artifactProjectionMetadata(content), projections, ...(projections.some((entry) => entry.pathMiss) ? { unanswered: true, hint: partialPathMissHint() } : {}) }, transport);
             }
             const projected = projectArtifactPath(artifactContent, options.jq);
             return emitTransportResult(projected.missed
-                ? { status: "ok", artifactId: id, sha256: artifact.sha256, path: options.jq, content: null, pathMiss: true, missedAt: projected.at, available: projected.available, unanswered: true, hint: artifactPathMissHint(projected.at) }
-                : { status: "ok", artifactId: id, sha256: artifact.sha256, path: options.jq, content: projected.content ?? null, ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}), ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}), ...(artifactNullHint(projected.content, projected.nullEntries) !== undefined ? { hint: artifactNullHint(projected.content, projected.nullEntries) } : {}) }, transport);
+                ? { status: "ok", artifactId: id, sha256: artifact.sha256, ...artifactProjectionMetadata(content), path: options.jq, content: null, pathMiss: true, missedAt: projected.at, available: projected.available, unanswered: true, hint: artifactPathMissHint(projected.at) }
+                : { status: "ok", artifactId: id, sha256: artifact.sha256, ...artifactProjectionMetadata(content), path: options.jq, content: projected.content ?? null, projections: [{ path: options.jq, content: projected.content ?? null, ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}), ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}) }], ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}), ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}), ...(artifactNullHint(projected.content, projected.nullEntries) !== undefined ? { hint: artifactNullHint(projected.content, projected.nullEntries) } : {}) }, transport);
         }
         // r6-onboarding 2026-10-21: 47 artifact fetches, 0 used a projection; the 10
         // large ones (up to 55 KB) pulled whole workflow templates just to read one
@@ -1053,6 +1122,76 @@ async function cmdBench(args) {
     const dims = report.dimensions;
     return failedSteps === 0 && dims.intent.passed === dims.intent.cases ? 0 : 1;
 }
+/** r29f F8：discovery 面复用同一投影层（相对本命令 result，不是 call 信封）。 */
+function emitProjectedResult(result, transport, jq) {
+    const raw = Array.isArray(jq) ? jq : jq === undefined ? [] : [jq];
+    const keysOnly = raw.some((entry) => entry === true) || (raw.length === 0 && jq === true);
+    const paths = raw
+        .filter((entry) => typeof entry === "string")
+        .flatMap((path) => path.split(","))
+        .map((path) => path.trim())
+        .filter(Boolean);
+    if (paths.length === 0 && !keysOnly)
+        return emitTransportResult(result, transport);
+    const projected = projectResultExtract(result, paths, keysOnly);
+    return emitTransportResult(projected ?? result, transport);
+}
+function enrichDescribeParamMiss(registry, toolName, param, miss) {
+    // r31b F1: a miss must teach the next move — closest name, or "that param
+    // lives on another tool" — instead of dumping the whole available table.
+    const available = Array.isArray(miss.available) ? miss.available.map((entry) => String(entry)) : [];
+    const didYouMean = typeof miss.didYouMean === "string" ? miss.didYouMean : undefined;
+    const family = toolName.includes(".") ? toolName.split(".")[0] : toolName;
+    // Known cross-tool identity pairs first (新建 vs 更新), then same-family,
+    // then any other tool that declares the param.
+    const preferredPair = toolName === "data.save" && param === "bizObjectId"
+        ? "data.update"
+        : toolName === "data.update" && param === "formData"
+            ? "data.save"
+            : undefined;
+    const otherTools = registry
+        .filter((tool) => tool.name !== toolName && tool.inputSchema && Object.prototype.hasOwnProperty.call(tool.inputSchema, param))
+        .map((tool) => tool.name)
+        .sort((left, right) => {
+        const rank = (name) => {
+            if (preferredPair !== undefined && name === preferredPair)
+                return 0;
+            if (name.startsWith(`${family}.`))
+                return 1;
+            return 2;
+        };
+        return rank(left) - rank(right) || left.localeCompare(right);
+    });
+    const otherTool = preferredPair && otherTools.includes(preferredPair) ? preferredPair : otherTools[0];
+    // Known cross-tool identity guidance for the data lane (新建 vs 更新).
+    const dataIdentityHint = toolName === "data.save" && param === "bizObjectId"
+        ? "新建用 data.save（schemaCode+formData）；更新用 data.update + bizObjectId"
+        : undefined;
+    const cappedAvailable = available.slice(0, 8);
+    const hintParts = [
+        didYouMean !== undefined ? `本工具最接近的参数是 ${didYouMean}` : undefined,
+        otherTool !== undefined ? `参数 "${param}" 属于 ${otherTool}${otherTools.length > 1 ? `（同名还在 ${otherTools.slice(1, 3).join("、")}）` : ""}` : undefined,
+        dataIdentityHint,
+    ].filter((part) => typeof part === "string" && part.length > 0);
+    return {
+        ...miss,
+        ...(didYouMean !== undefined ? { didYouMean, nextCommand: `omc describe ${toolName} --param ${didYouMean}` } : {}),
+        ...(otherTool !== undefined
+            ? {
+                otherTool,
+                otherTools: otherTools.slice(0, 5),
+                nextCommand: `omc describe ${otherTool} --param ${param}`,
+            }
+            : {}),
+        ...(hintParts.length > 0 ? { hint: hintParts.join("；") } : {}),
+        ...(dataIdentityHint !== undefined ? { guidance: dataIdentityHint } : {}),
+        available: cappedAvailable,
+        ...(available.length > cappedAvailable.length ? { availableTruncated: available.length - cappedAvailable.length } : {}),
+        message: hintParts.length > 0
+            ? `本工具没有参数 "${param}"——${hintParts.join("；")}`
+            : `本工具没有参数 "${param}"——available 是本工具的合法参数（已截断）`,
+    };
+}
 function cmdDiscovery(kind, transport, value, options = {}) {
     const registry = buildToolRegistry();
     let result;
@@ -1079,7 +1218,7 @@ function cmdDiscovery(kind, transport, value, options = {}) {
         // agent paid 4×54 KB on the default face before any hint could land).
         if (options.json !== true && options.compact !== true && !scoped) {
             result = commandIndex(registry);
-            return emitTransportResult({ status: "ok", ...result }, transport);
+            return emitProjectedResult({ status: "ok", ...result }, transport, options.jq);
         }
         const inventory = commandInventory(registry, { compact: options.compact === true });
         // r19 ticket 05: above this many hits a filter word is "broad" — the filtered
@@ -1170,16 +1309,28 @@ function cmdDiscovery(kind, transport, value, options = {}) {
     }
     else if (options.schemaOnly)
         result = describeSchemaOnly(registry, value ?? "");
-    else if (options.param)
-        result = describeParam(registry, value ?? "", options.param);
+    else if (options.param) {
+        const missOrHit = describeParam(registry, value ?? "", options.param);
+        // r31b F1: enrich a param miss with otherTool / capped available / guidance.
+        result =
+            missOrHit && missOrHit.found === false
+                ? enrichDescribeParamMiss(registry, value ?? "", options.param, missOrHit)
+                : missOrHit;
+    }
     else if (options.example !== undefined)
         result = describeExample(registry, value ?? "", typeof options.example === "string" ? options.example : undefined);
     else if (options.full) {
         const full = describeToolFull(registry, value ?? "");
-        // r9: the same `--full` contract was re-shipped 8 times (134 KB) while the
-        // caller only wanted to re-check a shape. Within a project session the
-        // second identical read returns an artifact reference instead of the body.
-        result = full ? (repeatFullDescribe(value ?? "", full) ?? full) : full;
+        // r31b F3: `--full` means "give me the body". Short-circuit only when the
+        // caller opts in with `--cache-ok` (legacy r9 repeat-read suppression).
+        if (!full)
+            result = full;
+        else if (options.cacheOk)
+            result = repeatFullDescribe(value ?? "", full) ?? full;
+        else {
+            repeatFullDescribe(value ?? "", full, { recordOnly: true });
+            result = full;
+        }
     }
     else {
         result = describeTool(registry, value ?? "");
@@ -1236,7 +1387,7 @@ function cmdDiscovery(kind, transport, value, options = {}) {
         const textNote = byText.length > 0 ? `；didYouMeanByText: ${byText.join("、")}` : "";
         return emitInvalid(transport, { message: `${kind} target not found: "${requested}"${shown.length > 0 ? `; did you mean: ${shown.join("、")}` : ""}${textNote}${absence}${approvalPointer}${intentPointer}${formPointer}${pointer}` });
     }
-    return emitTransportResult({ status: "ok", ...result }, transport);
+    return emitProjectedResult({ status: "ok", ...result }, transport, options.jq);
 }
 function cmdUsage(transport, options = {}) {
     return emitTransportResult(usageReport(undefined, { records: options.records === true, top: options.top, resolveLikeWriter: true }), transport);
@@ -1254,11 +1405,11 @@ function cmdNext(goal, transport) {
  * capability overview. Read-only, zero environment contact; a projection of
  * the tool registry, the coverage manifest, and the intent capability registry.
  */
-function cmdCapabilities(transport, compact = false) {
+function cmdCapabilities(transport, compact = false, jq) {
     const result = compactCapabilities(buildToolRegistry(), { compact });
-    return emitTransportResult({ status: "ok", ...result }, transport);
+    return emitProjectedResult({ status: "ok", ...result }, transport, jq);
 }
-function cmdCapability(id, transport, executable = false) {
+function cmdCapability(id, transport, executable = false, jq) {
     const registry = buildToolRegistry();
     const resolved = resolveCapabilityId(id);
     if (!resolved) {
@@ -1269,9 +1420,64 @@ function cmdCapability(id, transport, executable = false) {
         const bundle = executableCapabilityBundle(registry, resolved);
         if (!bundle)
             return emitInvalid(transport, { message: `capability "${id}" 没有可执行 bundle` });
-        return emitResult({ status: "ok", capability: bundle }, transport);
-    }
-    return emitResult({ status: "ok", capability: capabilityDetail(registry, resolved) }, transport);
+        return emitProjectedResult({ status: "ok", capability: bundle }, transport, jq);
+    }
+    const detail = capabilityDetail(registry, resolved);
+    if (!detail)
+        return emitInvalid(transport, { message: `capability "${id}" 无详情` });
+    // r29a F4：app/folder/model/rule 面附应用参数名矩阵（主/别名），一次看完。
+    const appScopeMatrix = buildAppScopeMatrix(registry, resolved);
+    return emitProjectedResult({
+        status: "ok",
+        capability: {
+            ...detail,
+            ...(appScopeMatrix !== undefined ? { appScopeArgs: appScopeMatrix } : {}),
+        },
+    }, transport, jq);
+}
+/**
+ * r29a F4：跨 app/folder/model/rule 的「工具 → 应用参数名(主/别名)」小表。
+ * 只在这四个能力面上挂，避免每条 capability 都膨胀。
+ */
+function buildAppScopeMatrix(registry, capabilityId) {
+    const faces = new Set(["app", "folder", "model", "businessrule", "rule"]);
+    if (!faces.has(capabilityId))
+        return undefined;
+    const laneByCapability = {
+        app: "app-management",
+        folder: "app-tree-folders",
+        model: "model-management",
+        businessrule: "B1-businessrule",
+        rule: "B1-businessrule",
+    };
+    const lane = laneByCapability[capabilityId];
+    const rows = registry
+        .filter((tool) => tool.lane === lane || ((capabilityId === "rule" || capabilityId === "businessrule") && tool.name.startsWith("rule.")))
+        .map((tool) => {
+        const keys = Object.keys(tool.inputSchema);
+        const primary = keys.includes("applicationCode") ? "applicationCode" : keys.includes("appCode") ? "appCode" : null;
+        const aliases = keys.includes("applicationCode") && keys.includes("appCode")
+            ? ["applicationCode", "appCode"]
+            : primary === "applicationCode"
+                ? ["applicationCode"]
+                : primary === "appCode"
+                    ? ["appCode"]
+                    : [];
+        return {
+            tool: tool.name,
+            primary,
+            aliases,
+            note: primary === null ? "无应用范围参数（按 schemaCode/自身键定位）" : aliases.length > 1 ? "双别名；冲突报 app-code-conflict" : undefined,
+        };
+    });
+    if (rows.length === 0)
+        return undefined;
+    return {
+        face: capabilityId,
+        rows,
+        relatedTopics: ["app-scope"],
+        hint: "完整矩阵也见 `omc help app-scope`",
+    };
 }
 /**
  * Read + validate an intent file, or emit the shared invalid-input envelope.
@@ -1621,14 +1827,14 @@ function cmdHelpSearch(topic, query, transport, searchMode, limit) {
                 : "")
         : "";
     if (topic === undefined) {
-        console.error("用法：omc help <topic>  |  omc help --search \"<词>\"（跨 topic 检索，命中节正文随结果返回）");
+        console.error("用法：omc help <topic>  |  omc help --topic <name>  |  omc help --search \"<词>\"（跨 topic 检索，命中节正文随结果返回）");
         console.error("权威路线：omc help omc-start-here（随包 skills/，不是分发镜像）");
         console.error("环境就绪：omc call discover_environment --env <env> --args '{}'");
         console.error(`命令：${commands.join("、")}`);
         console.error(`方法论 topic：${topics.map((entry) => entry.name).join("、")}`);
         return emitTransportResult({
             status: "ok",
-            usage: "omc help <topic>",
+            usage: "omc help <topic> | omc help --topic <name>",
             discovery: DISCOVERY_AUTHORITY,
             commands,
             topics,
@@ -1702,7 +1908,22 @@ function cmdHelpSearch(topic, query, transport, searchMode, limit) {
     }
     if (all) {
         console.error(`omc help ${document.name} --all（${Buffer.byteLength(document.content, "utf8")} B）`);
-        return emitTransportResult({ status: "ok", topic: document }, transport);
+        // r32 F3（真机）：三种模式三种形状——默认回 sections[]、--section 回顶层 content、
+        // --all 却回 {topic:{name,description,content}}。按前两种写的解析（.content /
+        // .result.topic 当字符串）在 --all 上全部取不到，而默认模式的 hint 恰恰把 --all
+        // 指成"确需整篇"的下一步。
+        // 现在 --all 与前两者同形：topic 是 topic 名（字符串），正文在顶层 content，
+        // 并附 bytes/chars/complete。**不要再把 content 放进 topic**——那会让整篇在
+        // 信封里出现两次，撑破 64KiB 预算后被外置成 artifact（r32 实测：help-write-hazards
+        // 因此从"直接回正文"退化成"回一个每次不同的 artifactId"，golden 永久漂移）。
+        return emitTransportResult({
+            status: "ok",
+            topic: document.name,
+            content: document.content,
+            bytes: Buffer.byteLength(document.content, "utf8"),
+            chars: document.content.length,
+            complete: true,
+        }, transport);
     }
     // Shape first. Round 10 paid 35,872 B per full read of one topic, seven times
     // in a single session, to use one or two headings. The index names every
@@ -1738,14 +1959,16 @@ function onboardingHelp() {
     return [
         "首次使用、或不确定从哪开始：omc help omc-start-here（随包权威 topic 路线）；被拒或状态异常：omc help omc-refusals。",
         "中文可读输出：任何命令加 --utf8——它让人类可读诊断（stderr/散文）按 UTF-8 原文输出。stdout 的 JSON 信封在非 UTF-8 代码页下仍保持 \\uXXXX 转义（保证 JSON.parse/ConvertFrom-Json 一定可解析，这是有意为之）。要连信封也是中文明文，必须先让管道按 UTF-8 解码（chcp 65001）——只设 OMC_ASCII_STDOUT=0 关写出端转义，在 cp936 管道下会把信封解码坏。",
-        "方法论按需读：omc help <topic> 默认只回节索引（每节字节数）；用 --section \"<标题>\" 取正文（可重复），确需整篇才 --all。找具体事实（错误码/字段名/命令名）不要整篇 dump：omc help --search \"<词>\"（跨 topic，命中节正文随结果返回）。",
+        "方法论按需读：omc help <topic>（或 omc help --topic <name>）默认只回节索引（每节字节数）；用 --section \"<标题>\" 取正文（可重复），确需整篇才 --all。找具体事实（错误码/字段名/命令名）不要整篇 dump：omc help --search \"<词>\"（跨 topic，命中节正文随结果返回）。",
         "目标→工具一步定位：omc next \"<你要做什么>\"（离线、只读，给能力/说明/首批命令；不确定会明说并回退到 omc-requirement-analysis）。",
-        "大结果取值一步到位：读面回 detailArtifactId 时，用 omc call <tool> … --jq <path>（可重复；`[]` 映射数组，如 items[].fields.planNo）或 --extract/--extract-keys，省掉再跑一次 omc artifact get；artifact get 正文超 8KB 默认也只回形状（--jq/--keys 定向取，--full 才整包）。批量形状预检用 --args-list … --preflight（零 wire、零写入，一次报全）。",
+        // r30f F20：写清两道门——读面 diet(~2048) 与 stdout 预算(--max-output-bytes，默认 64KiB) 不是一回事。
+        "输出预算：`--max-output-bytes` 默认 65536（64KiB；超则回 artifact 指针 + sha256），只约束最终 stdout 信封（投影/--jq 之后）；`artifact get` 内联上限 8192。读面另有独立 diet 门（~2048）会先外置 detailArtifactId——抬高 --max-output-bytes 不会把已 diet 的大表重新内联。",
+        "大结果取值一步到位：读面回 detailArtifactId 时，用 omc call <tool> … --jq <path>（可重复；`[]` 映射数组，如 items[].fields.planNo）或 --extract/--extract-keys，省掉再跑一次 omc artifact get。commands/capabilities/describe 也支持 --jq。批量形状预检用 --args-list … --preflight（零 wire、零写入，一次报全）。",
         // r25 真机（2026-11-04）：探针连跑同一读面 2–3 次想验证「第二次是否 unchanged」，
         // 结果三次都是全量，还去 describe 找 dedupe 参数（多花 3 轮）。读面确实不做跨调用
         // 结果去重——**明说**比留白强，省掉一次探索。
         "读面不做跨调用结果去重：同一读面同参数连跑 N 次就是 N 次真实读（不会回 unchanged，也没有 dedupe 开关）。要省就 --jq 定向取值或把结果落到自己的变量里复用；`unchanged:true` 只出现在写面回读缓存那一条路径。",
-        "工具发现：omc commands --json（含 capability id/lane/recipes；加 --compact 只回工具行、无目录散文）· omc capabilities（能力 id/lane/aliases/tools/依赖顺序）· omc capability <id> --executable（单能力完整执行包）。",
+        "工具发现：omc commands --json（含 capability id/lane/recipes；加 --compact 只回工具行、无目录散文）· omc capabilities（能力 id/lane/aliases/tools/依赖顺序）· omc capability <id> --executable（单能力完整执行包）。应用参数矩阵：omc help app-scope。",
         "单工具/契约：omc describe <tool>（schema+recipe+能力路由）· omc contract <lane>（wire 契约+能力路由）；环境就绪：omc call discover_environment --env <env> --args '{}'。",
         "写入两道门：对话层草稿确认（omc help omc-config-draft-review）+ 环境 writable 开关；生产环境每笔写需在 args 里带 confirmProduction:true。",
     ].join("\n");
@@ -1819,6 +2042,22 @@ async function main() {
         process.stdout.write(`${ownPackageVersion()}\n`);
         return 0;
     }
+    // r29f F3：commander 在 action 前就吞掉 `--help`。`omc call <tool> --help`
+    // 必须在这里短路转发 describe，否则永远只见通用 call 选项。
+    if (bare[0] === "call" && bare[1] && bare[1] !== "help" && !bare[1].startsWith("-") && (bare.includes("--help") || bare.includes("-h"))) {
+        const toolName = bare[1];
+        const registry = buildToolRegistry();
+        const described = describeTool(registry, toolName);
+        console.error(`工具：${toolName}`);
+        console.error(`输出预算：--max-output-bytes 默认 2048（超则回 artifact 指针 + sha256）；artifact get 内联上限 8192`);
+        console.error(`投影：--jq/--extract 相对 result（不要写 result. 前缀；误写会自动剥并标 autoStripped）`);
+        if (described) {
+            writeEnvelope(envelope("ok", { ...described, helpNote: "来自 omc describe；完整面用 omc describe <tool> [--full|--param|--example]" }, request));
+            return CLI_EXIT_CODES.ok;
+        }
+        writeEnvelope(envelope("error", { tool: toolName }, request, { code: "invalid-input", message: `未知工具 ${toolName}；用 omc commands --json --compact 查名单`, retryable: false }));
+        return CLI_EXIT_CODES.invalidInput;
+    }
     command.addHelpText("after", `\n${onboardingHelp()}\n`);
     // No command at all: guide the agent (help text + onboarding), exit 0. This
     // is a benign "show me the surface" invocation, not a failure.
@@ -1826,7 +2065,11 @@ async function main() {
         command.outputHelp();
         return CLI_EXIT_CODES.ok;
     }
-    command.command("help [topic]").option("--section [heading]", "按标题取该节内容；可重复或用逗号一次取多节：--section a --section b / --section a,b（不带值则列出该 topic 的节标题）").option("--sections").option("--all", "回整篇正文（默认只回节索引：标题 + 各节字节）").option("--search <query>", "跨 topic 全文检索（错误码/字段名/命令名）；命中节正文随结果返回，不需要再取一次").option("--search-mode <mode>", "all（默认，同一节包含全部词）或 any（包含任一）").option("--limit <n>", "检索最多返回几节（默认 5，1–50）").option("--max-output-bytes <bytes>").action(async (topic, options) => { commandExitCode = await withTransport(options, request, (transport) => cmdHelp(topic, command.commands.map((entry) => entry.name()), transport, options.section, options.sections === true, options.all === true, typeof options.search === "string" ? options.search : undefined, typeof options.searchMode === "string" ? options.searchMode : undefined, typeof options.limit === "string" ? options.limit : undefined)); });
+    // r30f F15：topic 既是位置参数也接受 `--topic <name>` 别名（肌肉记忆对齐 capability/contract）。
+    command.command("help [topic]").option("--topic <name>", "topic 别名（与位置参数等价：`omc help omc-refusals` = `omc help --topic omc-refusals`）").option("--section [heading]", "按标题取该节内容；可重复或用逗号一次取多节：--section a --section b / --section a,b（不带值则列出该 topic 的节标题）").option("--sections").option("--all", "回整篇正文（默认只回节索引：标题 + 各节字节）").option("--search <query>", "跨 topic 全文检索（错误码/字段名/命令名）；命中节正文随结果返回，不需要再取一次").option("--search-mode <mode>", "all（默认，同一节包含全部词）或 any（包含任一）").option("--limit <n>", "检索最多返回几节（默认 5，1–50）").option("--max-output-bytes <bytes>").action(async (topic, options) => {
+        const resolvedTopic = typeof options.topic === "string" && options.topic.trim() !== "" ? options.topic.trim() : topic;
+        commandExitCode = await withTransport(options, request, (transport) => cmdHelp(resolvedTopic, command.commands.map((entry) => entry.name()), transport, options.section, options.sections === true, options.all === true, typeof options.search === "string" ? options.search : undefined, typeof options.searchMode === "string" ? options.searchMode : undefined, typeof options.limit === "string" ? options.limit : undefined));
+    });
     command.command("setup").option("--list").option("--edit <environment>").option("--remove <environment>").action(async (options) => {
         // r25 真机（2026-11-04）：setup 不在 ownsStdout 里，于是非 TTY 拒绝时主流程会补一个
         // `error.code=internal` 的信封——明明是可预期的用法错误（stdin 不是终端），却被包成
@@ -1886,7 +2129,7 @@ async function main() {
         commandExitCode = CLI_EXIT_CODES.ok;
     });
     command.command("doctor").option("--environment <environment>").option("--env <environment>").option("--service <serviceCode>", "可选：体检单个业务集成服务的鉴权参数形状（掩码/占位/全 0 检出，WARN 非致命）").action(async (options) => { commandExitCode = await cmdDoctor(new ConfigStore(defaultPaths()), options.environment ?? options.env, options.service); });
-    command.command("call <tool>").option("--env <environment>").option("--environment <environment>").option("--args <json>").option("--args-file <path>").option("--args-list <json-array>", '同一工具跑 N 次（JSON 数组，每条一个 args 对象）；逐条执行、默认不中断，最后回 succeeded/failed 汇总。适合批量建字段等').option("--preflight", "与 --args-list 一起用：只跑参数校验 + 写前语义闸（零 wire、零写入），一次报全所有形状问题").option("--keys", "与 artifact get 的 --keys 同义（= --extract-keys）：列出本次结果 artifact 的顶层键与体积").addOption(new Option("--extract <path>", "在本次结果的 artifact 内取一个路径的值（可重复；省掉一次 artifact get）").argParser((value, previous = []) => [...previous, value]).default([])).addOption(new Option("--jq [path]", "同 --extract，并支持 [] 映射（如 items[].fields.planNo）；裸 --jq 列出结果的顶层键").argParser((value, previous = []) => [...previous, value]).default([])).option("--extract-keys", "列出本次结果 artifact 的顶层键与体积（省掉一次 artifact get --keys）").option("--max-output-bytes <bytes>").option("--request-id <requestId>").option("--timeout-ms <milliseconds>").option("--wait <milliseconds>").option("--dry-run").addHelpText("after", `\n${onboardingHelp()}\n`).action(async (tool, options) => {
+    command.command("call <tool>").option("--env <environment>").option("--environment <environment>").option("--args <json>").option("--args-file <path>").option("--args-list <json-array>", '同一工具跑 N 次（JSON 数组，每条一个 args 对象）；逐条执行、默认不中断，最后回 succeeded/failed 汇总。适合批量建字段等').option("--preflight", "与 --args-list 一起用：只跑参数校验 + 写前语义闸（零 wire、零写入），一次报全所有形状问题").option("--keys", "与 artifact get 的 --keys 同义（= --extract-keys）：列出本次结果 artifact 的顶层键与体积").addOption(new Option("--extract <path>", "在本次结果的 artifact 内取一个路径的值（可重复；省掉一次 artifact get）").argParser((value, previous = []) => [...previous, value]).default([])).addOption(new Option("--jq [path]", "同 --extract，并支持 [] 映射（如 items[].fields.planNo）；裸 --jq 列出结果的顶层键").argParser((value, previous = []) => [...previous, value]).default([])).option("--extract-keys", "列出本次结果 artifact 的顶层键与体积（省掉一次 artifact get --keys）").option("--max-output-bytes <bytes>", "最终 stdout 信封预算；默认 65536（投影/--jq 之后再判）；读面 diet(~2048) 独立外置 detailArtifactId，抬高本参数不会把已 diet 的大表重新内联；artifact get 内联上限 8192").option("--request-id <requestId>").option("--timeout-ms <milliseconds>").option("--wait <milliseconds>").option("--dry-run").addHelpText("after", `\n${onboardingHelp()}\n`).action(async (tool, options) => {
         const rest = [tool, ...(options.env ? ["--env", options.env] : []), ...(options.environment ? ["--environment", options.environment] : []), ...(options.args !== undefined ? ["--args", options.args] : []), ...(options.argsFile !== undefined ? ["--args-file", options.argsFile] : []), ...(options.argsList !== undefined ? ["--args-list", options.argsList] : []), ...(options.preflight ? ["--preflight"] : []), ...(Array.isArray(options.extract) ? options.extract.flatMap((path) => ["--extract", path]) : []), ...(Array.isArray(options.jq) ? options.jq.flatMap((path) => path === true ? ["--jq"] : ["--jq", path]) : []), ...(options.extractKeys ? ["--extract-keys"] : []),
             ...(options.keys ? ["--keys"] : []), ...(options.maxOutputBytes !== undefined ? ["--max-output-bytes", options.maxOutputBytes] : []), ...(options.requestId ? ["--request-id", options.requestId] : []), ...(options.timeoutMs !== undefined ? ["--timeout-ms", options.timeoutMs] : []), ...(options.wait !== undefined ? ["--wait", options.wait] : []), ...(options.dryRun ? ["--dry-run"] : [])];
         commandExitCode = await cmdCall(new ConfigStore(defaultPaths()), rest);
@@ -2030,7 +2273,7 @@ async function main() {
         .option("--code <schemaCode>", "模型 code")
         .option("--schema <schemaCode>")
         .option("--name <name>", "模型名")
-        .option("--fields <json>", "JSON 数组，每条是一个 field.create 参数；子表加 childFields")
+        .option("--fields <json>", "JSON 数组，每条是一个 field.create 参数；子表加 subFields")
         .option("--fields-json <json>")
         .option("--folder <folderId>", "建在哪个应用目录（省略=默认目录）")
         .option("--app <applicationCode>")
@@ -2049,7 +2292,7 @@ async function main() {
         `  常见错写：DEPARTMENT_MULTI→DEPARTMENT_MULTI_SELECTOR、STAFF_SINGLE→STAFF_SELECTOR、DROP_DOWN_BOX→DROPDOWN_BOX\n\n` +
         `choices（RADIO/CHECKBOX/DROPDOWN 系列）：**字符串数组**，如 [\"待处理\",\"已完成\"]——不是 [{key,value}]\n` +
         `关联字段（WORK_SHEET/MULT_WORK_SHEET）：options:{\"schemaCode\":\"<目标模型>\"} + relativeCode:\"<目标模型>\"\n` +
-        `子表：childFields:[…]（每条同字段形状）\n`)
+        `子表：subFields:[…]（每条同字段形状；childFields 仍作别名接受）\n`)
         .action(async (options) => {
         const rest = ["model-scaffold",
             ...(options.code ? ["--code", options.code] : []),
@@ -2107,23 +2350,20 @@ async function main() {
             ...(options.apply ? ["--apply"] : [])];
         commandExitCode = await cmdFieldAdd(rest);
     });
-    command.command("script [file]").option("--env <environment>", "行内无 env 时的默认环境").option("--continue", "某行失败后继续执行剩余行（默认停在首个失败）").description("NDJSON 多调脚本：每行 {\"tool\":\"<名称>\",\"args\":{...},\"env\":\"<环境>\",\"dryRun\":true}（# 注释/空行忽略；file 为 - 读 stdin）；一个进程一次会话跑完全部，逐行输出 {index,tool,exitCode,result}").action(async (file, options) => {
+    command.command("script [file]").option("--env <environment>", "行内无 env 时的默认环境").option("--continue", "某行失败后继续执行剩余行（默认首败即停）").description("NDJSON 多调脚本：每行 {\"tool\":\"<名称>\",\"args\":{...},\"env\":\"<环境>\",\"dryRun\":true}（# 与 // 注释/空行忽略；其它非法行跳过计入 summary.skipped；file 为 - 读 stdin）。一个进程一次会话串行跑完全部（共用登录，比逐条 omc call 快；测写锁竞争请用多个独立 omc call 进程）。逐行输出 {index,tool,exitCode,result}，末行 {summary:{total,ok,failed,skipped,stoppedAt?}}。").action(async (file, options) => {
         const { runScript, parseScript, readScriptInput } = await import("./script.js");
-        let lines;
-        try {
-            lines = parseScript(readScriptInput(file ?? "-"));
-        }
-        catch (error) {
-            console.error(String(error instanceof Error ? error.message : error));
+        const parsed = parseScript(readScriptInput(file ?? "-"));
+        const lines = parsed.lines;
+        if (lines.length === 0 && parsed.skipped.length === 0) {
+            console.error("脚本为空：每行一个 {\"tool\":\"<名称>\",\"args\":{...}} 调用（# 与 // 开头为注释）");
             commandExitCode = CLI_EXIT_CODES.invalidInput;
             return;
         }
-        if (lines.length === 0) {
-            console.error("脚本为空：每行一个 {\"tool\":\"<名称>\",\"args\":{...}} 调用");
-            commandExitCode = CLI_EXIT_CODES.invalidInput;
-            return;
-        }
-        commandExitCode = await runScript(lines, { defaultEnv: options.env, continueOnError: options.continue === true });
+        commandExitCode = await runScript(lines, {
+            defaultEnv: options.env,
+            continueOnError: options.continue === true,
+            skipped: parsed.skipped,
+        });
         // `script` emits NDJSON (one envelope per line), so the single-envelope
         // recorder never ran and usage.jsonl left every batch at its initial
         // "no-envelope" status — a successful 4-call batch looked like 4 failures
@@ -2132,7 +2372,7 @@ async function main() {
         recordUsageOutput({
             status: commandExitCode === 0 ? "ok" : "refused",
             ...(commandExitCode === 0 ? {} : { error: { code: "script-batch-failed" } }),
-            script: { lines: lines.length },
+            script: { lines: lines.length, skipped: parsed.skipped.length },
         }, 0);
     });
     const rollbackCommand = command.command("rollback").description("配置回滚（git-revert 语义）：list 列写时间线 / plan 预览恢复（diff+后续写覆盖警告）/ apply 执行恢复——恢复走完整写闸门并记 journal（回滚可再回滚）。接入全部配置写面（workflow/规则/数据规则/视图/表单草稿/在线JS/字典/字段/模型/应用/报表）；publish 类生命周期推进不可逆（plan 会说明）；journal 与 before 快照为本机边界（不跨机器）");
@@ -2187,14 +2427,15 @@ async function main() {
             pureKeys: (options.keys === true || bareJq) && options.summary !== true, ...(typeof options.keys === "string" ? { keys: options.keys } : {}), full: options.full === true }));
     });
     command.command("bench").option("--live-sample").option("--env <environment>").action(async (options) => { commandExitCode = await cmdBench([...(options.liveSample ? ["--live-sample"] : []), ...(options.env ? ["--env", options.env] : [])]); });
-    command.command("commands").option("--json").option("--compact").option("--filter <keyword>").option("--lane <id>").option("--max-output-bytes <bytes>").action(async (options) => { commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("commands", transport, undefined, { json: options.json === true, compact: options.compact === true, ...(options.filter ? { filter: options.filter } : {}), ...(options.lane ? { lane: options.lane } : {}) })); });
-    command.command("describe <tool>").option("--full").option("--schema-only").option("--param <name>").option("--example [id]").option("--max-output-bytes <bytes>").action(async (tool, options) => {
-        commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("describe", transport, tool, { full: options.full === true, schemaOnly: options.schemaOnly === true, ...(options.param ? { param: options.param } : {}), ...(options.example ? { example: options.example } : {}) }));
+    const jqOption = () => new Option("--jq [path]", "路径投影（与 call --jq 同 DSL；可逗号多路径；裸 --jq 列顶层键）").argParser((value, previous = []) => [...previous, value]).default([]);
+    command.command("commands").option("--json").option("--compact").option("--filter <keyword>").option("--lane <id>").option("--max-output-bytes <bytes>").addOption(jqOption()).action(async (options) => { commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("commands", transport, undefined, { json: options.json === true, compact: options.compact === true, ...(options.filter ? { filter: options.filter } : {}), ...(options.lane ? { lane: options.lane } : {}), ...(options.jq !== undefined ? { jq: options.jq } : {}) })); });
+    command.command("describe <tool>").option("--full").option("--cache-ok", "允许 --full 在同会话重复读时短路为 artifact 指针（默认每次回全文）").option("--schema-only").option("--param <name>").option("--example [id]").option("--max-output-bytes <bytes>").addOption(jqOption()).action(async (tool, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("describe", transport, tool, { full: options.full === true, cacheOk: options.cacheOk === true, schemaOnly: options.schemaOnly === true, ...(options.param ? { param: options.param } : {}), ...(options.example ? { example: options.example } : {}), ...(options.jq !== undefined ? { jq: options.jq } : {}) }));
     });
-    command.command("contract <lane>").option("--full").option("--tool <name>").option("--max-output-bytes <bytes>").action(async (lane, options) => { commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("contract", transport, lane, { full: options.full === true, ...(options.tool ? { tool: options.tool } : {}) })); });
+    command.command("contract <lane>").option("--full").option("--tool <name>").option("--max-output-bytes <bytes>").addOption(jqOption()).action(async (lane, options) => { commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("contract", transport, lane, { full: options.full === true, ...(options.tool ? { tool: options.tool } : {}), ...(options.jq !== undefined ? { jq: options.jq } : {}) })); });
     // 2026-11-05 用户实测：`commands --json` 存在，于是大家自然写 `capabilities --json`
     // ——旧实现报 `unknown option`（退出码 10）。输出本来就是 JSON 信封，接受它做兼容别名。
-    command.command("capabilities").option("--compact").option("--json", "兼容别名：输出本就是 JSON 信封（与 commands --json 对齐）").option("--max-output-bytes <bytes>").action(async (options) => { commandExitCode = await withTransport(options, request, (transport) => cmdCapabilities(transport, options.compact === true)); });
+    command.command("capabilities").option("--compact").option("--json", "兼容别名：输出本就是 JSON 信封（与 commands --json 对齐）").option("--max-output-bytes <bytes>").addOption(jqOption()).action(async (options) => { commandExitCode = await withTransport(options, request, (transport) => cmdCapabilities(transport, options.compact === true, options.jq)); });
     // `--env` is accepted but ignored: `next` is a zero-environment-contact route
     // solver, and a caller who reflexively passes `--env` should not be refused
     // (round 15 dogfood: `next "<goal>" --env local` → unknown option, one round).
@@ -2208,8 +2449,8 @@ async function main() {
             ...(Number.isFinite(parsedTop) && parsedTop > 0 ? { top: parsedTop } : {}),
         }));
     });
-    command.command("capability <id>").option("--executable").option("--max-output-bytes <bytes>").action(async (id, options) => {
-        commandExitCode = await withTransport(options, request, (transport) => cmdCapability(id, transport, options.executable === true));
+    command.command("capability <id>").option("--executable").option("--max-output-bytes <bytes>").addOption(jqOption()).action(async (id, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdCapability(id, transport, options.executable === true, options.jq));
     });
     const intentCommand = command.command("intent");
     intentCommand.command("schema").option("--example [id]").action((options) => { commandExitCode = cmdIntentSchema({ request, maxOutputBytes: CLI_DEFAULT_OUTPUT_BYTES }, typeof options.example === "string" ? options.example : undefined, options.example !== undefined); });