@thinkingai/ae-cli 6.0.52 → 6.0.54

package/skills/ae-analysis/SKILL.md

@@ -1,33 +1,59 @@
 ---
 name: ae-analysis
-version: 4.2.20
-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, project configuration, tracking plans, governance asset lists/rules/lineage/impact/dependency, batch asset operations, projects, and resource links. Use when the user asks to query data, explain a change, export evidence, 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."
+version: 4.2.31
+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."
 ---
 
 # ae-analysis
 
 This is the single entry skill for analysis intent and command execution.
 
+## Capability contract
+
+- Responsibilities: analysis queries and assets, metadata discovery, audience definitions, local input-file upload, and the governance/project/tracking workflows described below.
+- Inputs: verified project context and the requested measures, time windows, filters or operation-specific resources; upload also needs a local file and a discovered purpose.
+- Outputs: query evidence with its scope, verified metadata, operation/resource identifiers, uploaded input-file identifiers, or asynchronous run/artifact status as applicable. Query rows are not automatically a persisted audience.
+- Boundaries: engagement operations and metadata data-table writes/dimension binding are outside this skill's workflows; find the capability needed for any remaining work.
+- Completion: the requested analysis-side result is verified, or pending/blocked work is identified. Keep any other parts of the user's request unfinished until addressed.
+
+## Cross-skill collaboration
+
+When remaining work is outside this skill's scope, or a necessary prerequisite needs another capability, follow [the collaboration protocol](references/collaboration.md). Choose from the skills available in this run by capability, preserve verified context, and continue the remaining task. Reuse this protocol if already loaded.
+
+## Agent Context Telemetry
+
+Hard rule: before running gateway-backed `ae-cli` commands in this skill, maintain the current Agent context in `.ae/cli-agent-context.json` at the working directory root, unless the user explicitly asks not to send intent telemetry. Keep the business command clean; do not append `--agent-context <base64url-json>` by default. Runtime auto-detection alone is only a partial fallback and is not enough for user-intent telemetry.
+
+The context file must use `intent_source: "agent_context_file"` and should include a concise task-level `user_intent`, the current `session_goal`, stable `agent_session_id`, current `agent_turn_id` when available, `intent_relation`, and `intent_revision`. Include `agent_model` whenever the current model can be confirmed. Use the user's original language for `session_initial_intent`, `user_intent`, and `session_goal`; for example, use Chinese text for a Chinese user request. Omit unknown parent-turn fields rather than guessing; do not omit the whole context payload. Prefer concise intent summaries over long raw transcripts. Update the file when starting a CLI-backed task or when the user's CLI purpose changes. Reuse it while the purpose and model remain unchanged.
+
+The Agent must actively obtain the current model identifier and write it explicitly as `agent_model` in the context file. Use trusted runtime context or bounded metadata for the exact current session and turn; for example, Codex's current-session `turn_context.model`. Do not rely solely on a model environment variable being present. Never infer the model from the Agent/product name, a configured default, or another session. This requirement applies to every Agent client. Update the file when the model changes, even if the CLI purpose stays the same.
+
+If the model cannot be confirmed, omit `agent_model`, set `context_capture_status: "partial"`, and continue; do not block or delay the business command or ask the user to identify the model just for telemetry. Once confirmed, write the model and remove the stale partial marker so the CLI can compute capture status from the remaining fields.
+
 ## Analysis workflow
 
 For data queries:
 
-1. Take the current project and requested metrics, windows, groups and filters. Reuse known assets and definitions; discover unknown business measures with [metadata resolution](references/metadata_resolution.md), then select the needed saved-report or ad-hoc command/model references.
+1. Take the current project and requested metrics, windows, groups and filters. Before choosing a knowledge-base or analysis route, apply the [Project Semantic Knowledge and Discovery](#project-semantic-knowledge-and-discovery) gate. Reuse known assets and definitions; discover unknown business measures with [metadata resolution](references/metadata_resolution.md), then select the needed saved-report or ad-hoc command/model references.
 2. Confirm any new business mapping once, fill the required parameters, and execute the applicable saved report or complete ad-hoc definition. Reuse confirmed meanings in dependent queries. If the confirmation tool cannot obtain a reply, present the same choices in text and wait for the reply.
 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.
 
 ## Route before reading
 
 1. Map the request to a command family before opening any reference.
-   - CLI Agent asset-authentication and metric-recommendation review: this includes requests to recommend project assets for certification/authentication, review asset-certification candidates, review project asset-governance recommendations, or review recommended metrics. Open `references/governance_recommendation_export.md` and route to `analysis-meta governance-recommendation export|submit|decisions`. For review-page submission, open `references/agent_review_submit_to_page.md` and use `analysis-meta agent-review submit-to-page|list|detail|records|review|retry`. Do not load project semantics, project KB, or personal semantic preferences as a preflight.
-   - Project semantic knowledge-base build/update/refresh/sync: open `references/project_semantic_knowledge_wiki.md` and route to `project-semantic asset-package export`, local semantic planning, and local Wiki rendering. Default to CLI semantic precompilation into Markdown sources, source ZIP upload, and KB schema/compile. Update changed source files and run incremental KB compilation on refresh. Never substitute read-only snapshot import. Stop on company permission denial. This is a command-reference workflow inside `ae-analysis`, not a standalone project semantic Skill.
+   - CLI Agent asset-authentication and metric-recommendation review: this includes requests to recommend project assets for certification/authentication, review asset-certification candidates, review project asset-governance recommendations, review recommended metrics, or explicitly auto-review/auto-certify recommended assets. Open `references/governance_recommendation_export.md` and route to `analysis-meta governance-recommendation export|submit|auto-review|decisions`. For review-page submission, open `references/agent_review_submit_to_page.md` and use `analysis-meta agent-review submit-to-page|list|detail|records|review|retry`. Do not load project semantics, project KB, or personal semantic preferences as a preflight.
+   - Project semantic knowledge-base build/update/refresh/sync: open `references/project_semantic_knowledge_wiki.md` and route to `project-semantic asset-package export`, local semantic planning, and local Wiki rendering. Default to CLI semantic precompilation into Markdown sources, source ZIP upload, formal preset initialization/reuse, and KB compilation. Do not regenerate Schema or AI-validate unchanged presets during normal refresh. Update changed source files and use incremental compilation on ordinary refresh; a navigation taxonomy version change requires the full migration rebuild reported by the source-tree packager. Never substitute read-only snapshot import. Stop on company permission denial. This is a command-reference workflow inside `ae-analysis`, not a standalone project semantic Skill.
    - Known family: open only its dedicated reference. For example, a retention request goes directly to `references/adhoc_run.md`, the common `references/ai_models.md`, and `references/ai_models/retention.md`.
    - Unknown family: search [`references/command_index.md`](references/command_index.md) with `rg` or an equivalent text-search tool and keep only the matching rows. `command_index.md` is a search-only fallback; never open it with a whole-file read or print the entire file.
 2. Read the selected command's dedicated reference before composing it:
    - `event list` -> `references/event_list.md`
+   - 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.
+   - 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.
    - replace hyphens with underscores in gateway filenames.
@@ -40,6 +66,10 @@ For data queries:
 
 Routing is complete when one command family and its dedicated references are selected. The generated command index is exhaustive and must stay out of model context except for matching search rows. This file contains routing and workflow rules only; do not duplicate a hand-maintained command inventory here.
 
+Use `analysis report list` and `analysis dashboard list` only for manageable-asset directories before edit or management workflows. They exclude read-only shared assets. For viewing, finding, or selecting a saved report or dashboard, prefer `analysis asset search` so readable assets remain discoverable.
+
+Saved-report writes follow the analysis page's product boundary: `analysis report create/update` accepts at most one compound filter level, and every entry in that group's `items` must be a leaf filter. Do not flatten a deeper tree returned by `analysis report get`; use a metadata-only update or obtain an explicit page-compatible replacement definition. Ad-hoc analysis keeps its model-specific recursive filter support.
+
 ## Boundaries and priority
 
 Use this skill for these CLI services:
@@ -49,17 +79,19 @@ Use this skill for these CLI services:
 - `analysis-governance`: gateway asset governance operations, including governed asset lists/exports, lineage, dependency, impact, query history, rule schema/list/create/update/delete, batch asset actions, and operation records. Use this service for asset governance workflows, not for metadata event/property/metric CRUD.
 - `tracking`: gateway tracking plan, checking, ingest, live-data, and event blacklist operations.
 - `personal-semantic-preference`: current user's project-scoped personal semantic preferences. Use it as agent context before resolving ambiguous business wording, asset choices, or recurring user preferences.
-- `project-semantic` and `kb` only inside the explicit project semantic knowledge-base command-reference workflow. They are not prerequisites for asset-authentication and metric-recommendation review.
+- `project-semantic`: asset-package export for an explicit project knowledge-base build or refresh. The old governed project-semantic lifecycle is no longer available through CLI.
 
-For metadata gateway detail outside the commands in the generated index, use the metadata skill. For Engage, DataOps, or Community work, use the corresponding skill.
+For work outside the command families covered here, use the collaboration protocol to discover a matching available capability rather than assume a particular Skill name.
 
 Use `ae-cli` as the only execution path for this skill. If a command is missing, unsupported, not implemented, or a capability gap is confirmed, report that gap; do not switch to direct MCP execution. A validation error or `need_clarification` calls for its specific input correction. A transport failure such as `fetch failed` means the result is unavailable: report the error with any already obtained results and stop the dependent request. Resume after environment recovery; do not start route probes, sleeps or background network polling. A transport failure does not establish a missing capability or empty data.
 
 For tags and audience clusters, use the native `analysis user-tag ...` and `analysis user-cluster ...` gateway commands.
 
-For CLI Agent asset-authentication and metric-recommendation review, route to `analysis-meta governance-recommendation export|submit|decisions`. Common returns the deterministic evidence packet; the Agent owns the fixed human approval display from `references/governance_recommendation_export.md`, including business-domain grouping, plain-text status labels, and risk/conflict explanation. Do not use project-semantic, project-KB, or personal-semantic-preference commands as prerequisite context for this workflow. Do not use management commands such as `asset-authentication list|export|update` or metric CRUD commands to synthesize recommendations. Do not bypass curated commands with `ae-cli capability inspect|validate|dry-run|run` for `governance.asset_authentication.dashboard_package`, `metadata.metric.recommended_scan`, or `metadata.metric.recommended_create`.
+For CLI Agent asset-authentication and metric-recommendation review, route to `analysis-meta governance-recommendation export|submit|auto-review|decisions`. Common returns the deterministic evidence packet; the Agent owns the fixed human approval display from `references/governance_recommendation_export.md`, including business-domain grouping, plain-text status labels, and risk/conflict explanation. Call `auto-review` only when the user explicitly asks for automatic review or automatic certification; a plain recommendation request and a recommendation-plus-page-submission request must not check the automatic certification project config or auto-certify assets. When `auto-review` is called without an explicit `--limit`, the CLI validates the auto-certification and project-semantic switches, read-only probes top-20/top-50/top-100 pending recommendation material as needed, then the CLI Agent builds one set of automatic certification decisions from the final material and submits those decisions for execution/audit. The CLI Agent, not Common historical recommendation state, owns semantic-duplicate detection; duplicate skips must name concrete conflicting asset targets. The auto-review result also returns `manual_review_handoff` for assets still uncertified after automatic review; if the user later asks to submit those leftovers to the page, build `agent-review submit-to-page` from `manual_review_handoff.page_review_items` so dashboard/report parent context is preserved, treat only `manual_review_handoff.items` as the human certification workload, and include each automatic non-certification reason in the item summary. Do not use project-semantic, project-KB, or personal-semantic-preference commands as prerequisite context for this workflow. Do not use management commands such as `asset-authentication list|export|update` or metric CRUD commands to synthesize recommendations. Do not bypass curated commands with `ae-cli capability inspect|validate|dry-run|run` for `governance.asset_authentication.dashboard_package`, `metadata.metric.recommended_scan`, or `metadata.metric.recommended_create`.
+
+Start a recommendation with `governance-recommendation export` before lengthy Agent analysis so Common can atomically mark the project as running. Later exports in the same Agent turn may expand the candidate pool. If Common returns `RECOMMENDATION_RUNNING`, stop this attempt and report that a recommendation is already in progress; do not retry with another Agent context or bypass the marker. Successful page submission and automatic review release the marker; recommendation-only or failed Agent runs rely on the fixed expiry. No separate start or finish CLI command is required.
 
-After presenting recommendations, the Agent may ask whether to submit them to the review page. A user choice to submit authorizes `analysis-meta agent-review submit-to-page` only; it does not authorize approval or certification. If the user declines, do not write or repeatedly suggest submission. Existing explicit submission authorization remains valid and does not need another prompt. A preauthorized unattended task may submit review proposals only; it must never call `agent-review review|retry`, legacy `governance-recommendation submit`, or direct certification/metric mutations automatically. Use `agent-review list|detail|records` and the task's persisted proposal fingerprint to reuse prior batches. Do not resubmit or send repeated notifications for unchanged proposals, pending reviews, completed items, or previously declined suggestions. A new run ID alone is not new evidence. Report the returned `review_url` once and remain quiet until there is a meaningful change or required user action. See `references/agent_review_submit_to_page.md` for stable request keys and packet rules.
+After presenting recommendations, the Agent may ask whether to submit them to the review page. A user choice to submit authorizes `analysis-meta agent-review submit-to-page` only; it does not authorize approval, certification, config checking, or `governance-recommendation auto-review`. If the user declines, do not write or repeatedly suggest submission. Existing explicit submission authorization remains valid and does not need another prompt. A preauthorized unattended task may submit review proposals only; it must never call `agent-review review|retry`, legacy `governance-recommendation submit`, `governance-recommendation auto-review`, or direct certification/metric mutations automatically. Use `agent-review list|detail|records` and the task's persisted proposal fingerprint to reuse prior batches. Do not resubmit or send repeated notifications for unchanged proposals, pending reviews, completed items, or previously declined suggestions. A new run ID alone is not new evidence. Report the returned `review_url` once and remain quiet until there is a meaningful change or required user action. See `references/agent_review_submit_to_page.md` for stable request keys and packet rules.
 
 Report review details must explain calculation logic and statistical measures, not only business purpose. Follow resolve/export -> material-package completeness check -> gap-only `analysis-meta agent-review evidence` or `analysis report get` -> chunked AI explanation -> independent preflight -> authorized submit-to-page -> detail readback. LOCAL_ONLY stops at the local preflight result. `governance-recommendation export` is expected to include report `evidence_snapshot.analysis` and `target_revision` in `review_material_package.candidate_assets`; do not ask the customer to run `analysis report get` for every report when those fields are present. Fetch `agent-review evidence` only when a report item lacks current analysis, when validating a generated draft, or when the material package explicitly marks a definition gap. Read `references/agent_review_evidence.md` for stable analysis fields and their limits. Populate `item.ai_summary.analysis_explanation` with evidence-backed measures, dimensions, calculations, filters, time_scope, and query_columns as applicable; interpret each supported SQL projection column separately. Reference only actual fact-supporting response paths rooted at `evidence_snapshot.analysis`; `source_path` is provenance, not an automatic evidence_refs substitution. Preserve server facts separately from AI interpretation and explicitly identify null, missing, dynamic or unparsed evidence. For DYNAMIC SQL, label supported sql.raw/normalized_definition.params discussion as original-text interpretation, never fabricate select_columns or runtime substitutions. Common create stores the submitted packet; it does not fill missing calculation explanations for the Agent. Before calling `submit-to-page`, check required `evidence_snapshot.analysis` and resolvable references in `analysis_explanation.calculations` / `analysis_explanation.measures`; missing required structure remains an error. Reviewer-readability and interpretation defects follow the bounded quality correction/warning procedure. Verify the stored snapshot and references in detail after submission. Never guess SQL, aliases, columns, formulas, time ranges, timezones, or successful execution. Definition inspection, evidence reads, validation, and submission are not proof of query results, approval, or certification.
 
@@ -96,10 +128,12 @@ ae-cli capability search|inspect|validate|dry-run|run [options]
 ```
 
 - Gateway commands use kebab-case flags such as `--project-id`; the CLI sends snake_case JSON.
+- Gateway commands must be preceded by the `.ae/cli-agent-context.json` update described in the Agent Context Telemetry section. The hidden `--agent-context <base64url-json>` option is only a fallback for isolated no-write environments or local debugging, not the preferred path for this skill.
 - JSON values must be JSON string literals.
 - Global flags include `--host`, `--format json|table`, `--jq`, `--validate`, `--dry-run`, and `--yes`. Use `--validate` only to resolve a concrete complex-input issue; use `--dry-run` for high-risk writes or an explicitly requested preview. These modes are mutually exclusive.
 - 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.
 - 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)。
 
@@ -146,22 +180,49 @@ Use the current turn's project ID supplied by the Agent host. When no project is
 
 ### Project Semantic Knowledge
 
-Do not call project-semantic catalog, entry, candidate, release, or publish commands as prerequisite context for ordinary analysis or asset-governance requests. The retired governed-project-semantic lifecycle is not part of this CLI Agent flow.
+When the user explicitly asks to build, update, refresh, rebuild, or sync a project semantic knowledge base, open `references/project_semantic_knowledge_wiki.md`. That command-reference workflow starts from `ae-cli project-semantic asset-package export` and then uploads/compiles KB sources. The retired governed project-semantic candidate and release lifecycle is not part of this knowledge-base build path or CLI Agent asset-authentication and metric-recommendation review.
 
-When the user explicitly asks to build, update, refresh, rebuild, or sync a project semantic knowledge base, open `references/project_semantic_knowledge_wiki.md`. That command-reference workflow starts from `ae-cli project-semantic asset-package export` and then uploads/compiles KB sources. Do not load a standalone project semantic Skill for this workflow.
+### Project Semantic Knowledge and Discovery
+
+Do not call project-semantic catalog, entry, candidate, release, or publish commands. The governed project-semantic lifecycle has been retired from CLI; use `personal-semantic-preference` for current-user semantics and the knowledge-base workflow for project knowledge.
+
+For a project-scoped request that may need an asset or metric definition, decide the route before any analysis asset, report, or metric lookup. Follow an explicitly named knowledge base directly; skip this gate if the user rules out knowledge bases. Otherwise call `ae-cli config show` once per host and authenticated account in this conversation, and recheck when that scope changes or the answer is over 24 hours old. The command uses the CLI's daily company configuration cache; do not force a remote refresh for each question.
+
+If `data.routing.knowledge_base` is `auto`, consider whether a project knowledge base could answer the question or provide the needed asset definition. If it could, use `ae-kb-discovery` first, prefer an exact project binding, and read matching pages through `ae-kb`. For data questions, verify the selected asset's semantic coverage and run the applicable analysis command. If pages provide only related definitions, limitations, or partial coverage, retain that evidence and continue normal asset or metric discovery for the missing requirements through the KB analysis workflow. If no relevant knowledge-base page is found, continue with normal discovery. If the routing value is `explicit` or `data.source` is `unavailable`, use the normal analysis route without implicit KB discovery. A KB candidate without a relevant page hit does not justify using its assets.
 
 ### Personal Semantic Preferences
 
-When the request involves personal business wording, asset preferences, or explicit personalization, call `ae-cli personal-semantic-preference list --project-id <project_id>` once per host, authenticated user, project, and conversation; reuse the result within that scope. Use the current project supplied by the Agent host. If an entry is adopted, read [`references/personal_semantic_preference_list.md`](references/personal_semantic_preference_list.md) and fetch that entry with `--mark-used`. Read the same reference before recording a durable user preference; a one-time analysis confirmation is task context.
-This rule does not apply to CLI Agent asset-authentication and metric-recommendation review through `analysis-meta governance-recommendation export|submit|decisions`; that workflow must not load personal semantic preferences as prerequisite context.
+When the request involves personal business wording, asset preferences, explicit personalization, or a project-scoped request to remember/save a reusable analysis workflow, call `ae-cli personal-semantic-preference list --project-id <project_id>` once per host, authenticated user, project, and conversation; reuse the result within that scope. Use the current project supplied by the Agent host. If an entry is adopted, read [`references/personal_semantic_preference_list.md`](references/personal_semantic_preference_list.md) and fetch that entry with `--title <title_from_list> --mark-used`. Read the same reference before recording a durable user preference; a one-time analysis confirmation is task context.
+This rule does not apply to CLI Agent asset-authentication and metric-recommendation review through `analysis-meta governance-recommendation export|submit|auto-review|decisions`; that workflow must not load personal semantic preferences as prerequisite context.
+
+Personal semantics supply the current user's defaults, interpretation corrections, asset choices, and output preferences. Verify any selected asset or calculation against its saved definition before execution; a personal preference does not replace the asset's current definition.
+
+The Agent owns the personal preference capture trigger. Choose `context_type` by meaning:
+
+- `preference`: durable interpretation or output preference without an exact asset binding.
+- `asset_context`: durable user wording or intent bound to one or more exact project assets. Send the complete ordered `resource_refs` array; each item has `resource_type`, string `resource_key`, and `display_name`.
+- `experience`: a confirmed reusable project work method or analysis workflow without an exact asset binding.
+- `background`: stable personal context without an exact asset binding.
+
+Any stable choice of a concrete asset, including an event-selection scenario, must use `asset_context`; do not encode asset IDs only in prose. During a project task, collect durable current-user preferences, stable interpretation corrections, reusable asset-selection choices, recurring output preferences, reusable project analysis workflows, and current-user working definitions that have not become approved project semantics. If the user says "remember the above workflow", "save this process for this project", "以后按这个流程", or equivalent while a project scope is active, record it here as `context_type=experience` instead of using `ae-cli memory`. A working definition remains eligible for personal storage even when it would also benefit other project users. Store it only as the current user's preference; never describe it as approved project authority or copy a bound asset definition into its content. Keep future governance or lifecycle instructions out of the stored content. Do not save transient task details, one-off analysis results, company knowledge, standalone metadata facts, reports, or dashboards as personal preferences.
+
+An explicit stable statement, correction, or confirmation that passes that evidence gate authorizes `personal-semantic-preference add` or `update` without a second "save" confirmation. Compare against the already loaded catalog first; when one existing preference matches, fetch it with `--mark-used`, update that existing preference, and avoid creating a duplicate. Otherwise add a new one. An explicit instruction not to retain it always wins. Delete remains high risk and requires explicit user confirmation.
+
+Personal capture and project recommendation are independent. Save or update the personal semantic first when its evidence gate is met. If the same content looks reusable as a formal project-wide definition, finish the current task and then ask whether the user wants to recommend it as a project semantic candidate. Do not make project recommendation a prerequisite for personal capture, do not submit a candidate without that user choice, and never approve or publish on behalf of an ordinary user.
+
+After a successful add, update, or delete, merge that response into the conversation's cached directory locally. Do not call list again merely to observe the write.
+
+When a later published project semantic matches a personal semantic, treat the project semantic as formal and allow the personal record to become redundant, expire, or merge through the supported lifecycle. When they conflict, keep the project semantic formal, disclose the conflict, and preserve the personal record unless the user explicitly changes or deletes it. These are consumption and lifecycle rules; do not append them to the stored personal semantic content.
+
+Stale or expired preferences are automatically hidden by list filtering and backend maintenance. Do not look for or invent a separate command for that behavior.
 
 ### Metadata discovery
 
-Reuse known definitions and canonical metadata directly. For an unknown business measure, follow [`references/metadata_resolution.md`](references/metadata_resolution.md): search relevant saved metrics/reports, read their definitions, and discover only missing events or properties. `allowed_resource_types` is authoritative for a compiler error. Confirm a selected business mapping once, even when there is only one suitable candidate; reuse the task's already confirmed mappings.
+Reuse known definitions and canonical metadata directly. For an unknown business measure, follow [`references/metadata_resolution.md`](references/metadata_resolution.md): search relevant saved metrics/reports, read their definitions, and discover only missing events or properties. `allowed_resource_types` is authoritative for a compiler error. Verifying fields, types, and filters for an already explicit or confirmed meaning is evidence completion, not a new business choice. Confirm a selected business mapping once, even when there is only one suitable candidate; reuse the task's already confirmed mappings.
 
 ### Saved business asset or ad-hoc
 
-If an exact asset or definition came from a knowledge-base page, first read and follow [`../ae-kb/references/analysis-workflow.md`](../ae-kb/references/analysis-workflow.md). Attempt the matched asset before using the ordinary fallback below. If it cannot produce a usable result, preserve that evidence, then follow the workflow's explicit fallback and disclosure rules.
+If an exact asset or definition came from a knowledge-base page, first read and follow [`../ae-kb/references/analysis-workflow.md`](../ae-kb/references/analysis-workflow.md). Inspect the live definition and attempt an exact, semantically applicable saved asset first. When inspection establishes a mismatch, missing fields, or partial coverage, continue ordinary discovery for the original request without a forced data query. Preserve useful KB evidence, resolve only missing metadata, and follow the workflow's authorized fallback and disclosure rules. A KB limitation is not itself task completion.
 
 Use a suitable saved report with supported requested overrides. For a custom combination, reuse the applicable definitions in an ad-hoc model. Read [`references/analysis_gateway_assets.md`](references/analysis_gateway_assets.md) for saved filters, dashboard context and asset selection. Load model references when constructing an ad-hoc definition.
 

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

@@ -2,6 +2,8 @@
 
 Use this to submit existing asset certification proposals for a human to review on the asset certification management page. This creates a review batch and notification, not an approval or certification. Do not use it to approve assets. Candidate discovery starts with `analysis-meta governance-recommendation export`; its `review_material_package` is the customer-visible handoff package for generating the page draft.
 
+After `analysis-meta governance-recommendation auto-review`, candidate discovery may instead come from `manual_review_handoff`. Use that path only when the user explicitly asks to submit assets that remained uncertified after automatic review. Submit `manual_review_handoff.page_review_items` so the review page can still render dashboard/report parent context; entries with `manual_review_context:true` are hierarchy/source context, while `manual_review_handoff.items` is the exact uncertified workload. Keep original evidence links and snapshots, include `manual_review_reason` / `auto_review_decision.display_reason` / `auto_review_decision.reason` in each uncertified item summary as reviewer-readable text, and copy `manual_review_handoff.auto_review_trace` into submit-to-page `source_metadata.auto_review_trace` so the page audit records show which assets Agent already certified automatically. Page-visible conflict reasons must describe semantic risk, such as suspicious duplicates, close meanings, or ambiguous business definitions, only when a concrete conflicting asset is returned; a historical decision code without a conflicting target must not be presented as duplicate evidence. Do not expose internal evidence-fingerprint or historical-audit-record wording.
+
 L2 admission: owned by Common ta-cli / AgentReviewService. Typed project and source flags, fixed ASSET_GOVERNANCE schema 1.0 defaults, local proposal validation, explicit stable request keys, and lossless string IDs add safety beyond generic JSON invocation. `submit-to-page` deliberately maps to `metadata.agent_review.create` so users cannot confuse it with the existing executing `governance-recommendation submit`. Other agent-review actions map directly to their capability action. All calls use the analysis Gateway route and CLI-token authentication.
 
 All seven review capabilities require the exact project function `assetAuthentication`, matching the shared service. Read actions, including evidence, require `metadata:read`; submission, review and retry require `metadata:write`. Each submission/decision/retry contains 1 to 5000 unique items; the domain service also enforces its packet size limit.

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

@@ -92,11 +92,16 @@ Formula rules:
 
 Saved formula report round-trip rules:
 
-- `analysis report get` can return saved formula metrics with `custom_filters`, `formulation`, `custom_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.
+- `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.
 - Continue to use the `formula + dependencies` shape above when authoring a new formula metric.
 
+Saved report filter round-trip rules:
+
+- `analysis report get` can return historical recursive filter groups in report-level or metric-level `filters`. A group is `{"relation":"and|or","items":[...]}`; `items` may contain leaf filters or nested groups. Preserve this tree on read.
+- Follow the shared saved-report boundary in [`../ai_models.md`](../ai_models.md): never flatten a deeper historical tree or keep only its last leaf. For a page-compatible tree, change only the requested leaf and retain all surrounding `relation` and `items` nodes before validating the complete definition.
+
 ## Aggregation
 
 - `event`: without property use `total_count`, `user_count`, or `per_user_count`; numeric properties support `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `median`, `percentile`, `variance`, and `stddev`; string/date/datetime properties support `distinct_count`; boolean properties support `true_count`, `false_count`, `not_empty_count`, `empty_count`, and `distinct_count`.

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

@@ -22,7 +22,13 @@ Use for ordered conversion steps with a conversion window.
 }
 ```
 
-If the user asks to match users across events by a shared event property, set `relation_event_property_name`.
+If the user asks to match users across events by a shared event property, set `funnel.relation_event_property_name`. For different property names in different events, set `funnel.steps[].relation_event_property_name`; each override takes precedence over the common property. Every step must have a relation property when any step uses one, and their property types must match.
+
+For saved reports, optional `funnel.steps[].display_name` sets the label shown for that funnel step. `analysis report get` returns the saved value, and report create/update writes it back, so preserve every step's `display_name` when replacing a definition. Omission uses the event's resolved display name.
+
+`funnel.start_step` and `funnel.end_step` preserve the selected conversion interval. They are one-based and must satisfy `1 <= start_step < end_step <= steps.length`; omission selects the whole funnel. A dimension's `funnel_step` selects the step providing its grouping value. Saved reports with an older global grouping step are read back with that step on each affected dimension.
+
+Queries and exports show the selected steps and calculate cumulative conversion from the selected starting population. For step populations `[4, 3, 2]`, selecting steps 2–3 returns `3 → 2` and `66.67%`; omitting the selection returns all three populations with cumulative rates `75%` and `50%`. Selecting a display interval does not remove the earlier events from the funnel's qualification rules.
 
 Step-level event-property filters belong inside the matching `funnel.steps[].filters`. Use `event_property_name`, not the common `field` object. `values` is an array of strings, including `"true"` / `"false"` for boolean properties; omit values for existence operators. For example, ordered registration -> login -> first payment:
 
@@ -32,9 +38,9 @@ Step-level event-property filters belong inside the matching `funnel.steps[].fil
   "time_particle_size": "day",
   "funnel": {
     "steps": [
-      {"event": "register"},
-      {"event": "login"},
-      {"event": "payment", "filters": [
+      {"event": "register", "display_name": "Completed registration"},
+      {"event": "login", "display_name": "Completed login"},
+      {"event": "payment", "display_name": "First payment", "filters": [
         {"event_property_name": "is_first_pay", "operator": "eq", "values": ["true"]}
       ]}
     ],
@@ -44,3 +50,5 @@ Step-level event-property filters belong inside the matching `funnel.steps[].fil
 ```
 
 Preserve step order, conversion window, and all requested filters when correcting input. Only actual funnel results support step counts and conversion rates; independent event UVs are not an ordered funnel.
+
+Step filters can also contain compound nodes such as `{"relation":"or","items":[{"event_property_name":"channel","operator":"eq","values":["app"]},{"event_property_name":"channel","operator":"eq","values":["web"]}]}`. Each nested leaf remains event-only. Relative-time leaf filters preserve `time_relative`, `time_unit`, and `relative_event_time_retention_phase`.

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

@@ -24,3 +24,26 @@ For property metrics, set `hot_property` and use a property aggregation such as
 ## Aggregation
 
 - `heat_map`: without property use `total_count`, `user_count`, or `per_user_count`; numeric properties support `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `median`, `variance`, and `stddev`; string/date/datetime properties support `distinct_count`; boolean properties support `true_count`, `false_count`, `not_empty_count`, `empty_count`, and `distinct_count`. `percentile` is not supported.
+
+## Comparison groups, processing, and canvas
+
+`heat_map.compared_groups` accepts uniquely named groups with independent recursive `filters` and `relation`. These are filtered groups within the selected time range. The heat-map engine does not support date comparison periods.
+
+`event_processing` selects one event per entity before heat aggregation. `mode` is `FIRST`, `LAST`, `MAX`, or `MIN`: FIRST/MIN select the minimum ordering value and LAST/MAX the maximum. By default the ordering value is event time; optional `property` selects a numeric, string, date, or datetime field. `filters` and `relation` select events eligible for processing.
+
+`canvas` limits coordinates to `x_min..x_max` and `y_min..y_max`. All four finite bounds are required, minima must not exceed maxima, and bounds support at most 10 integer digits and 4 decimal places. Optional `background` preserves an already uploaded image using `attachment_name`, `original_filename`, `created_at`, `width`, `height`, and `byte_size`. It does not upload a local file. Omit canvas to include all non-null coordinates.
+
+Example fields inside `heat_map`:
+
+```json
+{
+  "compared_groups": [
+    {"name": "Home page", "filters": [{"field": {"name": "page", "type": "event_property"}, "operator": "eq", "values": ["home"]}]},
+    {"name": "All pages"}
+  ],
+  "event_processing": {"mode": "LAST"},
+  "canvas": {"x_min": 0, "x_max": 1920, "y_min": 0, "y_max": 1080}
+}
+```
+
+Hot-event filters, comparison groups, processing conditions, and canvas bounds/background metadata survive report get → update → run. X/Y coordinate properties must be numeric.

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

@@ -18,3 +18,27 @@ Use for elapsed-time analysis between an initial event and a return event.
   }
 }
 ```
+
+`window.unit` accepts `minute`, `hour`, or `day`; its positive integer value must fit a millisecond duration. The native interval engine does not implement second/week/month windows, so those inputs are rejected instead of being interpreted as days.
+
+Use `relation_event_property_name` for a shared property, or `initial_relation_event_property_name` and `return_relation_event_property_name` for different properties. Each event-specific name overrides the shared name. Both resolved properties must have compatible types. `relation_comparison` defaults to `equal`; `higher_by`/`lower_by` mean the return value equals the initial value plus/minus `relation_difference`. These modes require numeric properties and a nonnegative integer difference; omit the difference for `equal`.
+
+Optional `interval` output settings:
+
+```json
+{
+  "initial_event": "level_start",
+  "return_event": "level_complete",
+  "window": {"value": 1, "unit": "day"},
+  "initial_relation_event_property_name": "start_level",
+  "return_relation_event_property_name": "end_level",
+  "relation_comparison": "higher_by",
+  "relation_difference": 2,
+  "buckets": {"mode": "custom", "unit": "minute", "boundaries": [1, 5, 30]},
+  "selected_statistics": ["avgValue", "percent95", "midValue"]
+}
+```
+
+`buckets` uses either `equal` with `count` from 2 to 30, or `custom` with 1–29 strictly increasing positive integer `boundaries` and `unit` (`second/minute/hour/day`). Do not mix the fields of the two modes. Omission keeps the native 12-subdivision default.
+
+`selected_statistics` controls the ordered statistic columns, including exports. Values: `maxValue`, `threeQuarterValue`, `midValue`, `quarterValue`, `minValue`, `avgValue`, `percent99`, `percent95`, `percent90`, `percent80`, `percent70`, `percent60`, `percent40`, `percent30`, `percent20`, `percent10`, `percent5`. Omission uses the first six; `[]` selects none. Duplicates are invalid. Relation conditions, buckets, and statistics survive report get → update → run.

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

@@ -53,3 +53,23 @@ for level in result["links"]:
 ```
 
 For path analysis, `preview_rows` is a graph-display boundary aligned with the analysis UI: it keeps up to that many real nodes per path level, then combines overflow nodes into `more`. `result.nodes` retains the synthesized `more` node for graph structure and drilldown coordinates. The top-level `returned_rows` counts real business nodes actually returned across all levels; it excludes synthesized `more` nodes and the real nodes folded into them. The count may still exceed `preview_rows` because the boundary applies independently to each level. `has_more=true` means at least one level contains real nodes folded into `more`; a linear multi-level path can return more real nodes than `preview_rows` with `has_more=false`.
+
+## Source filters, event splits, and limits
+
+`path.source_filters` selects source-event occurrences using event-property leaves (`event_property_name`, `operator`, and string `values`) or recursive `items`/`relation` groups. `path.source_filter_relation` combines the top-level source filters. Global `filters` still accept only user properties, tags, and clusters; nested groups and supported relative-time conditions are preserved.
+
+`path.event_splits` splits individual included events into property-value nodes:
+
+```json
+{
+  "source_filters": [{"event_property_name": "amount", "operator": "gt", "values": ["10"]}],
+  "event_splits": [{
+    "event": "purchase", "event_property_name": "amount",
+    "bucket_mode": "custom", "bucket_boundaries": [10, 100]
+  }],
+  "max_steps": 4,
+  "max_nodes_per_step": 12
+}
+```
+
+Each split event must occur in `included_events` and can appear only once in `event_splits`. Numeric bucket, array grouping, and time granularity options follow the shared dimension contract. `max_steps` is 1–30 (default 10); `max_nodes_per_step` is 7–30 (default 7). Retention-only filter phase and dimension options are invalid for path analysis. Report reads preserve these settings for subsequent updates.

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

@@ -41,3 +41,5 @@ For property aggregations, pass the user property:
 ## Aggregation
 
 - `prop_analysis`: use `user_count` without property; numeric properties support `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `median`, `variance`, and `stddev`; string/date/datetime properties support `distinct_count`; boolean properties support `true_count`, `false_count`, `not_empty_count`, `empty_count`, and `distinct_count`. `percentile` is not supported.
+
+Global `filters` and `user_crowds[].filters` both support recursive `items`/`relation` groups. Date/time leaves preserve the shared relative-time options, and tag/cluster leaves preserve `cluster_date_policy` plus `specified_cluster_date`. A saved report read retains crowd names, crowd filter trees, and each crowd's relation. Keep these when updating the report; do not replace a selected crowd with all users.

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

@@ -23,3 +23,33 @@ Use for ranking users/entities by an event metric.
 ## Aggregation
 
 - `rank_list`: without property use `total_count`, `user_count`, or `per_user_count`; numeric properties support `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `median`, `variance`, and `stddev`; string/date/datetime properties support `distinct_count`; boolean properties support `true_count`, `false_count`, `not_empty_count`, `empty_count`, and `distinct_count`. `percentile` is not supported.
+
+## Metric filters, accompanying columns, and formulas
+
+- `rank_filters` and `rank_relation` apply only to the primary regular ranking metric. `filters` and `relation` apply globally. Both filter arrays preserve compound groups and relative-time conditions.
+- `accompanying_metrics` is an ordered array of event metric definitions (`event`, `aggregation`, `property`, `filters`, `relation`, or `formula`/`dependencies`). Each entry can set `order_by: "ASC"|"DESC"|"NONE"`; default `NONE` displays the metric without using it to break ties. Backend limits on the number of columns still apply.
+- `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.
+
+```json
+{
+  "rank_dimension": {"field":{"name":"#account_id","type":"user_property"}},
+  "rank_formula": {
+    "formula": "revenue / users",
+    "dependencies": [
+      {"alias":"revenue","event":"purchase","aggregation":"sum","property":"amount"},
+      {"alias":"users","event":"purchase","aggregation":"user_count"}
+    ]
+  },
+  "order_by": "DESC",
+  "accompanying_metrics": [{"event":"purchase","aggregation":"total_count","order_by":"ASC"}],
+  "accompanying_properties": [{"field":{"name":"country","type":"user_property"}}]
+}
+```
+
+Use the object above as `rank_list` inside a definition with `time_range`. Saved report reads retain the primary filters, accompanying columns, their ordering, and formula definitions; preserve all of them during updates.
+
+Ranking accepts one root `comparison_time_ranges` entry using the shared event comparison shape, for example `[{"mode":"previous_period","display_name":"Previous period"}]`. The native ranking engine supports at most one comparison period; multiple entries are rejected. Preserve the returned comparison period on report edits so the comparison values and rank changes remain available.
+
+Preserve `rank_quota_entities` returned for a regular primary ranking metric. Formula ranking keeps its identity overrides inside `rank_formula.quota_entities`; accompanying metrics keep theirs inside each `quota_entities`. These independent identities affect distinct-user counts and per-user denominators and must survive saved-report edits. Do not supply regular `rank_quota_entities` together with `rank_formula`.

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

@@ -56,7 +56,51 @@ Initial-event and return-event property filters use the retention-specific shape
 
 ## Aggregation
 
-- `retention` simultaneous metrics: without property use `total_count`, `user_count`, or `per_user_count`; numeric properties support only `sum` and `avg_per_user`; boolean properties support only `true_count`, `false_count`, `not_empty_count`, and `empty_count`.
+- `retention` simultaneous metrics: without property use `total_count`, `user_count`, or `per_user_count`; numeric properties support `sum`, `avg_per_user`, and `cumulative_avg_per_user` (the saved page's A114 stage accumulated per-user value); boolean properties support only `true_count`, `false_count`, `not_empty_count`, and `empty_count`. `cumulative_avg_per_user` requires the matching Common round-trip fix; it is not a supported event-analysis aggregation.
+
+## Saved formula round trips
+
+`analysis report get` preserves a saved simultaneous formula's `formulation`, `custom_filters`, `custom_event_desc`, `event_desc`, `format`, and `event_type` when present. Keep these fields unchanged when updating the returned definition. In particular, `custom_filters[].index` binds filters to each formula occurrence. Do not replace these saved fields with newly inferred dependencies. New formulas still require `formula` plus explicit `dependencies`.
+
+## Metric roles and combination
+
+`retention.simultaneous_metrics` supports at most one `return_users` metric (the default role) and one `initial_date` metric. The latter measures users on their cohort entry date. Repeated roles are rejected because the engine has one calculation slot per role.
+
+```json
+{
+  "simultaneous_metrics": [
+    {
+      "role": "return_users", "event": "payment", "aggregation": "sum", "property": "amount",
+      "filters": [{"event_property_name": "currency", "operator": "eq", "values": ["CNY"]}],
+      "relation": "and", "format": "float3"
+    },
+    {
+      "role": "initial_date", "event": "register", "aggregation": "user_count",
+      "combine_operator": "DIVIDE", "initial_date_first": false, "combined_format": "float4"
+    }
+  ]
+}
+```
+
+Place this object inside `retention`. `combine_operator` belongs to `initial_date` and requires both roles; allowed values are `ADD`, `SUBTRACT`, `MULTIPLY`, and `DIVIDE`. `initial_date_first=false` puts the return-user metric first. The example divides return-user revenue by the initial-date user count. `initial_date_first` and `combined_format` require a combination operator. Number formats are `float`, `float3`, `float4`, `percent`, and `integer`.
+
+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.
+
+`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
+
+| Field inside `retention` | Values and meaning |
+| --- | --- |
+| `group_mode` | `RANGE_FIRST`: first initial event in the range; `PERIOD_FIRST`: first initial event per day/week/month; `PERIOD_EACH`: every initial event per period. Omission preserves the environment default. |
+| `return_group_mode` | `RANGE_FIRST` or `RANGE_EACH` for return-event grouping. |
+| `relation_property_as_group` | Whether to include the relation property in result groups; omission preserves the native default. |
+| `summary_first_day_of_week` | Monday `1` through Sunday `7`, for weekly summary rows. |
+| `hide_incomplete_data` | Whether to hide incomplete retention periods. |
+| `only_simultaneous_metrics` | Show only simultaneous metrics; defaults to true when metrics are supplied. |
+| `stage_summary` | `initial_users`, `retained_users`, and `initial_date_metric`: `sum` or `avg`; `simultaneous_metric`: `sum`, `avg`, or `weight_avg`. |
+
+Dimension `retention_source` chooses `initial_event` or `return_event`. Preserve all returned grouping and summary settings during report edits: they affect populations and reported values. `unit_num` must be nonnegative; `stat_type` accepts only `retention` or `lost`.
 
 ## Returned rows
 

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

@@ -20,9 +20,27 @@ Use for revenue cohort metrics such as LTV, ROI, revenue, and cost.
 ```
 
 `cost_metric` is optional when the user does not ask for cost/ROI.
-`selected_metrics` supports `payUsers`, `payAmount`, `cumPayUsers`, `cumPayAmount`, `payRate`, `cumPayRate`, `ltv`, `ltvMultiple`, and `roi`.
-Select at most four metrics per query. The revenue service keeps only the first four supported selections and removes ROI when cost is absent. If more metrics are required, split the selections into non-overlapping batches with the same definition and scope, then join results by verified cohort/group keys. Check returned titles for every requested metric; a successful response alone does not prove full metric coverage.
+`selected_metrics` supports `payUsers`, `payAmount`, `cumPayUsers`, `cumPayAmount`, `payRate`, `cumPayRate`, `ltv`, `ltvMultiple`, `rollingLtv`, and `roi`.
+Select at most four metrics per query. The semantic compiler rejects more than four selections and requires `cost_metric` when `roi` is selected. If more metrics are required, split the selections into non-overlapping batches with the same definition and scope, then join results by verified cohort/group keys. Check returned titles for every requested metric; a successful response alone does not prove full metric coverage.
 
 ## Aggregation
 
 - `revenue`: without property use `total_count`, `user_count`, or `per_user_count`; numeric properties support `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `median`, `variance`, and `stddev`; string/date/datetime properties support `distinct_count`; boolean properties support `true_count`, `false_count`, `not_empty_count`, `empty_count`, and `distinct_count`. `percentile` is not supported.
+
+## Formula revenue and cost metrics
+
+Both `revenue_metric` and `cost_metric` accept a formula with alias dependencies. Omit `event`, `aggregation`, `property`, `filters`, and `relation` on formula metrics; each dependency supplies its own event and aggregation. Regular revenue metrics default to the pay event, and regular cost metrics default to the initial event when `event` is omitted.
+
+```json
+{
+  "formula": "amount / users",
+  "dependencies": [
+    {"alias": "amount", "event": "purchase", "aggregation": "sum", "property": "amount"},
+    {"alias": "users", "event": "purchase", "aggregation": "user_count"}
+  ],
+  "name": "ARPPU",
+  "format": "float3"
+}
+```
+
+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).

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

@@ -17,3 +17,5 @@ Use only with `analysis report create/update`; do not use with `analysis adhoc r
 ```
 
 Prefer `time_range` for new tag reports. `recent_day`, `start_time`, and `end_time` are only for report readback or precise round-trip updates.
+
+Historical tag report `time_particle_size` accepts only `day` or omission. Other grains, including `total`, `week`, and `month`, are rejected instead of being silently converted to day. Date-tag value grouping uses the separate `time_particle` field; it does not change the historical snapshot grain. Root `first_day_of_week` applies to calendar grouping and accepts 1 through 7.