@thinkingai/ae-cli 6.1.6 → 6.1.8

package/skills/ae-engage/references/scene-strategy.md

@@ -1,6 +1,6 @@
 # engage-scene strategy
 
-> Capability ids: `engage-scene.strategy.{list,get,create,update,log,batch-copy,manage}` · Domain: `engage`.
+> Trigger keywords: config center, scene config, operation strategy · Capability ids: `engage-scene.strategy.{list,get,create,update,log,predict,batch-copy,manage}` · Domain: `engage`.
 
 Scene management / config center — config item strategy management. `create`/`update` pass backend DTOs via `--payload` (native camelCase structure); `project_id` is injected into the payload.
 
@@ -24,6 +24,12 @@ ae-cli engage-scene strategy update --project-id <project_id> \
 # Query a strategy's log
 ae-cli engage-scene strategy log --project-id <project_id> --strategy-uuid <uuid>
 
+# Predict custom-audience size (mix QP)
+ae-cli engage-scene strategy predict --project-id <project_id> \
+  --qp '<targetClusterQp JSON string>' \
+  --zone-offset 8 \
+  [--strategy-uuid <uuid>]
+
 # Batch-copy strategies
 ae-cli engage-scene strategy batch-copy --project-id <project_id> --config-id <config_id> \
   --strategy-ids '["s1","s2"]' [--op-mode batch]
@@ -42,6 +48,7 @@ ae-cli engage-scene strategy manage --project-id <project_id> --config-id <confi
 | create | `--project-id`, `--payload` | payload = `ConfigStrategyAddDTO`. |
 | update | `--project-id`, `--payload` | payload = `ConfigStrategyModifyDTO` (`strategyUuid` + fields). |
 | log | `--project-id`, `--strategy-uuid` | read. |
+| predict | `--project-id`, `--qp`, `--zone-offset` | Optional `--strategy-uuid`, `--request-id`. read. |
 | batch-copy | `--project-id`, `--config-id`, `--strategy-ids` | `--op-mode` optional (default `batch`). |
 | manage | `--project-id`, `--config-id`, `--action` | Lifecycle actions require `--strategy-uuid-list`; review actions require `--strategy-list`; write. |
 
@@ -51,13 +58,21 @@ ae-cli engage-scene strategy manage --project-id <project_id> --config-id <confi
 - `create`: `data.strategy_uuid`.
 - `update`: `data.success`.
 - `log`: `data.log`.
+- `predict`: `data.entity_num`, `data.real_available`, `data.predict_num_list`, `data.refresh_time`.
 - `batch-copy`: `data.result`.
 - `manage`: `data.item`.
 
 ## Decision Rules
 
 - Discover real strategy UUIDs / config IDs first; never invent IDs.
+- **Custom audience (`targetClusterType=1`)** — follow [`scene-strategy-audience.md`](scene-strategy-audience.md) end-to-end:
+  1. Preflight every **用户满足** user property and **用户行为** event via `analysis-meta property get` / `event get`; if missing, **stop** and list available properties — never invent or drop.
+  2. Assemble mix QP with **two-block layout**: `totalCFilter.filts[0]` = 用户满足, `totalCFilter.filts[1]` = 用户行为; `totalCFilter.relation` = 且/或 between them. **Never** nest `event` inside user-side `COMPOUND`.
+  3. `JSON.stringify` → `targetClusterQp`; then `strategy create|update`.
+  4. **Do not** call `analysis user-cluster create` unless the user explicitly asks for an existing/named cluster.
+  - Full QP spec + examples A/B/C: [`scene-strategy-audience.md`](scene-strategy-audience.md).
 - **`create` requires an enabled template** on the same config item. Enable workflow: `config-param batch-add` → `template create` → `template update` (non-empty `config[]` with real `paramId`) → `template update-status --status 1`. Otherwise `create` returns `TEMPLATE_ENABLE`.
 - `create` output field is `data.strategy_uuid` (not `strategy_id`).
 - `manage` supports `online`, `offline`, `suspend`, `delete`, `approve`, `deny`, and `cancel`; it is a write operation.
 - Save-and-submit and strategy test-send are separate high-impact operations and remain unexposed; use the product UI.
+- **Audience estimate (预估人数):** `ae-cli engage-scene strategy predict` — see [`scene-strategy-audience.md`](scene-strategy-audience.md) § Audience size estimate.

package/skills/ae-engage/references/scene-template.md

@@ -1,6 +1,6 @@
 # engage-scene template
 
-> Capability ids: `engage-scene.template.{list,get,copy,create,update,update-status,delete}` · Domain: `engage`.
+> Trigger keywords: config center, scene config, template · Capability ids: `engage-scene.template.{list,get,copy,create,update,update-status,delete}` · Domain: `engage`.
 
 Scene management / config center — config item template management. `create`/`update` pass backend DTOs via `--payload` (native camelCase structure); `project_id` is injected into the payload.
 

package/skills/ae-engage/references/update-channel-status.md

@@ -1,9 +1,8 @@
 # ae-engage engage-setting channel update-status
 
+> Trigger keywords: push channel · Mapped command: `ae-cli engage-setting channel update-status`
 
-Update the status of an Engage channel.
-
-Mapped command: `ae-cli engage-setting channel update-status`
+Enable or disable an Engage push channel.
 
 ## Flags
 

package/skills/ae-generate-tracking-code/SKILL.md

@@ -34,7 +34,7 @@ description: "Interactive generation of AE tracking code, LogBus2 configuration,
 | LogBus2 配置 | LogBus2 Configuration | `daemon.json` for LogBus2 log sync tool |
 | LoggerConsumer | LoggerConsumer | Server SDK consumer that writes events to local log files |
 | BatchConsumer | BatchConsumer | Server SDK consumer that uploads events in batches |
-| 公共属性 | Super Property | Properties attached to all events automatically |
+| 公共属性 | Super Property | Properties attached to all events automatically. ⚠️ The correct Chinese AE term is "公共属性" or "公共事件属性". Never translate "Super Property" as "超级属性" — that is NOT a valid AE term. |
 | 预置属性 | Preset Property | System properties prefixed with `#` (e.g. `#device_id`, `#time`) |
 | 事件属性 | Event Property | Custom properties on specific events |
 | 用户属性 | User Property | Properties set on the user profile |
@@ -91,12 +91,12 @@ First, check if `.ae-cli/draft.json` exists and read existing configuration:
 **⚠️ Key: SERVER_URL and APP_ID are independent config items. Even if draft.json has project_id and host, you MUST resolve and confirm them. `project_id` ≠ `APP_ID`, `host` ≠ `SERVER_URL`.**
 
 1. **APP_ID** — Prefer automatic lookup before asking:
-   - If `meta.project_id` is known, run `ae-cli analysis_common +list_projects` once for the current host.
+   - If `meta.project_id` is known, run `ae-cli analysis project info list` once for the current host.
    - Find the project whose `projectId` matches `meta.project_id`.
    - If the matched project has `appId`, ask: **"I found APP_ID `<appId>` for project `<projectId>`. Use it? yes / enter new value"**
    - If the project is missing, ambiguous, or has no `appId`, ask the user to copy APP_ID from AE Admin → "Project Settings" → "Integration Config".
 2. **SERVER_URL** — Data ingestion endpoint (**different from web URL**; go to AE Admin → "Project Settings" → "Integration Config" → fill in "Public URL")
-   - If `meta.project_id` is known, you may try `ae-cli analysis_meta +get_project_config --project_id <project_id>` once.
+   - If `meta.project_id` is known, you may try `ae-cli analysis project info get --project-id <project_id>` once.
    - Use the returned value only if the response explicitly contains a receiver URL field such as `serverUrl`, `pushUrl`, `push_url`, `receiverUrl`, `publicUrl`, `publicReceiverAddress`, `privateReceiverAddress`, or equivalent ingestion endpoint field.
    - If both `publicReceiverAddress` and `privateReceiverAddress` are present, prefer `publicReceiverAddress` as `SERVER_URL` for generated snippets unless the user explicitly needs an internal/private-network receiver.
    - If a value is found, ask: **"I found SERVER_URL `<url>` for project `<projectId>`. Use it? yes / enter new value"**
@@ -646,6 +646,7 @@ Validation steps:
 - Including `platform === "server"` exclusive events in client code
 - Including `platform === "client"` exclusive events in server code (unless `platform === "both"`)
 - **Skipping SDK main doc read and guessing integration method** — each SDK has different integration approaches; must read wiki main doc's "Integrate SDK" section first, and choose the correct method based on project characteristics (with/without build tools)
+- **Translating "Super Property" as "超级属性" in any user-facing output (code comments, interaction prompts, markdown) — the correct AE Chinese term is "公共事件属性" or "公共属性"**
 - **Entering Phase 1 before Phase 0.5 is complete** — SDK integration must be confirmed before inserting code, otherwise generated track() calls won't work
 
 ---

package/skills/ae-generate-tracking-code/references/client-sdk-insert.md

@@ -1,6 +1,6 @@
 # Mode A — Client SDK Code Insertion
 
-> **Terminology**: 客户端 SDK = client SDK | 代码插入 = code insertion/injection | 前置检查 = pre-check | 集成方式 = integration method | 埋点 = tracking/event tracking | 业务触发点 = business trigger point | 公共属性 = super property | 用户属性 = user property | 自动采集事件 = auto-track event | 插入位置预览 = insertion site preview | 语言风格校验 = language style check
+> **Terminology**: 客户端 SDK = client SDK | 代码插入 = code insertion/injection | 前置检查 = pre-check | 集成方式 = integration method | 埋点 = tracking/event tracking | 业务触发点 = business trigger point | 公共属性 = super property (公共事件属性; never "超级属性") | 用户属性 = user property | 自动采集事件 = auto-track event | 插入位置预览 = insertion site preview | 语言风格校验 = language style check
 
 ## ⚠️ Mandatory Pre-checks (do not skip)
 

package/skills/ae-generate-tracking-code/references/server-sdk-insert.md

@@ -1,6 +1,6 @@
 # Server-side Code Insertion (LoggerConsumer + LogBus2)
 
-> **Terminology**: 服务端 SDK = server-side SDK | 代码插入 = code insertion/injection | LoggerConsumer = writes events to local log files (recommended for production) | LogBus2 = log sync tool that reads local logs and uploads to TE | 架构 = architecture | 异步上报 = async upload | 批量上传 = batch upload | 重试策略 = retry strategy | 公共属性 = super property | 用户属性 = user property | 依赖管理 = dependency management
+> **Terminology**: 服务端 SDK = server-side SDK | 代码插入 = code insertion/injection | LoggerConsumer = writes events to local log files (recommended for production) | LogBus2 = log sync tool that reads local logs and uploads to TE | 架构 = architecture | 异步上报 = async upload | 批量上传 = batch upload | 重试策略 = retry strategy | 公共属性 = super property (公共事件属性; never "超级属性") | 用户属性 = user property | 依赖管理 = dependency management
 
 ## Architecture
 

package/skills/ae-generate-tracking-code/references/snippet-delivery.md

@@ -1,6 +1,6 @@
 # Snippet Output Mode
 
-> **Terminology**: 片段/代码片段 = snippet/code snippet | 产物 = deliverable/output | markdown 响应 = markdown response | 初始化 = initialization | 公共属性 = super property | 用户属性 = user property | 事件组 = event group | 触发时机 = trigger timing | 验证步骤 = verification steps | 设备绑定 = device binding | 自动采集事件 = auto-track event | 占位值 = placeholder value | 属性类型 = property type
+> **Terminology**: 片段/代码片段 = snippet/code snippet | 产物 = deliverable/output | markdown 响应 = markdown response | 初始化 = initialization | 公共属性 = super property (公共事件属性; never "超级属性") | 用户属性 = user property | 事件组 = event group | 触发时机 = trigger timing | 验证步骤 = verification steps | 设备绑定 = device binding | 自动采集事件 = auto-track event | 占位值 = placeholder value | 属性类型 = property type
 
 ## Deliverables
 

package/skills/ae-generate-tracking-plan/SKILL.md

@@ -29,7 +29,7 @@ description: "Interactive generation of an AE tracking plan and upload. Trigger
 | 货币体系 | Currency System | Hard currency (diamonds), soft currency (gold), etc. |
 | 事件 | Event | Named user action or system occurrence (`event_name`) |
 | 事件属性 | Event Property | Data attached to an event (`prop_names`) |
-| 公共事件属性 | Common/Super Property | Property attached to every event automatically |
+| 公共事件属性 | Common/Super Property | Property attached to every event automatically. ⚠️ The correct Chinese AE term is "公共事件属性" or "公共属性". Never translate "Super Property" as "超级属性" — that is NOT a valid AE term. |
 | 用户属性 | User Property | Property on the user profile (persistent state) |
 | 预置属性 | Preset Property | System property prefixed with `#` (`#device_id`, `#time`, etc.) |
 | 自动采集事件 | Auto-track Event | SDK auto-collected events (`ta_app_start`, `ta_page_show`, etc.) |
@@ -700,7 +700,10 @@ Based on SDK integration mode collected in Phase 0, decide whether to inject aut
 3. Auto-track event `event_tag` set to `"System Event"`
 4. Auto-track events only carry preset properties (`prop_names` is empty or contains only preset property names)
 5. Preset properties prefixed with `#` are not added to `event_properties` pool (auto-collected by SDK)
-6. **Deduplication**: Templates may already contain same-name auto-track events (e.g. `ta_app_start` marked `source: "template"`); CLI deduplicates by event name globally and will not inject duplicates
+6. **Cleanup + Deduplication**: The CLI will:
+   - **Remove** auto-track events inherited from templates or existing plans that don't match the user's selected SDKs. For example: if a template built for Android/iOS contains `ta_app_install`, `ta_app_start`, `ta_app_end` but the user selects JavaScript SDK, those `ta_app_*` events will be automatically removed since JavaScript SDK does not support them.
+   - **Inject** the correct auto-track events for the user's selected SDKs.
+   - **Deduplicate** by event name globally — won't inject events that already exist in the draft (correct auto-track events inherited from templates are kept).
 
 **SDK type → Recommended events** (see `references/autotrack-events.md` for details):
 
@@ -1300,6 +1303,7 @@ The tracking plan has been uploaded successfully. Would you like to generate tra
 - Asking all anchor questions at once
 - Skipping Phase 3 and uploading directly
 - Manually assembling xlsx bypassing `.ae-cli/draft.json`
+- Translating "Super Property" as "超级属性" in any user-facing output (interaction prompts, plan summaries, event/property descriptions) — the correct AE Chinese term is "公共事件属性" or "公共属性"
 - Calling `fetch` AE API directly within the skill — all AE communication must go through project scripts / CLI
 
 ---

package/skills/ae-metadata/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: ae-metadata
 version: 1.0.0
-description: "AE/TE metadata capability-gateway CLI: metadata event/property detail, data-table management, and property dimension-table binding. Metadata CLI routes through the analysis gateway. Input-file upload belongs to ae-analysis."
+description: "AE/TE metadata capability-gateway CLI: metadata data-table management and property dimension-table binding. Metadata CLI routes through the analysis gateway. Input-file upload and event/property detail belong to ae-analysis."
 ---
 
 # ae-metadata
 
 CLI domain **`metadata`** routes to the analysis capability gateway (`/api/cli/analysis/v1/...`), using auth header **`cli-token`**.
 
-Parallel to **`ae-analysis`** (MCP `analysis_meta` for metadata lists/governance). Use **this skill** for gateway-backed metadata detail and data-table/dimension-table operations; use **`ae-analysis`** for MCP metadata list/search, metrics, virtual create, and batch edit.
+Parallel to **`ae-analysis`**. Use **this skill** for gateway-backed metadata detail and data-table/dimension-table operations; use **`ae-analysis`** for metadata list/search, metrics, virtual create, and batch edit.
 
 ## Global AE CLI Rules
 
@@ -16,7 +16,7 @@ Parallel to **`ae-analysis`** (MCP `analysis_meta` for metadata lists/governance
 |---|---|
 | `--format <json\|table>` | Output format. Default JSON. |
 | `--jq <expr>` | jq filter on JSON output. |
-| `--host <url>` | Override active AE host, e.g. `ae-cli metadata event get --host <url> ...`. |
+| `--host <url>` | Override active AE host, e.g. `ae-cli metadata data-table list --host <url> ...`. |
 | `--validate` | Optional: fix params only (`/validate`). Alone while iterating complex `qp` / payload — then run. Do not stack with `--dry-run`. |
 | `--dry-run` | Optional: confirm ready to run (`/dry-run`). Alone for risk/output preview. Do not stack with `--validate`. |
 
@@ -28,20 +28,18 @@ Output and errors:
 Safety:
 - Read-only commands can run directly after IDs/names are verified.
 - Ordinary writes (`data-table *-write`, `property-bindings-update`, dimension-table bind/create) execute without `--yes`. Delete commands are `high-risk-write`: dry-run first, summarize impact, wait for explicit confirmation, then execute with `--yes`.
-- **Before any command**, read the matching `references/<name>.md` (filename = command with spaces → underscores, e.g. `metadata event get` → `metadata_event_get.md`).
+- **Before any command**, read the matching `references/<name>.md` (filename = command with spaces → underscores, e.g. `metadata data-table list` → `metadata_data_table_list.md`).
 - Never invent `project_id`, event/property names, `input_file_id`, or `data_table_id`. Discover names via `ae-analysis` and data table IDs via `metadata data-table list`.
 
 ## When to Use
 
 Switch to **`ae-metadata`** when the user needs:
 
-- Full detail for **one** super-event (incl. virtual event `definition`)
-- Full detail for **one** super-property (incl. virtual property `definition`)
 - Metadata data-table list/get/create/update/delete/download
 - For local uploads, switch to `ae-analysis` and use `analysis input-file upload` with a discovered purpose.
 - Bind an existing data table to a property, or create a CSV dimension table and bind it
 
-Stay on **`ae-analysis`** for: metadata event/property/metric list/search, metric CRUD, batch metadata, virtual create, project config, tracking plans.
+Stay on **`ae-analysis`** for: metadata event/property detail, metadata event/property/metric list/search, metric CRUD, batch metadata, virtual create, project config, tracking plans.
 
 ## Command Format
 
@@ -55,14 +53,12 @@ ae-cli metadata property <dimension-table-action> [options]
 
 ## PROJECT_ID_GATE
 
-Same rules as `ae-analysis`: reuse verified project context in one conversation; otherwise `ae-cli analysis_common +list_projects` (or `ae-analysis` skill) to resolve `project_id`.
+Same rules as `ae-analysis`: reuse verified project context in one conversation; otherwise `ae-cli analysis project info list` (or `ae-analysis` skill) to resolve `project_id`.
 
-## Commands (12)
+## Commands (10)
 
 | User command | Capability id | Reference |
 |---|---|---|
-| `metadata event get` | `metadata.event.get` | [metadata_event_get.md](references/metadata_event_get.md) |
-| `metadata property get` | `metadata.property.get` | [metadata_property_get.md](references/metadata_property_get.md) |
 | `metadata data-table list` | `metadata.data_table.list` | [metadata_data_table_list.md](references/metadata_data_table_list.md) |
 | `metadata data-table get` | `metadata.data_table.get` | [metadata_data_table_get.md](references/metadata_data_table_get.md) |
 | `metadata data-table csv-write` | `metadata.data_table.csv_write` | [metadata_data_table_csv_write.md](references/metadata_data_table_csv_write.md) |
@@ -78,15 +74,12 @@ Same rules as `ae-analysis`: reuse verified project context in one conversation;
 
 ```bash
 ae-cli metadata --help
-ae-cli metadata event get --help
-ae-cli metadata property get --help
 ae-cli metadata data-table list --help
-ae-cli metadata event get --project-id 1 --event-name <name> --dry-run
 ae-cli metadata data-table list --project-id 1 --dry-run
 ae-cli analysis input-file purpose list --project-id 1
 ```
 
 ## Related Skills
 
-- **`ae-analysis`**: `analysis-meta event list` / `analysis-meta property list` to discover names before detail get.
+- **`ae-analysis`**: `analysis-meta event get` / `analysis-meta property get` for detail, and `analysis-meta event list` / `analysis-meta property list` to discover names.
 - **Dev workflow**: `.cursor/skills/te-cli-capability-gateway` — inspect gateway schema when adding new metadata capabilities.

package/skills/ae-metadata/references/metadata_property_dimension_table_bind_existing.md

@@ -22,6 +22,6 @@ ae-cli metadata property bind-existing-dimension-table --project-id <project_id>
 
 ## Decision Rules
 
-- Confirm the property with `metadata property get` or `analysis-meta property list`.
+- Confirm the property with `analysis-meta property get` or `analysis-meta property list`.
 - Confirm the data table with `metadata data-table get`.
 - This is an ordinary `write` command and does not require CLI confirmation.

package/skills/ae-system/SKILL.md

@@ -0,0 +1,357 @@
+---
+name: ae-system
+version: 1.0.0
+description: "AE Agent system administration CLI for root and agent administrators. Use when the user asks to manage Agent members, sandboxes, company model visibility/defaults, usage statistics, cost quotas, balance alerts, or IM channels. Must use ae-cli system commands, discover real IDs before writes, and never attempt to bypass a permission denial."
+---
+
+# ae-system
+
+Use the `system` domain for Agent system administration:
+
+```bash
+ae-cli system +<command> [options]
+```
+
+## Mandatory Rules
+
+- These commands are only for users whose Agent role is `root` or `agent_admin`.
+- The te-agent `/api/admin/**` endpoint is the final authorization boundary. A member receives a permission error (HTTP 403). Do not retry login or attempt a different endpoint after a 403.
+- Run `ae-cli auth login --host <host>` before using this domain. System administration requires a user access-token session; sandbox identity headers are not an authorization substitute.
+- `+npm-install` is the exception that must also run inside a Linux te-agent sandbox because it packages the installed Linux files. It still requires the logged-in user to be `root` or `agent_admin`.
+- Discover real IDs with a list command before any update or delete. Never guess a user, sandbox, model, quota rule, or channel ID.
+- Read and ordinary write commands run without confirmation. Commands marked `high-risk-write` require confirmation unless the user explicitly authorizes `--yes`.
+- Use `--dry-run` to inspect method, path, query, and redacted body without executing.
+- JSON inputs accept inline JSON, `@file`, or `-` for stdin. Prefer `@file` for channel credentials and other sensitive values.
+- Successful output is JSON by default. Use `--format table` only when a human-readable table is more useful.
+- After each command, check stderr and `_notice.host_compat`. If present, show the version warning and its update commands before the business result.
+
+## Command Groups
+
+### Members
+
+| Command | Risk | Purpose |
+| --- | --- | --- |
+| `+list-member-candidates` | read | List TE company users that can be added. |
+| `+list-members` | read | List Agent members in the current company. |
+| `+add-members` | write | Add one or more TE users, optionally binding a quota rule or creating sandboxes. |
+| `+set-member-status` | write | Enable or disable a member. |
+| `+set-member-role` | write | Change a non-root member between `agent_admin` and `member`. |
+| `+remove-member` | high-risk-write | Remove a non-root member. |
+
+Examples:
+
+```bash
+ae-cli system +list-members --status enabled --page 1 --page-size 20
+
+ae-cli system +add-members \
+  --members '[{"openId":"ou_x","loginName":"alice","displayName":"Alice"}]' \
+  --create-sandbox true
+
+ae-cli system +set-member-role --user-id <user-id> --role agent_admin
+```
+
+`+list-members` filters:
+
+- `--q`: login/display name search.
+- `--status`: `all | enabled | disabled`.
+- `--page`, `--page-size`: page size is 1-100.
+- `--all`: return all matches.
+- `--sort-field periodUsedAmount`, `--sort-dir asc|desc`: central usage sort.
+
+`+add-members --members` schema:
+
+```json
+[
+  {
+    "openId": "required",
+    "loginName": "optional",
+    "displayName": "optional"
+  }
+]
+```
+
+Optional flags are `--rule-id` and `--create-sandbox true|false`.
+
+### Sandboxes
+
+| Command | Risk | Purpose |
+| --- | --- | --- |
+| `+list-sandboxes` | read | List company sandboxes. |
+| `+batch-create-sandboxes` | write | Create personal sandboxes for 1-100 users. |
+| `+update-sandbox` | write | Update a sandbox description. |
+| `+set-sandbox-enabled` | write | Enable or disable a sandbox. |
+| `+start-sandbox` | write | Start a sandbox container. |
+| `+stop-sandbox` | write | Stop a sandbox container. |
+| `+list-sandbox-users` | read | List users bound to a sandbox. |
+| `+bind-sandbox-user` | write | Bind a member to a sandbox. |
+| `+unbind-sandbox-user` | high-risk-write | Remove a sandbox user binding. |
+| `+remove-sandbox` | high-risk-write | Delete a sandbox and its bindings. |
+
+Examples:
+
+```bash
+ae-cli system +batch-create-sandboxes \
+  --user-ids '["<user-id-1>","<user-id-2>"]' \
+  --description "Data team"
+
+ae-cli system +set-sandbox-enabled --id <sandbox-id> --enabled true
+ae-cli system +bind-sandbox-user --id <sandbox-id> --user-id <user-id>
+```
+
+Use Agent database user IDs from `+list-members`, not TE openIds, for sandbox commands.
+
+### Shared Sandbox Tools
+
+| Command | Risk | Purpose |
+| --- | --- | --- |
+| `+upload-sandbox-tool` | write | Validate, ZIP, and upload an existing tool directory. |
+| `+npm-install` | write | Install one exact npm CLI version in a temporary sandbox directory, generate `tool.json`, and upload it. |
+
+Uploaded tools are registered for the current company with `enabled=false`. Upload does not activate the tool in any running sandbox. Review and enable/activate it through sandbox tool management after upload.
+
+#### Preferred npm Flow
+
+Run this inside the target Linux te-agent sandbox:
+
+```bash
+ae-cli auth login --host <host>
+ae-cli system +npm-install --package eslint@9.32.0
+```
+
+For a scoped package or a custom shared-tool identifier:
+
+```bash
+ae-cli system +npm-install \
+  --package @scope/example-cli@1.2.3 \
+  --name example-cli
+```
+
+Requirements and behavior:
+
+- `--package` must be an exact registry package version. Tags, ranges, URLs, Git sources, npm aliases, and local paths are rejected.
+- The installed package must expose at least one `package.json` `bin` entry. Each bin becomes one tool command.
+- The default tool name is the unscoped package name. Use `--name` only when a different valid lowercase tool identifier is required.
+- npm lifecycle scripts are disabled with `--ignore-scripts` by default. Use `--allow-scripts true` only after reviewing and trusting the package and all transitive dependencies.
+- The command calls the admin upload-policy endpoint before starting npm. A disabled feature, expired session, or non-admin role fails before installation.
+- Installation uses a temporary prefix with development dependencies omitted. Temporary installation and ZIP files are removed whether upload succeeds or fails.
+- npm-created `node_modules/.bin` symlinks are converted to regular executable wrappers in the ZIP. All other symlinks, special files, and links resolving outside the package root are rejected.
+- Pure JavaScript Node.js CLIs are the supported baseline. Packages that require native addons, downloaded platform binaries, build tools, system libraries, or lifecycle setup may fail when scripts are disabled or when activated in a different runtime image.
+- If lifecycle scripts are necessary, install and upload from the same Linux sandbox image family that will execute the tool. Upload never makes an incompatible native artifact portable.
+
+#### Existing Directory Flow
+
+Use the low-level command when the tool is already installed or assembled:
+
+```bash
+ae-cli system +upload-sandbox-tool --path /absolute/path/to/tool-root
+```
+
+The directory root must contain exactly one `tool.json`. An external manifest is allowed only when the root has no `tool.json`:
+
+```bash
+ae-cli system +upload-sandbox-tool \
+  --path /absolute/path/to/tool-root \
+  --manifest /absolute/path/to/tool.json
+```
+
+Minimal manifest:
+
+```json
+{
+  "schemaVersion": 1,
+  "name": "example-cli",
+  "displayName": "Example CLI",
+  "description": "Optional description",
+  "version": "1.2.3",
+  "commands": [
+    {
+      "name": "example",
+      "entry": "node_modules/example-cli/bin/example.js",
+      "runtime": "node"
+    }
+  ]
+}
+```
+
+Upload contract:
+
+- `name` and command names must start with a lowercase letter and contain only lowercase letters, numbers, `.`, `_`, or `-`, with a maximum length of 64.
+- Command names must not replace reserved runtime commands such as `node`, `npm`, `npx`, `bash`, `python`, `git`, `curl`, or `sudo`.
+- Every command `entry` must be a regular file under the upload root. Use `runtime: "node"` for JavaScript entry files and `runtime: "native"` only for an executable compatible with the sandbox Linux image.
+- Paths must be relative and normalized. Absolute paths, `..`, backslashes, control characters, empty segments, and a `current` path segment are rejected.
+- ZIP limits are 50 MB compressed, 500 MB unpacked, 50 MB per file, and 10,000 files. The server publishes only after independently validating the same boundaries.
+- Do not pre-create or write `/data/app/te_agent_ta/share/tools` from a sandbox. Sandboxes are read-only for that directory; the authenticated te-agent upload endpoint owns the final write and registration.
+- A tool name can be registered only once per company in this first static-version flow. Choose the final name and version before upload.
+
+### Models
+
+| Command | Risk | Purpose |
+| --- | --- | --- |
+| `+list-system-models` | read | List system models and company visibility. |
+| `+set-system-model-enabled` | write | Toggle a system model for the current company. |
+| `+list-company-models` | read | List company models, including disabled models. |
+| `+set-company-model-enabled` | write | Toggle a company model for all company users. |
+| `+get-default-models` | read | Read the `AE_AGENT` and `AI_QA` default slots. |
+| `+set-default-model` | write | Set one default model slot. |
+| `+clear-default-model` | high-risk-write | Clear one default model slot. |
+
+Examples:
+
+```bash
+ae-cli system +list-system-models
+ae-cli system +set-system-model-enabled --model-id <model-id> --enabled false
+ae-cli system +set-default-model --model-id <model-id> --biz-type AE_AGENT
+```
+
+`--biz-type` is `AE_AGENT | AI_QA` and defaults to `AE_AGENT`. Use the database `id` returned by a model list, not the provider model name.
+
+### Usage
+
+| Command | Risk | Purpose |
+| --- | --- | --- |
+| `+get-usage-summary` | read | Get token/cost summary for a relative or absolute range. |
+| `+get-usage-details` | read | Get paginated usage grouped by user, model, date, or application type. |
+
+Examples:
+
+```bash
+ae-cli system +get-usage-summary --days 30
+
+ae-cli system +get-usage-details \
+  --start-date 2026-07-01 \
+  --end-date 2026-07-24 \
+  --group-by user \
+  --page 1 \
+  --page-size 20
+```
+
+Summary range:
+
+- Use `--days 1..365`, or provide both `--start-date` and `--end-date`.
+- Dates use `YYYY-MM-DD`.
+
+Details flags:
+
+- `--start-date` and `--end-date` are required.
+- `--group-by`: `user | model | date | app_type`.
+- Optional filters: `--search`, `--open-id`, `--model-id`, `--model-scope`, `--app-type`.
+- `--model-scope` requires `--model-id`.
+- `--sort-by`: `totalTokens | cost | share | requestCount`.
+- `--sort-dir`: `asc | desc`.
+
+### Cost Control
+
+| Command | Risk | Purpose |
+| --- | --- | --- |
+| `+get-cost-summary` | read | Get company cost, quota, and usage summary. |
+| `+get-balance-alert` | read | Get balance alert config and current status. |
+| `+set-balance-alert` | write | Enable, update, or disable the balance alert. |
+| `+list-quota-rules` | read | List cost/token quota rules. |
+| `+create-quota-rule` | write | Create a company or user quota rule. |
+| `+update-quota-rule` | write | Update a quota rule. |
+| `+remove-quota-rule` | high-risk-write | Delete a quota rule. |
+| `+bind-quota-rule-user` | write | Bind a quota rule to a TE user openId. |
+
+Examples:
+
+```bash
+ae-cli system +set-balance-alert --enabled true --threshold 100
+
+ae-cli system +create-quota-rule --rule @quota-rule.json
+ae-cli system +bind-quota-rule-user --id <rule-id> --open-id <open-id>
+```
+
+Quota rule JSON:
+
+```json
+{
+  "name": "Daily user quota",
+  "subjectType": "USER",
+  "periodType": "DAY",
+  "quotaType": "TOKEN",
+  "totalTokens": "10",
+  "allowedModels": ["<model-id>"],
+  "modelLimits": [
+    {
+      "modelId": "<model-id>",
+      "limitTokens": "5"
+    }
+  ],
+  "openIds": ["<open-id>"]
+}
+```
+
+Rules:
+
+- `subjectType`: `USER | COMPANY`.
+- `periodType`: `DAY | WEEK | MONTH`.
+- `quotaType`: `COST | TOKEN`.
+- COST uses `budgetAmount`; TOKEN uses `totalTokens`. Token values are expressed in millions.
+- `allowedModels` and `modelLimits` are optional according to the server rule type.
+- Update accepts a partial rule object.
+
+### Channels
+
+| Command | Risk | Purpose |
+| --- | --- | --- |
+| `+list-channels` | read | List Feishu, Lark, and Slack channels. |
+| `+create-channel` | write | Create one channel. |
+| `+update-channel` | write | Update channel settings, credentials, model, prompt, or enabled state. |
+| `+remove-channel` | high-risk-write | Delete a channel, unbind users, and stop its connection. |
+
+Always use `@file` for channel payloads when they contain credentials:
+
+```bash
+ae-cli system +create-channel --channel @channel.json
+ae-cli system +update-channel --id <channel-id> --channel @channel-update.json
+```
+
+Create schema:
+
+```json
+{
+  "name": "Required display name",
+  "type": "feishu",
+  "config": {
+    "appId": "Feishu/Lark",
+    "appSecret": "Feishu/Lark",
+    "botToken": "Slack",
+    "appToken": "Slack",
+    "clientId": "optional",
+    "clientSecret": "optional"
+  },
+  "model": "optional Model.id or modelId::scope",
+  "systemPrompt": "optional"
+}
+```
+
+Update accepts a partial object with `name`, `config`, `model`, `systemPrompt`, `enabled`, or `unbindUsers`. Channel type is immutable after creation. Dry-run replaces secret values with `***`.
+
+## Permission Errors
+
+A permission response looks like:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "type": "permission",
+    "message": "..."
+  }
+}
+```
+
+On this response:
+
+1. Do not retry with another admin path.
+2. Do not recommend re-login unless the server returned 401 instead.
+3. Tell the user that `root` or `agent_admin` is required.
+
+## Transport Status
+
+This is a Transitional L2 domain backed by te-agent `/api/admin/**`.
+
+- Maintainer: te-agent admin routes and `src/commands/te-system/**`.
+- Migration target: system Capability Gateway.
+- Review date: 2026-10-24.
+- Exit condition: migrate after equivalent gateway schema, auth, risk, dry-run, and output contracts are stable.