@thinkingai/ae-cli 6.0.41 → 6.0.44

package/dist/{te-team-GZPU6UWA.js → te-team-EFKWYKMK.js}

@@ -1,16 +1,16 @@
 import {
   getAuthHeaders,
   kbApi
-} from "./chunk-AFXA7BRK.js";
+} from "./chunk-4KVPKXFX.js";
 import {
   printError,
   printOutput
-} from "./chunk-WZRX4KOH.js";
-import "./chunk-S5NTSDBS.js";
-import "./chunk-ZQKDZXDO.js";
-import "./chunk-3FY3RJ26.js";
-import "./chunk-AXDXJTPC.js";
-import "./chunk-JHENBQ5B.js";
+} from "./chunk-GT46FPXN.js";
+import "./chunk-4SGZG4XY.js";
+import "./chunk-ZZUOD757.js";
+import "./chunk-UW5UN47B.js";
+import "./chunk-LYVNONC4.js";
+import "./chunk-QGM4M3NI.js";
 
 // src/commands/te-team/shared.ts
 var API_PREFIX = process.env.AE_API_PREFIX ?? "/agent";

package/dist/{update-TOBFXF2V.js → update-OGPSZM5A.js}

@@ -7,18 +7,18 @@ import {
   printError,
   printOutput,
   recordVersionSyncResult
-} from "./chunk-WZRX4KOH.js";
+} from "./chunk-GT46FPXN.js";
 import {
   peekCliToken
-} from "./chunk-S5NTSDBS.js";
-import {
-  missingAeHostHint
-} from "./chunk-ZQKDZXDO.js";
+} from "./chunk-4SGZG4XY.js";
 import {
   getActiveHost,
+  missingAeHostHint,
   normalizeUrl
-} from "./chunk-3FY3RJ26.js";
-import "./chunk-JHENBQ5B.js";
+} from "./chunk-ZZUOD757.js";
+import "./chunk-UW5UN47B.js";
+import "./chunk-LYVNONC4.js";
+import "./chunk-QGM4M3NI.js";
 
 // src/commands/update.ts
 var HOST_OPTION_DESC = "Override active AE host URL (e.g., https://ta.thinkingdata.cn)";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingai/ae-cli",
-  "version": "6.0.41",
+  "version": "6.0.44",
   "description": "CLI tool for ThinkingAI (AE) analytics platform",
   "type": "module",
   "bin": {
@@ -38,13 +38,14 @@
     "verify:retired-api-command": "node --test test/retired-api-command.test.mjs",
     "verify:analysis-common-tools": "node scripts/verify-te-common-tools.mjs",
     "verify:team-tools": "node scripts/verify-te-team-tools.mjs",
-    "verify:agent-tools": "node scripts/verify-agent-tools.mjs && npm run verify:sandbox-tools",
+    "verify:agent-tools": "node --test test/agent-command-registry.test.mjs && tsx tests/te-agent-credentials.test.ts && tsx tests/te-agent-unified-auth.test.ts && tsx tests/te-agent-conversations.test.ts && tsx scripts/verify-agent-tools.mjs && npm run verify:approval && npm run verify:sandbox-tools",
+    "verify:approval": "tsx tests/approval-command.test.ts && tsx tests/approval-cli-client.test.ts && tsx tests/approval-skill.test.ts",
     "verify:memory": "tsx tests/memory-command.test.ts && tsx tests/memory-cli-client.test.ts && tsx tests/memory-skill.test.ts",
     "verify:system-tools": "node scripts/verify-system-tools.mjs && npx tsx tests/system-domain.test.ts && npx tsx tests/te-agent-download.test.ts && npx tsx tests/sandbox-tool-package.test.ts",
     "verify:sandbox-tools": "tsx test/sandbox-tools.test.ts",
     "verify:skill-version-management": "tsx tests/skill-version-management.test.ts",
     "verify:skill-reference-files": "tsx tests/skill-reference-files.test.ts",
-    "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: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 && tsx tests/local-data-inspect-convert.test.ts && tsx tests/local-data-upload-client.test.ts && tsx tests/local-data-upload-command.test.ts && tsx tests/local-data-encoding-sniff.test.ts && tsx tests/local-data-time-formats.test.ts && tsx tests/local-data-eight-types.test.ts && tsx tests/local-data-mapping-extras.test.ts && tsx tests/local-data-plan.test.ts && tsx tests/local-data-handoff.test.ts && tsx tests/local-data-reuse.test.ts && tsx tests/local-data-conflicts-resolutions.test.ts && tsx tests/runner-variadic-flags.test.ts && node test/local-data-skill.test.mjs",
     "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",
@@ -77,18 +78,27 @@
     "archiver": "^5.3.2",
     "cli-table3": "^0.6.5",
     "commander": "^12.1.0",
+    "csv-parse": "^7.0.2",
     "exceljs": "^4.4.0",
+    "iconv-lite": "^0.7.3",
     "jq-wasm": "^3.0.0-jq-1.8.2",
+    "jschardet": "^3.1.4",
     "json-bigint": "^1.0.0",
+    "saxes": "^6.0.0",
+    "stream-json": "^1.9.1",
     "turndown": "^7.2.4",
     "undici": "^6.19.0",
+    "unzipper": "^0.12.5",
     "ws": "^8.18.0",
     "xlsx": "^0.18.5"
   },
   "devDependencies": {
     "@types/archiver": "^5.3.4",
+    "@types/iconv-lite": "^0.0.1",
     "@types/node": "^22.0.0",
+    "@types/stream-json": "^1.7.8",
     "@types/turndown": "^5.0.6",
+    "@types/unzipper": "^0.10.11",
     "@types/ws": "^8.5.0",
     "jszip": "^3.10.1",
     "tsup": "^8.0.0",

package/skills/ae-agent/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: ae-agent
-version: 1.5.1
-description: "AE Agent platform CLI for Agent, archived conversation, automation, model, MCP, Skill, attachment, and user-memory work. Use when managing these resources, browsing Agent markets, restoring archived conversations, creating scheduled automations, persisting user memory, or answering from user preferences, background, stable workflows, or historical conventions."
+version: 1.5.3
+description: "AE Agent platform CLI for Agent, approval, archived conversation, automation, model, MCP, Skill, attachment, and user-memory work. Use when managing these resources, browsing Agent markets, handling approval requests and tasks, restoring archived conversations, creating scheduled automations, persisting user memory, or answering from user preferences, background, stable workflows, or historical conventions."
 ---
 
 # ae-agent
 
 > **CRITICAL — Before running any `ae-cli agent +<command>` command, you MUST first read the corresponding `references/<command>.md`.** The reference filename equals the command name without the leading `+`, for example `+add-mcp` -> `references/add-mcp.md`.
+> **CRITICAL — Before running hierarchical approval commands, read the matching resource reference: `approval-type.md`, `approval-request.md`, `approval-task.md`, or `approval-effect.md`.**
 > **CRITICAL — Never guess record IDs (Agent / automation / model / MCP / Skill / submission / share / attachment).** Always use the appropriate `+list-*` command to discover real IDs first.
 > **CRITICAL — Agent platform resources are served under `/api/sandbox/agent/*`, but `ae-cli memory` is now served under `/api/cli/memory/v1/*` and uses the CLI token main chain.** Do not reference legacy memory paths.
 
@@ -22,6 +23,7 @@ Agent resource commands live under the `agent` service. Quick help:
 ae-cli agent --help
 ae-cli agent +list-agents --help
 ae-cli agent +create-automation --help
+ae-cli agent approval-request --help
 ```
 
 User memory commands live under the `memory` service:
@@ -32,11 +34,11 @@ ae-cli memory +<command> [options]
 
 ## Global AE CLI Rules
 
-- Use this skill for Agent platform resource management: Agents, archived conversations, automations, models, MCP servers, Skills, attachments, the MCP/Skill market, Skill copy/approval/share flows, and user memories.
-- **Read operations** (`+list-*`) can run directly once required IDs are known.
+- Use this skill for Agent platform resource management: Agents, generic approvals, archived conversations, automations, models, MCP servers, Skills, attachments, the MCP/Skill market, Skill copy/approval/share flows, and user memories.
+- **Read operations** (`risk: read`) can run directly once required IDs are known.
 - **Write operations** (`risk: write`) can run directly once required IDs and references are verified.
-- **Delete operations** (`risk: high-risk-write`) require explicit user authorization. Pass `--yes` only after the user confirms.
-- Prefer `--dry-run` before delete operations to inspect the request shape without executing.
+- **High-risk write operations** (`risk: high-risk-write`) require explicit user authorization. Pass `--yes` only after the user confirms.
+- Prefer `--dry-run` before high-risk write operations to inspect the request shape without executing.
 - Local-Agent runtime `memory +mark-used` is silent internal usage accounting after an answer actually uses memory.
 - Personal and company scope resources can be created/updated/deleted; company scope requires root/agent_admin role; system resources are read-only (exception: root users can approve/reject submissions and set company-scope meta).
 - Toggle operations on company/system resources only affect the current user's preference, not the global state.
@@ -49,7 +51,7 @@ ae-cli memory +<command> [options]
 | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--format <json\|table>` | Output format. Default is JSON.                                                                                                              |
 | `--host <url>`           | Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli agent +<command> --host <url>`. |
-| `--yes`                  | Skip confirmation for `high-risk-write` (delete) operations.                                                                                 |
+| `--yes`                  | Skip confirmation for `high-risk-write` operations after explicit user authorization.                                                       |
 | `--dry-run`              | Show request details (method + URL + body) without executing.                                                                                |
 
 ### Output and Errors
@@ -65,13 +67,14 @@ Use `ae-agent` for all Agent platform resource work:
 - **Agents, conversations & automations**: list Agents, find/restore archived conversations, and create/list/update scheduled Agent automations.
 - **Models**: list, add, delete, toggle custom models.
 - **MCP servers**: list, add, delete, toggle MCP servers; browse the MCP market; set market meta.
-- **Skills**: list, add, delete, toggle Skills; browse the Skill market; set market meta; copy system/company Skills to personal; submit/approve/reject company-scope Skills; share/accept/reject peer-to-peer Skills.
+- **Approvals**: discover versioned approval types, submit/query/cancel approval requests, and query/approve/reject approval tasks.
+- **Skills**: list, add, delete, toggle Skills; browse the Skill market; set market meta; copy system/company Skills to personal; use legacy company-publish approval commands during the compatibility period; share/accept/reject peer-to-peer Skills.
 - **Attachments**: list, upload, soft-delete sandbox files in the attachment library.
 - **User Memory**: recall, account for, create, update, extract, organize, preview, and initialize long-term user memories through the `memory` domain.
 
 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 (69 commands)
+## Tool Groups (82 commands)
 
 ### Agents (5)
 
@@ -166,6 +169,13 @@ If the user's intent is data analysis, audience management, metadata governance,
 - `+approve-skill` ([doc](references/approve-skill.md)) — approve a submission (root only). Creates a company-scope copy
 - `+reject-skill` ([doc](references/reject-skill.md)) — reject a submission with a reason (root only)
 
+### Generic Approval Workflow (13)
+
+- `approval-type list|get` ([doc](references/approval-type.md)) — discover versioned approval definitions and input contracts
+- `approval-request list|get|submit|cancel` ([doc](references/approval-request.md)) — query, submit, and cancel approval requests with stable request IDs
+- `approval-task list|get|approve|reject` ([doc](references/approval-task.md)) — query and decide approval tasks with stable task IDs
+- `approval-effect list|get|retry` ([doc](references/approval-effect.md)) — inspect safe execution state and explicitly retry failed/manual-required Effects
+
 ### Skill Share (peer-to-peer) (4)
 
 - `+share-skill` ([doc](references/share-skill.md)) — share a personal Skill to a same-company user
@@ -188,7 +198,7 @@ If the user's intent is data analysis, audience management, metadata governance,
 
 Use the `memory` domain, not the `agent` domain. The memory domain uses te-claude CLI token APIs under `/api/cli/memory/v1/memories*`, like analysis-side CLI token transport. It must not call Web-only `/api/memories*`, `/api/agent-session-defaults*`, or legacy `/api/sandbox/agent/memories*`.
 
-> **CRITICAL — Memory commands marked `write` in the table below run without `--yes`; only `high-risk-write` delete operations use `--yes` after explicit user confirmation. For local Agents, `+mark-used` is silent internal accounting and also runs without `--yes`. Web Agents never call it.**
+> **CRITICAL — Memory commands marked `write` in the table below run without `--yes`. Within the memory domain, `high-risk-write` delete operations use `--yes` after explicit user confirmation. For local Agents, `+mark-used` is silent internal accounting and also runs without `--yes`. Web Agents never call it.**
 
 | Command              |  Risk | Purpose                                                                                        |
 | -------------------- | ----: | ---------------------------------------------------------------------------------------------- |
@@ -256,7 +266,7 @@ For a local Agent, a successful `+mark-used` response means only that the dedupl
 - **Market category keys**: `ae_preset | dev_tool | search_tool | data_query | content_gen | enterprise | life | automation | other`. Sort options: `newest | calls | likes` (`calls` sorts MCP by call count, Skill by download count). Market scope: `all | system | company | custom` (`custom` = personal).
 - **Meta on create/copy**: `+add-mcp` / `+add-skill` / `+copy-skill` accept optional `--category / --icon-emoji / --icon-color`; these are applied via a follow-up meta PATCH after creation. MCP creation still does NOT validate server connectivity.
 - **Copy vs toggle**: `+copy-skill` copies a system/company Skill to an independent personal copy. MCP has no copy (use `+toggle-mcp` to enable a system/company MCP per-user).
-- **Approval & share are Skill-only**: MCP has no approval or share flow. `+approve-skill` / `+reject-skill` require root.
+- **Approval & share boundaries**: MCP has no approval or share flow. Generic approval commands currently expose `skill.publish@1` and future registered approval types; legacy `+approve-skill` / `+reject-skill` remain during the compatibility period and require root.
 - **`--id` semantics differ by command**: `+submit-skill` / `+share-skill` / `+copy-skill` take a Skill ID; `+cancel-skill-submission` / `+approve-skill` / `+reject-skill` take a submission ID; `+accept-skill-share` / `+reject-skill-share` take a share ID.
 
 ## Typical Workflows

package/skills/ae-agent/references/approval-effect.md

@@ -0,0 +1,44 @@
+# agent approval-effect (Inspect and Retry Approval Effects)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Generic Approval Effect / read + high-risk-write**
+
+## Commands
+
+```bash
+ae-cli agent approval-effect list --status failed --limit 20
+ae-cli agent approval-effect list --status manual_required --approval-request-id <request-id>
+ae-cli agent approval-effect get --effect-id <effect-id>
+ae-cli --dry-run agent approval-effect retry --effect-id <effect-id> --expected-version 3 --expected-attempt 1 --reason "Artifact storage was restored" --client-request-id <unique-id>
+ae-cli --yes agent approval-effect retry --effect-id <effect-id> --expected-version 3 --expected-attempt 1 --reason "Artifact storage was restored" --client-request-id <unique-id>
+```
+
+## Mandatory Rules
+
+- Effect identity is independent from request and task identity. Use `--effect-id`; use `--approval-request-id` only as a list filter.
+- List/get return a safe view with request/type/resource summary, status, attempt, stable failure category, and safe result reference. They do not return artifact contents, credentials, runner leases, idempotency keys, or sensitive decision payloads.
+- Retry only an Effect whose latest server state is `failed` or `manual_required`. Never infer Adapter idempotency or retry a `pending`, `running`, or `succeeded` Effect.
+- Immediately before retry, run `get` and pass both `optimistic_version` as `--expected-version` and `attempt` as `--expected-attempt`.
+- `--reason` is required and becomes auditable retry evidence. Generate a unique `--client-request-id` for the logical retry.
+- Retry is `high-risk-write`. Obtain explicit user authorization, then pass `--yes`. Do not bypass permission, tenant-hidden, state, version, attempt, or artifact errors.
+- The CLI transport does not perform business retries. Refresh state and ask for a new decision after a stable conflict.
+
+## Dry-run Boundary
+
+`--dry-run` is only a local method, URL, and body preview. The body uses snake_case and sets the server-required `confirm_risk` field, but the preview does not verify current administrator status, live Effect state, or artifact availability, and it does not authorize actual execution or bypass the CLI confirmation gate.
+
+## Error Handling
+
+- `approval_effect_retry_conflict`: re-run `get`; the status, optimistic version, attempt, or runner ownership changed. Do not blindly replay stale values, and stop unless the refreshed Effect is `failed` or `manual_required`.
+- Artifact unavailable/manual recovery errors: repair the underlying storage or Adapter condition before considering another retry.
+- Permission and tenant-hidden not-found errors must not be bypassed or retried with guessed IDs.
+
+## Transition Metadata
+
+- Transition status: transitional
+- Owning module: te-agent approval domain
+- Current transport: CLI-token-only versioned REST at `/agent/api/cli/approval/v1`
+- Gateway target: `approval.effect.list`, `approval.effect.get`, and `approval.effect.retry`
+- Review after: 2026-11-17
+- Exit condition: Migrate these commands when equivalent Gateway schemas preserve safe output, administrator authorization, high-risk confirmation, expected version/attempt fencing, idempotency, cursor pagination, dry-run, and structured error contracts.

package/skills/ae-agent/references/approval-request.md

@@ -0,0 +1,46 @@
+# agent approval-request (Manage Approval Requests)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md) and read [`approval-type.md`](approval-type.md) before submitting.
+
+Domain: **Generic Approval Request / read + write**
+
+## Commands
+
+```bash
+ae-cli agent approval-request list --status pending --limit 20
+ae-cli agent approval-request list --cursor <next_cursor> --approval-type-id skill.publish@1
+ae-cli agent approval-request get --approval-request-id <request-id>
+ae-cli agent approval-request submit --approval-type-id skill.publish@1 --resource-id <skill-id> --reason "Publish this Skill" --payload '{"description":"Publish this Skill"}' --client-request-id <unique-id>
+ae-cli --dry-run agent approval-request cancel --approval-request-id <request-id> --expected-version 0 --client-request-id <unique-id>
+ae-cli agent approval-request cancel --approval-request-id <request-id> --expected-version 0 --reason "No longer needed" --client-request-id <unique-id>
+```
+
+## Mandatory Rules
+
+- Keep resource and request identities separate: `--resource-id` identifies the business resource; `--approval-request-id` identifies the approval aggregate.
+- Generate a stable unique `--client-request-id` for each logical write. Reuse it only to replay the identical command.
+- Read the latest request before cancellation and pass its `optimistic_version` as `--expected-version`.
+- `--payload` must be a JSON object whose keys recursively use snake_case and match the selected type's `input_schema`.
+- Request filters use opaque cursor pagination. Pass `next_cursor` unchanged to the next `--cursor` call.
+- A requester may cancel their own pending request without a reason. A company manager cancelling another user's request must provide `--reason`.
+- Write commands are ordinary `write` operations. They do not require `--yes`.
+
+## Dry-run Boundary
+
+`--dry-run` is a local method, URL, and body preview. It does not call te-agent and therefore does not verify server permissions, current request state, artifact availability, registered type state, or future conditional routing.
+
+## Error Handling
+
+- `approval_active_request_conflict`: inspect the active request instead of creating another one.
+- `approval_version_conflict`: refresh the request/task, then decide whether to issue a new logical command with a new client request ID.
+- `approval_idempotency_conflict`: do not reuse the client request ID with a changed payload.
+- Permission and tenant-hidden not-found errors must not be bypassed or retried with guessed IDs.
+
+## Transition Metadata
+
+- Transition status: transitional
+- Owning module: te-agent approval domain
+- Current transport: CLI-token-only versioned REST at `/agent/api/cli/approval/v1`
+- Gateway target: `approval.request.list`, `approval.request.get`, `approval.request.submit`, and `approval.request.cancel`
+- Review after: 2026-11-17
+- Exit condition: Migrate these commands when equivalent Gateway schemas preserve idempotency, optimistic concurrency, cursor pagination, authorization, dry-run, and structured output contracts.

package/skills/ae-agent/references/approval-task.md

@@ -0,0 +1,45 @@
+# agent approval-task (Review Approval Tasks)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Generic Approval Task / read + write**
+
+## Commands
+
+```bash
+ae-cli agent approval-task list --status pending --limit 20
+ae-cli agent approval-task list --approval-request-id <request-id>
+ae-cli agent approval-task get --task-id <task-id>
+ae-cli --dry-run agent approval-task approve --task-id <task-id> --expected-version 0 --client-request-id <unique-id>
+ae-cli agent approval-task approve --task-id <task-id> --expected-version 0 --note "Reviewed" --client-request-id <unique-id>
+ae-cli agent approval-task reject --task-id <task-id> --expected-version 0 --reason "Missing evidence" --client-request-id <unique-id>
+```
+
+## Mandatory Rules
+
+- Keep task and request identities separate. `--task-id` selects the actionable unit; `--approval-request-id` only filters task lists.
+- Never guess task IDs. Discover current tasks with `approval-task list`, then read the chosen task with `get`.
+- Read the latest task immediately before a decision and pass its `optimistic_version` as `--expected-version`.
+- Approval allows an optional `--note`; rejection requires a non-empty `--reason`.
+- Generate a stable unique `--client-request-id` for each logical decision. Reuse it only to replay the identical decision.
+- Current server role and company membership are authoritative. A task returned earlier may become ineligible before the write.
+- Write commands are ordinary `write` operations. They do not require `--yes`.
+
+## Dry-run Boundary
+
+`--dry-run` is a local method, URL, and body preview. It does not call te-agent and therefore does not verify current approver eligibility, live task/request versions, or future multi-step and conditional routing.
+
+## Error Handling
+
+- `approval_version_conflict`: refresh both the task and request before deciding whether to retry.
+- `approval_idempotency_conflict`: do not reuse the client request ID with a changed action or payload.
+- Permission and tenant-hidden not-found errors must not be bypassed or retried with guessed IDs.
+
+## Transition Metadata
+
+- Transition status: transitional
+- Owning module: te-agent approval domain
+- Current transport: CLI-token-only versioned REST at `/agent/api/cli/approval/v1`
+- Gateway target: `approval.task.list`, `approval.task.get`, `approval.task.approve`, and `approval.task.reject`
+- Review after: 2026-11-17
+- Exit condition: Migrate these commands when equivalent Gateway schemas preserve task identity, current-role authorization, optimistic concurrency, idempotency, cursor pagination, dry-run, and structured output contracts.

package/skills/ae-agent/references/approval-type.md

@@ -0,0 +1,32 @@
+# agent approval-type (Discover Approval Types)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Generic Approval / read**
+
+## Commands
+
+```bash
+ae-cli agent approval-type list
+ae-cli agent approval-type get --approval-type-id skill.publish@1
+```
+
+## Mandatory Rules
+
+- Use `list` to discover registered versioned type IDs. Never guess a type version.
+- Use `get` before `approval-request submit`; its `input_schema` defines the type-specific snake_case payload.
+- `--approval-type-id` is a versioned type identity such as `skill.publish@1`, not a request or task ID.
+- V1 definitions describe one `ANY_ONE` step. Do not infer future multi-step or conditional behavior from local CLI output.
+
+## Output
+
+The response keeps the te-agent public snake_case contract, including `input_schema`, `snapshot_schema`, `principal_selector`, `flow`, and `effect` metadata.
+
+## Transition Metadata
+
+- Transition status: transitional
+- Owning module: te-agent approval domain
+- Current transport: CLI-token-only versioned REST at `/agent/api/cli/approval/v1`
+- Gateway target: `approval.type.list` and `approval.type.get`
+- Review after: 2026-11-17
+- Exit condition: Migrate these commands to equivalent Capability Gateway schemas once discovery, authorization, output, and versioning contracts are stable, or remove the curated commands if L3 provides the same typed safety.

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

@@ -0,0 +1,19 @@
+# Generic Approval Command Risk Index
+
+This index provides command-level risk metadata for generic approval examples. The command implementation remains the source of truth for runtime admission.
+
+| CLI command                                  | Transport                     | Risk            | Reference            |
+| -------------------------------------------- | ----------------------------- | --------------- | -------------------- |
+| `ae-cli agent approval-type list`            | CLI-token-only versioned REST | read            | approval-type.md     |
+| `ae-cli agent approval-type get`             | CLI-token-only versioned REST | read            | approval-type.md     |
+| `ae-cli agent approval-request list`         | CLI-token-only versioned REST | read            | approval-request.md  |
+| `ae-cli agent approval-request get`          | CLI-token-only versioned REST | read            | approval-request.md  |
+| `ae-cli agent approval-request submit`       | CLI-token-only versioned REST | write           | approval-request.md  |
+| `ae-cli agent approval-request cancel`       | CLI-token-only versioned REST | write           | approval-request.md  |
+| `ae-cli agent approval-task list`            | CLI-token-only versioned REST | read            | approval-task.md     |
+| `ae-cli agent approval-task get`             | CLI-token-only versioned REST | read            | approval-task.md     |
+| `ae-cli agent approval-task approve`         | CLI-token-only versioned REST | write           | approval-task.md     |
+| `ae-cli agent approval-task reject`          | CLI-token-only versioned REST | write           | approval-task.md     |
+| `ae-cli agent approval-effect list`          | CLI-token-only versioned REST | read            | approval-effect.md   |
+| `ae-cli agent approval-effect get`           | CLI-token-only versioned REST | read            | approval-effect.md   |
+| `ae-cli agent approval-effect retry`         | CLI-token-only versioned REST | high-risk-write | approval-effect.md   |

package/skills/ae-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-analysis
-version: 4.2.0
+version: 4.2.2
 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."
 ---
 
@@ -8,9 +8,11 @@ description: "Use ae-cli for AE/TE analysis-side data questions, asset operation
 
 This is the single entry skill for analysis intent and command execution.
 
-## Before any command
+## Route before reading
 
-1. If the command family is already known, open its dedicated reference directly. Otherwise search only the matching row in [`references/command_index.md`](references/command_index.md) (for example with `rg`); do not read the exhaustive index end to end.
+1. Map the request to a command family before opening any reference.
+   - Known family: open only its dedicated reference. For example, a retention request goes directly to `references/adhoc_run.md` plus the `retention` section of `references/ai_models.md`.
+   - Unknown family: search [`references/command_index.md`](references/command_index.md) with `rg` or an equivalent text-search tool and keep only the matching rows. `command_index.md` is a search-only fallback; never open it with a whole-file read or print the entire file.
 2. Read the selected command's dedicated reference before composing it:
    - `event list` -> `references/event_list.md`
    - `analysis dashboard list` -> `references/dashboard_list.md`
@@ -20,7 +22,7 @@ This is the single entry skill for analysis intent and command execution.
 5. For analysis data retrieval, choose `run` or `export` using [`references/analysis_data_retrieval.md`](references/analysis_data_retrieval.md).
 6. When an AI-QP compile failure contains `slot_kind`, `allowed_resource_types`, `search_targets`, and `next_action`, read and follow [`metadata_resolution.md`](metadata_resolution.md).
 
-The generated command index is exhaustive. This file contains routing and workflow rules only; do not duplicate a hand-maintained command inventory here.
+Routing is complete when one command family and its dedicated references are selected. The generated command index is exhaustive and must stay out of model context except for matching search rows. This file contains routing and workflow rules only; do not duplicate a hand-maintained command inventory here.
 
 ## Boundaries and priority
 
@@ -111,9 +113,10 @@ When the request can map to a saved business definition:
 
 1. Extract metric, dimensions, filters, time window, and comparison semantics.
 2. Search reports; use dashboard search only to discover candidate embedded reports.
-3. Read the candidate definition and verify semantic equality, not merely a similar name.
-4. Use report/dashboard data when the definition matches.
-5. Use `analysis adhoc run|export` when no definition matches, the user explicitly requests ad-hoc exploration, or custom grouping/filtering is required.
+3. Before querying a selected dashboard's report data, call `analysis dashboard get` exactly once with the verified project and dashboard IDs. Preserve non-empty `location.folder_name`, `dashboard_name`, `remark`, and `notes[].note_title/description` as authored dashboard context for all results from that dashboard. Do not repeat the detail call per report.
+4. Read the candidate definition and verify semantic equality, not merely a similar name.
+5. Use report/dashboard data when the definition matches.
+6. Use `analysis adhoc run|export` when no definition matches, the user explicitly requests ad-hoc exploration, or custom grouping/filtering is required.
 
 Do not call removed QP builders or schema helpers for ad-hoc analysis. `--definition` is the AI-facing contract from `ai_models.md`, not raw QP or a frontend DTO.
 
@@ -165,6 +168,7 @@ For attribution, use the algorithms and self-checks in [`references/analysis_int
 - Include the metric, time window, dimension/filter scope, value, and baseline needed to reproduce it.
 - Separate observed evidence from inferred causes and state uncertainty.
 - For attribution, include total absolute/percentage change and dimension contributions sorted by absolute delta; verify the contribution sum.
+- For saved dashboard answers, use non-empty `location.folder_name`, `dashboard_name`, `remark`, and `notes[].note_title/description` to establish business scope. Label folder names and notes as authored context, separately from observed query evidence.
 - Do not return an unexplained raw table.
 - State missing data, definition, permission, or capability constraints explicitly.
 

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

@@ -66,4 +66,6 @@ Execution failures are returned as command failures with `request_id`; only the
 
 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 metadata error retains `path`, `slot_kind`, `raw_value`, `allowed_resource_types`, `search_targets`, and `candidates`. Follow [`../metadata_resolution.md`](../metadata_resolution.md); do not guess from display text.
 
+For a complex definition, finish the complete user-requested definition first, validate that exact definition once, and then run the same definition once. Never execute a simplified variant that omits requested filters or groups just to obtain a result. If validation rejects fields, inspect this command's model contract or capability schema once, correct all reported fields together, and revalidate the complete definition.
+
 Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Use the context only with an action advertised by the selected source, call `analysis query-context get`, and assemble the coordinate only from its returned option fragments. Do not pass raw QP or infer a coordinate from display text.

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

@@ -124,11 +124,13 @@ Property aggregation example:
 {
   "time_range": {"mode": "previous", "unit": "day", "value": 7},
   "metrics": [
-    {"event": "purchase", "aggregation": "sum", "property": "amount"}
+    {"event": "purchase", "display_name": "Purchase revenue", "aggregation": "sum", "property": "amount"}
   ]
 }
 ```
 
+Set optional `display_name` on an event metric when the report should show a business-facing metric name. It applies to regular event metrics, saved metrics, and formula metrics. Omit it to use the event name or the default formula-metric label.
+
 Formula metric example:
 
 ```json
@@ -136,6 +138,7 @@ Formula metric example:
   "time_range": {"mode": "previous", "unit": "day", "value": 7},
   "metrics": [
     {
+      "display_name": "Revenue per user",
       "formula": "revenue / users",
       "dependencies": [
         {"alias": "revenue", "event": "purchase", "aggregation": "sum", "property": "amount"},
@@ -175,6 +178,33 @@ Use for retained/lost users from an initial event to a return event.
 
 Use `stat_type=lost` for lost-user analysis. Use `rtn_rate_or_num=count` when the user asks for user counts instead of rates.
 
+Initial-event and return-event property filters use the retention-specific shape below. Put them inside `retention`; use `event_property_name` instead of a generic `field` object. Do not use top-level `filters`, `retention.filters`, or `initial_event_filters`.
+
+```json
+{
+  "time_range": {"mode": "custom", "start_time": "2026-08-18 00:00:00", "end_time": "2026-08-18 23:59:59"},
+  "time_particle_size": "day",
+  "retention": {
+    "initial_event": "register",
+    "initial_filters": [
+      {"event_property_name": "case_id", "operator": "eq", "values": ["retention_test"]}
+    ],
+    "initial_filter_relation": "and",
+    "return_event": "login",
+    "return_filters": [
+      {"event_property_name": "case_id", "operator": "eq", "values": ["retention_test"]}
+    ],
+    "return_filter_relation": "and",
+    "stat_type": "retention",
+    "unit_num": 1,
+    "rtn_rate_or_num": "rate",
+    "groups": [
+      {"field": {"name": "channel", "type": "event_property"}}
+    ]
+  }
+}
+```
+
 ### `funnel`
 
 Use for ordered conversion steps with a conversion window.

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

@@ -12,7 +12,7 @@ ae-cli analysis alert list [options]
 
 Capability id: `analysis.alert.list`
 
-Input sends `project_id`, optional `query`, `limit`, and `offset`. Do not send camelCase aliases.
+Input sends `project_id`, optional `queries`, `limit`, and `offset`. `queries` accepts 1 to 20 non-empty strings with OR semantics; matching rows include `matched_queries` and `matched_fields`. Do not send singular `query` or camelCase aliases.
 
 Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
 
@@ -21,7 +21,6 @@ Parameters:
 | Parameter | Description | Required |
 | --- | --- | --- |
 | `--project-id` | See command help | Yes |
-| `--query` | See command help | No |
+| `--queries` | JSON array of 1 to 20 keyword filters | No |
 | `--limit` | See command help | No |
 | `--offset` | See command help | No |
-

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

@@ -81,7 +81,7 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. Analys
 | `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` | `analysis.report.list` | Find accessible reports | `--project-id`, optional `--queries`, `--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 |
@@ -95,10 +95,10 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. Analys
 | `report-version rollback` | `analysis.report_version.rollback` | Rollback a report version | `--report-id`, `--target-version` | Rollback result |
 | `report-abnormal get` | `analysis.report_abnormal.get` | Inspect report abnormal dependencies | `--report-id` | Abnormal info |
 | `dashboard-report add` | `analysis.dashboard_report.add` | Add reports to a dashboard | `--dashboard-id`, `--report-ids` | Add result |
-| `dashboard list` | `analysis.dashboard.list` | Find accessible dashboards | `--project-id`, optional `--query`, `--fields`, `--limit`, `--offset` | Paginated dashboard summaries |
+| `dashboard list` | `analysis.dashboard.list` | Find accessible dashboards | `--project-id`, optional `--queries`, `--fields`, `--limit`, `--offset` | Paginated dashboard summaries |
 | `dashboard create` | `analysis.dashboard.create` | Create a dashboard | `--project-id`, `--dashboard-name`, optional `--space-id`, `--folder-id` | Created dashboard |
-| `dashboard get` | `analysis.dashboard.get` | Inspect one dashboard definition/share/report structure, including creator and creation/update time | `--project-id`, `--dashboard-id` | Dashboard detail |
-| `dashboard update` | `analysis.dashboard.update` | Update settings or upsert a note | `--operation settings|note-upsert`, IDs, optional `--payload` | Update result |
+| `dashboard get` | `analysis.dashboard.get` | Inspect one dashboard location/definition/share/report structure, including notes, creator, and creation/update time | `--project-id`, `--dashboard-id` | Dashboard detail with location and normalized notes |
+| `dashboard update` | `analysis.dashboard.update` | Update settings, upsert a note, or replace the dashboard-level business filter | `--operation settings|note-upsert|business-filter`, IDs, optional `--filter`/`--payload` | Update result |
 | `dashboard share-info` | `analysis.dashboard.share_info` | Read dashboard sharing info | `--project-id`, `--dashboard-id` | Share info |
 | `dashboard share` | `analysis.dashboard.share` | Modify dashboard sharing | `--project-id`, `--dashboard-id`, `--payload` or `--member-authorities` | Share update result |
 | `dashboard delete` | `analysis.dashboard.delete` | Delete dashboards | `--project-id`, `--dashboard-ids '[...]'` | Delete result |
@@ -130,8 +130,9 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. Analys
 | `bi-panel-page-data run` | `analysis.bi_panel_page_data.run` | Bounded inline BI page data | `--panel-id`, `--page-key`, `--result-type charts|summary` | Inline page data |
 | `bi-panel-page-data export` | `analysis.bi_panel_page_data.export` | Large/long BI page data | same as run, optional `--artifact-format jsonl` | Async artifact descriptor |
 | `project-space list` | `analysis.project_space.list` | Find accessible project spaces | `--project-id`, optional list filters | Paginated project spaces |
+| `project-space business-filter-upsert` | `analysis.project_space.business_filter_upsert` | Create or replace the space-level business filter | `--project-id`, `--space-id`, `--filter` | Saved space filter |
 | `project-space get` | `analysis.project_space.get` | Inspect one project space | `--project-id`, `--space-id` | Project space detail |
-| `favorite add` | `analysis.favorite.add` | Favorite dashboard/BI/folder | `--asset-id`, `--asset-type`, optional `--payload` | Favorite result |
+| `favorite add` | `analysis.favorite.add` | Favorite dashboard/BI/folder | required `--asset-id`, `--asset-type`; optional `--space-id` | Favorite result |
 | `favorite remove` | `analysis.favorite.remove` | Remove favorite | same as add | Remove result |
 | `public-link create` | `analysis.public_link.create` | Generate public link | `--resource-type`, `--resource-id`, `--effective-at`, `--expires-at` | Link result |
 | `public-link list` | `analysis.public_link.list` | List public links | `--project-id`, optional list filters | Paginated links |
@@ -213,10 +214,10 @@ Output is the gateway envelope; `data` contains members.
 ## Examples
 
 ```bash
-ae-cli analysis dashboard list --project-id 1 --query retention --limit 50
+ae-cli analysis dashboard list --project-id 1 --queries '["retention","留存"]' --limit 50
 ae-cli analysis adhoc run --project-id 1 --model-type sql --definition '{"sql":"select * from events limit 20"}'
 ae-cli analysis adhoc export --project-id 1 --model-type sql --definition '{"sql":"select * from events where country ${Text:country}","params":[{"name":"country","type":"text","value":"US"}]}' --artifact-format jsonl
-ae-cli analysis report list --project-id 1 --query revenue --limit 50
+ae-cli analysis report list --project-id 1 --queries '["revenue","收入"]' --limit 50
 ae-cli analysis report-data run --project-id 1 --report-ids '[1001]' --preview-rows 50
 ae-cli analysis report-data run --project-id 1 --report-ids '[1001]' --filters '{"relation":"and","items":[{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}' --group-by '[{"field":{"name":"country","type":"user_property"}}]' --sql-params '[{"name":"platform","value":"ios"}]' --preview-rows 50
 ae-cli analysis drilldown-entities run --query-context-id ctx_0123456789abcdef0123456789abcdef --source '{"report_id":1001}' --coordinate '{"cohort_date":"2026-07-01","group_values":[],"period_index":1,"population":"retained"}'

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

@@ -7,10 +7,10 @@ Do not use for dashboard assets. Use `dashboard list`.
 Command:
 
 ```bash
-ae-cli analysis bi-panel list --project-id <project_id> [--query <keyword>] [--limit 50] [--offset 0]
+ae-cli analysis bi-panel list --project-id <project_id> [--queries '["growth","retention"]'] [--limit 50] [--offset 0]
 ```
 
-Input sends `project_id` and optional `query`, `fields`, `limit`, `offset`. Prefer the default projection for discovery. Do not request generic `id`; BI panel summaries use fields such as `panel_id` and `name` when projected.
+Input sends `project_id` and optional `queries`, `fields`, `limit`, `offset`. `queries` accepts 1 to 20 non-empty strings with OR semantics; matching rows include `matched_queries` and `matched_fields`, and singular `query` is not accepted. Prefer the default projection for discovery. Do not request generic `id`; BI panel summaries use fields such as `panel_id` and `name` when projected.
 
 When `has_more=true`, continue only with the returned `next_offset`; do not calculate the next page locally.