@thinkingai/ae-cli 6.1.14 → 6.1.17

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.1.14",
+  "version": "6.1.17",
   "description": "CLI tool for ThinkingAI (AE) analytics platform",
   "type": "module",
   "bin": {
@@ -39,13 +39,15 @@
     "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 && 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:kb-skill": "node test/kb-skill-query-workflow.test.mjs",
     "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",
@@ -78,18 +80,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

@@ -178,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/analysis_gateway_assets.md

@@ -97,8 +97,8 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. Analys
 | `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 `--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,6 +130,7 @@ 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 | required `--asset-id`, `--asset-type`; optional `--space-id` | Favorite result |
 | `favorite remove` | `analysis.favorite.remove` | Remove favorite | same as add | Remove result |

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

@@ -2,6 +2,8 @@
 
 <!-- Generated by scripts/generate-analysis-skill-index.mts. Do not edit manually. -->
 
+**Search-only fallback:** search this file for matching command rows. When the command family is already known, open its dedicated reference directly. Never load or print this exhaustive file in full.
+
 This is the exhaustive command and flag inventory for the analysis skill. Read the linked command reference for routing, semantic input contracts, output interpretation, and cases where the command must not be used.
 
 | Command | Capability ID | Risk | Flags | Reference |
@@ -41,7 +43,7 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli analysis dashboard share` | analysis.dashboard.share | write | `--project-id` (number; required) — Numeric project ID.<br>`--dashboard-id` (number; required) — Dashboard ID.<br>`--member-authorities` (json; optional) — Complete user authority map: {"<numeric_user_id>":"READ\|EDIT\|CREATOR\|MAINTAIN"}. An empty object removes all directly shared users.<br>`--payload` (json; optional) — Optional snake_case object for complex capability payload fields. | [dashboard_share.md](dashboard_share.md) |
 | `ae-cli analysis dashboard share-info` | analysis.dashboard.share_info | read | `--project-id` (number; required) — Numeric project ID.<br>`--dashboard-id` (number; required) — Dashboard ID. | [dashboard_share_info.md](dashboard_share_info.md) |
 | `ae-cli analysis dashboard task-status` | analysis.dashboard.task_status | read | `--project-id` (number; required) — Numeric project ID.<br>`--dashboard-id` (number; required) — Dashboard ID. | [dashboard_task_status.md](dashboard_task_status.md) |
-| `ae-cli analysis dashboard update` | analysis.dashboard.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--operation` (string; required) — Update operation: settings or note-upsert.<br>`--dashboard-id` (number; optional) — Dashboard ID for a single-dashboard update.<br>`--dashboard-ids` (json; optional) — Dashboard ID array for batch settings updates.<br>`--dashboard-name` (string; optional) — Dashboard name for single rename.<br>`--zone-offset` (number; optional) — Fixed dashboard time zone offset in hours. For example, UTC+8 is 8 and UTC-5 is -5. Valid range: -12 to 14.<br>`--refresh-type` (number; optional, min=0, max=1) — Dashboard refresh type: 0 real-time, 1 scheduled.<br>`--dashboard-status` (string; optional) — Dashboard status: normal or freeze.<br>`--note-id` (number; optional) — Dashboard note ID. Omit to create a new note.<br>`--note-title` (string; optional) — Dashboard note title.<br>`--description` (string; optional) — Dashboard note description.<br>`--ui-config` (string; optional) — Dashboard or note UI config string.<br>`--payload` (json; optional) — Optional snake_case object for complex capability payload fields. | [dashboard_update.md](dashboard_update.md) |
+| `ae-cli analysis dashboard update` | analysis.dashboard.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--operation` (string; required) — Update operation: settings, note-upsert, or business-filter.<br>`--dashboard-id` (number; optional) — Dashboard ID for a single-dashboard update.<br>`--dashboard-ids` (json; optional) — Dashboard ID array for batch settings updates.<br>`--dashboard-name` (string; optional) — Dashboard name for single rename.<br>`--zone-offset` (number; optional) — Fixed dashboard time zone offset in hours. For example, UTC+8 is 8 and UTC-5 is -5. Valid range: -12 to 14.<br>`--refresh-type` (number; optional, min=0, max=1) — Dashboard refresh type: 0 real-time, 1 scheduled.<br>`--dashboard-status` (string; optional) — Dashboard status: normal or freeze.<br>`--note-id` (number; optional) — Dashboard note ID. Omit to create a new note.<br>`--note-title` (string; optional) — Dashboard note title.<br>`--description` (string; optional) — Dashboard note description.<br>`--ui-config` (string; optional) — Dashboard or note UI config string.<br>`--filter` (json; optional) — Dashboard-level business filter in snake_case QP form. Required with --operation business-filter. Pass {"junction_kind":"and","ta_filters":[]} to clear it.<br>`--payload` (json; optional) — Optional snake_case object for complex capability payload fields. | [dashboard_update.md](dashboard_update.md) |
 | `ae-cli analysis dashboard-daily-report get` | analysis.dashboard_daily_report.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--dashboard-id` (number; required) — Dashboard ID. | [dashboard_daily_report_get.md](dashboard_daily_report_get.md) |
 | `ae-cli analysis dashboard-daily-report send` | analysis.dashboard_daily_report.send | write | `--project-id` (number; required) — Numeric project ID.<br>`--dashboard-id` (number; required) — Dashboard ID.<br>`--need-csv` (boolean; optional) — Whether to include CSV attachment.<br>`--host-url` (string; optional) — Public host URL used in report links.<br>`--send-title` (string; optional) — Daily report title.<br>`--send-content` (string; optional) — Daily report content.<br>`--lang` (string; optional) — Report language.<br>`--screen-type` (string; optional) — Screenshot screen type.<br>`--zone-offset` (number; optional) — Time zone offset.<br>`--email-login-users` (string; optional) — Comma-separated login users for email.<br>`--email-new` (string; optional) — Comma-separated direct email addresses. The server selects company SMTP or the default mail service.<br>`--dd-url` (json; optional) — DingTalk webhook URL array, e.g. ["https://..."].<br>`--wx-url` (json; optional) — WeCom webhook URL array, e.g. ["https://..."].<br>`--feishu-info` (json; optional) — Feishu image upload and bot config, e.g. {"app_id":"cli_xxx","app_secret":"secret_xxx","webhook":["https://..."]}.<br>`--kim-url` (json; optional) — KIM/custom webhook URL array, e.g. ["https://..."].<br>`--slack-url` (json; optional) — Slack webhook URL array, e.g. ["https://..."].<br>`--payload` (json; optional) — Optional snake_case object for complex capability payload fields. | [dashboard_daily_report_send.md](dashboard_daily_report_send.md) |
 | `ae-cli analysis dashboard-daily-report send-status` | analysis.dashboard_daily_report.send_status | read | `--project-id` (number; required) — Numeric project ID.<br>`--task-id` (number; required) — Task ID returned by dashboard-daily-report send. | [dashboard_daily_report_send_status.md](dashboard_daily_report_send_status.md) |
@@ -76,6 +78,7 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli analysis input-file inspect` | gateway lifecycle | read | `--input-file-id` (string; required) — Uploaded input file ID, for example ifile_<32 lowercase hex>. | [input_file_inspect.md](input_file_inspect.md) |
 | `ae-cli analysis input-file purpose list` | analysis.input_file.purpose.list | read | `--project-id` (number; required) — Numeric project ID. | [input_file_purpose_list.md](input_file_purpose_list.md) |
 | `ae-cli analysis input-file upload` | gateway lifecycle | write | `--project-id` (number; required) — Numeric project ID.<br>`--purpose` (string; required) — Purpose returned by analysis input-file purpose list.<br>`--file` (string; required) — Local file path to upload. | [input_file_upload.md](input_file_upload.md) |
+| `ae-cli analysis project-space business-filter-upsert` | analysis.project_space.business_filter_upsert | write | `--project-id` (number; required) — Numeric project ID.<br>`--space-id` (number; required) — Project space ID.<br>`--filter` (json; required) — Space-level business filter in snake_case QP form. Pass {"junction_kind":"and","ta_filters":[]} to clear it. | [project_space_business_filter_upsert.md](project_space_business_filter_upsert.md) |
 | `ae-cli analysis project-space get` | analysis.project_space.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--space-id` (number; required) — Project space ID.<br>`--fields` (json; optional) — Optional result field projection JSON array. | [project_space_get.md](project_space_get.md) |
 | `ae-cli analysis project-space list` | analysis.project_space.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected. | [project_space_list.md](project_space_list.md) |
 | `ae-cli analysis public-link create` | analysis.public_link.create | write | `--project-id` (number; required) — Numeric project ID.<br>`--company-id` (number; optional) — Company ID. Derived from project ID when omitted.<br>`--resource-type` (string; required) — Resource type: dashboard or bi_panel.<br>`--resource-id` (number; required) — Target resource ID.<br>`--access-controls` (json; optional) — Public link access-control JSON.<br>`--remark` (string; optional) — Public link remark.<br>`--effective-at` (string; required) — Effective time, yyyy-MM-dd HH:mm:ss.<br>`--expires-at` (string; required) — Expiration time, yyyy-MM-dd HH:mm:ss.<br>`--payload` (json; optional) — Optional snake_case object for complex capability payload fields. | [public_link_create.md](public_link_create.md) |

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

@@ -1,6 +1,6 @@
 # analysis dashboard get
 
-Use when the user needs one dashboard detail, including basic metadata such as creator and create/update time, settings, reports, notes, and sharing information.
+Use when the user needs one dashboard detail or when an agent needs the business context for dashboard report data. The detail includes location, creator and create/update time, settings, reports, notes, and sharing information.
 
 Do not use to query report result data. Use `dashboard-report-data run` or `dashboard-report-data export`.
 
@@ -12,4 +12,10 @@ ae-cli analysis dashboard get --project-id <project_id> --dashboard-id <dashboar
 
 Input sends `project_id`, `dashboard_id`, and optional `use_cache`.
 
-Output is the gateway envelope. `data` contains the dashboard detail returned by the capability gateway.
+Output is the gateway envelope. `data` contains the dashboard detail returned by the capability gateway. Business-context fields are stable snake_case:
+
+- `dashboard_id`, `dashboard_name`, and optional `remark` identify and describe the dashboard.
+- `location` always contains `space_id`, `space_name`, `folder_id`, and `folder_name`; values are null when that level does not apply. `folder_name` is the immediate parent folder.
+- `notes` is an array whose items contain `note_id`, `note_title`, and `description`.
+
+When this detail is fetched before a dashboard data query, preserve non-empty `location.folder_name`, `dashboard_name`, `remark`, and `notes[].note_title/description` as dashboard context. Use them to interpret the report results, but distinguish this authored context from conclusions observed in the queried data.

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

@@ -2,7 +2,9 @@
 
 Execute bounded inline dashboard report data queries. Dashboard report data follows report-data model coverage: the 12 analysis report models from `ai_models.md` plus tag report data.
 
-Typical closed loop: find the dashboard -> inspect its reports -> resolve exact filter values when needed -> optionally resolve a physical query route -> run -> verify actual route and per-report warnings -> drill down through the returned report source.
+Typical closed loop: find the dashboard -> inspect its dashboard context and reports -> resolve exact filter values when needed -> optionally resolve a physical query route -> run -> verify actual route and per-report warnings -> drill down through the returned report source.
+
+Before the first data query for a selected dashboard, run `ae-cli analysis dashboard get` exactly once with the same `project_id` and `dashboard_id`. Preserve non-empty `location.folder_name`, `dashboard_name`, `remark`, and `notes[].note_title/description` as dashboard context for every report result in this dashboard query. A folder name such as `Campaign A` can provide business scope that a generic dashboard name such as `Base Data` does not. Treat notes as authored explanatory context, not as measured evidence. Do not repeat `dashboard get` for each report in the same continuous workflow unless the dashboard changes or the user explicitly requests a refresh.
 
 Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `run` command instead of `dashboard-report-data export`.