@thinkingai/ae-cli 6.1.11 → 6.1.13

package/skills/ae-engage/references/task-submit-approval.md

@@ -27,6 +27,8 @@ Provide exactly one of `--task-id` or `--request`.
 
 - Prefer `task save` followed by `submit-approval --task-id`. The server loads the persisted draft, validates its
   trigger rule, and reuses the existing save-and-submit approval workflow.
+- Never put `taskId` or `task_id` inside `--request`. Existing drafts must use `--task-id`; embedded task IDs fail
+  with `REQUEST_TASK_ID_NOT_ALLOWED` so request fields are never silently discarded.
 - Do not reconstruct or pass `trigger_rule`. It is an internal persisted field.
 - The legacy `--request` mode remains available for existing callers.
 - Required body fields (server validates): `task_name`, `channel_type`, `channel_id`, `group_content_list`, `target_cluster_type`, `trigger_type`, `completion_indicator_def`, `frequency_limits`, `enable_channel_touch_limits`, `group_id`, `trigger_time_strategy`.
@@ -41,5 +43,6 @@ Provide exactly one of `--task-id` or `--request`.
 |---|---|
 | `APPROVAL_INPUT_INVALID` | neither or both of `task_id` and `request` supplied |
 | `REQUEST_REQUIRED` | `--request` missing or not an object |
+| `REQUEST_TASK_ID_NOT_ALLOWED` | `request.taskId` or `request.task_id` supplied; use `--task-id` |
 | `REQUEST_FIELDS_REQUIRED` | required body fields absent/blank |
 | `CAPABILITY_EXECUTION_FAILED` | unmapped domain failure; check `invocation_id` / Hermes logs |

package/skills/ae-experiment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-experiment
-version: 1.0.0
+version: 1.0.1
 description: "Use when managing Atlas AB experiments, traffic layers, Features, metrics, buckets, and experiment reports through ae-cli"
 ---
 
@@ -14,6 +14,7 @@ AE CLI (`ae-cli`) exposes Atlas AB Experiment capabilities through the `experime
 - Use `--project-id` / `-p` for project-scoped commands.
 - Use `--req` JSON for complex save, status, and delete DTOs.
 - Do not invent experiment IDs, traffic layer IDs, bucket IDs, Feature keys, metric IDs, or payload field names.
+- Bind only metric IDs returned by `experiment metric list`; create and verify a missing metric before saving the experiment.
 - Read commands can run directly after IDs are verified.
 - Write commands require explicit user intent and normally keep the confirmation prompt. Use `--dry-run` before write calls when composing JSON.
 
@@ -22,6 +23,12 @@ Naming and response boundary:
 - CLI command segments and flags use kebab-case.
 - Outer Capability input and all response keys use snake_case.
 - Nested business DTOs passed through `--req` keep their native camelCase fields.
+- **CRITICAL:** `save build-guide` / `save validate` responses recursively snake_case
+  `example_args.req`. Never copy those keys into `--req`. Use camelCase
+  (`expName`, `metricId`, …). Authoritative names:
+  `ae-cli capability inspect experiment.experiment.save` (or the matching final save id)
+  → `input_schema.properties.req`. `save validate` `valid: true` is **not** a final-save
+  schema pass — snake_case `req` can still fail on `experiment … save`.
 - Audience QP is semantic at the CLI boundary: write `targeting.definitionRequest`; read
   `targeting.definition_request`. Never generate or submit `targetConfig`.
 - Metric QP is semantic at the CLI boundary: write `metricDefinition`; read
@@ -52,7 +59,9 @@ Naming and response boundary:
 4. Check readiness with `experiment experiment ready-check`.
 5. For a non-mutex traffic layer, run `experiment experiment conflict-check` before submit (needs `feature_key_list` from context or `experiment get`).
 6. Move status with `experiment experiment manage`.
-7. Query reports with summary, sample-size, and metric-trend commands.
+7. Query reports with `experiment report summary`, `experiment report sample-size`, and `experiment report metric-trend`.
+
+If an experiment save returns `error_code: METRIC_NOT_FOUND`, list metrics for the same project. Create and verify the metric before retrying; never retry with another invented ID. Metric deletion returns `error_code: METRIC_IN_USE` while an active experiment binding exists.
 
 ## Parameter Conventions
 
@@ -62,7 +71,7 @@ Naming and response boundary:
 ae-cli experiment experiment get --project-id 1 --exp-id exp_123
 ae-cli experiment experiment save --project-id 1 --req '{"expName":"Demo"}' --dry-run
 ae-cli experiment metric save --project-id 1 --req '{"metricId":"login_users","metricName":"Login users","createType":"event","goalDirection":"up","metricDesc":"Users who logged in","metricDefinition":{"type":"event","event":"login","aggregation":"user_count"}}' --dry-run
-ae-cli capability run experiment.report.metric-trend --input '{"project_id":1,"exp_id":"exp_123","metric_id":"metric_1","start_time":"2026-07-01","end_time":"2026-07-07"}'
+ae-cli experiment report metric-trend --project-id 1 --exp-id exp_123 --metric-id metric_1 --start-time 2026-07-01 --end-time 2026-07-07
 ```
 
 Optional global parameters work as in other domains: `--host`, `--mcp-url`, `--format`, `--jq`, `--dry-run`, and `--yes`.
@@ -77,6 +86,10 @@ Open the matching file in `references/` before using a command, especially for w
 
 When a save command returns `next_tool: experiment.save.build-guide`, call the guide first, then `experiment save validate`, then retry the final save capability.
 
+Read [`save_build_guide.md`](references/save_build_guide.md) and
+[`save_validate.md`](references/save_validate.md) before using these helpers. Rebuild
+`--req` in camelCase from `inspect` / skill references; do not paste `example_args.req`.
+
 ### Experiment
 
 `experiment experiment save`, `capability run experiment.experiment.save-submit`, `experiment experiment list`, `experiment experiment list-archived`, `experiment experiment get`, `experiment experiment ready-check`, `experiment experiment conflict-check`, `experiment experiment manage`, `experiment experiment update-group`, `experiment experiment batch-delete`, `experiment operation-log query`
@@ -87,7 +100,7 @@ When a save command returns `next_tool: experiment.save.build-guide`, call the g
 
 ### Reports
 
-`capability run experiment.report.summary`, `capability run experiment.report.sample-size`, `capability run experiment.report.metric-trend`, `capability run experiment.query.cancel`
+`experiment report summary`, `experiment report sample-size`, `experiment report metric-trend`, `capability run experiment.query.cancel`
 
 ### Metric and Feature
 

package/skills/ae-experiment/references/delete_metric.md

@@ -9,3 +9,5 @@ ae-cli experiment metric delete --project-id <id> --metric-id <metricId> [--yes]
 Flags:
 - `--project-id`, `-p`: Project ID.
 - `--metric-id`: Metric ID.
+
+Deletion is rejected with `error_code: METRIC_IN_USE` while the metric has an active experiment binding. Remove the metric from the related experiment before retrying.

package/skills/ae-experiment/references/query_experiment_metric_trend.md

@@ -1,12 +1,12 @@
-# capability run experiment.report.metric-trend
+# experiment report metric-trend
 
 Query experiment metric trend report.
 
 ```bash
-ae-cli capability run experiment.report.metric-trend --input '{"project_id":1,"exp_id":"exp_123","metric_id":"metric_1","start_time":"2026-07-01","end_time":"2026-07-07"}'
+ae-cli experiment report metric-trend --project-id 1 --exp-id exp_123 --metric-id metric_1 --start-time 2026-07-01 --end-time 2026-07-07
 ```
 
-Required input: `project_id`, `exp_id`, `metric_id`, `start_time`, `end_time`.
-Optional input: `request_id`, `force_refresh`.
+Required flags: `--project-id`, `--exp-id`, `--metric-id`, `--start-time`, `--end-time`.
+Optional: `--request-id`, `--force-refresh`.
 
-Response shape: `data.report`, with recursively snake_case keys. Preserve `request_id` for cancellation.
+Response shape: `data.report`, with recursively snake_case keys. Preserve `request_id` for cancellation via `capability run experiment.query.cancel`.

package/skills/ae-experiment/references/query_experiment_report_summary.md

@@ -1,11 +1,12 @@
-# capability run experiment.report.summary
+# experiment report summary
 
 Query experiment report summary.
 
 ```bash
-ae-cli capability run experiment.report.summary --input '{"project_id":1,"exp_id":"exp_123","force_refresh":false}'
+ae-cli experiment report summary --project-id 1 --exp-id exp_123
+ae-cli experiment report summary --project-id 1 --exp-id exp_123 --force-refresh true
 ```
 
-Required input: `project_id`, `exp_id`. Optional input: `force_refresh`.
+Required flags: `--project-id`, `--exp-id`. Optional: `--force-refresh`.
 
 Response shape: `data.report`, with recursively snake_case keys.

package/skills/ae-experiment/references/query_experiment_sample_size_report.md

@@ -1,12 +1,13 @@
-# capability run experiment.report.sample-size
+# experiment report sample-size
 
 Query experiment sample-size report.
 
 ```bash
-ae-cli capability run experiment.report.sample-size --input '{"project_id":1,"exp_id":"exp_123","start_time":"2026-07-01","end_time":"2026-07-07","by_hour":false}'
+ae-cli experiment report sample-size --project-id 1 --exp-id exp_123 --start-time 2026-07-01 --end-time 2026-07-07
+ae-cli experiment report sample-size --project-id 1 --exp-id exp_123 --start-time 2026-07-01 --end-time 2026-07-07 --by-hour true
 ```
 
-Required input: `project_id`, `exp_id`, `start_time`, `end_time`.
-Optional input: `request_id`, `force_refresh`, `by_hour`.
+Required flags: `--project-id`, `--exp-id`, `--start-time`, `--end-time`.
+Optional: `--request-id`, `--force-refresh`, `--by-hour`.
 
-Response shape: `data.report`, with recursively snake_case keys. Preserve `request_id` for cancellation.
+Response shape: `data.report`, with recursively snake_case keys. Preserve `request_id` for cancellation via `capability run experiment.query.cancel`.

package/skills/ae-experiment/references/save_build_guide.md

@@ -0,0 +1,39 @@
+# experiment save build-guide
+
+Build a read-only save guide for feature, traffic layer, experiment, or metric saves.
+
+```bash
+ae-cli experiment save build-guide --project-id <id> --operation-mode save_experiment
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--operation-mode`: `save_feature`, `save_traffic_layer`, `save_experiment`, or `save_metric`.
+
+## CRITICAL — do not copy `example_args.req` keys verbatim
+
+Guide responses are recursively snake_cased for display. That wrongly rewrites nested DTO
+placeholders inside `data.guide.example_args.req` (for example `expName` → `exp_name`,
+`metricId` → `metric_id`).
+
+Those snake_case keys are **not** valid `--req` fields for the final save commands.
+
+Authoritative field names:
+
+| Mode | Inspect / final save | Nested `--req` style |
+| --- | --- | --- |
+| `save_experiment` | `experiment.experiment.save` | camelCase (`expName`, `trafficLayerId`, …) |
+| `save_metric` | `experiment.metric.save` | camelCase (`metricId`, `metricDefinition`, …) |
+| `save_feature` | `experiment.feature.save` | camelCase (`featureKey`, `targetPlatform`, …) |
+| `save_traffic_layer` | `experiment.traffic-layer.save` | camelCase (`bucketId`, `layerName`, …) |
+
+Before composing `--req`:
+
+1. Read `data.guide.required_fields` / `mode_rules` for **what** is required (names there may
+   already be camelCase).
+2. Treat `example_args.req` as structure-only placeholders; **rename keys to camelCase**.
+3. Prefer `ae-cli capability inspect <final-save-capability-id>` `input_schema.properties.req`
+   when unsure.
+4. Then run `experiment save validate` and the final `experiment … save`.
+
+Response shape: `data.guide`.

package/skills/ae-experiment/references/save_experiment.md

@@ -16,6 +16,12 @@ Flags:
 - Capability input uses outer `project_id`; nested `req` fields remain native camelCase. Hermes overwrites `req.projectId` with the outer project ID.
 - Never call this with `req=null`, `req={}`, or a modify payload containing only `expId`; those are terminal validation failures.
 - On `valid=false`, do not retry the same payload. Fix the reported field(s) or ask the user for missing input.
+- **Do not** paste `save build-guide` / `save validate` `example_args.req` keys into `--req`.
+  Those responses snake_case nested placeholders (`exp_name`). Final save requires camelCase
+  (`expName`, `expSupposition`, `trafficLayerId`, `featureKeyList`, `metrics[].metricId`, …).
+  If unsure, run `ae-cli capability inspect experiment.experiment.save` and copy
+  `input_schema.properties.req` field names. `save validate` may return `valid: true` for
+  snake_case `req` and still fail here with `unknown field …`.
 
 Response shape is `data.result`. Object keys inside the result are recursively snake_case. A create commonly returns the new experiment ID as `data.result`; a patch commonly returns `true`.
 
@@ -36,6 +42,7 @@ Nested payload fields must match the server DTO types, not just the visible CLI
 - `groups[].allocation` rule: each value must be an **integer**, and the **sum of all group allocations must equal `100` exactly** (for example `34 + 33 + 33 = 100`, not `33 + 33 + 33 = 99` and not decimal thirds).
 - `groups[].expGroupValue` is a JSON-encoded string of a string array. Pass a string whose content is a JSON array, not a native JSON array.
 - `metrics` is an array of metric binding objects. Each object contains `metricId` and `metricRole`.
+- Every `metricId` must come from `experiment metric list` for the same project. If save returns `error_code: METRIC_NOT_FOUND`, create the metric with `experiment metric save`, verify it, and then retry the experiment save.
 
 ## Modes
 
@@ -103,6 +110,10 @@ ae-cli experiment experiment save --project-id 1 --req '{"expId":"exp_123","allo
   `targeting.definitionRequest`. Do not submit the internal `targeting.targetConfig`
   JSON or any `Cxx`/`Axxx` code. Resolve event and property names with Analysis
   metadata first.
+- Avoid redundant adjacent `compound` groups with the same `relation`. Hermes
+  safely flattens those groups when an Atlas experiment is saved or submitted so
+  the generated cluster QP stays within the backend layer limit. Different
+  relations are always preserved.
 
 Semantic audience example:
 

package/skills/ae-experiment/references/save_metric.md

@@ -8,10 +8,14 @@ ae-cli experiment metric save --project-id <id> --req '<json>'
 
 Flags:
 - `--project-id`, `-p`: Project ID.
-- `--req`: Metric save request JSON object.
+- `--req`: Metric save request JSON object (**camelCase** keys such as `metricId`, `metricDefinition`).
 
 Create mode requires metric identifiers and metric configuration. Modify mode uses `update=true`.
 
+Do not paste `save build-guide` / `save validate` `example_args.req` keys (`metric_id`, …) into
+`--req`. Those responses snake_case nested placeholders; final save requires camelCase.
+See [`save_build_guide.md`](save_build_guide.md) / [`save_validate.md`](save_validate.md).
+
 ## Semantic Metric Contract
 
 - Supply metric QP as `req.metricDefinition`.

package/skills/ae-experiment/references/save_validate.md

@@ -0,0 +1,33 @@
+# experiment save validate
+
+Dry-run helper for save payloads. Does **not** persist data.
+
+```bash
+ae-cli experiment save validate --project-id <id> --operation-mode save_experiment --req '{"expName":"Demo"}'
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--operation-mode`: `save_feature`, `save_traffic_layer`, `save_experiment`, or `save_metric`.
+- `--req`: Candidate save request object. **Must use native camelCase DTO keys.**
+
+## CRITICAL — `valid: true` is not a save schema pass
+
+`experiment.save.validate` checks operation-mode / outer helper contract. It does **not**
+fully enforce the final save capability `input_schema`.
+
+Consequences:
+
+- `--req '{"exp_name":"Demo"}'` can return `valid: true`.
+- The same payload fails on `experiment experiment save` with `unknown field exp_name`.
+
+Rules:
+
+1. Never submit snake_case DTO keys in `--req` (`exp_name`, `metric_id`, `feature_key`, …).
+2. Do not trust `data.validation.example_args.req` key casing; rebuild with camelCase.
+3. After `valid: true`, still use camelCase and prefer
+   `ae-cli … save --dry-run` / `capability inspect` before a real write.
+4. On final save `INVALID_CAPABILITY_INPUT` / `unknown field`, fix casing — do not widen
+   the payload with more snake_case keys.
+
+Response shape: `data.validation`.

package/skills/ae-experiment-design/SKILL.md

@@ -9,7 +9,7 @@ Turn a business objective into an evidence-backed experiment design, an implemen
 
 ## Hard boundaries
 
-- Use `ae-cli` for every AE/TE platform interaction. Do not substitute raw HTTP, browser automation, direct database queries, MCP tools, or application SDKs.
+- Use `ae-cli` for every AE/TE platform interaction. Do not substitute raw HTTP, browser automation, direct database queries, or application SDKs.
 - Do not infer an SDK request from the fact that an experiment needs implementation. Load SDK references only when the user explicitly asks about an A/B experiment SDK or client SDK integration.
 - Do not copy general tracking SDK documentation into this Skill. Route generic initialization, event reporting, `track`, user identity, user properties, data upload, LogBus, and REST questions to `ae-data-integration-helper` when that Skill is available.
 - Use only the event-metric calculation contracts defined in

package/skills/ae-experiment-design/references/platform-operations.md

@@ -4,12 +4,12 @@ Read this reference before any AE/TE platform interaction.
 
 ## Hard boundary
 
-All platform operations must use `ae-cli`. Do not call raw APIs, use browser automation, query a database, invoke te-mcp, or fabricate a platform result.
+Use `ae-cli` for all platform operations. Do not call raw APIs, use browser automation, query a database, or fabricate a platform result.
 
 Use curated commands when their contract is known. Use the Capability Gateway for experiment capabilities that do not yet have a curated command:
 
 ```bash
-ae-cli capability search "<terms>" [--project-id <id>]
+ae-cli capability search "<terms>" --domain <domain> [--project-id <id>]
 ae-cli capability inspect <capability-id> --project-id <id>
 ae-cli capability validate <capability-id> --input '<json-object>'
 ae-cli capability dry-run <capability-id> --input '<json-object>'
@@ -30,10 +30,16 @@ After every `ae-cli` invocation, inspect stderr and `_notice.host_compat`. If a
 
 ## Project gate
 
-Resolve an unverified project through:
+When the user supplies a project ID, resolve it directly:
 
 ```bash
-ae-cli analysis project info list --query "<project name>" --fields '["project_id","project_name"]' --limit 20 --offset 0
+ae-cli project info get --project-id <id>
+```
+
+When the user supplies only a project name, search and disambiguate:
+
+```bash
+ae-cli project info list --query "<project name>" --fields '["project_id","project_name"]' --limit 20 --offset 0
 ```
 
 Reuse a project only when its ID and host were verified in the same continuous conversation. If multiple projects match, stop and ask the user to choose.

package/skills/ae-experiment-insight/references/platform-operations.md

@@ -4,12 +4,12 @@ Read this reference before retrieving any AE/TE experiment evidence.
 
 ## Hard boundary
 
-All platform discovery and reads must use `ae-cli`. Do not call raw APIs, use browser automation, query a database, invoke te-mcp, or invent report values.
+Use `ae-cli` for all platform discovery and reads. Do not call raw APIs, use browser automation, query a database, or invent report values.
 
 Use the Capability Gateway when no curated experiment command exists:
 
 ```bash
-ae-cli capability search "<terms>" [--project-id <id>]
+ae-cli capability search "<terms>" --domain <domain> [--project-id <id>]
 ae-cli capability inspect <capability-id> --project-id <id>
 ae-cli capability run <capability-id> --input '<json-object>'
 ```
@@ -22,10 +22,16 @@ After every `ae-cli` invocation, inspect stderr and `_notice.host_compat`. If pr
 
 ## Resolution gates
 
-Resolve the project first:
+When the user supplies a project ID, resolve it directly:
 
 ```bash
-ae-cli analysis project info list --query "<project name>" --fields '["project_id","project_name"]' --limit 20 --offset 0
+ae-cli project info get --project-id <id>
+```
+
+When the user supplies only a project name, search and disambiguate:
+
+```bash
+ae-cli project info list --query "<project name>" --fields '["project_id","project_name"]' --limit 20 --offset 0
 ```
 
 Then discover experiment list/get capabilities and resolve the exact experiment by verified ID or exact-match name. If multiple candidates remain, ask the user.

package/skills/ae-metadata/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-metadata
-version: 1.0.0
+version: 1.0.1
 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."
 ---
 
@@ -30,6 +30,7 @@ Safety:
 - 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 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`.
+- `metadata data-table download` is an async artifact command: plain invocation submits, `--wait` waits, and `--output <file>` waits then streams atomically. Resume with `analysis run wait`; local interruption never cancels the remote run.
 
 ## When to Use
 

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

@@ -5,6 +5,7 @@
 ```bash
 ae-cli metadata data-table download --project-id <project_id> --data-table-id <id>
 ae-cli metadata data-table download --project-id <project_id> --data-table-id <id> --request-id cli_0123456789abcdef0123456789abcdef --timeout-seconds 120
+ae-cli metadata data-table download --project-id <project_id> --data-table-id <id> --output <file>
 ```
 
 | Parameter | Required | Description |
@@ -12,6 +13,13 @@ ae-cli metadata data-table download --project-id <project_id> --data-table-id <i
 | `--project-id` / `-p` | Yes | Numeric project ID. |
 | `--data-table-id` | Yes | Data table ID. |
 | `--request-id` | No | Optional `cli_<32 lowercase hex>` request ID. |
-| `--timeout-seconds` | No | Timeout in seconds, 1 to 7200. |
+| `--timeout-seconds` | No | Remote runtime in seconds, 1 to 21600. |
+| `--wait` | No | Wait for run `SUCCEEDED` and artifact `COMPLETED`. |
+| `--output` | No | Wait, then stream and atomically publish the artifact to this file. |
+| `--force` | No | Replace an existing `--output` file atomically; invalid without `--output`. |
 
-Use this command when the user needs an exported data-table artifact.
+Use this command when the user needs an exported data-table artifact. Plain
+invocation submits only. `--output` implies `--wait`; resume an interrupted
+wait with `ae-cli analysis run wait --run-id <run_id> [--output <file>]`.
+Local interruption never cancels the remote run. Do not use this command for
+inline data-table metadata; use `metadata data-table get` instead.

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

@@ -5,7 +5,7 @@
 ## Command
 
 ```bash
-ae-cli metadata data-table list --project-id <project_id>
+ae-cli metadata data-table list --project-id <project_id> --limit 50 --offset 0
 ae-cli metadata data-table list --project-id <project_id> --dry-run
 ```
 
@@ -14,14 +14,17 @@ ae-cli metadata data-table list --project-id <project_id> --dry-run
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--limit` / `-l` | No | Page size. Default: 50, maximum: 200. |
+| `--offset` / `-o` | No | Zero-based page offset. Default: 0. |
 
 ## Request Body
 
 ```json
-{ "project_id": 1 }
+{ "project_id": 1, "limit": 50, "offset": 0 }
 ```
 
 ## Decision Rules
 
 - Use this command to discover `data_table_id` before get, delete, download, or property binding.
 - If the list is empty, do not invent IDs; create/upload a table first or ask for the target table.
+- Read rows from `data.items`; pagination metadata is always `total`, `limit`, `offset`, `has_more`, and `next_offset`.

package/skills/ae-system/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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."
+version: 1.1.0
+description: "AE Agent system administration CLI for root and agent administrators. Use when the user asks to manage Agent members, sandboxes and shared tools, company model visibility/defaults/pricing, usage statistics and exports, 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
@@ -19,11 +19,13 @@ ae-cli system +<command> [options]
 - 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`.
+- Before every write, run `--dry-run`, show the target and effect, and obtain explicit user confirmation. The CLI itself prompts only for `high-risk-write`; `--yes` can bypass that prompt and is not a security boundary.
 - 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.
+- Do not treat an absent ae-cli command as proof that an HTTP endpoint is unreachable. An Agent with Bash/network access can construct requests directly; server authentication, role checks, company isolation, and resource ownership are the actual controls.
+- Do not call `DELETE /api/admin/members?openId=...` or `/api/internal/sandboxes/**` through ad-hoc HTTP. They are intentionally excluded from this Skill because other systems own those integration contracts.
 
 ## Command Groups
 
@@ -37,6 +39,7 @@ ae-cli system +<command> [options]
 | `+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. |
+| `+get-member-stats` | read | Get one member's token usage and recent conversation count. |
 
 Examples:
 
@@ -77,6 +80,7 @@ Optional flags are `--rule-id` and `--create-sandbox true|false`.
 | Command | Risk | Purpose |
 | --- | --- | --- |
 | `+list-sandboxes` | read | List company sandboxes. |
+| `+get-sandbox-config` | read | Read feature status and create/active seat limits. |
 | `+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. |
@@ -106,9 +110,33 @@ Use Agent database user IDs from `+list-members`, not TE openIds, for sandbox co
 | --- | --- | --- |
 | `+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. |
+| `+list-sandbox-tools` | read | List preset and custom tools for the current company. |
+| `+sync-sandbox-tools` | write | Synchronize preset tools from the server manifest. |
+| `+get-sandbox-tool-distribution` | read | Read the sandboxes currently receiving one tool. |
+| `+set-sandbox-tool-enabled` | write | Enable or disable one registered tool. |
+| `+remove-sandbox-tool` | high-risk-write | Delete a fully reclaimed tool registration. |
+| `+activate-sandbox-tools` | write | Activate selected commands on selected or all running sandboxes. |
+| `+deactivate-sandbox-tools` | write | Remove managed command shims from selected or all running sandboxes. |
+| `+refresh-sandbox-tool-status` | write | Refresh observed tool state on target sandboxes. |
+| `+list-sandbox-tool-operations` | read | List activation/deactivation history. |
 
 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.
 
+For activate/deactivate/status operations:
+
+```bash
+ae-cli system +activate-sandbox-tools \
+  --target-mode selected \
+  --sandbox-ids '["<sandbox-id>"]' \
+  --tool-ids '["<tool-id>"]'
+```
+
+- `--target-mode selected` requires 1-50 `--sandbox-ids`; `all-running` forbids them.
+- `--tool-ids` contains 1-20 real IDs from `+list-sandbox-tools`.
+- `--command-names-by-tool-id` optionally limits an operation to named commands.
+- `--expected-tool-snapshots-by-id` carries the version/package/command snapshot returned by the server for optimistic concurrency checks.
+- JSON maps accept inline JSON, `@file`, or stdin. Use dry-run and user confirmation before distribution changes.
+
 #### Preferred npm Flow
 
 Run this inside the target Linux te-agent sandbox:
@@ -189,6 +217,9 @@ Upload contract:
 | --- | --- | --- |
 | `+list-system-models` | read | List system models and company visibility. |
 | `+set-system-model-enabled` | write | Toggle a system model for the current company. |
+| `+get-model-sync-settings` | read | Read the default visibility policy for newly synchronized system models. |
+| `+set-model-sync-settings` | write | Update the new-system-model visibility policy. |
+| `+get-system-model-price-rules` | read | Read one managed system model's stored pricing snapshot. |
 | `+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. |
@@ -211,11 +242,16 @@ ae-cli system +set-default-model --model-id <model-id> --biz-type AE_AGENT
 | --- | --- | --- |
 | `+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. |
+| `+get-agent-tool-calls` | read | Get Agent tool-call count for a range, optionally refreshing the cache. |
+| `+get-usage-combinations` | read | Drill one parent group into the remaining dimensions. |
+| `+export-usage` | read | Stream filtered one-dimension usage groups to CSV. |
+| `+export-usage-details` | read | Stream full or drill-down multi-dimension details to CSV. |
 
 Examples:
 
 ```bash
 ae-cli system +get-usage-summary --days 30
+ae-cli system +get-usage-summary --days 30 --refresh true
 
 ae-cli system +get-usage-details \
   --start-date 2026-07-01 \
@@ -223,12 +259,26 @@ ae-cli system +get-usage-details \
   --group-by user \
   --page 1 \
   --page-size 20
+
+ae-cli system +get-usage-combinations \
+  --start-date 2026-07-01 \
+  --end-date 2026-07-24 \
+  --parent-dimension user \
+  --open-id <open-id>
+
+ae-cli system +export-usage \
+  --start-date 2026-07-01 \
+  --end-date 2026-07-24 \
+  --group-by user \
+  --output ./system-usage.csv
 ```
 
 Summary range:
 
 - Use `--days 1..365`, or provide both `--start-date` and `--end-date`.
 - Dates use `YYYY-MM-DD`.
+- Do not combine `--days` with an absolute date pair.
+- `--refresh true` is available on `+get-usage-summary` and `+get-agent-tool-calls` and bypasses the overview cache.
 
 Details flags:
 
@@ -239,11 +289,22 @@ Details flags:
 - `--sort-by`: `totalTokens | cost | share | requestCount`.
 - `--sort-dir`: `asc | desc`.
 
+Combination drill-down requires exactly one parent selector:
+
+- `user` → `--open-id` only.
+- `model` → `--model-id` and `--model-scope` only.
+- `app_type` → `--app-type` only.
+- `date` → `--date` only, inside the selected range.
+
+CSV exports require an explicit `--output`. The target is created exclusively: an existing file is never overwritten, and an HTTP or stream failure removes the incomplete file. The JSON result reports the absolute local path, bytes written, server filename, and content type.
+
 ### Cost Control
 
 | Command | Risk | Purpose |
 | --- | --- | --- |
 | `+get-cost-summary` | read | Get company cost, quota, and usage summary. |
+| `+get-balance` | read | Get the current model account balance and currency. |
+| `+list-over-limit-users` | read | List members over cost or token quota limits. |
 | `+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. |
@@ -347,6 +408,8 @@ On this response:
 2. Do not recommend re-login unless the server returned 401 instead.
 3. Tell the user that `root` or `agent_admin` is required.
 
+An authenticated `root` or `agent_admin` is still scoped to their own company. The current service checks the database role and company against the session, and audited member, channel, sandbox-tool, and sandbox-management routes apply company/resource ownership checks. Never use that statement as a claim that every unreviewed admin route is safe.
+
 ## Transport Status
 
 This is a Transitional L2 domain backed by te-agent `/api/admin/**`.