@thinkingai/ae-cli 6.0.37 → 6.0.38

package/dist/{te-analysis-IWQZO423.js → te-analysis-RAC67YYD.js}

@@ -9,6 +9,7 @@ import {
   CapabilityGatewayError,
   buildCapabilityGatewayUrl,
   dryRunCapability,
+  executeCapability,
   executeCapabilityWithEnvelope,
   fetchCapabilityGateway,
   requestCapabilityGateway,
@@ -5860,6 +5861,24 @@ var dataTypeFlag = {
   required: false,
   desc: "Live data type: normal (default) or error."
 };
+var debugDeviceIdFlag = {
+  name: "device-id",
+  type: "string",
+  required: true,
+  desc: "Debug device ID reported by the SDK as #device_id."
+};
+var debugDeviceNameFlag = {
+  name: "device-name",
+  type: "string",
+  required: true,
+  desc: "Human-readable name for the Debug device."
+};
+var eventNameFlag = {
+  name: "event-name",
+  type: "string",
+  required: false,
+  desc: "Optional event name filter."
+};
 var eventNamesFlag = {
   name: "event-names",
   type: "json",
@@ -6086,6 +6105,323 @@ var trackingPlanSyncFromMeta = createTrackingCapabilityCommand({
   buildInput: projectInput2
 });
 
+// src/commands/te-analysis/tracking/plan/sync-display-names.ts
+import { existsSync as existsSync3 } from "fs";
+import { readFile } from "fs/promises";
+
+// src/tracking/plan/display-name-sync.ts
+function buildDisplayNameSyncPlan(draft, metadata) {
+  return {
+    event: buildGroup(
+      "event",
+      eventDefinitions(draft.events),
+      existingDefinitions(metadata.events, "event_name", "event_desc")
+    ),
+    event_property: buildGroup(
+      "event_property",
+      propertyDefinitions([
+        ...draft.common_event_properties,
+        ...draft.event_properties
+      ]),
+      existingDefinitions(metadata.eventProperties, "prop_name", "prop_desc")
+    ),
+    user_property: buildGroup(
+      "user_property",
+      propertyDefinitions(draft.user_properties),
+      existingDefinitions(metadata.userProperties, "prop_name", "prop_desc")
+    )
+  };
+}
+function assertTrackingDraft(value) {
+  if (!isRecord(value)) {
+    throw new Error("Tracking draft must be a JSON object.");
+  }
+  for (const field of [
+    "events",
+    "event_properties",
+    "common_event_properties",
+    "user_properties"
+  ]) {
+    if (!Array.isArray(value[field])) {
+      throw new Error(`Tracking draft field "${field}" must be an array.`);
+    }
+  }
+}
+function eventDefinitions(events) {
+  return definitions(
+    events.map((event) => ({
+      name: event.event_name,
+      displayName: event.display_name
+    })),
+    "event"
+  );
+}
+function propertyDefinitions(properties) {
+  return definitions(
+    properties.map((property) => ({
+      name: property.name,
+      displayName: property.display_name
+    })),
+    "property"
+  );
+}
+function definitions(candidates, kind) {
+  const byName = /* @__PURE__ */ new Map();
+  const missing = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) {
+    const name = nonEmptyString(candidate.name);
+    if (!name) continue;
+    const displayName = nonEmptyString(candidate.displayName);
+    if (!displayName) {
+      if (!byName.has(name)) missing.add(name);
+      continue;
+    }
+    const previous = byName.get(name);
+    if (previous && previous !== displayName) {
+      throw new Error(
+        `Tracking draft maps ${kind} "${name}" to conflicting display names: "${previous}" and "${displayName}".`
+      );
+    }
+    byName.set(name, displayName);
+    missing.delete(name);
+  }
+  return {
+    definitions: [...byName.entries()].map(([name, displayName]) => ({
+      name,
+      displayName
+    })),
+    missing: [...missing]
+  };
+}
+function existingDefinitions(value, nameField, displayNameField) {
+  if (!Array.isArray(value)) return [];
+  const rows = [];
+  for (const item of value) {
+    if (!isRecord(item)) continue;
+    const name = nonEmptyString(item[nameField]);
+    if (!name) continue;
+    rows.push({
+      name,
+      displayName: nonEmptyString(item[displayNameField])
+    });
+  }
+  return rows;
+}
+function buildGroup(type, source, existing) {
+  const existingByName = new Map(
+    existing.map((item) => [item.name, item.displayName])
+  );
+  const items = [];
+  const skippedExisting = [];
+  const missingInMetadata = [];
+  for (const definition of source.definitions) {
+    if (!existingByName.has(definition.name)) {
+      missingInMetadata.push(definition.name);
+      continue;
+    }
+    if (existingByName.get(definition.name)) {
+      skippedExisting.push(definition.name);
+      continue;
+    }
+    items.push(
+      type === "event" ? { event_name: definition.name, event_desc: definition.displayName } : { prop_name: definition.name, prop_desc: definition.displayName }
+    );
+  }
+  return {
+    type,
+    items,
+    skippedExisting,
+    missingInMetadata,
+    missingInDraft: source.missing
+  };
+}
+function nonEmptyString(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : void 0;
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// src/commands/te-analysis/tracking/plan/sync-display-names.ts
+var GATEWAY_DOMAIN = "analysis";
+var LIST_CAPABILITIES = {
+  events: "metadata.event.list",
+  eventProperties: "metadata.property.list",
+  userProperties: "metadata.property.list"
+};
+var EDIT_CAPABILITY = "metadata.super_metadata.batch_edit";
+var MAX_BATCH_SIZE = 200;
+var trackingPlanSyncDisplayNames = {
+  service: "tracking",
+  resource: "plan",
+  command: "sync-display-names",
+  description: "Fill blank event and property metadata display names from a local tracking-plan draft. Existing non-empty display names are never overwritten.",
+  flags: [
+    projectIdFlag,
+    {
+      name: "draft",
+      type: "string",
+      required: true,
+      desc: "Local tracking-plan draft.json containing event/property display_name values."
+    }
+  ],
+  risk: "write",
+  validate: (ctx) => {
+    if (!existsSync3(ctx.str("draft"))) {
+      throw new Error(
+        "--draft must reference a readable tracking-plan JSON file."
+      );
+    }
+  },
+  dryRun: async (ctx) => {
+    const draft = await readDraft(ctx.str("draft"));
+    return {
+      project_id: ctx.num("project-id"),
+      draft: ctx.str("draft"),
+      source_counts: sourceCounts(draft),
+      behavior: "Fill blank metadata display names only; preserve all existing non-empty display names.",
+      steps: [
+        ...Object.values(LIST_CAPABILITIES).map((capabilityId) => ({
+          method: "POST",
+          url: buildCapabilityGatewayUrl(
+            ctx.host(),
+            GATEWAY_DOMAIN,
+            `capabilities/${capabilityId}/execute`
+          )
+        })),
+        {
+          method: "POST",
+          url: buildCapabilityGatewayUrl(
+            ctx.host(),
+            GATEWAY_DOMAIN,
+            `capabilities/${EDIT_CAPABILITY}/execute`
+          ),
+          note: "Called only for non-empty update groups, in batches of at most 200 items."
+        }
+      ]
+    };
+  },
+  execute: async (ctx) => {
+    const projectId = ctx.num("project-id");
+    const draftPath = ctx.str("draft");
+    const draft = await readDraft(draftPath);
+    const [eventResult, eventPropertyResult, userPropertyResult] = await Promise.all([
+      executeCapability(
+        ctx.host(),
+        GATEWAY_DOMAIN,
+        LIST_CAPABILITIES.events,
+        {
+          project_id: projectId,
+          fields: ["event_name", "event_desc"]
+        }
+      ),
+      executeCapability(
+        ctx.host(),
+        GATEWAY_DOMAIN,
+        LIST_CAPABILITIES.eventProperties,
+        {
+          project_id: projectId,
+          table_type: "event",
+          fields: ["prop_name", "prop_desc"]
+        }
+      ),
+      executeCapability(
+        ctx.host(),
+        GATEWAY_DOMAIN,
+        LIST_CAPABILITIES.userProperties,
+        {
+          project_id: projectId,
+          table_type: "user",
+          fields: ["prop_name", "prop_desc"]
+        }
+      )
+    ]);
+    const plan = buildDisplayNameSyncPlan(draft, {
+      events: eventResult?.events,
+      eventProperties: eventPropertyResult?.properties,
+      userProperties: userPropertyResult?.properties
+    });
+    const updateResults = {};
+    for (const group of Object.values(plan)) {
+      updateResults[group.type] = await executeUpdates(ctx, projectId, group);
+    }
+    return {
+      project_id: projectId,
+      draft: draftPath,
+      policy: "blank_only",
+      updated: counts(plan, (group) => group.items.length),
+      skipped_existing: counts(plan, (group) => group.skippedExisting.length),
+      missing_in_metadata: counts(
+        plan,
+        (group) => group.missingInMetadata.length
+      ),
+      missing_display_name_in_draft: counts(
+        plan,
+        (group) => group.missingInDraft.length
+      ),
+      details: {
+        missing_in_metadata: Object.fromEntries(
+          Object.values(plan).map((group) => [
+            group.type,
+            group.missingInMetadata
+          ])
+        ),
+        missing_display_name_in_draft: Object.fromEntries(
+          Object.values(plan).map((group) => [
+            group.type,
+            group.missingInDraft
+          ])
+        )
+      },
+      batches: updateResults
+    };
+  }
+};
+async function readDraft(filePath) {
+  let value;
+  try {
+    value = JSON.parse(await readFile(filePath, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `Unable to read tracking draft "${filePath}": ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  assertTrackingDraft(value);
+  return value;
+}
+async function executeUpdates(ctx, projectId, group) {
+  const results = [];
+  for (let offset = 0; offset < group.items.length; offset += MAX_BATCH_SIZE) {
+    const items = group.items.slice(offset, offset + MAX_BATCH_SIZE);
+    results.push(
+      await executeCapability(ctx.host(), GATEWAY_DOMAIN, EDIT_CAPABILITY, {
+        project_id: projectId,
+        type: group.type,
+        items
+      })
+    );
+  }
+  return results;
+}
+function sourceCounts(draft) {
+  return {
+    event: draft.events.length,
+    event_property: new Set(
+      [...draft.common_event_properties, ...draft.event_properties].map(
+        (property) => property.name
+      )
+    ).size,
+    user_property: draft.user_properties.length
+  };
+}
+function counts(plan, value) {
+  return Object.fromEntries(
+    Object.values(plan).map((group) => [group.type, value(group)])
+  );
+}
+
 // src/commands/te-analysis/tracking/plan/index.ts
 var commands63 = [
   trackingPlanGet,
@@ -6094,7 +6430,8 @@ var commands63 = [
   trackingPlanGenerate,
   trackingPlanExport,
   trackingPlanImportExcel,
-  trackingPlanSyncFromMeta
+  trackingPlanSyncFromMeta,
+  trackingPlanSyncDisplayNames
 ];
 var plan_default = commands63;
 
@@ -6329,8 +6666,116 @@ var commands70 = [
 ];
 var event_blacklist_default = commands70;
 
-// src/commands/te-analysis/tracking/index.ts
+// src/commands/te-analysis/tracking/debug-device/add.ts
+var trackingDebugDeviceAdd = createTrackingCapabilityCommand({
+  resource: "debug-device",
+  command: "add",
+  capabilityId: "tracking.debug_device.add",
+  description: "Create or update a Debug device for an AE project.",
+  flags: [projectIdFlag, debugDeviceIdFlag, debugDeviceNameFlag],
+  risk: "write",
+  buildInput: (ctx) => ({
+    ...projectInput2(ctx),
+    device_id: ctx.str("device-id"),
+    device_name: ctx.str("device-name")
+  })
+});
+
+// src/commands/te-analysis/tracking/debug-device/list.ts
+var trackingDebugDeviceList = createTrackingCapabilityCommand({
+  resource: "debug-device",
+  command: "list",
+  capabilityId: "tracking.debug_device.list",
+  description: "List Debug devices and the device selected by the current CLI user.",
+  flags: [projectIdFlag],
+  risk: "read",
+  buildInput: projectInput2
+});
+
+// src/commands/te-analysis/tracking/debug-device/select.ts
+var trackingDebugDeviceSelect = createTrackingCapabilityCommand({
+  resource: "debug-device",
+  command: "select",
+  capabilityId: "tracking.debug_device.select",
+  description: "Select the active Debug device for the current CLI user.",
+  flags: [projectIdFlag, debugDeviceIdFlag],
+  risk: "write",
+  buildInput: (ctx) => ({
+    ...projectInput2(ctx),
+    device_id: ctx.str("device-id")
+  })
+});
+
+// src/commands/te-analysis/tracking/debug-device/index.ts
 var commands71 = [
+  trackingDebugDeviceList,
+  trackingDebugDeviceAdd,
+  trackingDebugDeviceSelect
+];
+var debug_device_default = commands71;
+
+// src/commands/te-analysis/tracking/debug-data/list.ts
+var debugStartTimeFlag = {
+  name: "start-time",
+  type: "string",
+  required: false,
+  desc: "Query start time in YYYY-MM-DD HH:mm:ss local time. Defaults to one hour ago."
+};
+var trackingDebugDataList = createTrackingCapabilityCommand({
+  resource: "debug-data",
+  command: "list",
+  capabilityId: "tracking.debug_data.list",
+  description: "List Debug data received from one device.",
+  flags: [projectIdFlag, debugDeviceIdFlag, debugStartTimeFlag, eventNameFlag],
+  risk: "read",
+  buildInput: (ctx) => compactInput({
+    ...projectInput2(ctx),
+    device_id: ctx.str("device-id"),
+    start_time: optionalString(ctx, "start-time") ?? formatLocalTime(new Date(Date.now() - 60 * 60 * 1e3)),
+    event_name: optionalString(ctx, "event-name")
+  }),
+  postProcess: (result, input) => {
+    const data = isRecord2(result) ? result : {};
+    const eventList = Array.isArray(data.event_list) ? data.event_list : [];
+    const deviceDataList = Array.isArray(data.device_data_list) ? data.device_data_list : [];
+    return {
+      device_id: input.device_id,
+      start_time: input.start_time,
+      ...input.event_name ? { event_name: input.event_name } : {},
+      has_data: deviceDataList.length > 0,
+      event_count: eventList.length,
+      data_count: deviceDataList.length,
+      event_list: eventList,
+      device_data_list: deviceDataList
+    };
+  }
+});
+function formatLocalTime(value) {
+  const pad = (part) => String(part).padStart(2, "0");
+  return [
+    value.getFullYear(),
+    "-",
+    pad(value.getMonth() + 1),
+    "-",
+    pad(value.getDate()),
+    " ",
+    pad(value.getHours()),
+    ":",
+    pad(value.getMinutes()),
+    ":",
+    pad(value.getSeconds())
+  ].join("");
+}
+function isRecord2(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+// src/commands/te-analysis/tracking/debug-data/index.ts
+var commands72 = [trackingDebugDataList];
+var debug_data_default = commands72;
+
+// src/commands/te-analysis/tracking/index.ts
+var commands73 = [
   ...plan_default,
   ...sdk_sample_default,
   ...plan_change_log_default,
@@ -6338,9 +6783,11 @@ var commands71 = [
   ...ingest_default,
   ...ingest_error_default,
   ...live_data_default,
-  ...event_blacklist_default
+  ...event_blacklist_default,
+  ...debug_device_default,
+  ...debug_data_default
 ];
-var tracking_default = commands71;
+var tracking_default = commands73;
 
 // src/commands/te-analysis/alert/shared.ts
 var alertIdFlag = {
@@ -6460,7 +6907,7 @@ var analysisAlertStop = createAnalysisCapabilityCommand({
 });
 
 // src/commands/te-analysis/alert/index.ts
-var commands72 = [
+var commands74 = [
   analysisAlertList,
   analysisAlertGet,
   analysisAlertCreate,
@@ -6469,7 +6916,7 @@ var commands72 = [
   analysisAlertStart,
   analysisAlertStop
 ];
-var alert_default = commands72;
+var alert_default = commands74;
 
 // src/commands/te-analysis/alert-detail/list.ts
 var analysisAlertDetailList = createAnalysisCapabilityCommand({
@@ -6483,10 +6930,10 @@ var analysisAlertDetailList = createAnalysisCapabilityCommand({
 });
 
 // src/commands/te-analysis/alert-detail/index.ts
-var commands73 = [
+var commands75 = [
   analysisAlertDetailList
 ];
-var alert_detail_default = commands73;
+var alert_detail_default = commands75;
 
 // src/commands/te-analysis/alert-job/list.ts
 var analysisAlertJobList = createAnalysisCapabilityCommand({
@@ -6500,10 +6947,10 @@ var analysisAlertJobList = createAnalysisCapabilityCommand({
 });
 
 // src/commands/te-analysis/alert-job/index.ts
-var commands74 = [
+var commands76 = [
   analysisAlertJobList
 ];
-var alert_job_default = commands74;
+var alert_job_default = commands76;
 
 // src/commands/te-analysis/alert-notice-config/list.ts
 var analysisAlertNoticeConfigList = createAnalysisCapabilityCommand({
@@ -6517,10 +6964,10 @@ var analysisAlertNoticeConfigList = createAnalysisCapabilityCommand({
 });
 
 // src/commands/te-analysis/alert-notice-config/index.ts
-var commands75 = [
+var commands77 = [
   analysisAlertNoticeConfigList
 ];
-var alert_notice_config_default = commands75;
+var alert_notice_config_default = commands77;
 
 // src/commands/te-analysis/index.ts
 registerCapabilityGatewayRoute("analysis", { gatewayDomain: "analysis" });
@@ -6566,8 +7013,8 @@ var baseCommands = [
   ...alert_job_default,
   ...alert_notice_config_default
 ];
-var commands76 = [...baseCommands];
-var te_analysis_default = commands76;
+var commands78 = [...baseCommands];
+var te_analysis_default = commands78;
 export {
   baseCommands,
   te_analysis_default as default

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingai/ae-cli",
-  "version": "6.0.37",
+  "version": "6.0.38",
   "description": "CLI tool for ThinkingAI (AE) analytics platform",
   "type": "module",
   "bin": {
@@ -41,7 +41,7 @@
     "verify:agent-tools": "node scripts/verify-agent-tools.mjs && npm run verify:sandbox-tools",
     "verify:system-tools": "node scripts/verify-system-tools.mjs && npx tsx tests/system-domain.test.ts && npx tsx tests/sandbox-tool-package.test.ts",
     "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:tracking-tools": "tsx test/tracking-client.test.mjs && tsx test/tracking-skill-flow.test.mjs && node test/tracking-commands.test.mjs && tsx tests/tracking-display-name-sync.test.ts",
     "verify:self-check-overlay": "node test/self-check-overlay.test.mjs",
     "verify:update-check": "npx tsx test/update-check.test.mjs",
     "verify:version-sync": "npx tsx tests/version-sync.test.ts",

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

@@ -239,6 +239,10 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli tracking check list` | tracking.check.list | read | `--project-id` (number; required) — Numeric project ID. | [check_list.md](check_list.md) |
 | `ae-cli tracking check retry` | tracking.check.retry | write | `--project-id` (number; required) — Numeric project ID.<br>`--uuid` (string; required) — Tracking check task UUID.<br>`--request-id` (string; optional) — Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted.<br>`--timeout-seconds` (number; optional) — Optional capability execution timeout in seconds. | [check_retry.md](check_retry.md) |
 | `ae-cli tracking check run` | tracking.check.run | write | `--project-id` (number; required) — Numeric project ID.<br>`--check-scope` (json; required) — Tracking check scope JSON object.<br>`--result-scope` (json; optional) — Optional tracking check result scope JSON object. | [check_run.md](check_run.md) |
+| `ae-cli tracking debug-data list` | tracking.debug_data.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--device-id` (string; required) — Debug device ID reported by the SDK as #device_id.<br>`--start-time` (string; optional) — Query start time in YYYY-MM-DD HH:mm:ss local time. Defaults to one hour ago.<br>`--event-name` (string; optional) — Optional event name filter. | [debug_data_list.md](debug_data_list.md) |
+| `ae-cli tracking debug-device add` | tracking.debug_device.add | write | `--project-id` (number; required) — Numeric project ID.<br>`--device-id` (string; required) — Debug device ID reported by the SDK as #device_id.<br>`--device-name` (string; required) — Human-readable name for the Debug device. | [debug_device_add.md](debug_device_add.md) |
+| `ae-cli tracking debug-device list` | tracking.debug_device.list | read | `--project-id` (number; required) — Numeric project ID. | [debug_device_list.md](debug_device_list.md) |
+| `ae-cli tracking debug-device select` | tracking.debug_device.select | write | `--project-id` (number; required) — Numeric project ID.<br>`--device-id` (string; required) — Debug device ID reported by the SDK as #device_id. | [debug_device_select.md](debug_device_select.md) |
 | `ae-cli tracking event-blacklist add` | tracking.event_blacklist.add | write | `--project-id` (number; required) — Numeric project ID.<br>`--event-names` (json; required) — JSON array of event names. | [event_blacklist_add.md](event_blacklist_add.md) |
 | `ae-cli tracking event-blacklist list` | tracking.event_blacklist.list | read | `--project-id` (number; required) — Numeric project ID. | [event_blacklist_list.md](event_blacklist_list.md) |
 | `ae-cli tracking event-blacklist update` | tracking.event_blacklist.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--event-names` (json; required) — JSON array of event names.<br>`--type` (number; required) — Blacklist event config type: 0 or 1. | [event_blacklist_update.md](event_blacklist_update.md) |
@@ -252,6 +256,7 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli tracking plan get` | tracking.plan.get | read | `--project-id` (number; required) — Numeric project ID. | [plan_get.md](plan_get.md) |
 | `ae-cli tracking plan import-excel` | tracking.plan.import_excel | write | `--project-id` (number; required) — Numeric project ID.<br>`--input-file` (string; optional) — Local tracking-plan XLSX path. The CLI uploads it with purpose track.program.xlsx before import.<br>`--input-file-id` (string; optional) — Existing input_file_id returned by `analysis input-file upload --purpose track.program.xlsx`.<br>`--lang` (string; optional) — Excel language: zh, en, ja, ko, zh_CN, en_US, ja_JP, or ko_KR. | [plan_import_excel.md](plan_import_excel.md) |
 | `ae-cli tracking plan save-items` | tracking.plan.save_items | write | `--project-id` (number; required) — Numeric project ID.<br>`--events` (json; optional) — Optional JSON array of tracking events.<br>`--event-props` (json; optional) — Optional JSON array of tracking event properties.<br>`--user-props` (json; optional) — Optional JSON array of tracking user properties.<br>`--common-event-props` (json; optional) — Optional JSON array of common tracking event properties. | [plan_save_items.md](plan_save_items.md) |
+| `ae-cli tracking plan sync-display-names` | gateway lifecycle | write | `--project-id` (number; required) — Numeric project ID.<br>`--draft` (string; required) — Local tracking-plan draft.json containing event/property display_name values. | [plan_sync_display_names.md](plan_sync_display_names.md) |
 | `ae-cli tracking plan sync-from-meta` | tracking.plan.sync_from_meta | write | `--project-id` (number; required) — Numeric project ID. | [plan_sync_from_meta.md](plan_sync_from_meta.md) |
 | `ae-cli tracking plan-change-log export` | tracking.plan_change_log.export | read | `--project-id` (number; required) — Numeric project ID.<br>`--log-id` (number; required) — Tracking plan change log ID.<br>`--request-id` (string; optional) — Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted.<br>`--timeout-seconds` (number; optional, min=1, max=21600) — Async runtime in seconds. Default and max: 21600 (6 hours); cancel earlier with analysis query cancel --run-id <run_id>. | [plan_change_log_export.md](plan_change_log_export.md) |
 | `ae-cli tracking plan-change-log list` | tracking.plan_change_log.list | read | `--project-id` (number; required) — Numeric project ID. | [plan_change_log_list.md](plan_change_log_list.md) |

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

@@ -0,0 +1,28 @@
+# tracking debug-data list
+
+Use this command to query Debug data received from one device and verify an SDK reporting flow.
+
+Command:
+
+```bash
+ae-cli tracking debug-data list \
+  --project-id <project_id> \
+  --device-id <device_id> \
+  --start-time "YYYY-MM-DD HH:mm:ss" \
+  [--event-name <event_name>]
+```
+
+Capability id: `tracking.debug_data.list`.
+
+Input sends `project_id`, `device_id`, `start_time`, and optional `event_name`. When omitted, `start_time` defaults to one hour ago in local time.
+
+The normalized result includes `has_data`, `event_count`, `data_count`, `event_list`, and `device_data_list`. Treat validation as successful only when `has_data` is true and the returned event names, property structures, and error fields are correct.
+
+## Parameters
+
+| Parameter      | Required | Description                                                                |
+| -------------- | -------- | -------------------------------------------------------------------------- |
+| `--project-id` | Yes      | Numeric AE project ID.                                                     |
+| `--device-id`  | Yes      | Debug device ID used by the reporting client.                              |
+| `--start-time` | No       | Query start time in local `YYYY-MM-DD HH:mm:ss`; defaults to one hour ago. |
+| `--event-name` | No       | Exact event name filter.                                                   |

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

@@ -0,0 +1,23 @@
+# tracking debug-device add
+
+Use this command to create or update a Debug device for one AE project.
+Do not use it to select the active device or query Debug data; use `debug-device select` and `debug-data list` for those actions.
+
+Command:
+
+```bash
+ae-cli tracking debug-device add --project-id <project_id> --device-id <device_id> --device-name <device_name>
+```
+
+Capability id: `tracking.debug_device.add`.
+
+Input sends `project_id`, `device_id`, and `device_name`. Prefer a stable device ID that the validation script can reuse. After creation, select the same device with `tracking debug-device select`.
+The result confirms that the device was created or updated; use `debug-device list` to verify the saved device before selecting it.
+
+## Parameters
+
+| Parameter       | Required | Description                                          |
+| --------------- | -------- | ---------------------------------------------------- |
+| `--project-id`  | Yes      | Numeric AE project ID.                               |
+| `--device-id`   | Yes      | Stable Debug device ID used by the reporting client. |
+| `--device-name` | Yes      | Human-readable Debug device name.                    |

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

@@ -0,0 +1,19 @@
+# tracking debug-device list
+
+Use this command to list Debug devices for one AE project and identify the device selected by the current CLI user.
+
+Command:
+
+```bash
+ae-cli tracking debug-device list --project-id <project_id>
+```
+
+Capability id: `tracking.debug_device.list`.
+
+Input sends `project_id`. The result contains the available Debug devices and current selection. Use the returned device IDs for `debug-device select` and `debug-data list`; do not invent an ID.
+
+## Parameters
+
+| Parameter      | Required | Description            |
+| -------------- | -------- | ---------------------- |
+| `--project-id` | Yes      | Numeric AE project ID. |