@thinkingai/ae-cli 6.1.20 → 6.1.21

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

@@ -0,0 +1,184 @@
+# analysis-meta agent-review submit-to-page
+
+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.
+
+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.
+
+```bash
+ae-cli analysis-meta agent-review submit-to-page \
+  --project-id 1 --title 'Retention asset review' \
+  --source-run-id rec_source --source-task-id task_review \
+  --client-request-id review_task_proposal_001 \
+  --ai-summary '{"summary":"Evidence-backed retention assets"}' \
+  --presentation-snapshot '{"project":{"name":"Example"},"evidenceDate":"2026-09-08","topics":[{"id":"retention","name":"Retention","groups":[{"id":"retention_core","name":"核心留存看板","items":[{"id":"dashboard_1"},{"id":"report_1"},{"id":"event_login"}]}]}],"relations":[{"parent":"dashboard_1","child":"report_1","type":"contains"},{"parent":"report_1","child":"event_login","type":"uses"}],"analysisByItem":{}}' \
+  --items '[{"client_item_id":"dashboard_1","target_ref":{"type":"dashboard","key":"1"},"action_type":"CERTIFY","proposal_payload":{"authentication_status":1},"ai_summary":{"summary":"<verified dashboard recommendation basis; main risks or explicit evidence gaps>"},"evidence_snapshot":{"source_run_id":"rec_source"}},{"client_item_id":"report_1","target_ref":{"type":"report","key":"1"},"action_type":"CERTIFY","proposal_payload":{"authentication_status":1},"ai_summary":{"summary":"<verified report recommendation basis; main risks or explicit evidence gaps>"},"evidence_snapshot":{"source_run_id":"rec_source"}},{"client_item_id":"event_login","target_ref":{"type":"event","key":"login"},"action_type":"CERTIFY","proposal_payload":{"authentication_status":1},"ai_summary":{"summary":"<verified metadata recommendation basis; main risks or explicit evidence gaps>"},"evidence_snapshot":{"source_run_id":"rec_source"}}]' \
+  --dry-run
+```
+
+Large real drafts should be submitted as a local file instead of shell-escaped JSON:
+
+```bash
+ae-cli analysis-meta governance-recommendation export \
+  --project-id 1 --limit 20 --format json > recommendation-export.json
+
+# The Agent turns review_material_package into submit-to-page-draft.json:
+# ai_summary, presentation_snapshot, item ai_summary/reasons, evidence_snapshot.
+ae-cli analysis-meta agent-review submit-to-page \
+  --project-id 1 \
+  --client-request-id review_task_proposal_001 \
+  --input-file submit-to-page-draft.json \
+  --dry-run
+```
+
+`submit-to-page-draft.json` must follow this customer/Agent contract. `--project-id` and `--client-request-id` are still supplied as CLI flags so a replay keeps the same project and stable operation key:
+
+```json
+{
+  "review_type": "ASSET_GOVERNANCE",
+  "schema_version": "1.0",
+  "title": "<review batch title>",
+  "source_run_id": "<governance-recommendation export run_id>",
+  "source_task_id": "<optional preauthorized task id>",
+  "ai_summary": {
+    "summary": "<batch overview generated by the Agent from the material package>"
+  },
+  "presentation_snapshot": {
+    "project": {
+      "id": 1,
+      "name": "<project name>"
+    },
+    "evidenceDate": "YYYY-MM-DD",
+    "topics": [
+      {
+        "id": "<business-domain-id>",
+        "name": "<business-domain-name>",
+        "groups": [
+          {
+            "id": "<second-level-group-id>",
+            "name": "<second-level group or source dashboard>",
+            "items": [
+              { "id": "<client_item_id>" }
+            ]
+          }
+        ]
+      }
+    ],
+    "relations": [
+      { "parent": "<dashboard item id>", "child": "<report item id>", "type": "contains" },
+      { "parent": "<report item id>", "child": "<metadata item id>", "type": "uses" }
+    ],
+    "analysisByItem": {}
+  },
+  "items": [
+    {
+      "client_item_id": "<stable item id used by presentation_snapshot>",
+      "target_ref": {
+        "type": "dashboard|report|event|event_prop|user_prop|user_tag|user_cluster|metric",
+        "key": "<lossless target key>"
+      },
+      "action_type": "CERTIFY",
+      "proposal_payload": {
+        "authentication_status": 1
+      },
+      "source_link": "<copied source URL>",
+      "evidence_links": [
+        { "label": "<source label>", "url": "<copied evidence URL>" }
+      ],
+      "evidence_snapshot": {
+        "analysis": "<Common packaged evidence when available>",
+        "target_revision": "<definition version/hash>"
+      },
+      "ai_summary": {
+        "summary": "<item reason with evidence basis and risks>",
+        "analysis_explanation": {
+          "business_purpose": "<what the reviewer uses this asset for>",
+          "measures": [
+            {
+              "statement": "<measure explanation>",
+              "evidence_refs": ["evidence_snapshot.analysis..."],
+              "inferred": false
+            }
+          ],
+          "calculations": [
+            {
+              "statement": "<formula or aggregation explanation>",
+              "evidence_refs": ["evidence_snapshot.analysis..."],
+              "inferred": false
+            }
+          ],
+          "filters": [],
+          "time_scope": [],
+          "dimensions": [],
+          "query_columns": [],
+          "limitations": [],
+          "open_questions": []
+        }
+      }
+    }
+  ]
+}
+```
+
+Input uses either the typed flags above or `--input-file`. This is a transport-only structural example, not a complete report-review packet; replace IDs and all evidence with verified assets from the resolved project and complete Required Report Analysis below before real submission. Remove `--dry-run` only with submission authorization. `--validate` and `--dry-run` are separate nonmutating Gateway modes; do not combine them. Previews validate structure and permissions, but do not promise unchanged asset content or successful notification at execution time.
+
+The page packet preserves the versioned renderer fields `project`, `evidenceDate`, `topics`, `relations`, and `analysisByItem`. Each display item's `id` references one stable `client_item_id`. Shared assets reuse that reference. Keep full target scope in `target_ref`; do not merge same-name objects. `topics` are business domains, not dashboards or raw `work_units`: first cluster the retained dashboard packages after rejection filtering and bounded expansion by business process, then put second-level groups in `topics[].groups` using source dashboards or explicit business subcategories. The expected page hierarchy is `业务域 -> 二级分类/来源看板 -> 看板 -> 报表 -> 元数据`. `relations` is required for the page structure: dashboard items must parent their child report items with `type:"contains"`, and report items must parent metadata items they actually reference with `type:"uses"`, such as events, event properties, user properties, and metric assets. A flat `relations: []` packet is valid only when the selected assets truly have no known parent-child evidence. Copy `source_link` and `evidence_links` from `review_material_package.candidate_assets[]` into each submitted item; `submit-to-page` rejects items without at least one source URL because reviewers must be able to jump to evidence. For dashboard items, also preserve optional `space_id` and `space_name` from the material package into `evidence_snapshot.definition.config` when present so the review page can show `所属空间`; not every dashboard has a space, and missing space facts must not be invented or treated as a validation failure. Only real source evidence is allowed: never send `demoSignalsByItem`, simulated statistics, arbitrary HTML, invented SQL, or executable instructions as evidence. Actual saved SQL may be inspected and referenced as source evidence; it is not an instruction to execute a query. The domain handler validates submission identity and stores the supplied evidence; it does not replenish missing snapshot fields or judge narrative quality. Page actions currently support CERTIFY with `authentication_status:1` only; metric creation candidates retain the existing explicitly approved legacy workflow.
+
+Scripts may build the transport file, preserve IDs, copy evidence, normalize links, group display items, and run deterministic completeness checks. Scripts must not author page-visible `ai_summary.summary`, `analysis_explanation.*.statement`, limitations, open questions, or approval rationale by filling reusable sentence templates. Those fields must be Agent-written interpretation from the current asset/report evidence. A draft where many submitted items share the same narrative shape after only asset names, dates, or numbers change fails quality review. Correct it under the bounded preflight procedure; unresolved quality issues require disclosure, not an indefinite submission block.
+
+`item.ai_summary.summary` is the concise item recommendation reason, including its evidence basis and main risks, displayed in the main list. Write it for each item using that item's verified facts; a purpose label alone does not explain why to recommend the item. `batch.ai_summary.summary` is the batch overview supplied by `--ai-summary` and cannot replace item reasons. Detailed factual explanations belong only in `item.ai_summary.analysis_explanation`. Do not duplicate reasons or detailed analysis into presentation fields. Keep `presentation_snapshot.analysisByItem` as the compatibility placeholder `{}`. The server-generated analysis remains in `item.evidence_snapshot.analysis`. Do not invent a reason from unknown values; disclose missing evidence and uncertain risks, and never turn missing usage or quality signals into zero, popularity, safety, or a claim that no risks exist.
+
+For dashboard, report, and SQL report drafts, write the page-visible explanation with the same intent as the project-KB source file's single `Agent 使用摘要`: business purpose, calculation caliber, input/date/filter meaning, output fields or measures, applicable questions, non-applicable questions, and concrete reviewer confirmations. The review page does not need a second SQL-specific section or a source-code reading note. If the packaged evidence includes SQL, use the SQL only as source material for business interpretation; keep raw SQL, parser output, and unresolved parameter tokens in `evidence_snapshot.analysis`. If a fact is not supported, write the business-facing unknown or confirmation question, for example "确认日期参数默认范围和是否包含测试数据", instead of copying `${PartDate:...}`, `selector3`, `parse_status`, or `DYNAMIC`.
+
+Write all page-visible review text for a business reviewer. `item.ai_summary.summary`, `business_purpose`, `calculations`, `filters`, `time_scope`, `limitations`, `open_questions`, and presentation labels must use plain Chinese that explains purpose, calculation 口径, date/filter choices, and reviewer action. Saved business event names and field names such as `agent_session_message_send`, `session_id`, and `response_duration` may appear when they help the reviewer verify the 口径. While drafting, avoid template copy such as “保存定义摘要”, “审核时需确认口径”, “本草稿不改写 SQL”, “其下报表和依赖元数据已随同提交审核”, or a sentence that only repeats asset name + heat + 未认证. Such copy is a quality finding handled by the bounded correction/warning procedure, not an unconditional dispatch ban. The item reason must answer why this exact asset is worth reviewing now, which saved definition facts support it, and what concrete risk remains. Keep implementation vocabulary out of visible text: do not show `SAVED_REPORT_ONLY`, `DYNAMIC`, `REPORT`, `T1`, temporary SQL aliases such as `a0`/`a1`, runtime parameter names such as `Variable2`/`selector3`/`PartDate date1`, `source_path`, `evidence_snapshot`, raw JSON, raw SQL, projection/select-column jargon, hash/revision values, dashboard-override limitations, timezone-not-saved notes, or “query not proven/executed/returned rows” caveats. Convert them to reviewer decisions only when material: for example `T1`/`day` means `按天`, and dynamic SQL parameter uncertainty becomes “确认参数含义、默认日期范围和是否包含测试数据”.
+
+## Normal Submission Workflow
+
+Every item needs an Agent assessment of review urgency and related-definition comparisons, not just a narrative summary. Follow [Priority and Definition Comparisons](agent_review_priorities_comparisons.md): use `ai_summary.recommendation.priority` / `priority_reason` / `evidence_refs`, classified `ai_summary.comparisons[]`, and `ai_summary.comparison_review` coverage. These are stored inside the existing AI summary object; they are not top-level packet fields or new Common admission checks. Unknown priority stays unassessed; LOW is lower review urgency, not a defer decision. Only POSSIBLE_CONFLICT comparisons should create conflict badges, with reciprocal links between both in-packet assets. Empty comparisons without recorded coverage do not mean no conflict. Older page versions may label all comparisons as conflicts: verify renderer support before authorized dispatch and disclose compatibility gaps rather than silently mislabeling non-conflicts.
+
+For both normal submission preparation and no-submit material checks, [Independent Agent Preflight](agent_review_preflight.md) is mandatory before step 5. A fresh-context reviewer checks the raw sources and exact draft; author self-checks or CLI dry-run success do not replace that review. In `LOCAL_ONLY` mode, stop after local review and do not execute steps 5-7. Preserve every original snapshot field, especially `signals`, even when absent from the abbreviated JSON example above. Common does not restore omitted evidence.
+
+1. Resolve the project and exact asset identities, then obtain the current recommendation export. Keep target keys, `run_id`, `snapshot_hash`, and `review_material_package` intact; do not bind same-name assets by guesswork. Apply [Rejection Filtering and Bounded Expansion](governance_recommendation_export.md#rejection-filtering-and-bounded-expansion) before drafting: start at 20, filter to pending review work, expand to 50 then 100 only if pending assets or visible business domains are insufficient, and use the latest successful packet.
+2. Apply the daily review capacity before drafting. Unless the user requests otherwise, select about 20-50 pending review assets, never more than about 80, and balance roughly 3-6 visible business domains with per-domain quotas. Rank pending candidates by impact, heat, user count, dependency breadth, and under-covered business domains. Keep overflow counts/domains for the batch summary and later batches.
+3. Generate the review draft from `review_material_package`: candidate items, heat evidence, copied `source_link` / `evidence_links`, relations, report/AI-model definition summaries, versions/hash, batch `ai_summary`, item reasons, and Agent-generated `presentation_snapshot.topics[].groups`. Only create visible topics for business domains that contain selected pending review assets. Authenticated/completed assets may be included as direct context under those topics, but zero-pending domains must not be submitted as standalone page sections.
+4. Fetch `analysis-meta agent-review evidence` only for targets whose material package marks a definition or analysis gap, or when validating a generated draft. Read [the stable analysis field reference](agent_review_evidence.md), inspect the returned `evidence_snapshot.analysis`, parse status, limitations, hash and revision. Do not ask customers to manually run `analysis report get` for every report.
+5. Draft AI explanations and per-item priorities from packaged definitions and current Common evidence, then run cross-asset comparisons over merged chunks before independent preflight. Select real, fact-supporting paths before submission; keep original facts separate from AI interpretation and disclose missing, null or dynamic evidence. The same maximum 3 correction attempts covers explanations, priorities and comparisons together.
+6. With current submission authorization, submit after independent preflight PASS or the bounded warning-continuation outcome in [preflight](agent_review_preflight.md#continue-with-disclosed-quality-issues). At most 3 corrections are allowed; remaining quality failures must be disclosed in the batch overview and affected-item notes, without relabeling the quality verdict PASS. Submit the final hash-recorded material with `submit-to-page --input-file <draft.json>` and a stable `client_request_id`. Preserve the original source-run identity on network replay. Evidence fetching, preflight PASS and retry exhaustion never supply submission or approval authorization. Ordinary structural/API failures cannot be bypassed.
+7. Read detail and compare the stored snapshot with the final dispatched material and source facts. Track the last reviewed draft separately from warning-only additions so those disclosed additions are not mistaken for storage changes. After submission, read detail and check that those paths resolve, still support the claims, and that `presentation_snapshot.relations` can render 看板 -> 报表 -> 元数据 for the submitted assets. `evidence_hash` includes collection time and can differ across reads; `target_revision` corresponds to the saved definition, not all sampled signals. Do not treat a changed full snapshot hash as a cross-scan business change or require it to equal the preview hash. If important facts changed or hierarchy is missing, report the mismatch; do not silently rewrite explanations, approve, or resubmit. Inspect records only for actual review/execution outcomes.
+8. Return the `review_page_url` field from `submit-to-page` when it is present. If only `review_url` is returned, treat it as a relative product-page path and prepend the public AE web host, not a local Common/API host. Never tell a reviewer to open `http://127.0.0.1:8992/#/...` or another backend capability host as the review page.
+
+## Required Report Analysis
+
+Before real page submission, verify the filtering and scope rules in [Rejection Filtering and Bounded Expansion](governance_recommendation_export.md#rejection-filtering-and-bounded-expansion). No same-definition rejected dashboard or its removed display branch may remain in submitted items, groups, topics, or relations; shared assets may remain under other retained dashboards. Active deferrals and items already in unfinished review batches must be excluded from pending work when that state is available. Verify that all displayed references resolve and that counts reflect the retained graph. Include eligible pending assets across the retained branches rather than a few representative themes. The initial top 20 is a candidate pool, not a submission quota; expand to 50 then 100 when pending review assets or visible business domains are insufficient, and stop at 100 or earlier when sufficient or exhausted. The final page batch is still capped for human review capacity: default target about 20-50 pending assets, hard cap about 80, roughly 3-6 visible domains, with per-domain quotas before adding extra assets from one domain. Explain the final scope, overflow and shortfall, and do not submit an empty batch. Business themes organize this retained coverage; merge dashboards describing the same business process instead of copying source order into one topic per dashboard. Do not submit a business topic whose displayed assets are all authenticated/completed context.
+
+Generate Agent-written narrative only for material that the reviewer will actually see as work: the batch overview, visible business domains, and pending review assets. Hidden domains and pure authenticated context rows should keep copied evidence, signals, links, snapshots and relations, but should not receive long new `ai_summary.summary` or `analysis_explanation` prose unless needed to explain a visible pending item.
+
+Before drafting every report proposal, use the definition and analysis embedded in `review_material_package` first. Current Common export should place report `evidence_snapshot.analysis` and `target_revision` under `review_material_package.candidate_assets`; this is the normal path and should not require an extra report-definition command per report. Call `analysis-meta agent-review evidence` only for report items whose package analysis is missing, stale, or explicitly marked as a gap. Inspect the returned `model_type`, normalized definition, saved SQL, parameters, output columns, filters, grouping, and hashes for SQL reports. A report name, purpose, screenshot, or prior AI summary does not replace the definition. Do not execute report data merely to inspect calculation logic. If a required definition is absent from the package and evidence endpoint, report a material gap instead of submitting a purpose-only explanation.
+
+After reading each report from the material package, draft its interpretation from the packaged analysis. Fetch `agent-review evidence` only for the gap cases above or for spot validation of the generated draft. Store AI interpretation in `item.ai_summary.analysis_explanation`, not in the authoritative `evidence_snapshot.analysis`. Common create stores the submitted packet for page review; it does not repair a missing Agent calculation explanation during create. Agent-supplied snapshots, SQL text, columns, hashes, or a `verified` flag cannot manufacture server evidence. The renderer consumes the stored explanation, not a new AI answer on page load.
+
+Before a real `submit-to-page` call, run a local completeness check over the exact payload: every report item must contain current `evidence_snapshot.analysis`, and must contain reviewer-readable `item.ai_summary.analysis_explanation.calculations` or `item.ai_summary.analysis_explanation.measures`. A purpose-only report summary is incomplete; missing required analysis or resolvable evidence references still fails structural validation. Do not invent either to force submission. Dashboard items may summarize the child reports, but their own missing calculation analysis is not a blocker because the actual calculation belongs to the reports below the dashboard.
+
+The independent Agent review must include narrative-quality checks before dispatch: flag generic summaries, repeated sentence templates, and repeated limitation/open-question text that does not name the specific unresolved evidence. The author must repair concrete findings, with at most 3 correction/re-review attempts. After the limit, continue an already authorized submission with unresolved findings disclosed; LOCAL_ONLY remains local. These are Agent quality findings, not CLI or Common narrative admission checks. Passing structural checks does not prove that explanations were model-generated or business-correct.
+
+Use arrays of `{ "statement": "...", "evidence_refs": ["..."], "inferred": false }` for the following explanation sections. The statements are AI interpretations; factual clauses require exact, Common-verifiable paths rooted at `evidence_snapshot.analysis`. Use only paths present in the current evidence response that support the retrieved source facts; do not invent field names, array indexes, aliases, or references. `source_path` identifies provenance and is not automatically an AI evidence reference. After submission, read detail and check that those paths resolve in the server-returned snapshot. An unresolved path is missing evidence, not a verified fact. For `DYNAMIC` SQL, follow the original-text-only rules in [agent_review_evidence.md](agent_review_evidence.md); do not manufacture parsed projections or runtime values.
+
+| Section         | Required interpretation when source evidence is available                                                                                                                                                                                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `measures`      | Explain every statistical measure: what is counted or aggregated, its unit and population, and whether it counts rows, events, or distinct users. Do not infer business meaning from an alias alone.                                                                                                 |
+| `dimensions`    | Explain actual grouping, breakdown, grain, and dimension expressions, keeping technical keys and display names distinct.                                                                                                                                                                             |
+| `calculations`  | Explain actual formulas and aggregation steps, including numerators, denominators, distinctness, conditional logic, null handling, windows, or join effects where present in the source. Do not invent an unstated calculation rule.                                                                 |
+| `filters`       | Explain saved predicates, their AND/OR relationships and scope, and the difference between row filters and post-aggregation filters where applicable. Missing filters do not prove that the query has no constraints.                                                                                |
+| `time_scope`    | Explain the saved time field, range or relative window, timezone, time grain, and date parameters only where verified. Separate report query time from asset-usage statistics windows. Unbound runtime parameters remain unresolved.                                                                 |
+| `query_columns` | For SQL reports, explain each SELECT projection in source order: the verified alias or unnamed expression, calculation, and supported source lineage. Projection columns are not all columns of the source tables. Preserve duplicate aliases and positional identity; do not merge columns by name. |
+
+Keep `business_purpose`, `reading`, and `limitations` alongside these sections; purpose alone is insufficient. Mark genuine business interpretation as `inferred:true` and retain the evidence behind it. Put unavailable definitions, unsupported model extraction, SQL parse failures, unexpanded `SELECT *`, unresolved parameters, or unknown units/lineage in `limitations` or `open_questions`; leave unsupported factual sections empty instead of filling them with plausible prose. Do not expand wildcard columns from guesses or present a best-effort parse as complete. A constant-only acceptance query is test evidence, not a real business statistic.
+
+Never guess or rewrite saved SQL, projected columns, or formulas to make a recommendation look complete. Reading a definition, obtaining deterministic analysis, passing validation/dry-run, or creating a review batch does not prove the query ran successfully, produced real rows, or certified the asset. Actual success claims require their corresponding execution result and review records. Missing analysis evidence must be disclosed rather than replaced with a purpose-only claim of complete review.
+
+Before writing, consult the user's current intent. Submission can be offered once; declining produces no write. Prior explicit submission authorization does not require repeated permission. A preauthorized unattended task only submits proposals and never approves, retries certification, invokes legacy submit, or creates metrics.
+
+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.

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

@@ -0,0 +1,29 @@
+# `attribution` AI-facing definition
+
+Shared input: [common building blocks](../ai_models.md#common-building-blocks).
+
+Use to attribute target conversions to touchpoint/source events.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 14},
+  "attribution": {
+    "target_event": "purchase",
+    "target_aggregation": "total_count",
+    "attribution_events": [
+      {"event": "ad_click"},
+      {"event": "campaign_view"}
+    ],
+    "attribution_model": "first",
+    "window": {"value": 7, "unit": "day"},
+    "direct_conversion": true
+  }
+}
+```
+
+`attribution_model` values: `first`, `last`, or `linear`.
+The target aggregation is intentionally narrow: use `total_count` without a property, or `sum` with a numeric `target_property`. Do not use `user_count`.
+
+## Aggregation
+
+- `attribution`: use `total_count` without `target_property`, or `sum` with a numeric `target_property`.

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

@@ -0,0 +1,40 @@
+# `distribution` AI-facing definition
+
+Shared input: [common building blocks](../ai_models.md#common-building-blocks).
+
+Use for user distribution buckets for an event or property metric.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "distribution_metrics": [
+    {
+      "event": "purchase",
+      "aggregation": "sum",
+      "property": "amount",
+      "filters": [
+        {
+          "field": {"name": "vip_users", "type": "cluster"},
+          "operator": "in_cluster"
+        }
+      ],
+      "relation": "and",
+      "interval_type": "user_defined",
+      "quota_interval_arr": [100, 1000, 10000]
+    }
+  ],
+  "groups": [
+    {"field": {"name": "country", "type": "user_property"}}
+  ]
+}
+```
+
+Use `interval_type=def` for automatic buckets, `user_defined` for explicit numeric boundaries, and `discrete` to group by raw values.
+
+Distribution filters must be attached to the corresponding `distribution_metrics[].filters`.
+Do not use top-level `filters` or `relation` in a distribution definition.
+When multiple metrics need the same filter, attach it to each metric explicitly. If the requested filter scope is ambiguous, clarify which metric it applies to before running the analysis.
+
+## Aggregation
+
+- `distribution`: without property use `count`, `active_days`, or `active_hours`; numeric properties support `sum`, `avg`, `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/event.md

@@ -0,0 +1,108 @@
+# `event` AI-facing definition
+
+Shared input: [common building blocks](../ai_models.md#common-building-blocks).
+
+Use for event metrics, trends, grouping, filters, and comparisons.
+
+## Unknown business metric
+
+When the requested metric's event, aggregation or property is unknown, resolve it with [`../metadata_resolution.md`](../metadata_resolution.md), confirm the business mapping once, then submit the complete definition:
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "metrics": [{"event": "<confirmed canonical event>", "aggregation": "<confirmed aggregation>"}]
+}
+```
+
+A verified saved metric uses `{"event":"<verified_metric_name>"}` and supplies its own aggregation and property; omit those two fields when referencing it. An event measure requires a compatible aggregation and, when applicable, property. Do not invent an amount property to satisfy `sum`; discover the selected event's properties when needed. Reuse a verified canonical definition directly.
+
+## Event measures and periods
+
+For two comparable periods, batch compatible metrics in one event definition. If daily trends are also needed, use `day` with `comparison_time_ranges`; the response can contain each period's own totals and both daily series. Do not first query a combined daily window and try to sum daily unique users into period users. If only period totals are needed, use `total` (also the default when omitted).
+
+```json
+{
+  "time_range": {"mode":"custom","start_time":"<main_start>","end_time":"<main_end>"},
+  "comparison_time_ranges": [
+    {"mode":"custom","start_time":"<baseline_start>","end_time":"<baseline_end>"}
+  ],
+  "time_particle_size": "day",
+  "metrics": [
+    {"event":"<user_event>","aggregation":"user_count"},
+    {"event":"<amount_event>","aggregation":"sum","property":"<amount_property>"}
+  ]
+}
+```
+
+Replace placeholders with the requested windows and specified event-measure definition; retain confirmed metadata bindings through `--resolutions`. Use `[{"mode":"previous_period"}]` only for the immediately preceding equal-length period. Check the first real response, then reuse it. Read [event result totals](#event-totals-and-comparison-columns) for column blocks and `period_values`; saved metrics and non-additive aggregates need their own verified total semantics.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "time_particle_size": "day",
+  "metrics": [
+    {"event": "login", "aggregation": "user_count"}
+  ],
+  "groups": [
+    {"field": {"name": "country", "type": "user_property"}}
+  ],
+  "filters": [
+    {"field": {"name": "country", "type": "user_property"}, "operator": "eq", "values": ["US"]}
+  ],
+  "relation": "and"
+}
+```
+
+Property aggregation example:
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "metrics": [
+    {"event": "purchase", "aggregation": "sum", "property": "amount"}
+  ]
+}
+```
+
+Omit `display_name` by default; apply business-facing labels in the final answer instead. Saved report create/update supports this optional display label for event, saved, and formula metrics. Add this optional field only when the target host's capability schema or a successful validation explicitly supports `display_name` for that command; a saved report supporting it does not prove ad-hoc support. If rejected, remove only the unsupported label, preserving events, aggregations, properties, filters, and formula dependencies. Use the returned metric titles to label results.
+
+Formula metric example:
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "metrics": [
+    {
+      "formula": "revenue / users",
+      "dependencies": [
+        {"alias": "revenue", "event": "purchase", "aggregation": "sum", "property": "amount"},
+        {"alias": "users", "event": "login", "aggregation": "user_count"}
+      ]
+    }
+  ]
+}
+```
+
+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`.
+- 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.
+
+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.
+- 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.
+
+## 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`.
+
+## Event totals and comparison columns
+
+Pair `rows[i]` with `row_metadata[i]`. A row with `scope=total` and `total_query=true` is a total-query row; it need not have `period_values`. A day-grain stage row has `scope=total`; its `period_values` contains aggregation labels in metric order, such as `["dist", "sum"]`, not numbers. Read the numeric totals from the corresponding `rows[i]` cells: `dist` marks an independent period distinct count, `sum` marks a sum. `Overview` is localized display text, not a stable row identifier. Date rows have `drilldown_date`.
+
+With time comparison, titles and values contain a main-period block followed by each comparison block: time column, then the same metric titles again (group columns, if present, come first). Preserve column indexes and block identity; turning repeated titles into object keys loses a period. The stage row contains a total per metric per block, while date rows contain the paired daily values. Use each block's actual date columns; row metadata alone does not describe every comparison date. Missing metadata, truncated rows, or an unexpected aggregate leaves that total unverified; inspect the saved structure before choosing an additional query.

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

@@ -0,0 +1,46 @@
+# `funnel` AI-facing definition
+
+Shared input: [common building blocks](../ai_models.md#common-building-blocks).
+
+Use for ordered conversion steps with a conversion window.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "time_particle_size": "day",
+  "funnel": {
+    "steps": [
+      {"event": "view_product"},
+      {"event": "add_to_cart"},
+      {"event": "purchase"}
+    ],
+    "window": {"value": 3, "unit": "day"},
+    "groups": [
+      {"field": {"name": "channel", "type": "user_property"}}
+    ]
+  }
+}
+```
+
+If the user asks to match users across events by a shared event property, set `relation_event_property_name`.
+
+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:
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 14},
+  "time_particle_size": "day",
+  "funnel": {
+    "steps": [
+      {"event": "register"},
+      {"event": "login"},
+      {"event": "payment", "filters": [
+        {"event_property_name": "is_first_pay", "operator": "eq", "values": ["true"]}
+      ]}
+    ],
+    "window": {"value": 7, "unit": "day"}
+  }
+}
+```
+
+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.

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

@@ -0,0 +1,26 @@
+# `heat_map` AI-facing definition
+
+Shared input: [common building blocks](../ai_models.md#common-building-blocks).
+
+Use for two-dimensional heat map analysis based on numeric event coordinate properties.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "heat_map": {
+    "hot_event": "click",
+    "hot_aggregation": "total_count",
+    "x_prop": "screen_x",
+    "y_prop": "screen_y",
+    "filters": [
+      {"field": {"name": "page", "type": "event_property"}, "operator": "eq", "values": ["home"]}
+    ]
+  }
+}
+```
+
+For property metrics, set `hot_property` and use a property aggregation such as `sum` or `avg`.
+
+## 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.

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

@@ -0,0 +1,20 @@
+# `interval` AI-facing definition
+
+Shared input: [common building blocks](../ai_models.md#common-building-blocks).
+
+Use for elapsed-time analysis between an initial event and a return event.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "time_particle_size": "day",
+  "interval": {
+    "initial_event": "register",
+    "return_event": "first_purchase",
+    "window": {"value": 7, "unit": "day"},
+    "groups": [
+      {"field": {"name": "channel", "type": "user_property"}}
+    ]
+  }
+}
+```

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

@@ -0,0 +1,38 @@
+# `path` AI-facing definition
+
+Shared input: [common building blocks](../ai_models.md#common-building-blocks).
+
+Use for behavior paths before or after a source event.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "filters": [
+    {"field": {"name": "account_id", "type": "user_property"}, "operator": "exists"}
+  ],
+  "relation": "and",
+  "path": {
+    "source_event": "purchase",
+    "included_events": ["view_product", "add_to_cart", "purchase"],
+    "session_interval": 30,
+    "session_unit": "minute",
+    "direction": "forward"
+  }
+}
+```
+
+`direction=forward` asks what users do after `source_event`; `direction=backward` asks what users did before it. Do not send original-QP fields such as `source_type` or `event_names`.
+
+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`.
+
+Path `filters` are global member filters compiled to the original QP `user_filter`. They support `user_property`, `cluster`, and `tag`, but not `event_property`. Do not move a user filter into the source event's event-property filter.
+
+Path session timeout accepts only these unit/value ranges:
+
+- `second`: `1..999`
+- `minute`: `1..999`
+- `hour`: `1..24`
+
+Do not use `day`. Express one day as `session_interval=24` with `session_unit=hour`.
+
+Property types come from project metadata. If resolution says a field is an `event_property`, never relabel it as `user_property` just to satisfy the path schema. Remove the unsupported global filter, choose a model that supports event-property filtering, or ask the user to clarify the intended constraint. A familiar name such as `channel` is not universally an event or user property across projects.

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

@@ -0,0 +1,39 @@
+# `prop_analysis` AI-facing definition
+
+Shared input: [common building blocks](../ai_models.md#common-building-blocks).
+
+`prop_analysis` dimensions and filters support `user_property`, `cluster`, and `tag`; they do not support `event_property`.
+
+Use for user-property metrics, grouping, filters, and user-crowd comparison.
+
+```json
+{
+  "prop_analysis": {
+    "metric": {"aggregation": "user_count"},
+    "groups": [
+      {"field": {"name": "country", "type": "user_property"}}
+    ],
+    "filters": [
+      {"field": {"name": "vip_level", "type": "user_property"}, "operator": "gte", "values": ["3"]}
+    ],
+    "user_crowds": [
+      {
+        "name": "US users",
+        "filters": [
+          {"field": {"name": "country", "type": "user_property"}, "operator": "eq", "values": ["US"]}
+        ]
+      }
+    ]
+  }
+}
+```
+
+For property aggregations, pass the user property:
+
+```json
+{"prop_analysis":{"metric":{"aggregation":"distinct_count","property":"account_id"}}}
+```
+
+## 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.

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

@@ -0,0 +1,25 @@
+# `rank_list` AI-facing definition
+
+Shared input: [common building blocks](../ai_models.md#common-building-blocks).
+
+Use for ranking users/entities by an event metric.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "rank_list": {
+    "rank_dimension": {"field": {"name": "#account_id", "type": "user_property"}},
+    "rank_event": "purchase",
+    "rank_aggregation": "sum",
+    "rank_property": "amount",
+    "rank_type": "dense_rank",
+    "order_by": "DESC"
+  }
+}
+```
+
+`rank_type` values: `rank`, `dense_rank`, or `row_rank`.
+
+## 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.