@thinkingai/ae-cli 6.1.6 → 6.1.7

package/dist/{te-dataops-MJV54MNY.js → te-dataops-VYN3IOKO.js}

@@ -1268,8 +1268,8 @@ var addSyncSolution = {
     { name: "srcDatasourceId", type: "string", required: true, desc: "Source datasource ID" },
     { name: "sinkComponent", type: "string", required: true, desc: "Sink component name from +list_sync_datasources, e.g. te_etl, ClickHouse, MySQL" },
     { name: "sinkDatasourceId", type: "string", required: true, desc: "Sink datasource ID" },
-    { name: "sourceConfig", type: "string", required: true, desc: "Source configuration JSON string. Preset warehouse source requires tableType, bizClassify, dbBizType, authedSpace, partitionKeys, and successOnEmpty" },
-    { name: "sinkConfig", type: "string", required: true, desc: "Sink configuration JSON string. Preset warehouse sink requires tableType, bizClassify, dbBizType, authedSpace, and partitionKeys" },
+    { name: "sourceConfig", type: "string", required: true, desc: "Source configuration JSON. Include component and follow the source-specific template in the ae-dataops integration skill" },
+    { name: "sinkConfig", type: "string", required: true, desc: "Sink configuration JSON. Include component and follow the sink-specific template in the ae-dataops integration skill" },
     { name: "channelConfig", type: "string", required: false, desc: "Channel configuration JSON string. Include gatewayConfig when source or sink uses the preset warehouse" },
     { name: "fieldsMapping", type: "string", required: false, desc: "Field mapping JSON string" },
     { name: "remark", type: "string", required: false, desc: "Remark" }
@@ -1298,13 +1298,13 @@ function buildArgs35(ctx) {
 var saveSyncSolution = {
   service: "dataops_integration",
   command: "+save_sync_solution",
-  description: "Update a sync solution. Requires complete sourceConfig and sinkConfig JSON; not a partial patch. Call +get_sync_detail --withParams true first",
+  description: "Update a sync solution. Requires complete sourceConfig and sinkConfig JSON; not a partial patch. Call +get_sync_detail --withParams true first. syncName is accepted for compatibility but ignored",
   flags: [
     { name: "spaceCode", type: "string", required: true, desc: "Space code" },
     { name: "syncId", type: "string", required: true, desc: "Sync solution ID" },
-    { name: "syncName", type: "string", required: false, desc: "New sync solution name" },
-    { name: "sourceConfig", type: "string", required: true, desc: "Complete source configuration JSON" },
-    { name: "sinkConfig", type: "string", required: true, desc: "Complete sink configuration JSON" },
+    { name: "syncName", type: "string", required: false, desc: "Ignored on update; the current name is preserved" },
+    { name: "sourceConfig", type: "string", required: true, desc: "Complete source configuration JSON. Include component and follow the source-specific template in the ae-dataops integration skill" },
+    { name: "sinkConfig", type: "string", required: true, desc: "Complete sink configuration JSON. Include component and follow the sink-specific template in the ae-dataops integration skill" },
     { name: "channelConfig", type: "string", required: false, desc: "Complete channel configuration JSON; pass it to keep or update custom channel settings" },
     { name: "fieldsMapping", type: "string", required: false, desc: "Complete field mapping JSON; pass it to keep or update field mappings" },
     { name: "remark", type: "string", required: false, desc: "Updated remark" }

package/dist/{te-dataops-OA7I6HBG.js → te-dataops-Y5QAPPPF.js}

@@ -1266,8 +1266,8 @@ var addSyncSolution = {
     { name: "srcDatasourceId", type: "string", required: true, desc: "Source datasource ID" },
     { name: "sinkComponent", type: "string", required: true, desc: "Sink component name from +list_sync_datasources, e.g. te_etl, ClickHouse, MySQL" },
     { name: "sinkDatasourceId", type: "string", required: true, desc: "Sink datasource ID" },
-    { name: "sourceConfig", type: "string", required: true, desc: "Source configuration JSON string. Preset warehouse source requires tableType, bizClassify, dbBizType, authedSpace, partitionKeys, and successOnEmpty" },
-    { name: "sinkConfig", type: "string", required: true, desc: "Sink configuration JSON string. Preset warehouse sink requires tableType, bizClassify, dbBizType, authedSpace, and partitionKeys" },
+    { name: "sourceConfig", type: "string", required: true, desc: "Source configuration JSON. Include component and follow the source-specific template in the ae-dataops integration skill" },
+    { name: "sinkConfig", type: "string", required: true, desc: "Sink configuration JSON. Include component and follow the sink-specific template in the ae-dataops integration skill" },
     { name: "channelConfig", type: "string", required: false, desc: "Channel configuration JSON string. Include gatewayConfig when source or sink uses the preset warehouse" },
     { name: "fieldsMapping", type: "string", required: false, desc: "Field mapping JSON string" },
     { name: "remark", type: "string", required: false, desc: "Remark" }
@@ -1296,13 +1296,13 @@ function buildArgs35(ctx) {
 var saveSyncSolution = {
   service: "dataops_integration",
   command: "+save_sync_solution",
-  description: "Update a sync solution. Requires complete sourceConfig and sinkConfig JSON; not a partial patch. Call +get_sync_detail --withParams true first",
+  description: "Update a sync solution. Requires complete sourceConfig and sinkConfig JSON; not a partial patch. Call +get_sync_detail --withParams true first. syncName is accepted for compatibility but ignored",
   flags: [
     { name: "spaceCode", type: "string", required: true, desc: "Space code" },
     { name: "syncId", type: "string", required: true, desc: "Sync solution ID" },
-    { name: "syncName", type: "string", required: false, desc: "New sync solution name" },
-    { name: "sourceConfig", type: "string", required: true, desc: "Complete source configuration JSON" },
-    { name: "sinkConfig", type: "string", required: true, desc: "Complete sink configuration JSON" },
+    { name: "syncName", type: "string", required: false, desc: "Ignored on update; the current name is preserved" },
+    { name: "sourceConfig", type: "string", required: true, desc: "Complete source configuration JSON. Include component and follow the source-specific template in the ae-dataops integration skill" },
+    { name: "sinkConfig", type: "string", required: true, desc: "Complete sink configuration JSON. Include component and follow the sink-specific template in the ae-dataops integration skill" },
     { name: "channelConfig", type: "string", required: false, desc: "Complete channel configuration JSON; pass it to keep or update custom channel settings" },
     { name: "fieldsMapping", type: "string", required: false, desc: "Complete field mapping JSON; pass it to keep or update field mappings" },
     { name: "remark", type: "string", required: false, desc: "Updated remark" }

package/dist/te-meta-GBDTMPEL.js

@@ -0,0 +1,95 @@
+import {
+  callMcpTool,
+  parseMcpResult,
+  resolveMcpUrl
+} from "./chunk-CPVTECJ3.js";
+import "./chunk-LCXU3AAT.js";
+import "./chunk-E7UXXHO3.js";
+import "./chunk-IR4ZLVPW.js";
+import "./chunk-V6FR6WTW.js";
+import "./chunk-24BAVOX3.js";
+import "./chunk-LYVNONC4.js";
+
+// src/commands/te-meta/shared.ts
+function createMcpCommand(config) {
+  const toolName = config.command.slice(1);
+  const mcpService = config.mcpService || "analysis";
+  return {
+    service: "analysis_meta",
+    command: config.command,
+    description: config.description,
+    flags: config.flags,
+    risk: config.risk,
+    dryRun: (ctx) => ({
+      method: "tools/call",
+      url: resolveMcpUrl(ctx.mcpUrl(), ctx.host(), mcpService),
+      body: {
+        name: toolName,
+        arguments: config.buildArgs(ctx)
+      }
+    }),
+    execute: async (ctx) => {
+      const url = resolveMcpUrl(ctx.mcpUrl(), ctx.host(), mcpService);
+      const result = await callMcpTool(url, toolName, config.buildArgs(ctx), ctx.host());
+      return parseMcpResult(result);
+    }
+  };
+}
+function optionalJson(ctx, name) {
+  const value = ctx.str(name);
+  return value === "" ? void 0 : ctx.json(name);
+}
+
+// src/commands/te-meta/meta/batch-edit-metadata.ts
+var batchEditMetadata = createMcpCommand({
+  command: "+batch_edit_metadata",
+  description: "Batch edit effective system metadata only",
+  flags: [
+    { name: "project_id", type: "number", required: true, alias: "p", desc: "Project ID" },
+    { name: "type", type: "string", required: true, desc: "Metadata type: event, event_property, or user_property" },
+    { name: "items", type: "json", required: true, desc: "Batch edit item list JSON array" }
+  ],
+  risk: "write",
+  mcpService: "te_analysis_extend",
+  buildArgs: (ctx) => ({
+    projectId: ctx.num("project_id"),
+    type: ctx.str("type"),
+    items: ctx.json("items")
+  })
+});
+
+// src/commands/te-meta/meta/batch-create-metadata.ts
+var batchCreateMetadata = createMcpCommand({
+  command: "+batch_create_metadata",
+  description: "Batch create effective system metadata only",
+  flags: [
+    { name: "project_id", type: "number", required: true, alias: "p", desc: "Project ID" },
+    { name: "events", type: "json", required: false, desc: "Event creation list JSON array" },
+    { name: "event_properties", type: "json", required: false, desc: "Event property creation list JSON array" },
+    { name: "user_properties", type: "json", required: false, desc: "User property creation list JSON array" }
+  ],
+  risk: "write",
+  mcpService: "te_analysis_extend",
+  buildArgs: (ctx) => ({
+    projectId: ctx.num("project_id"),
+    events: optionalJson(ctx, "events"),
+    eventProperties: optionalJson(ctx, "event_properties"),
+    userProperties: optionalJson(ctx, "user_properties")
+  })
+});
+
+// src/commands/te-meta/meta/index.ts
+var commands = [
+  batchEditMetadata,
+  batchCreateMetadata
+];
+var meta_default = commands;
+
+// src/commands/te-meta/index.ts
+var commands2 = [
+  ...meta_default
+];
+var te_meta_default = commands2;
+export {
+  te_meta_default as default
+};

package/dist/te-meta-ZTLTSHXC.js

@@ -0,0 +1,95 @@
+import {
+  callMcpTool,
+  parseMcpResult,
+  resolveMcpUrl
+} from "./chunk-3P3562ZX.js";
+import "./chunk-LCXU3AAT.js";
+import "./chunk-E7UXXHO3.js";
+import "./chunk-IR4ZLVPW.js";
+import "./chunk-V6FR6WTW.js";
+import "./chunk-24BAVOX3.js";
+import "./chunk-LYVNONC4.js";
+
+// src/commands/te-meta/shared.ts
+function createMcpCommand(config) {
+  const toolName = config.command.slice(1);
+  const mcpService = config.mcpService || "analysis";
+  return {
+    service: "analysis_meta",
+    command: config.command,
+    description: config.description,
+    flags: config.flags,
+    risk: config.risk,
+    dryRun: (ctx) => ({
+      method: "tools/call",
+      url: resolveMcpUrl(ctx.mcpUrl(), ctx.host(), mcpService),
+      body: {
+        name: toolName,
+        arguments: config.buildArgs(ctx)
+      }
+    }),
+    execute: async (ctx) => {
+      const url = resolveMcpUrl(ctx.mcpUrl(), ctx.host(), mcpService);
+      const result = await callMcpTool(url, toolName, config.buildArgs(ctx), ctx.host());
+      return parseMcpResult(result);
+    }
+  };
+}
+function optionalJson(ctx, name) {
+  const value = ctx.str(name);
+  return value === "" ? void 0 : ctx.json(name);
+}
+
+// src/commands/te-meta/meta/batch-edit-metadata.ts
+var batchEditMetadata = createMcpCommand({
+  command: "+batch_edit_metadata",
+  description: "Batch edit effective system metadata only",
+  flags: [
+    { name: "project_id", type: "number", required: true, alias: "p", desc: "Project ID" },
+    { name: "type", type: "string", required: true, desc: "Metadata type: event, event_property, or user_property" },
+    { name: "items", type: "json", required: true, desc: "Batch edit item list JSON array" }
+  ],
+  risk: "write",
+  mcpService: "te_analysis_extend",
+  buildArgs: (ctx) => ({
+    projectId: ctx.num("project_id"),
+    type: ctx.str("type"),
+    items: ctx.json("items")
+  })
+});
+
+// src/commands/te-meta/meta/batch-create-metadata.ts
+var batchCreateMetadata = createMcpCommand({
+  command: "+batch_create_metadata",
+  description: "Batch create effective system metadata only",
+  flags: [
+    { name: "project_id", type: "number", required: true, alias: "p", desc: "Project ID" },
+    { name: "events", type: "json", required: false, desc: "Event creation list JSON array" },
+    { name: "event_properties", type: "json", required: false, desc: "Event property creation list JSON array" },
+    { name: "user_properties", type: "json", required: false, desc: "User property creation list JSON array" }
+  ],
+  risk: "write",
+  mcpService: "te_analysis_extend",
+  buildArgs: (ctx) => ({
+    projectId: ctx.num("project_id"),
+    events: optionalJson(ctx, "events"),
+    eventProperties: optionalJson(ctx, "event_properties"),
+    userProperties: optionalJson(ctx, "user_properties")
+  })
+});
+
+// src/commands/te-meta/meta/index.ts
+var commands = [
+  batchEditMetadata,
+  batchCreateMetadata
+];
+var meta_default = commands;
+
+// src/commands/te-meta/index.ts
+var commands2 = [
+  ...meta_default
+];
+var te_meta_default = commands2;
+export {
+  te_meta_default as default
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingai/ae-cli",
-  "version": "6.1.6",
+  "version": "6.1.7",
   "description": "CLI tool for ThinkingAI (AE) analytics platform",
   "type": "module",
   "bin": {
@@ -39,8 +39,9 @@
     "verify:analysis-common-tools": "node scripts/verify-te-common-tools.mjs",
     "verify:experiment-tools": "node scripts/verify-te-experiment-tools.mjs && node --import tsx test/experiment/experiment-capability-command.test.mjs",
     "verify:team-tools": "node scripts/verify-te-team-tools.mjs",
-    "verify:agent-tools": "node scripts/verify-agent-tools.mjs",
-    "verify:tracking-tools": "tsx test/tracking-client.test.mjs && node test/tracking-skill-flow.test.mjs && node test/tracking-commands.test.mjs",
+    "verify:agent-tools": "node scripts/verify-agent-tools.mjs && npm run verify:sandbox-tools",
+    "verify:sandbox-tools": "tsx test/sandbox-tools.test.ts",
+    "verify:tracking-tools": "node test/tracking-client.test.mjs && node test/tracking-skill-flow.test.mjs && node test/tracking-commands.test.mjs",
     "verify:self-check-overlay": "node test/self-check-overlay.test.mjs",
     "verify:update-check": "npx tsx test/update-check.test.mjs",
     "qa-changed": "node scripts/qa-changed.mjs",
@@ -50,7 +51,7 @@
     "check:agents-docs": "node scripts/check-agents-docs-sync.mjs",
     "prepublishOnly": "npm run check:release && npm run build",
     "start": "node dist/index.js",
-    "test": "npx tsx src/index.ts --help"
+    "test": "npx tsx src/index.ts --help && npm run verify:sandbox-tools"
   },
   "repository": {
     "type": "git",

package/skills/ae-agent/SKILL.md

@@ -63,7 +63,7 @@ Use `ae-agent` for all Agent platform resource work:
 
 If the user's intent is data analysis, audience management, metadata governance, TeamRuns, or knowledge bases, switch to `ae-analysis` / `ae-engage` / `ae-dataops` / `ae-team` / `ae-kb`.
 
-## Tool Groups (66 commands)
+## Tool Groups (67 commands)
 
 ### Agents (5)
 
@@ -167,6 +167,10 @@ If the user's intent is data analysis, audience management, metadata governance,
 - `+del-attachment` ([doc](references/del-attachment.md)) — soft-delete an attachment
 - `+attachment-stats` ([doc](references/attachment-stats.md)) — attachment library stats (total count/size, image/document breakdown)
 
+### Sandbox tools (1)
+
+- `+list-sandbox-tools` ([doc](references/list-sandbox-tools.md)) — list tools activated in the current sandbox (scan /home/ta/.local/bin managed shims; report active/broken; local scan, no remote API)
+
 ## Cross-Command Notes
 
 - **Automation IDs**: use `+list-automations` to find the target ID internally, but do not surface raw automation IDs, raw JSON, or concrete detail paths in user-facing replies.

package/skills/ae-agent/references/list-sandbox-tools.md

@@ -0,0 +1,79 @@
+# agent +list-sandbox-tools (List Sandbox Tools)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Sandbox tools / read**
+
+## Use Cases
+
+- List tools activated in the current sandbox by scanning `/home/ta/.local/bin` for managed shims.
+- Each managed shim carries a `managed-by: te-agent-sandbox-tools` marker plus tool, version, command, target, and runtime fields. The command verifies the real target path, share-root containment, file type, and runtime-specific permissions.
+- This is a **local filesystem scan** — it does NOT call any remote API and does not require `--host` or a token.
+
+## Mandatory Rules (MUST)
+
+- Only entries with the `managed-by: te-agent-sandbox-tools` marker are reported; non-managed files in `/home/ta/.local/bin` are ignored (deactivate on the admin side only removes managed entries).
+- The command runs inside the sandbox; ensure `/home/ta/.local/bin` is readable.
+- Managed shim symlinks, oversized shims, malformed or duplicate marker fields, and targets outside `${SANDBOX_SYSTEM_SHARE_ROOT:-/data/app/te_agent_ta/share}/tools` are never treated as active.
+
+## Command
+
+```bash
+ae-cli agent +list-sandbox-tools
+
+# Filter to only broken entries
+ae-cli agent +list-sandbox-tools --status broken
+
+# Dry-run to inspect the scan target (no disk read)
+ae-cli agent +list-sandbox-tools --dry-run
+```
+
+## Parameters
+
+| Parameter  | Required | Description                            |
+| ---------- | -------- | -------------------------------------- |
+| `--status` | No       | Filter by status: `active` \| `broken` |
+
+## Decision Rules
+
+- Use this to inspect which managed sandbox tools are currently usable in this sandbox.
+- `active` = the real target stays inside the configured tools root, is a regular file, and is readable for `node` or executable for `native`.
+- `broken` = the managed shim or target fails marker, containment, file-type, or permission checks. Re-activate via the admin console to repair.
+- Legacy shims without version/runtime remain readable: both fields are reported as `unknown`, and the target must at least be readable.
+- `summary` counts reflect the full scan (before `--status` filtering); `tools` respects the `--status` filter.
+
+## Response Shape
+
+```json
+{
+  "tools": [
+    {
+      "tool": "ae-cli",
+      "version": "1.0.32",
+      "command": "ae-cli",
+      "runtime": "node",
+      "target": "/data/app/te_agent_ta/share/tools/ae-cli/1.0.32/bin/ae-cli.js",
+      "status": "active"
+    },
+    {
+      "tool": "gstack",
+      "version": "0.1.0",
+      "command": "gstack",
+      "runtime": "native",
+      "target": "/data/app/te_agent_ta/share/tools/gstack/0.1.0/bin/gstack",
+      "status": "broken",
+      "reason": "target missing"
+    }
+  ],
+  "summary": { "total": 2, "active": 1, "broken": 1 }
+}
+```
+
+## Next Steps on Failure
+
+- Empty `tools` with `summary.total=0`: no managed shims in this sandbox; activate tools from the admin console (system management → sandbox management → sandbox tools) first.
+- `broken` entries: the shared tool package may have been removed or the version path changed; re-activate the tool from the admin console.
+
+## Recommended Chaining
+
+- `+list-sandbox-tools` → spot `broken` → ask the admin to re-activate via the sandbox tools admin page.

package/skills/ae-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-analysis
-version: 4.0.3
+version: 4.0.4
 description: "Use ae-cli for AE/TE analysis-side data questions, asset operations, and asset governance: reports, analysis boards, BI dashboards, ad-hoc models, drilldown, detail data, alerts, clusters, tags, metrics, metadata, project configuration, tracking plans, governance asset lists/rules/lineage/impact/dependency, batch asset operations, projects, and resource links. Use when the user asks to query data, explain a change, export evidence, or inspect/create/update/govern analysis assets."
 ---
 
@@ -28,9 +28,8 @@ Use this skill for these CLI services:
 - `analysis`: reports, dashboards, BI panels, ad-hoc analysis, drilldown, detail data, alerts, clusters, tags, and async runs/artifacts.
 - `analysis-meta`: gateway metadata assets, events, properties, virtual metadata, metrics, data tables, exchange rules, and super metadata.
 - `analysis-governance`: gateway asset governance operations, including governed asset lists/exports, lineage, dependency, impact, query history, rule schema/list/create/update/delete, batch asset actions, and operation records. Use this service for asset governance workflows, not for metadata event/property/metric CRUD.
-- `tracking`: gateway tracking plan, checking, ingest, live-data, and event blacklist operations. Some legacy tracking commands still exist under the same service; prefer the dedicated reference for the exact command form.
-- `analysis_meta`: metadata governance, metrics, virtual metadata, project config, tracking plans, mark times, and entity catalog.
-- `analysis_common`: project discovery.
+- `tracking`: gateway tracking plan, checking, ingest, live-data, and event blacklist operations.
+- `analysis_meta`: legacy metadata batch operations not yet covered by gateway commands.
 
 For metadata gateway detail outside the commands in the generated index, use the metadata skill. For Engage, DataOps, or Community work, use the corresponding skill.
 
@@ -45,7 +44,6 @@ Command forms:
 ```bash
 ae-cli analysis +<command> [options]
 ae-cli analysis_meta +<command> [options]
-ae-cli analysis_common +<command> [options]
 ae-cli analysis <resource> <action> [options]
 ae-cli analysis-meta <resource> <action> [options]
 ae-cli analysis-governance <resource> <action> [options]
@@ -96,7 +94,7 @@ For every gateway command that exposes `--request-id`, ae-cli generates a `reque
 Before a project-scoped command:
 
 1. Reuse a project only when its ID and host/environment were already verified in the same continuous conversation.
-2. Otherwise call `analysis_common +list_projects` and resolve the supplied ID/name.
+2. Otherwise call `analysis project info list` and resolve the supplied ID/name.
 3. If there are multiple plausible projects, the host is unclear, or no project matches, show the candidates and ask; never guess.
 4. Re-verify after the user changes project, host, or environment.
 
@@ -123,9 +121,10 @@ Do not call removed QP builders or schema helpers for ad-hoc analysis. `--defini
 - Metric value, trend, comparison, or anomaly -> saved report/dashboard first, then ad-hoc data.
 - Metric definition search/create/update -> metadata commands.
 - Event/entity rows -> `event-detail run|export` or `entity-detail run|export`.
-- Events/entities from a query result -> follow the returned synchronous `query_context_id` and `sources[].drilldown`; never reconstruct raw QP or use export rows as coordinates.
+- Events/entities from a query result -> pass the original `--project-id`, then follow the returned synchronous `query_context_id` and `sources[].drilldown`; never reconstruct raw QP or use export rows as coordinates.
 - Cluster/tag definition -> matching gateway cluster/tag commands and matching model reference.
-- Alert/configuration/tracking-plan requests -> dedicated legacy command reference from the index.
+- Tag/cluster candidate values, including requests phrased as "latest version" or "latest result" -> resolve the exact asset, then use `analysis filter-value list` with `cluster_date_policy=LATEST`. This means the latest computed data snapshot, never a definition or configuration release; do not invent version lists, version IDs, draft states, or publish states.
+- Alert/configuration/tracking-plan requests -> the dedicated gateway command reference from the index.
 
 ### Run, export, and follow-up
 
@@ -133,7 +132,7 @@ Do not call removed QP builders or schema helpers for ad-hoc analysis. `--defini
 - `export` is for complete, unknown-size, over-limit, or long-running results. It returns `run_id` and `artifact_id`.
 - Drilldown event/entity/user-event exports are `csv.gz` full-download streams bounded by `model_full_download_limit`; never pass or simulate `limit`, `offset`, `page_num`, or `page_size`.
 - Inspect with `analysis run inspect`, download with `analysis artifact download`, and cancel with `analysis query cancel`. Do not call raw lifecycle URLs.
-- Drilldown requires a synchronous preview context and the selected source's returned row/column/metric coordinate options. If they are absent or the action is not advertised, report that drilldown/result-cluster creation is unavailable.
+- Drilldown requires the original `--project-id`, a synchronous preview context, and the selected source's returned row/column/metric coordinate options. Common rejects a project ID that does not match the stored context. If the context/options are absent or the action is not advertised, report that drilldown/result-cluster creation is unavailable.
 
 ### Writes and destructive operations
 

package/skills/ae-analysis/references/adhoc_export.md

@@ -2,6 +2,8 @@
 
 Submit one unified ad-hoc analysis export from an AI-facing model definition.
 
+Typical closed loop: define and validate the analysis -> resolve an authorized physical query route if needed -> submit once -> keep the returned run/artifact pair -> inspect -> download -> analyze the complete artifact. Use a separate synchronous run when interactive drilldown is required.
+
 Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `export` command instead of `adhoc run`.
 
 ## Command
@@ -15,6 +17,8 @@ ae-cli analysis adhoc export \
   [--use-cache true|false] \
   [--zone-offset <hours>] \
   [--fields '["列名"]'] \
+  [--cluster-query-scope GLOBAL|SLAVE] \
+  [--slave-cluster-id <id>] \
   [--artifact-format jsonl|csv] \
   [--timeout-seconds <n>]
 ```
@@ -44,6 +48,8 @@ Do not use raw QP, `events`, `event_view`, `visual_view`, removed ad-hoc QP buil
 
 Timezone contract: fixed `--zone-offset` values are integers from `-12` through `14`. Use `--zone-offset 99` for local-time mode, which analyzes timestamps as stored local time without applying a fixed UTC offset conversion; it does not mean UTC+99. Omit the flag to use the project's analysis default.
 
+Cluster routing is identical to `adhoc run`: omit for current self; discover permissions and physical IDs with `analysis query-cluster list`; `SLAVE` requires an ID. SQL, attribution, and default-interval distribution reject unsupported `GLOBAL` rather than silently changing scope.
+
 ## Output
 
 The response is an async artifact descriptor:
@@ -57,6 +63,8 @@ The response is an async artifact descriptor:
 
 Preserve the `run_id` and `artifact_id` from this exact submit response as one pair. Do not infer either ID from a path or reuse an ID from another export.
 
+Export submission compiles the definition before creating an artifact or run. The execute, `--validate`, and `--dry-run` paths return `AI_QP_COMPILE_FAILED` immediately when clarification is required, with `meta.compile_status`, full `meta.errors[]` (including `candidates` and `suggestions`), `meta.resolved`, and `meta.warnings`. A compile failure has no `run_id` or `artifact_id`; resolve the ambiguity and submit a new request.
+
 Use:
 
 ```bash

package/skills/ae-analysis/references/adhoc_run.md

@@ -4,6 +4,8 @@ Run one unified ad-hoc analysis inline query from an AI-facing model definition.
 
 Use this command for AI-facing ad-hoc model analysis. Do not use removed ad-hoc QP builder or schema helper commands.
 
+Typical closed loop: express the business question as an AI-facing definition -> let the compiler resolve metadata -> use `analysis filter-value list` only when an exact stored value remains unknown -> optionally resolve a physical route -> run -> verify `resolved`, warnings, and actual scope -> drill down only through the returned query context.
+
 Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `run` command instead of `adhoc export`.
 
 ## Command
@@ -17,6 +19,8 @@ ae-cli analysis adhoc run \
   [--use-cache true|false] \
   [--zone-offset <hours>] \
   [--fields '["列名"]'] \
+  [--cluster-query-scope GLOBAL|SLAVE] \
+  [--slave-cluster-id <id>] \
   [--limit <n>] \
   [--timeout-seconds <n>]
 ```
@@ -41,6 +45,8 @@ Do not use raw QP, `events`, `event_view`, `visual_view`, removed ad-hoc QP buil
 
 Timezone contract: fixed `--zone-offset` values are integers from `-12` through `14`. Use `--zone-offset 99` for local-time mode, which analyzes timestamps as stored local time without applying a fixed UTC offset conversion; it does not mean UTC+99. Omit the flag to use the project's analysis default.
 
+Cluster routing: omit both routing flags for current-self data. Before `GLOBAL` or `SLAVE`, call `analysis query-cluster list`; `SLAVE` requires exactly one returned physical cluster ID. SQL and attribution do not support `GLOBAL`; distribution with default intervals also rejects `GLOBAL`. These 查询集群 options are unrelated to 用户分群 definitions.
+
 ## Output
 
 The response may include:
@@ -50,7 +56,10 @@ The response may include:
 - `title` / `rows` / `total` / `returned_rows` / `truncated`: tabular preview fields. When truncated, use `adhoc export`; there is no next-page request.
 - `result`: direct result for non-tabular models.
 - `request_id`: lifecycle request id.
+- `actual_cluster_query_scope`, optional `actual_slave_cluster_id`, and `cluster_query_scope_source`: actual physical data route. Verify these before comparing results or following the query context.
 
 Execution failures are returned as command failures with `request_id`; only the explicit project-no-data condition is a successful empty result. Do not interpret an empty object as evidence that a failed query succeeded.
 
+The execute, `--validate`, and `--dry-run` paths all compile the AI-facing definition. If metadata resolution needs clarification, the command fails with `AI_QP_COMPILE_FAILED`; inspect `meta.compile_status`, `meta.errors[]`, `meta.resolved`, and `meta.warnings`. Each error retains `path`, `message`, `code`, `candidates`, and `suggestions`. Select an exact candidate from this response or ask the user; do not guess from display text.
+
 Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Use the context only with an action advertised by the selected source/metric, and assemble the coordinate only from returned option fragments. Do not pass raw QP or infer a coordinate from display text.

package/skills/ae-analysis/references/ai_models.md

@@ -376,7 +376,7 @@ Time placeholder:
 {
   "sql": "select * from events where ${PartDate:ds}",
   "params": [
-    {"name": "ds", "type": "part_date", "recent_day": "1-7"}
+    {"name": "ds", "type": "part_date", "recent_day": "1-7", "use_timezone": true}
   ]
 }
 ```
@@ -386,11 +386,13 @@ Rules:
 - If SQL has no `${...}` placeholder, omit `params`.
 - If SQL has placeholders, every placeholder must have one matching item in `params`.
 - Raw variables use `${name}`, not `${Variable:name}`. A selector's `value` must equal one of its `options[].value` values. `${PartDate:name}` expands to a complete predicate, so place it directly after `WHERE`/`AND` rather than after a column name.
+- `use_timezone` is an optional boolean definition field that is only valid for `part_date`. It defaults to `false`. When `true`, that PartDate parameter uses the query's effective timezone selected by `zone_offset` or the current user/project default; when `false`, it follows the non-timezone-aware PartDate path. This is distinct from the command-level `zone_offset`.
 - Do not pass SQL-IDE internals such as `sqlVoParams`, `sqlViewParams`, `paramType`, `paramName`, `paramExpress`, `commonFilter`, or `requiredEvents`.
 - Delimit any Trino identifier containing `#`, `$`, `@`, spaces, or punctuation with double quotes, for example `"#user_id"` and `"$part_event"`. Single quotes create string literals, not identifiers. Escape a literal double quote inside an identifier by doubling it. The CLI preserves the submitted SQL and does not rewrite identifiers.
 - For an event table, include a date-partition predicate on the discovered `"$part_date"` column, for example `WHERE "$part_date" BETWEEN '2026-07-01' AND '2026-07-07'`. The backend rejects event-table SQL without this condition.
 - Do not invent table or column names. If the user already provides a concrete table reference, use `analysis-meta datatable columns-get --project-id <project_id> --table-ref <table_ref>` to inspect columns before writing SQL. If the table itself is unknown, call `analysis sql-table list --project-id <project_id>` when available and select an exact returned `table_ref`; otherwise stop and ask for the table/data source. Ask the user only when multiple authorized tables remain semantically plausible after discovery.
 - For a saved dynamic SQL report, put the default values in `analysis report create/update --definition`. Verify the default once with `analysis report-data run` without `--sql-params`, then verify a changed value with one value-only `--sql-params` override.
+- `use_timezone` belongs to the saved parameter definition. To change it, update the report `definition`; never pass it through report-data `--sql-params`, which changes values only.
 - SQL tags and SQL clusters do not use this general parameter contract. They accept only `${PartDate:name}` with `type=part_date`, and their tables must be discovered with `analysis sql-table list/columns --usage tag_cluster`; see `user_tag_models.md` and `user_cluster_models.md`.
 
 ### `heat_map`

package/skills/ae-analysis/references/analysis_data_retrieval.md

@@ -80,6 +80,8 @@ Only synchronous `adhoc run`, `report-data run`, and `dashboard-report-data run`
 
 Follow-up commands are allowed only when the selected source/metric advertises the exact action. Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md), select only returned row/column/metric options, and never infer source IDs, dates, groups, model fields, or analysis angles from display text.
 
+Pass the original `--project-id` with every query-context or drilldown-context follow-up. Gateway uses it for project authorization, and Common rejects it if it does not match the project stored by the context ID.
+
 When present, compare `effective_time_range` with `data_time_range`. `effective_time_range` is the resolved query scope, while `data_time_range` is the observed returned-row range. `clipping_reasons=[]` means the gateway applied no silent range cap; a narrower `data_time_range` then reflects available/returned data rather than a gateway range clamp.
 
 Use that synchronous `query_context_id` for the advertised action only:

package/skills/ae-analysis/references/analysis_drilldown_contract.md

@@ -6,6 +6,8 @@ This contract controls every follow-up from an analysis result. Read it before c
 
 Only a synchronous `adhoc run`, `report-data run`, or `dashboard-report-data run` preview can create `query_context_id` and selectable drilldown coordinates. The selectable population is exactly the returned preview, after its `--limit` is applied. If `--limit 10` returns ten rows, only coordinates represented by those ten rows may be selected.
 
+Every query-context or drilldown-context follow-up must also pass the original `--project-id`. Gateway uses it for project authorization, then Common verifies that it matches the project stored by the context ID. Never substitute a different project ID.
+
 Exports never create a query context. A downloaded file, export submit response, or export artifact must never be used to invent or extend drilldown coordinates. To drill into a large result, first run a bounded synchronous preview containing the desired row; do not raise the limit merely to manufacture a complete target catalog.
 
 SQL, `heat_map`, `rank_list`, `revenue`, and scenario models do not support this analysis drilldown contract. Stop when `source.drilldown.actions` is empty or `unavailable_reason` is present.

package/skills/ae-analysis/references/analysis_gateway_assets.md

@@ -73,19 +73,21 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. Analys
 
 | Command | Capability ID | Use for | Key input | Output |
 | --- | --- | --- | --- | --- |
-| `adhoc run` | `analysis.adhoc.run` | Unified ad-hoc inline query for 12 AI models: 9 common + 3 scenario models | `--project-id`, `--model-type`, AI-facing `--definition` | Inline data plus optional `query_context_id` |
+| `filter-value list` | `analysis.filter_value.list` | Resolve exact stored values for one known event/user property before building a filter; not property discovery or aggregation | `--property-name`, `--table-type`, optional event/prefix/snapshot inputs | Candidate values in `items` |
+| `query-cluster list` | `analysis.query_cluster.list` | List physical 查询集群/data-routing options; not 用户分群/audience assets | `--project-id` | Current/accessible slave clusters and allowed routing parameters |
+| `adhoc run` | `analysis.adhoc.run` | Unified ad-hoc inline query for 12 AI models: 9 common + 3 scenario models | `--project-id`, `--model-type`, AI-facing `--definition`, optional physical cluster route | Inline data plus actual route and optional `query_context_id` |
 | `adhoc export` | `analysis.adhoc.export` | Unified ad-hoc async export for 12 AI models: 9 common + 3 scenario models | same as run, plus optional `--artifact-format`; no inline `--limit` | Async artifact descriptor; no drilldown context |
-| `drilldown-events run/export` | `analysis.query.drilldown_events` / `analysis.query.drilldown_events_export` | Preview or full-stream events for an advertised `EVENT_LIST` cell | `--query-context-id`, optional `--source`, `--coordinate` | Bounded event rows or `csv.gz` artifact |
-| `drilldown-entities run/export` | `analysis.query.drilldown_entities` / `analysis.query.drilldown_entities_export` | Preview/export users or custom entities for an advertised entity cell | `--query-context-id`, optional `--source`, `--coordinate` | Subject plus entity rows/artifact |
-| `query drilldown-user-events` | `analysis.query.drilldown_user_events` | Query one drilldown user's event sequence | `--drilldown-context-id`, `--user-id` | Event sequence rows |
-| `query create-result-cluster` | `analysis.query.create_result_cluster` | Save the advertised user/custom-entity cell population as its result cluster | `--query-context-id`, optional `--source`, `--coordinate`, `--cluster-name` | Result cluster creation result |
+| `drilldown-events run/export` | `analysis.query.drilldown_events` / `analysis.query.drilldown_events_export` | Preview or full-stream events for an advertised `EVENT_LIST` cell | `--project-id`, `--query-context-id`, optional `--source`, `--coordinate` | Bounded event rows or `csv.gz` artifact |
+| `drilldown-entities run/export` | `analysis.query.drilldown_entities` / `analysis.query.drilldown_entities_export` | Preview/export users or custom entities for an advertised entity cell | `--project-id`, `--query-context-id`, optional `--source`, `--coordinate` | Subject plus entity rows/artifact |
+| `query drilldown-user-events` | `analysis.query.drilldown_user_events` | Query one drilldown user's event sequence | `--project-id`, `--drilldown-context-id`, `--user-id` | Event sequence rows |
+| `query create-result-cluster` | `analysis.query.create_result_cluster` | Save the advertised user/custom-entity cell population as its result cluster | `--project-id`, `--query-context-id`, optional `--source`, `--coordinate`, `--cluster-name` | Result cluster creation result |
 | `report list` | `analysis.report.list` | Find accessible reports | `--project-id`, optional `--query`, `--fields`, `--limit`, `--offset` | Paginated report summaries |
 | `report list-export` | `analysis.report.list_export` | Export report catalog | same as list, plus optional `--artifact-format`, `--request-id` | Async artifact descriptor |
 | `report get` | `analysis.report.get` | Inspect current report definition as AI QP | `--project-id`, `--report-id` | Report metadata plus `model_type` and `definition` |
 | `report create` | `analysis.report.create` | Create a report from AI QP definition | `--report-name`, `--model-type`, `--definition` | Created report ID and normalized definition |
 | `report update` | `analysis.report.update` | Update metadata or AI QP definition | `--report-id`, `--report-version`, update fields | Update result |
 | `report delete` | `analysis.report.delete` | Delete reports | `--report-ids '[...]'` | Delete result |
-| `report-data run` | `analysis.report_data.run` | Bounded inline report data | `--report-ids`, optional AI-facing `--filters`, `--group-by`, SQL dynamic parameter value-only `--sql-params`, time/limit | Inline data plus optional `query_context_id` |
+| `report-data run` | `analysis.report_data.run` | Bounded inline report data | `--report-ids`, optional overrides, `--cluster-query-scope`, conditional `--slave-cluster-id`, time/limit | Inline data plus actual route and optional `query_context_id` |
 | `report-data export` | `analysis.report_data.export` | Large/long report data | same as run, plus optional `--artifact-format` | Async artifact descriptor; no drilldown context |
 | `query cancel` | `analysis.query.cancel` | Cancel any async analysis export | `--run-id`, optional `--reason` | Cancellation result |
 | `report-change-log list` | `analysis.report_change_log.list` | List one report's change logs | `--report-id` | Change log summaries |
@@ -105,7 +107,7 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. Analys
 | `dashboard freeze` | `analysis.dashboard.freeze` | Freeze/unfreeze dashboards | `--dashboard-ids`, optional `--freeze false` | Freeze status |
 | `dashboard abnormal-get` | `analysis.dashboard.abnormal_get` | Inspect abnormal dependencies | `--dashboard-id` | Abnormal info |
 | `dashboard task-status` | `analysis.dashboard.task_status` | Inspect scheduled task status | `--dashboard-id` | Task status |
-| `dashboard-report-data run` | `analysis.dashboard_report_data.run` | Bounded inline dashboard report data; `--filters` is analysis Filter JSON from `+get_filter_schema` | `--dashboard-id`, optional `--report-ids`, `--filters`, `--start-time`, `--end-time`, `--limit` | Inline data plus optional `query_context_id` |
+| `dashboard-report-data run` | `analysis.dashboard_report_data.run` | Bounded inline dashboard report data; omitted route follows saved dashboard configuration | `--dashboard-id`, optional reports/filters/time and physical cluster route | Inline data plus actual route and optional `query_context_id` |
 | `dashboard-report-data export` | `analysis.dashboard_report_data.export` | Large/long dashboard report data | same as run, plus optional `--artifact-format jsonl` | Async artifact descriptor; no drilldown context |
 | `run inspect` | `analysis.run.inspect` | Poll async export status | `--run-id` | Run and artifact status |
 | `artifact download` | `analysis.artifact.download` | Download run-bound export artifact | `--run-id`, `--artifact-id`, `--output` | Local output file info |