@thinkingai/ae-cli 6.0.54 → 6.0.56

package/skills/ae-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-analysis
-version: 4.2.31
+version: 4.2.42
 description: "Use ae-cli for AE 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 discovery, project configuration, tracking plans, local input-file upload, 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, inspect/create/update/govern analysis assets, recommend project assets for certification/authentication, review asset-certification recommendations, review metric recommendations, or build/update/refresh/sync a project semantic knowledge base from a governed asset package."
 ---
 
@@ -39,7 +39,13 @@ For data queries:
 3. Correct compiler errors at their reported paths. New evidence or a user correction changes a completed choice; preserve the other verified inputs.
 4. Use the returned result directly. Save original JSON only when the user requests a file or necessary local processing requires one; follow [result handling](references/analysis_data_retrieval.md#preserve-and-interpret-results). Keep stderr and the CLI exit status visible.
 5. Compute only missing values needed by the request, together in one local call. Reuse completed results and answer when the requested data is available, or explain the specific error or missing input.
-6. Only after a completed analysis data query and the final business analysis answer, ask once in the user's language whether the analysis met expectations: satisfied, partially satisfied, dissatisfied, or unable to judge. Do not ask after individual CLI calls, intermediate steps, discovery, metadata inspection, asset governance/writes, configuration, help, unrelated questions, query submission, running exports or failed queries. No explicit feedback means no submission or new feedback event. On a clear evaluation of the completed analysis, use [analysis query feedback](references/feedback_submit.md); preserve the evaluated session and turn IDs, the user's original feedback and a short verifiable route summary. Do not upload the analysis answer or infer a rating from silence, a follow-up question or a new requirement. Feedback collection must not block subsequent business work.
+6. Scenario collection is project opt-in. Before preparing or uploading a scenario sample, read `ae-cli project info get --project-id <source_project_id>` for the current host, authenticated account, and source analysis project. Only `data.analysis_scenario_collection_enabled === true` permits collection. Recheck for each new scenario and before appending feedback or a revision; do not reuse a previous grant or the company configuration's 24-hour cache. A missing field (including older services), false, unreadable configuration, or unknown project means skip collection and answer normally. Never enable the project switch, choose a different project, or invent a project ID to make collection succeed. The curated collect/append commands also check immediately before submission, and the service is authoritative if the switch changes. This controls only scenario samples; existing invocation and intent logs stay unchanged. `accepted=false, skipped=true` is a normal skip, not a failed analysis or successful upload. Do not retry, backfill, or fall back to `analysis feedback submit` to bypass this switch.
+
+   Collect one sample for the whole user scenario, not one per CLI call. After forming the final answer, use `ae-cli analysis scenario collect` as specified in [scenario collection](references/scenario_collect.md), then deliver that exact answer text. Capture the original question/confirmed clarifications, actual final answer and the ordered query path (existing capability/call IDs and optional short purpose; prefer only meta.invocation_id, never confuse a business request_id with gateway client_request_id), never query result rows or error payloads; do not score correctness or generate a separate self-evaluation. The question_id is the original scenario's first user turn ID, stable across clarification, retries, multiple queries and corrections. Store/reuse the IDs returned by collection in conversation context. On later user objections, scope corrections or reported omissions targeting that answer, append the user's original text with `ae-cli analysis scenario append --entry-type user_feedback` and the original question_id/target_answer_id; do not decide whether the user is right. An ambiguous request for an explanation may be preserved as user text when clearly linked; do not invent a link. A normal follow-up or changed requirement is not automatically negative feedback. After a substantive follow-up answer to the same scenario (recheck, explanation, correction or scope clarification), append answer_revision with that exact answer/query path and a new answer_id, even when the conclusion stays the same; keep earlier answers. If the triggering user request was not already captured as user_feedback, include its exact text using --user-message on answer_revision so later scope changes are not lost. Do not duplicate feedback text in user_message. Acknowledgments such as thanks alone need no entry. A genuinely separate question gets a new question_id. Do not create another initial sample for an existing scenario. A separate evaluation task reads these samples later and can join existing call telemetry for parameters/status/timing. Path-only evidence cannot prove numeric answer correctness; unresolved correctness stays unknown. Only attempted analysis data queries qualify; metadata, discovery, help and asset writes alone do not. No routine satisfaction question. Collection failure must not block the answer or subsequent business work, trigger login or automatic retries, or be claimed as successful ingestion. For external Agents this is a Skill collection step, not a guaranteed post-answer hook; it has one collection tool call but no additional evaluation task on the answering path.
+
+User feedback is evidence, not a correctness label. Preserve exact user words and their target answer even if you disagree. Do not routinely ask for a satisfaction rating. The existing `analysis feedback submit` contract remains available for explicit standalone user ratings without a collected scenario; when a scenario exists, use its append command instead of submitting duplicate feedback. No explicit feedback means no submission or new feedback event for `cli_analysis_feedback`. Do not upload the analysis answer through that legacy feedback command. All collection excludes credentials, full transcripts and private reasoning.
+
+
 
 ## Route before reading
 
@@ -50,9 +56,10 @@ For data queries:
    - 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`
+   - Project member groups (Project management → Member management → Member groups): use `project member-group list|members|create|rename|delete|add-members|remove-members` and the matching `references/project_member_group_<action>.md` (replace action hyphens with underscores). This manages project member groups, distinct from AgentSpace/system membership and analysis user-cluster/user-tag audiences.
    - Readable saved report/dashboard discovery -> `analysis asset search` and `references/asset_search.md`; this includes shared read-only assets.
    - `analysis dashboard list` -> `references/dashboard_list.md`
-   - Saved event-report chart/result-table layout -> `references/report_get.md` and the matching `report_create.md` or `report_update.md`. A table card on a specific analysis board -> `dashboard-report get/update` and `references/dashboard_report_get.md` / `references/dashboard_report_update.md`; the card display is separate from its source report definition.
+   - Saved event-report chart/result-table layout -> `references/report_get.md` and the matching `report_create.md` or `report_update.md`. A table card, card frame size, or grid position on a specific analysis board -> `dashboard-report get/update` and `references/dashboard_report_get.md` / `references/dashboard_report_update.md`; the card display is separate from its source report definition. Geometry writes need the fresh dashboard layout version; event chart/table settings remain event-only.
    - Event combination chart or per-metric bar/line and primary/secondary axes -> also read `references/event_report_presentation.md`. Series is source-report scoped and can affect its other trend cards; card display updates cannot create a local series override.
    - `personal-semantic-preference list` -> `references/personal_semantic_preference_list.md`
    - Asset center cross-source configuration (资产中心 / 跨源资产配置 / Excel 配置表导入): L3 discovery via `capability search "cross_source_config" --domain metadata --project-id <id>`; read [`references/cross_source_config.md`](references/cross_source_config.md) for workbook upload and validation. No dedicated business commands.
@@ -134,6 +141,8 @@ ae-cli capability search|inspect|validate|dry-run|run [options]
 - Execute a fully specified read or ordinary write directly. Do not routinely stack inspect, validate, dry-run, and run. Inspect the selected model contract once when a concrete schema mismatch requires it; reuse that inspected contract within the unchanged conversation scope. This is local evidence reuse, not a claim that the CLI caches contracts.
 - JSON is the default machine-readable output. On failure, preserve the structured error and non-zero exit.
 - `CREDENTIAL_STORE_UNREADABLE` (`error.type: config`) is a local credential read/decryption failure. Preserve the files and retry in the original OS user/runtime with machine-identifier access; do not automatically log in, replace tokens, or log out. It does not establish server-side token expiration.
+- Inject credentials into the current CLI invocation through environment variables or a specified file without changing stored machine accounts; automation scripts, CI/CD, and shared Agents are example use cases. Use `AE_CLI_TOKEN` plus required `AE_CLI_TOKEN_HOST`, `AE_CLI_TOKEN_FILE`, or global `--cli-token-file <path>` using `{"url":"https://host.example.com","token":"cli_..."}`. Precedence is explicit file > environment token > environment file > existing credentials. The bound host is the default; an explicit `--host` must match. Invalid selected sources return `EXTERNAL_CLI_TOKEN_INVALID` without identity fallback. Do not print or persist supplied tokens, or manage machine accounts while external mode is active (`EXTERNAL_CLI_TOKEN_ACTIVE`). Use `auth status` to inspect the selected source and identity.
+- The member's natural-day quota counts each Gateway capability `execute` call eligible for usage statistics (an identifiable user and statistics enabled), regardless of its database or business purpose. Report reads/saves, metadata reads, asset exports, data queries, cache hits, repeated calls, and failures within `execute` count, including schema errors, permission denials, and unknown capability IDs. Reusing an existing run does not exempt a new `execute` call. Gateway capability discovery (list/inspect), validate/dry-run, and separate run-status/artifact-download HTTP endpoints do not count; pagination and cancellation through capability execution, such as `analysis.query.cancel`, do count. `QUERY_DAILY_LIMIT_EXCEEDED` (HTTP 429) requires waiting until reset or contacting an administrator; `QUERY_QUOTA_UNAVAILABLE` fails explicitly. Do not change identities to bypass enforcement. See [quota and export policy](references/analysis_data_export.md) for blocked-call auditing, retry rules, async server defaults, and separate typed-CLI/local-wait limits.
 - Never invent command names, flags, payload fields, projects, resource IDs, asset names, canonical event/property identifiers, metric formulas, or dates. User-provided business wording is valid unresolved compiler input; it is not a claim that a canonical binding is known.
 - 中文时间表达必须按固定语义映射：最近7天/近7天 -> `mode=recent` -> QP `recentDay=0-7`，含今天；过去7天/前7天 -> `mode=previous` -> QP `recentDay=1-7`，不含今天。用户明确说明是否包含今天时，以该说明为准。完整映射见 [`references/ai_models.md`](references/ai_models.md)。
 

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

@@ -50,7 +50,7 @@ Rules:
 - `--resolutions`: only after user confirmation, pass deterministic bindings keyed by compiler error path while keeping each bound field's path and original wording. Fill the other confirmed model parameters in `--definition`. Follow [`metadata_resolution.md`](metadata_resolution.md).
 - `--artifact-format`: `jsonl` or `csv`.
 
-Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`. Shared lifecycle handling is in [analysis_data_export.md](analysis_data_export.md).
+Async export has no inline row limit. Omit `--timeout-seconds` to use the deployment's server default (normally 21600 seconds / 6 hours). The typed CLI accepts explicit `1..21600`; inspect this capability for the server default/max and use `capability run` for larger explicit values only when allowed. Read the run descriptor for the effective deadline; cancel earlier with `analysis query cancel --run-id <run_id>`. Shared lifecycle handling is in [analysis_data_export.md](analysis_data_export.md).
 
 Do not use raw QP, `events`, `event_view`, `visual_view`, removed ad-hoc QP builder outputs, or schema helper outputs as `--definition`.
 

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

@@ -33,6 +33,10 @@ The reviewer performs both passes on the complete retained scope. It may use scr
 
 ### B. Meaning, Not Filled Fields
 
+- Business topics: review every topic's Agent-authored `semantic_basis.business_question`, `grouping_reason`, and `evidence_item_ids` against definitions of items displayed in that topic. Missing basis is a semantic quality finding even though legacy transport accepts its absence. Copying a dashboard/report title or `topic_seed` is not a business interpretation. Explain why reports answer the same business question, identify justified cross-dashboard merges and within-dashboard splits, and use `待确认业务主题` with the specific uncertainty when evidence is insufficient. A legitimate business name can equal a source name: never reject it by keyword or equality alone.
+- Record `checked_topic_ids`, `unreviewed_topic_ids`, and topic-specific findings alongside item coverage. No whole-packet PASS with unchecked topics. Reuse the existing bounded correction budget and warning continuation policy; topic checks do not authorize certification or submission.
+
+
 - Review every retained item's recommendation, and every retained dashboard/report's definition-based explanation. Track checked IDs; sampling cannot establish a whole-batch PASS. If the scope is too large, split the review across fresh reviewers with disjoint ID lists and combine their coverage and findings.
 - Dashboard: explain the business question jointly answered by its actual child reports and why this particular combination merits review. A title plus heat and "stabilize downstream definitions" is insufficient.
 - Report: explain the actual counted entity, unit, aggregation/formula, measure-level and report-level filters, grouping and saved time semantics. Read raw/normalized configuration when the generic extractor loses model-specific meaning; for example a distinct count may count a company property rather than users. Empty generic measures/dimensions do not establish absent measures/grouping.

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

@@ -184,3 +184,7 @@ Before writing, consult the user's current intent. Submission can be offered onc
 Persist the exact payload, `client_request_id`, proposal fingerprint and returned batch ID in task state. Network replay uses the same key and exact payload, including the original `source_run_id`. Same key with different content is a conflict, not a reason to generate a new key. On subsequent runs, compare material proposal/evidence changes against stored state and `agent-review list|detail|records`; ignore incidental new run IDs and timestamps. Do not repeatedly submit, suggest, or notify on unchanged, pending, completed, rejected, or deferred evidence. Create a new batch only for new material evidence or explicit resubmission intent. Notification deduplication is owned by Common; the Agent does not send another notification separately.
 
 Output is the review detail, including string `id`, `review_url`, `review_page_url`, `status`, `notification_state`, versioned `items`, and `reused`. `review_page_url` is the user-facing page URL. `review_url` is kept for server compatibility and may be relative. An exact request replay returns its original batch. A new request can retain a new batch identity while reusing prior proposals: item-level `reused_batch_id` and `reused_item_id` identify the originals without dropping any requested items. Preserve both as decimal strings. `reused:true` alone does not prove the returned batch ID is an older batch. A fully reused batch can report `status:REUSED` and `notification_state:NOT_REQUIRED`; do not send another notification. Creation success is not proof of approval or certification. Return the link once for a newly actionable batch, distinguish notification failure, and read `detail` / `records` after a meaningful change.
+
+## Topic Semantic Evidence
+
+For each new topic include `semantic_basis` with Agent-authored `business_question`, `grouping_reason`, and nonempty `evidence_item_ids` from the same topic. See [independent Agent preflight](agent_review_preflight.md) for mandatory topic interpretation review. This optional transport extension preserves legacy packet compatibility; accepted structure never establishes semantic quality.

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

@@ -87,14 +87,70 @@ Formula metric example:
 Formula rules:
 
 - Write **bare aliases** only in `formula` (e.g. `"revenue / users"` or `"pay / dau"`).
-- **Do not** write `alias.Axxx` (e.g. `"pay.A103"` / `"revenue.A103"`). Aggregation codes come from each dependency's `aggregation`; the builder expands aliases to real event tokens such as `purchase.amount.A103/login.A101`.
+- **Do not** write `alias.Axxx` (e.g. `"pay.A103"` / `"revenue.A103"`). Event aggregation codes come from that dependency's `aggregation`; saved-metric dependencies retain their own definition. The builder expands aliases to native event or saved-metric tokens.
 - Verify the complete formula through one analysis query and inspect its resolved definition and result before saving it. Reuse that result; a formula does not require a removed QP builder.
 
+## Formula operand filters
+
+For a new or intentionally rewritten formula, put each operand's conditions in that dependency's `filters`; `relation` joins its filters and defaults to `and`. These use the generic filter shape (`field`, `operator`, `values`, or an `items`/`relation` group), not the event-only `event_property_name` shape. Resolve event properties against that dependency's event. For example, only the numerator below requires the spring festival and `win=true`; the denominator remains unfiltered:
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "metrics": [{
+    "formula": "completed / participants",
+    "dependencies": [
+      {
+        "alias": "completed", "event": "activity_dungeon", "aggregation": "total_count",
+        "relation": "and",
+        "filters": [
+          {"field": {"type": "event_property", "name": "festival_name"}, "operator": "eq", "values": ["spring"]},
+          {"field": {"type": "event_property", "name": "win"}, "operator": "is_true"}
+        ]
+      },
+      {"alias": "participants", "event": "char_login", "aggregation": "total_count"}
+    ]
+  }]
+}
+```
+
+Replace the example events and properties with verified project metadata. Use `is_true` / `is_false` without `values` for boolean conditions; do not encode `win=true` as `eq` with `[true]` or `["true"]`.
+
+- To filter only the denominator, add `filters` only to its dependency. To give both sides different conditions, populate each dependency independently. One alias's filters apply to all its repeated occurrences; use different aliases for different filters on the same event. Binding follows expression occurrence order, not the order of `dependencies` and not deduplicated event names.
+- Do not move operand filters to root `definition.filters` or to the formula metric's common `filters`: these are shared calculation scopes, not a substitute for numerator/denominator conditions. Keep any intentionally supplied common filters independent of the dependency conditions; never copy an operand's conditions there as a fallback.
+- Compound groups use `{"relation":"and|or","items":[...]}`. Saved-report writes still obey the shared one-compound-level boundary; ad-hoc queries keep recursive support.
+- Filters on a saved metric dependency are not supported; the server rejects them rather than ignoring them. Preserve that metric's existing definition or use an explicitly verified ordinary event dependency. Do not expand or replace a saved metric merely to bypass this restriction.
+- Before using this shape on an older host, check its capability schema for dependency `filters` / `relation`. A new CLI alone does not add server compiler support. If unsupported, report the deployment prerequisite; never silently omit the operand filters.
+- Choose one formula representation. Native `formulation` or non-empty `custom_filters` must not be mixed with non-empty authoring `dependencies`; conflicting input is rejected rather than losing saved conditions or native UI metadata. For an unchanged saved formula, preserve all returned native fields and omit `dependencies`. To intentionally reauthor it, supply a complete reviewed formula/dependency definition and remove conflicting native fields; do not claim this preserves arbitrary native metadata. A supported `format` and display metadata may be kept.
+
+### Saved metrics as formula operands
+
+An event-report formula can reference verified saved metrics directly, without expanding their event definitions. Use each metric's discovered `metric_name` in the dependency's `event` field; it is not a metric ID or a numbered report measure. The compiler resolves the visible metric and preserves its calculation definition. Write only bare aliases in the expression:
+
+```json
+{
+  "time_range": {"mode":"previous","unit":"day","value":7},
+  "metrics": [{
+    "formula":"third / total",
+    "dependencies":[
+      {"alias":"third","event":"<verified_third_party_metric_name>"},
+      {"alias":"total","event":"<verified_total_metric_name>"}
+    ]
+  }]
+}
+```
+
+Replace placeholders with confirmed metric names from the current project. Omit `aggregation`, `property`, and `percentile` for saved-metric operands: the metric already owns these choices. Do not add dummy `total_count` or `sum` to satisfy a validation error. A mixed formula may combine this saved-metric shape with an ordinary event dependency that supplies its real aggregation and required property/percentile. Missing, inaccessible, or ambiguous metadata must follow compiler guidance; do not silently replace a saved metric with an event or inline a different calculation.
+
+A saved metric's own filters belong to its calculation; this is different from adding new `filters` to a saved-metric dependency, which remains unsupported. When creating a filtered metric for later formula reuse, follow [`metric_create.md`](../metric_create.md#saved-metric-filters) and verify its saved conditions with `analysis-meta metric get`. Reuse that verified metric by name without expanding or stripping its definition. To divide filtered replies by all replies, keep the filtered metric only in the numerator and use an independently verified unfiltered metric or event in the denominator; moving its conditions to the formula's common filters changes both sides.
+
+This is a formula inside an event analysis/report, not `analysis-meta metric create`, and it does not imply saved-metric dependency support for retention or other models. Existing saved-formula round-trip rules below still apply.
+
 Saved formula report round-trip rules:
 
 - `analysis report get` can return saved formula metrics with `custom_filters`, `formulation`, `custom_event_desc`, `event_desc`, `format`, `event_type`, `event_split_indexes`, `quota_time_ranges`, `quota_entities`, and `event_uuid`. These are saved-report round-trip fields, not the authoring shape for a new formula.
 - When updating an existing report from its returned `definition`, preserve all of those fields unchanged unless the user explicitly requests that formula behavior to change. `custom_filters[*].index` binds each numerator/denominator occurrence to its own filter set, including repeated event/aggregation tokens.
-- For a display-name-only change, modify only `display_name`. Do not convert the saved formula to `formula + dependencies`, because rebuilding dependencies can change or discard per-component filters and other formula semantics.
+- For a display-name-only change, modify only `display_name`. Do not convert the saved formula to `formula + dependencies`; reauthoring is a different operation and cannot preserve arbitrary native metadata automatically. Mixed representations are rejected as described above.
 - Continue to use the `formula + dependencies` shape above when authoring a new formula metric.
 
 Saved report filter round-trip rules:

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

@@ -31,6 +31,7 @@ Use for ranking users/entities by an event metric.
 - `accompanying_properties` is an array of field dimensions. The main `rank_dimension` and accompanying properties support `array_grouping`, `time_granularity`, and historical tag/cluster date policies. Numeric buckets, funnel steps, and retention sources are not rank-list options.
 - For formula ranking, set `rank_formula` to a formula metric definition. Omit the mutually exclusive regular metric fields `rank_event`, `rank_aggregation`, `rank_property`, `rank_filters`, `rank_relation`, and `rank_quota_entities`; put formula filters inside `rank_formula.filters`. Keep the outer `order_by` as `ASC` or `DESC`.
 - Formula dependencies and accompanying metrics use the same aggregation restrictions as the primary metric, including the exclusion of `percentile`. Preserve saved formula metadata returned by report reads.
+- Both `rank_formula` and accompanying formulas support [operand-specific filters](event.md#formula-operand-filters) in each dependency's `filters` / `relation`, using generic `field` leaves. Keep these separate from the formula's common filters and the definition's global filters; rank-list aggregation and saved-metric restrictions still apply.
 
 ```json
 {

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

@@ -86,6 +86,8 @@ Place this object inside `retention`. `combine_operator` belongs to `initial_dat
 
 Both roles support `formula` and `dependencies` with the same retention aggregation restrictions. Use bare aliases for new formulas. Preserve returned `formulation` and `custom_filters` when updating a saved formula; they carry the native dependency metadata and filters. Metric `filters` use event-only leaves and support recursive `items`/`relation` groups.
 
+For conditions on just one formula operand, use that dependency's `filters` / `relation` as described in [formula operand filters](event.md#formula-operand-filters). Dependency leaves use the generic `field` shape, unlike the simultaneous metric's event-only filters. Do not replace operand conditions with shared metric filters; retain retention's aggregation and saved-metric restrictions.
+
 `relation_event_property_name` supplies a shared relation property. `initial_relation_event_property_name` and `return_relation_event_property_name` override it for the two cohort events; both must resolve whenever either is configured. A `return_users` metric can override `relation_event_property_name` for its own event. All relation properties must have compatible types; relation overrides do not apply to `initial_date`.
 
 ## Grouping and summary settings

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

@@ -44,3 +44,5 @@ Both `revenue_metric` and `cost_metric` accept a formula with alias dependencies
 ```
 
 Number formats are `float`, `float3`, `float4`, `integer`, and `percent`. Saved formulas may contain an expanded `formula`, `formulation`, and `custom_filters`; preserve that metadata on updates. Event and regular-metric filters support recursive `items`/`relation` groups using event-property leaves. `first_day_of_week` is between 1 (Monday) and 7 (Sunday).
+
+Formula dependency `filters` / `relation` support [operand-specific conditions](event.md#formula-operand-filters) using the generic `field` shape. Put revenue/cost numerator and denominator conditions in their own dependencies, not in the formula metric's mutually exclusive `filters` / `relation`. Revenue aggregation and saved-metric restrictions still apply.

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

@@ -10,7 +10,15 @@ ceilings.
 
 `--artifact-format` selects the logical row format, not compression. Read the returned `format`, `compression`, `file_name`, `content_type`, and `content_encoding`; analysis query exports are currently gzip-compressed even when the logical format is `jsonl` or `csv`.
 
-Default and maximum runtime is 21600 seconds (6 hours). Omit `--timeout-seconds` to use that default, or pass a smaller value when the caller explicitly wants an earlier deadline.
+Omit `--timeout-seconds` to use the server default (normally 21600 seconds / 6 hours). Common analysis-query and asset-governance exports use the deployment's async default, which may exceed 6 hours. The analysis-query typed flag still accepts explicit values only in `1..21600` (asset-governance typed flags retain `1..7200`); inspect the selected capability for the server default and maximum. If its schema allows a larger explicit value, use `capability run` with `timeout_seconds`. Other export families retain their own server policies; do not assume this deployment setting applies to every export.
+
+Read `effective_timeout_seconds`, `timeout_source`, and `deadline_at` from the returned run descriptor for the actual deadline.
+
+The member's natural-day quota counts each Gateway capability `execute` call eligible for usage statistics: the user is identifiable and statistics are enabled. Eligibility follows Gateway usage recording, regardless of business purpose or database engine (including MySQL and Trino). Report reads/saves, metadata reads, asset-governance exports, business data queries, cache hits, and failures that reach `execute` all count. This includes invalid input schemas, permission denials, unknown capability IDs, and accepted work that later fails or times out. A local CLI validation failure that never reaches Gateway `execute` does not count.
+
+Each repeated `execute` call counts, even with identical input or when a handler reuses an existing run. Gateway provides no general `client_request_id` idempotency guarantee. Resume the existing run through its status/download endpoints instead of submitting it again. Gateway capability-discovery list/inspect endpoints, validate/dry-run endpoints, and independent run-status/artifact-download HTTP endpoints do not enter capability execution and do not count. This applies to `analysis run inspect`, `analysis run wait` polling, and `analysis artifact download`. Business `list`/`get` commands still count when they execute a capability; the operation's name does not change its route. Pagination, cancellation, or another operation invoked through capability execution does count; for example, both `analysis query cancel` and `capability run analysis.query.cancel` enter `execute`.
+
+`QUERY_DAILY_LIMIT_EXCEEDED` (HTTP 429) requires waiting until reset or contacting an administrator. A call blocked at the daily limit does not increase the used quota, but remains eligible for failed-call usage auditing. `QUERY_QUOTA_UNAVAILABLE` means quota enforcement is unavailable and fails explicitly. Do not retry with another identity to bypass either error. Usage persistence is asynchronous and best effort: quota and usage recording share eligibility, but the quota counter need not equal the number of persisted usage rows.
 
 Choose one lifecycle form:
 
@@ -36,6 +44,8 @@ or a persistent transient network failure stops only local waiting; it never
 cancels the remote run. Resume with the returned `resume_command` or printed
 `analysis run wait` command.
 
+A server run can outlive one local wait window. Resume the same run instead of submitting it again.
+
 Waiting succeeds only for `status=SUCCEEDED` plus
 `artifact_status=COMPLETED`. Run or artifact `FAILED`/`CANCELED` is terminal and
 returns a non-zero error. Unknown states, authorization failures, and 404s fail

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

@@ -12,7 +12,7 @@ ae-cli analysis-governance asset batch-info-export --project-id <project_id> --n
 
 Capability id: governance.asset.batch_export_info.
 
-Input sends `project_id` and `node_ids`. Optional `request_id`, `format` (only `xlsx`), and `timeout_seconds` (1..7200, default 3600) may be supplied through `--payload`. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
+Input sends `project_id` and `node_ids`. Optional `request_id`, `format` (only `xlsx`), and `timeout_seconds` may be supplied through `--payload`; inspect the capability for the server default/range. The explicit `--timeout-seconds` flag retains its `1..7200` range. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
 
 Output `data` is an async XLSX descriptor with `run_id`, `artifact_id`, status, and expiry fields. Inspect and download the returned artifact IDs.
 
@@ -29,6 +29,6 @@ This capability starts an asynchronous artifact export. Use `--wait --output <pa
 
 - `--artifact-format xlsx` selects the logical data format. Follow the returned descriptor for compression and content type.
 - `--request-id cli_<32 lowercase hex>` assigns a stable request identifier.
-- `--timeout-seconds` accepts 1–7200 (server default: 3600).
+- Omit `--timeout-seconds` to use the server-provided default. This typed CLI accepts explicit values in `1..7200`; inspect this capability for the deployment default/max. Use `capability run` with a larger explicit `timeout_seconds` only when its schema permits it.
 - `--wait-timeout-seconds` controls how long this CLI invocation waits; it does not change the server runtime limit.
 - Explicit flags override corresponding `--payload` fields; omitted options preserve payload values.

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

@@ -14,7 +14,7 @@ ae-cli analysis-governance asset batch-sql-export --project-id <project_id> --no
 
 Capability id: governance.asset.batch_export_sql.
 
-Input sends `project_id` and `node_ids`. Optional `request_id`, `format` (only `xlsx`), and `timeout_seconds` (1..7200, default 3600) may be supplied through `--payload`. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
+Input sends `project_id` and `node_ids`. Optional `request_id`, `format` (only `xlsx`), and `timeout_seconds` may be supplied through `--payload`; inspect the capability for the server default/range. The explicit `--timeout-seconds` flag retains its `1..7200` range. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
 
 Output `data` is an async XLSX descriptor with `run_id`, `artifact_id`, status, and expiry fields. Alternatively, wait and download with `ae-cli analysis run wait --run-id <run_id> --output <file>` using the returned run ID; see [`run_wait.md`](run_wait.md).
 
@@ -31,6 +31,6 @@ This capability starts an asynchronous artifact export. Use `--wait --output <pa
 
 - `--artifact-format xlsx` selects the logical data format. Follow the returned descriptor for compression and content type.
 - `--request-id cli_<32 lowercase hex>` assigns a stable request identifier.
-- `--timeout-seconds` accepts 1–7200 (server default: 3600).
+- Omit `--timeout-seconds` to use the server-provided default. This typed CLI accepts explicit values in `1..7200`; inspect this capability for the deployment default/max. Use `capability run` with a larger explicit `timeout_seconds` only when its schema permits it.
 - `--wait-timeout-seconds` controls how long this CLI invocation waits; it does not change the server runtime limit.
 - Explicit flags override corresponding `--payload` fields; omitted options preserve payload values.

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

@@ -35,6 +35,6 @@ This capability starts an asynchronous artifact export. Use `--wait --output <pa
 
 - `--artifact-format jsonl` selects the logical data format. Follow the returned descriptor for compression and content type.
 - `--request-id cli_<32 lowercase hex>` assigns a stable request identifier.
-- `--timeout-seconds` accepts 1–7200 (server default: 3600).
+- Omit `--timeout-seconds` to use the server-provided default. This typed CLI accepts explicit values in `1..7200`; inspect this capability for the deployment default/max. Use `capability run` with a larger explicit `timeout_seconds` only when its schema permits it.
 - `--wait-timeout-seconds` controls how long this CLI invocation waits; it does not change the server runtime limit.
 - Explicit flags override corresponding `--payload` fields; omitted options preserve payload values.

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

@@ -12,7 +12,7 @@ Command:
 ae-cli analysis bi-panel-page-data export --project-id <project_id> --panel-id <panel_id> --page-key <page_key> --result-type charts [--chart-ids '["chart1"]'] [--artifact-format jsonl] --output <file>
 ```
 
-Input sends `project_id`, `panel_id`, `page_key`, `result_type=charts`, and optional chart, control, column, cache, request, timeout, and format fields. Use CLI flag `--artifact-format` for the gateway `format` input; `--format` is the CLI output formatter. The export does not accept row/block paging fields: Common streams chart rows directly and applies only `model_full_download_limit`. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`. BI summary is rendered presentation data; query it with `bi-panel-page-data run`.
+Input sends `project_id`, `panel_id`, `page_key`, `result_type=charts`, and optional chart, control, column, cache, request, timeout, and format fields. Use CLI flag `--artifact-format` for the gateway `format` input; `--format` is the CLI output formatter. The export does not accept row/block paging fields: Common streams chart rows directly and applies only `model_full_download_limit`. Omit `--timeout-seconds` to use the deployment's server default (normally 21600 seconds / 6 hours). The typed CLI accepts explicit `1..21600`; inspect this capability for the server default/max and use `capability run` for larger explicit values only when allowed. Read the run descriptor for the effective deadline; cancel earlier with `analysis query cancel --run-id <run_id>`. BI summary is rendered presentation data; query it with `bi-panel-page-data run`.
 
 Output is the gateway envelope. `data` contains an async export descriptor with `run_id`, `artifact_id`, status fields, and expiration fields. It does not create `query_context_id`. The CLI handles waiting and download with `--output`.
 

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

@@ -23,5 +23,5 @@ Parameters:
 | `--project-id` | Numeric project ID. | Yes |
 | `--uuid` | Tracking check task UUID. | Yes |
 | `--request-id` | Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted. | No |
-| `--timeout-seconds` | Async runtime in seconds. Default and max: 21600 (6 hours); cancel earlier with analysis query cancel --run-id <run_id>. | No |
+| `--timeout-seconds` | Async runtime in seconds. Omit to use the server default (normally 21600 / 6 hours). Explicit CLI values remain in 1..21600. Inspect the capability for its server default/max; use capability run for larger values only when allowed. Cancel with analysis query cancel --run-id <run_id>. | No |
 | `--output` | Wait and download to this local file. | No |