@thinkingai/ae-cli 6.1.24 → 6.1.26

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

@@ -1,23 +1,36 @@
 # analysis report update
 
-Use when the user explicitly wants to update saved report metadata or replace its AI QP definition.
+Use when the user explicitly wants to update saved report metadata, replace its AI QP definition, or change an event report's chart/result-table layout.
 
 Do not use raw QP, `qp`, `report_model`, or `analysis_query`. When changing the definition, pass `model_type` and AI QP `definition` together.
 
-Read [`ai_models.md`](ai_models.md) for the single AI-facing model registry. Report update supports the 12 analysis models plus `tag` for saved tag report data.
+Read [`ai_models.md`](ai_models.md) for the single AI-facing model registry. Report update supports the 13 analysis models plus `tag` for saved tag report data.
 
 Command:
 
 ```bash
 ae-cli analysis report update --project-id <project_id> --report-id <report_id> --report-version <version> --report-name "New name"
 ae-cli analysis report update --project-id <project_id> --report-id <report_id> --report-version <version> --model-type event --definition '{...}' [--resolutions '<confirmed_resolution_json>']
+ae-cli analysis report update --project-id <project_id> --report-id <report_id> --report-version <version> --presentation '{"table_layout":"event"}'
 ```
 
 When the caller supplies an existing snapshot, optional `--intent-snapshot` accepts `schema_version: 1`, non-empty `requirement`, `definition` and `model_type`. The CLI checks that its definition and model match the submitted values locally; the snapshot is never sent to Gateway. Metadata-only updates use no definition snapshot.
 
-Input sends `project_id`, `report_id`, `version` from CLI `--report-version`, and at least one of `report_name`, `report_desc`, or `definition`. Read `version` from `analysis report get` before updating. `model_type` is required when `definition` is provided; `resolutions` is allowed only when a definition is provided and is not supported with `model_type=tag`.
+Input sends `project_id`, `report_id`, `version` from CLI `--report-version`, and at least one of `report_name`, `report_desc`, `definition`, or top-level `presentation`. Read `version` from `analysis report get` before updating. `model_type` is required when `definition` is provided; `resolutions` is allowed only when a definition is provided and is not supported with `model_type=tag`.
 
-Output is the gateway envelope. `data` contains update status, `report_id`, and the normalized AI QP definition when a definition was updated.
+## Preserve display settings
+
+For same-model definition updates, omit `presentation` to preserve the saved event-report chart and result-table layout. For a display-only change, send `--presentation` without `--definition` or `--model-type`, using the current version. Only supplied presentation fields change; omitted fields are retained. Supported only for event reports: `chart_type=line|combo|bar|stacked|cumulative|pie`, `table_layout=date|event|group`, and report-level `series`. The gateway validates the effective presentation against the saved definition; pie always requires grouping without time comparison. Total-time reports support bar, or pie only when those grouping/comparison conditions hold. A model change uses the target model's display defaults unless an allowed event presentation is supplied.
+
+For combination styles/axes, read [event-report presentation](event_report_presentation.md) before updating. Series is a subset patch; `[]` is an explicit reset, and `chart_type=line` resets all series to primary-axis lines. Metric positions are tied to the current returned `definition.metrics` and report version. Changing source series also affects its other trend (`L0`) cards; card updates cannot override series locally. During definition changes, the server preserves uniquely matched technical metrics and rejects unsafe non-default series loss with `SERIES_PRESERVATION_CONFLICT`; follow its reset guidance instead of silently carrying old indexes into new metrics.
+
+Non-empty series-only updates require an existing compatible trend. Empty `series: []` also clears retained series on a compatible non-trend chart without changing that chart type. When changing from another chart, use explicit `chart_type=combo` with non-empty series; do not attach non-empty series to an explicit bar/pie/cumulative/line choice. If a definition change invalidates a previously valid chart, implicit preservation fails before writing; follow its compatible-chart guidance rather than promising an unchanged invalid display.
+
+To change a table card on an analysis board, use [`dashboard-report update`](dashboard_report_update.md) with `--chart-type table`, not report presentation. The source report, the analysis page's result table, and a dashboard card are separate display scopes. Raw `graphShape`, `byType`, `reportGraphShape`, `tableFormat`, and `dateOutside` are not authoring fields.
+
+Definition replacement follows the filter write boundary in [`ai_models.md`](ai_models.md): one compound group level with leaf-only, non-empty `items`. A deeper historical tree remains readable, but a deeper tree or empty group submitted for writing is rejected by the capability schema as `INVALID_CAPABILITY_INPUT`; use the returned field path or schema keyword to correct it. Omit `definition` for metadata-only changes and never flatten it.
+
+Output is the gateway envelope. `data` contains update status, `report_id`, and the normalized AI QP definition when a definition was updated, plus event-report `presentation`. It does not represent any dashboard card's display.
 
 When a definition is supplied, update and its `--validate` / `--dry-run` paths use the same compiler contract. `AI_QP_COMPILE_FAILED` preserves the full structured error array. The report is not changed on this failure; follow [`metadata_resolution.md`](metadata_resolution.md), keep each bound field's path and original wording, fill confirmed model parameters, and retry with `--resolutions` only after confirmation.
 
@@ -26,3 +39,7 @@ For the shortest safe update, read the current `version` exactly once with `anal
 For a SQL `part_date` parameter, `use_timezone` is a boolean saved definition field with default `false`. Change it only by submitting the complete updated `definition`; report-data `--sql-params` is value-only and must not contain `use_timezone`.
 
 After a successful update, call `analysis-meta asset url-get` with the updated `report_id` and output its `markdown_link`.
+
+The capability schema includes model-specific nested definition validation. Unknown fields, including nested filter/time-range fields and diagnostic backing fields, are rejected instead of silently ignored. Use canonical snake_case keys and aggregation names such as `user_count`; event report metrics and funnel `steps[]` may additionally carry `display_name`. When replacing a funnel definition, preserve every step's returned `display_name` so custom labels survive the round trip. Inspect the report capability itself for the full saved-report definition schema.
+
+Use `--report-desc ""` to clear an existing description. Omitting `--report-desc` preserves the saved description. Clearing only the description is a valid metadata-only update.

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

@@ -2,18 +2,18 @@
 
 List queryable columns for one server-authorized SQL table.
 
-For an unknown table, first call `analysis sql-table list --project-id <project_id>`, then copy an exact returned `table_ref`. Reuse an already verified authorized table reference in the same scope. Do not guess table or column names.
+For an unknown table, first call `analysis sql-table list --project-id <project_id>`, then copy the returned `sql_reference` (or legacy `table_ref`). Reuse an already verified authorized table reference in the same scope. Do not guess table or column names.
 
 ```bash
 ae-cli analysis sql-table columns \
   --project-id <project_id> \
   --table-ref <table_ref> \
-  [--usage analysis|tag_cluster]
+  [--usage analysis|tag_cluster|sql_datatable]
 ```
 
-The result identifies the resolved catalog/schema/table and returns its columns with machine names, types, and available descriptions. A unique table-only reference is accepted; ambiguous references fail with candidate tables instead of selecting one arbitrarily.
+The result includes `table_ref`, quoted `sql_reference`, `table_type`, nullable `source_type` and `repo_table_type`, and the resolved catalog/schema/table, and returns its columns with machine names, types, and available descriptions. A unique table-only reference is accepted; ambiguous references fail with authorized `candidate_tables` with quoted `sql_reference` values instead of selecting one arbitrarily. Quote the entire shell argument, for example `--table-ref '"hive"."space.name"."orders"'`. Double quotes inside an identifier are doubled. One to three identifier segments are supported; a two-segment reference uses the `hive` catalog.
 
-Pass the same `usage` used for `sql-table list`. For SQL tags and SQL clusters this must be `--usage tag_cluster`; the default is `analysis`.
+Pass the same `usage` used for `sql-table list`. For SQL tags and SQL clusters this must be `--usage tag_cluster`; use `--usage sql_datatable` for SQL-built data tables; the default is `analysis`. Do not fall back to another usage if the server rejects it.
 
 When copying returned columns into Trino SQL, delimit identifiers containing `#`, `$`, `@`, spaces, or punctuation with double quotes, for example `"#user_id"` or `"$part_event"`. Single quotes are string literals. The CLI does not auto-rewrite SQL.
 

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

@@ -10,16 +10,16 @@ ae-cli analysis sql-table list \
   [--queries '["user","event"]'] \
   [--limit <1-200>] \
   [--offset <next_offset>] \
-  [--usage analysis|tag_cluster]
+  [--usage analysis|tag_cluster|sql_datatable]
 ```
 
 ## Contract
 
 - Use this command before writing SQL when the table is not already known. Do not ask the customer to supply the fixed project event/user table name and do not guess `v_event_<id>` or `v_user_<id>`.
-- `table_ref` is the exact server-authorized reference to copy into SQL and into `analysis sql-table columns --table-ref`.
+- Use `sql_reference` (quoted catalog/schema/table with escaped double quotes) when copying a table into SQL or `analysis sql-table columns --table-ref`. The legacy `table_ref` remains accepted; do not split it on dots because identifier segments can contain dots.
 - `queries` accepts 1 to 20 non-empty strings with OR semantics. Matching rows include `matched_queries` and `matched_fields`; singular `query` is not accepted.
-- Each item also returns `catalog`, `schema`, `table`, `table_type`, and `description`.
-- `usage=analysis` is the default table set for SQL analysis and reports. Use `usage=tag_cluster` for SQL tags or SQL clusters. These server-authorized sets differ, and the same usage must be passed to `sql-table columns`.
+- Each item also returns `catalog`, `schema`, `table`, `table_type`, `description`, `usage`, `source_type`, `repo_table_type`, and `sql_reference`. `source_type=gaia` identifies space tables; source/type metadata may be null for ordinary tables. Do not infer a space table from `table_type=customTable`.
+- `usage=analysis` is the default table set for SQL analysis and reports. Use `usage=tag_cluster` for SQL tags or SQL clusters, and `usage=sql_datatable` for SQL-built data tables. Lists are flat; these usages select authorized sets rather than UI categories. Do not silently retry a rejected usage with `analysis`. These server-authorized sets differ, and the same usage must be passed to `sql-table columns`.
 - When `has_more=true`, continue only with the returned `next_offset`. Stop when `has_more=false`.
 - An empty list means the current identity has no queryable SQL tables in that project; do not fabricate a table name.
 
@@ -31,4 +31,4 @@ ae-cli analysis sql-table columns --project-id 1 --table-ref hive.ta.v_user_1
 ae-cli analysis adhoc run --project-id 1 --model-type sql --definition '{"sql":"select * from hive.ta.v_user_1 limit 10"}'
 ```
 
-Use the exact `table_ref` returned by the first command; the example reference is illustrative only.
+Use the exact `sql_reference` returned by the first command when writing SQL; the example reference is illustrative only.

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

@@ -12,6 +12,8 @@ ae-cli system query-monitor overview --company-id <company-id> --cluster-names '
 
 Capability id: `system.query_monitor.overview`.
 
+Selected project IDs and space codes must belong to the supplied company. A different company's scope is rejected before chart data is read.
+
 The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.
 
 ## Parameters

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

@@ -13,6 +13,8 @@ ae-cli system query-task cancel --company-id <company-id> --task-id <task-id> --
 
 Capability id: `system.query_task.cancel`.
 
+The task must belong to `--company-id` by project or workspace. A foreign-company or missing task ID is rejected before cancellation.
+
 Run `--dry-run` first, summarize the affected target and impact, then wait for explicit user confirmation before rerunning the unchanged command with global `--yes`.
 
 The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.

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

@@ -12,6 +12,10 @@ ae-cli system query-task export --company-id <company_id> --start-time '2026-07-
 
 Capability id: `system.query_task.export`.
 
+Selected project IDs and space codes must belong to the supplied company. A different company's scope is rejected before an export is submitted.
+
+The time range has the same completion-time semantics as [`query-task list`](system_query_task_list.md): inclusive boundary seconds, including milliseconds within the end second, and a maximum 31-day window. The CSV `start_time` is task initiation time, not the timestamp used for range filtering.
+
 If the required filter mappings are unknown, call `ae-cli system query-task options --company-id <company_id>` once. Reuse verified mappings within the same company/project scope; do not guess filter codes or cluster names.
 
 Use `--output` to wait and download the completed artifact. If interrupted, resume with `ae-cli analysis run wait --run-id <run_id> --output <file>` using the same export response. See [`run_wait.md`](run_wait.md).
@@ -25,8 +29,8 @@ The response uses `ok`, `data`, and `meta`. Empty task data is a successful expo
 | Parameter | Required | Description |
 |---|---|---|
 | `--company-id` | Yes | Company ID. |
-| `--start-time` | Yes | Inclusive range start in `yyyy-MM-dd HH:mm:ss`. |
-| `--end-time` | Yes | Inclusive range end in `yyyy-MM-dd HH:mm:ss`. |
+| `--start-time` | Yes | Inclusive completion-time range start in `yyyy-MM-dd HH:mm:ss`. |
+| `--end-time` | Yes | Inclusive completion-time range end, including the entire second, in `yyyy-MM-dd HH:mm:ss`. |
 | `--status-codes` | Yes | Non-empty task status-code JSON array. |
 | `--content-codes` | Yes | Non-empty query content-code JSON array. |
 | `--task-type-codes` | Yes | Non-empty query task-type-code JSON array. |

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

@@ -12,6 +12,8 @@ ae-cli system query-task get --company-id <company-id> --task-id <task-id>
 
 Capability id: `system.query_task.get`.
 
+The task must belong to `--company-id` by project or workspace. A foreign-company or missing task ID is rejected before details are read.
+
 The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.
 
 ## Parameters

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

@@ -1,6 +1,6 @@
 # system query-task list
 
-Use when the user needs to list query-monitor tasks within a mandatory bounded time range.
+Use when the user needs historical query logs within a mandatory bounded time range. For the realtime monitoring tab, use `ae-cli system query-task realtime-list` instead.
 
 Do not use it outside the system query-task operation or with fields absent from the inspected capability schema.
 
@@ -14,6 +14,10 @@ Capability id: `system.query_task.list`.
 
 If the required filter mappings are unknown, call `ae-cli system query-task options --company-id <company_id>` once. Reuse verified mappings within the same company/project scope; do not guess filter codes or cluster names.
 
+Project IDs and workspace codes must belong to `--company-id`; foreign-company values are rejected before querying. The global system-project ID `-1` cannot be selected as a company-scoped project.
+
+The range filters query **completion time**, not the returned `start_time` (task initiation time). Both boundary seconds are inclusive, including milliseconds within the end second. A task started before the window can appear if it completed inside it. Compare list and export using the same completion-time window; do not reject rows solely because `start_time` is outside it. The range must not exceed 31 days.
+
 The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.
 
 ## Parameters
@@ -21,8 +25,8 @@ The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `
 | Parameter | Required | Description |
 |---|---|---|
 | `--company-id` | Yes | Company ID. |
-| `--start-time` | Yes | Inclusive lower bound in `yyyy-MM-dd HH:mm:ss`. |
-| `--end-time` | Yes | Inclusive upper bound in `yyyy-MM-dd HH:mm:ss`. |
+| `--start-time` | Yes | Inclusive completion-time lower bound in `yyyy-MM-dd HH:mm:ss`. |
+| `--end-time` | Yes | Inclusive completion-time upper bound, including the entire second, in `yyyy-MM-dd HH:mm:ss`. |
 | `--project-ids` | Conditional | Non-empty project IDs or space codes are required. |
 | `--space-codes` | Conditional | Non-empty space codes or project IDs are required. |
 | `--status-codes` | Yes | Task status-code JSON array. |

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

@@ -1,6 +1,6 @@
 # system query-task options
 
-Use before query-task list or export to discover every valid filter value exposed by the current environment.
+Use before query-task list, realtime-list, or export to discover valid filter values exposed by the current environment.
 
 Command:
 
@@ -18,7 +18,7 @@ The response maps:
 - `projects[].project_id` and `workspaces[].space_code` to display names.
 - `clusters[].cluster_name` to its query engine metadata.
 
-Use the returned codes and names unchanged in `query-task list` or `query-task export`. Do not infer codes from UI labels or examples.
+Project and workspace options are limited to `--company-id`; status, content, task type, and cluster codes remain discoverable. Use the returned codes and names unchanged in `query-task list`, `query-task realtime-list`, or `query-task export`. Discovery does not authorize a project or workspace; execution still checks company ownership. Do not infer codes from UI labels or examples.
 
 ## Parameters
 

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

@@ -0,0 +1,15 @@
+# system query-task realtime-list
+
+Use for a one-time snapshot of the Query Monitor **Realtime Query** tab. The existing `query-task list` command is for historical **Query Logs** and requires a fixed start/end range. Do not substitute one for the other.
+
+```bash
+ae-cli system query-task realtime-list --company-id <company_id> --project-ids '[123]' --cluster-names '["cluster-a"]' --duration-minutes 30 --limit 100
+```
+
+Capability ID: `system.query_task.realtime_list`. Run `ae-cli system query-task options --company-id <company_id>` first if IDs, status codes, or cluster names are unknown. Discovery does not grant access; a project or workspace outside the company is rejected during execution.
+
+The global system-project ID `-1` cannot be selected as a company-scoped project. System tasks tied to a company workspace remain visible through that workspace where applicable.
+
+Provide at least one non-empty `--project-ids` or `--space-codes` JSON array, and a non-empty `--cluster-names` JSON array. `--duration-minutes` defaults to 30 (range 1–30). Optional `--status-codes` filters task states. `--limit` defaults to 100 (maximum 200). This command does not poll or cancel tasks.
+
+The response contains `items`, `limit`, `has_more`, and `snapshot_at`. `has_more` means the bounded snapshot has additional matching rows, not a full historical count. Task rows omit credentials, user identity tokens, internal SQL gateway selection, and SQL text. To inspect one task, use `query-task get`; cancel remains a separate high-risk operation requiring confirmation.

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

@@ -16,6 +16,12 @@ If a SQL cluster reads an event table, include a predicate on the quoted `"$part
 SQL clusters support only `${PartDate:name}` dynamic placeholders. Each placeholder requires a matching `params` item with `type=part_date` and either `recent_day` or `start_time` plus `end_time`. General SQL parameter types (`text`, `number`, `variable`, `time`, and `selector`) are rejected for SQL clusters.
 For `recent_day`, `0-7` means 最近7天 and includes today; `1-7` means 过去7天 and excludes today.
 
+`${base_date}` is a separate built-in computation-date macro, not a user-configurable dynamic placeholder. SQL clusters may use `${base_date}`, a formatted value such as `${base_date:yyyy-MM-dd}`, or a server-supported offset such as `${base_date:yyyy-MM-dd-1*day}`. Keep the macro in `sql` and do not add it to `params`; it is expanded when the cluster is calculated. Expansion produces plain text, so quote the macro when the SQL expression expects a string or date literal:
+
+```json
+{"type":"sql","sql":"SELECT \"#user_id\" FROM v_event_1 WHERE \"$part_date\"='${base_date:yyyy-MM-dd}'"}
+```
+
 Discover tables with `analysis sql-table list --project-id <project_id> --usage tag_cluster`, then inspect columns with the same `--usage tag_cluster`. This table set is server-authorized specifically for SQL tags/clusters and differs from the default analysis SQL set.
 
 Optional `include_filter` and `exclude_filter` use the shared filter-group shape.
@@ -87,3 +93,5 @@ Required: `type=behavior_sequence`, `completed`, `steps`. Each step requires `ev
   ]}
 }
 ```
+
+For space tables, use the returned `sql_reference` when writing SQL and loading columns. `source_type=gaia` identifies a space table; keep `--usage tag_cluster` for both discovery commands.

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

@@ -10,7 +10,7 @@ Flags: `--project-id`, `--tag-name`, `--display-name`, `--definition-request` re
 
 `tag_name` is a machine identifier: 1-80 characters, starts with a letter, and contains only letters, digits, or underscores. `display_name` is 1-80 characters. The CLI rejects violations before dispatch.
 
-Read `user_tag_models.md` before constructing `--definition-request`. Dynamic first/last ranges use semantic `time_range` values such as `{"mode":"recent","unit":"month","value":1}` for this month or `{"mode":"start_to_today","start_time":"2026-07-01"}` for a fixed start date through today. Create does not accept `--remark`; set it later with `user-tag update` when needed.
+Read `user_tag_models.md` before constructing `--definition-request`. Every metric tag requires `metric.time_range`; never omit it. Dynamic first/last ranges use semantic `time_range` values such as `{"mode":"recent","unit":"month","value":1}` for this month or `{"mode":"start_to_today","start_time":"2026-07-01"}` for a fixed start date through today. Create does not accept `--remark`; set it later with `user-tag update` when needed.
 
 The backend validates and compiles the definition inside the create operation; if metadata is ambiguous or missing, creation fails without creating the tag.
 
@@ -18,6 +18,12 @@ The backend validates and compiles the definition inside the create operation; i
 ae-cli analysis user-tag create --project-id <project_id> --tag-name high_value --display-name "High Value" --definition-request '{"type":"condition","condition_values":[{"value":"high","events":[{"event":"pay","operator":"gte","value":3,"aggregation":"count","time_range":{"mode":"recent","unit":"day","value":30}}]}]}'
 ```
 
+Median metric tag for the previous 30 days:
+
+```bash
+ae-cli analysis user-tag create --project-id <project_id> --tag-name median_payment --display-name "Median Payment" --definition-request '{"type":"metric","metric":{"event":"pay","aggregation":"median","property":"amount","time_range":{"mode":"previous","unit":"day","value":30}}}'
+```
+
 First/last tag for this month:
 
 ```bash

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

@@ -4,7 +4,7 @@ Get exact user tag details after discovery.
 
 Do not use it for fuzzy discovery, member data, or history statistics. Output contains saved tag metadata/definition for the requested names.
 
-After `user-tag create` or an update containing `--definition-request`, use this command to observe the automatically started computation; do not trigger `user-tag refresh`. For create, wait until `progress=100` and `refresh_time` is present. For a definition update, record the previous `refresh_time` first and wait until `progress=100` and `refresh_time` advances. Until then, `users_num` and member queries may still reflect the previous successful computation; treat that as stale data, not as evidence that the new definition was compiled or calculated incorrectly.
+After `user-tag create` or an update reporting `computation.triggered_automatically=true`, use this command to observe the automatically started computation; do not trigger `user-tag refresh`. For create, wait until `progress=100` and `refresh_time` is present. For a changed definition, record the previous `refresh_time` first and wait until `progress=100` and `refresh_time` advances. Until then, `users_num` and member queries may still reflect the previous successful computation; treat that as stale data, not as evidence that the new definition was compiled or calculated incorrectly. An identical definition is not recomputed; when update returns `not_triggered` and `next_action=none`, do not wait for a new refresh timestamp.
 
 The raw backend value is returned under `result`. The response also provides aggregate and per-tag `computation`, `result_freshness`, and `next_action`. `poll_get` includes an exact capability/input pair; `none` means the latest result is usable. `potentially_stale` with `is_stale=null` means `refresh_time` predates `update_time`, but the update may have changed metadata only; inspect the latest update instead of refreshing automatically.
 

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

@@ -24,7 +24,9 @@ Top-level `type` is exactly one of `condition`, `metric`, `first_last`, or `sql`
 
 ## Metric tag
 
-Required: `event`, `aggregation`. `property`, `percentile`, `time_range`, and `filters` are optional. Filters support only event properties and user properties. A string `field` is an event property; use `{name,type:"user_property"}` for a user property.
+Required: `event`, `aggregation`, and `time_range`. `property`, `percentile`, and `filters` are optional. Filters support only event properties and user properties. A string `field` is an event property; use `{name,type:"user_property"}` for a user property. Use the semantic time mappings in [`audience_models.md`](audience_models.md); never omit `time_range` from a metric tag.
+
+Supported aggregations are `count`, `active_days`, `sum`, `avg`, `max`, `min`, `median`, and `percentile`. `median` is a dedicated aggregation for a numeric event `property`; do not represent it as `percentile=50`.
 
 Use `aggregation=percentile` with a numeric event `property` and pass `percentile`. Supported percentile values match the page controls: `5`, `10`, `20`, `25`, `30`, `40`, `60`, `70`, `75`, `80`, `90`, `95`, and `99`. The `percentile` field is required for percentile aggregation and is rejected for every other aggregation.
 
@@ -32,10 +34,16 @@ Use `aggregation=percentile` with a numeric event `property` and pass `percentil
 {"type":"metric","metric":{"event":"pay","aggregation":"sum","property":"amount","time_range":{"mode":"previous","unit":"day","value":30},"filters":{"relation":"and","items":[{"field":"channel","operator":"eq","values":["app"]},{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}}}
 ```
 
+Median example:
+
+```json
+{"type":"metric","metric":{"event":"pay","aggregation":"median","property":"amount","time_range":{"mode":"previous","unit":"day","value":30}}}
+```
+
 Percentile example:
 
 ```json
-{"type":"metric","metric":{"event":"pay","aggregation":"percentile","property":"amount","percentile":90}}
+{"type":"metric","metric":{"event":"pay","aggregation":"percentile","property":"amount","percentile":90,"time_range":{"mode":"previous","unit":"day","value":30}}}
 ```
 
 ## First/last tag
@@ -54,6 +62,8 @@ From a fixed date through today:
 
 ## SQL tag
 
+Return one row per distinct analysis-subject ID, with the tag value in the second column; a list tag requires a native SQL `ARRAY(varchar)` value, not a JSON string or repeated scalar rows. The server infers the tag type from that column, so do not add `selectType`; aggregate repeated subjects in the SQL itself, for example with `array_agg(DISTINCT CAST(value AS varchar))` and `GROUP BY` the subject ID.
+
 ```json
 {"type":"sql","sql":"SELECT \"#user_id\", 'payer' AS tag_value FROM hive.ta.v_event_1 WHERE ${PartDate:partdate} AND \"$part_event\"='pay'","params":[{"name":"partdate","type":"part_date","recent_day":"1-7"}]}
 ```
@@ -61,8 +71,16 @@ From a fixed date through today:
 SQL tags support only `${PartDate:name}` dynamic placeholders. Every placeholder requires one `params` item with `type=part_date` and either `recent_day` or `start_time` plus `end_time`. `Text`, `Number`, `Variable`, `Time`, and `Selector` parameters are valid for general SQL analysis but are not valid for SQL tags.
 For `recent_day`, `0-7` means 最近7天 and includes today; `1-7` means 过去7天 and excludes today.
 
+`${base_date}` is a separate built-in computation-date macro, not a user-configurable dynamic placeholder. SQL tags may use `${base_date}`, a formatted value such as `${base_date:yyyy-MM-dd}`, or a server-supported offset such as `${base_date:yyyy-MM-dd-1*day}`. Keep the macro in `sql` and do not add it to `params`; it is expanded when the tag is calculated. Expansion produces plain text, so quote the macro when the SQL expression expects a string or date literal:
+
+```json
+{"type":"sql","sql":"SELECT \"#user_id\", 'payer' AS tag_value FROM hive.ta.v_event_1 WHERE \"$part_date\"='${base_date:yyyy-MM-dd}' AND \"$part_event\"='pay'"}
+```
+
 Before writing a SQL tag, use `analysis sql-table list --project-id <project_id> --usage tag_cluster`, then call `analysis sql-table columns --project-id <project_id> --table-ref <table_ref> --usage tag_cluster`. The `tag_cluster` authorized table set is intentionally different from the general analysis SQL table set; do not reuse a table discovered with the default `usage=analysis`.
 
 `#user_id`, `$part_event`, and any other Trino identifier containing `#`, `$`, `@`, spaces, or punctuation must be delimited with double quotes. Single quotes are only for values.
 
 When the SQL reads an event table, it must also filter the quoted `"$part_date"` date-partition column; the backend rejects event-table SQL without that predicate.
+
+For space tables, use the returned `sql_reference` when writing SQL and loading columns. `source_type=gaia` identifies a space table; keep `--usage tag_cluster` for both discovery commands.

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

@@ -2,7 +2,7 @@
 
 Explicitly recompute an existing user tag by exact `tag_name` without changing its definition.
 
-Use this only when an unchanged definition must be run again, such as an explicit retry or a recomputation against changed source data. Do not call it after `user-tag create` or an update containing `--definition-request`; those commands already start computation automatically. Do not use it to refresh one history snapshot. Output means recomputation was submitted, not completed. Poll `user-tag get` and verify the new computation before using `users_num` or querying members.
+Use this only when an unchanged definition must be run again, such as an explicit retry or a recomputation against changed source data. Do not call it after `user-tag create` or an update reporting `computation.triggered_automatically=true`; those commands already start computation. An identical definition update does not trigger computation and does not by itself authorize a separate refresh. Do not use this command to refresh one history snapshot. Output means recomputation was submitted, not completed. Poll `user-tag get` and verify the new computation before using `users_num` or querying members.
 
 The response marks this as an explicit trigger: `computation.triggered_by_command=true`, `computation.triggered_automatically=false`, `computation.status=submitted`, and `result_freshness.is_stale=true`. Follow the returned `next_action`, `next_capability_id`, and `next_input` to poll.
 

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

@@ -2,9 +2,9 @@
 
 Update a user tag. Discover the exact `tag_name` first.
 
-Do not use it for ID-file value replacement or to create a missing tag. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-tag refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. A schedule-only update changes periodic refresh without starting immediate recomputation. `--auto-refresh-cron` or `--auto-refresh-schedule` can enable periodic refresh directly, including on a previously disabled tag. A successful update means the definition was saved, not that the new result is complete. Record the current `refresh_time` before updating, then poll `user-tag get` until `progress=100` and `refresh_time` advances before using `users_num` or querying members.
+Do not use it for ID-file value replacement or to create a missing tag. A changed `--definition-request` automatically starts recomputation; the native service skips recomputation when the normalized definition and timezone are unchanged. Follow the returned `computation.triggered_automatically` and `next_action`; do not call `user-tag refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. A schedule-only update changes periodic refresh without starting immediate recomputation. `--auto-refresh-cron` or `--auto-refresh-schedule` can enable periodic refresh directly, including on a previously disabled tag. A successful update means the definition was saved, not that a triggered computation is complete. When computation was triggered, poll `user-tag get` until `progress=100` and `refresh_time` advances from the value recorded before the update. An unchanged definition returns `not_triggered` and `next_action=none`; do not wait for its refresh timestamp to change.
 
-The response distinguishes both paths. A definition update returns `computation.triggered_automatically=true`, `result_freshness.is_stale=true`, and normally `next_action=poll_get` with an exact capability/input pair. A display-name/remark-only update returns `computation.status=not_triggered`, `result_freshness.status=fresh`, and `next_action=none`.
+The response distinguishes both paths. An update that triggers recomputation returns `computation.triggered_automatically=true`, `result_freshness.is_stale=true`, and `next_action=poll_get` with an exact capability/input pair. An unchanged definition or display-name/remark-only update returns `computation.status=not_triggered`, `result_freshness.status=fresh`, and `next_action=none`.
 
 Flags: `--project-id`, `--tag-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`, `--enable-auto-refresh`, `--auto-refresh-schedule`, `--auto-refresh-cron`. The tag type comes from `definition_request.type` when the definition changes.
 

package/skills/ae-analysis/scripts/project-semantic-knowledge-wiki/build-empty-skeleton.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { normalizeSourceForHash } from './precompiled-source.mjs';
+
+const args = Object.fromEntries(process.argv.slice(2).reduce((pairs, part, index, all) => {
+  if (part.startsWith('--') && all[index + 1] && !all[index + 1].startsWith('--')) {
+    pairs.push([part.slice(2), all[index + 1]]);
+  }
+  return pairs;
+}, []));
+const packageRoot = path.resolve(required('asset-package'));
+const outputRoot = path.resolve(required('output'));
+const descriptor = readJson(path.join(packageRoot, '.asset-package.json'));
+const manifest = readJson(path.join(packageRoot, 'manifest.json'));
+const projectId = Number(descriptor.project_id ?? manifest.project_id);
+const projectName = String(args['project-name'] || descriptor.project_name || manifest.project_name || '')
+  .replace(/\s+/g, ' ').trim();
+const snapshotHash = String(descriptor.snapshot_hash ?? manifest.snapshot_hash ?? '');
+const scope = String(descriptor.asset_scope ?? manifest.asset_scope ?? '');
+const policy = descriptor.filter_policy ?? manifest.filter_policy ?? {};
+if (String(descriptor.schema_version ?? manifest.schema_version) !== '3.0'
+    || descriptor.truncated === true || manifest.truncated === true
+    || scope !== 'governed' || policy.authenticated_entry_assets_only !== true
+    || policy.dependency_closure !== true || !Number.isSafeInteger(projectId) || projectId < 1
+    || !projectName || !/^[0-9a-f]{64}$/i.test(snapshotHash)) {
+  throw new Error('A complete governed schema 3.0 package with valid project identity is required.');
+}
+for (const name of ['dashboard-catalog', 'report-catalog', 'metric-catalog']) {
+  if (readJsonl(path.join(packageRoot, 'indexes', `${name}.jsonl`)).length) {
+    throw new Error(`The ${name} is not empty; use the normal semantic Wiki builder.`);
+  }
+}
+if (readJsonl(path.join(packageRoot, 'sources', 'adopted-personal-semantics.jsonl')).length) {
+  throw new Error('Adopted personal semantics are present; the empty skeleton is not applicable.');
+}
+if (fs.existsSync(outputRoot)) throw new Error('Output already exists.');
+const flatRoot = path.join(outputRoot, 'flat');
+fs.mkdirSync(flatRoot, { recursive: true });
+const namespace = `pskb-p${projectId}`;
+const facts = [
+  ['index', 'index', 'index.md', `# ${projectName} project semantic knowledge base\n\n- Project overview: project identity and current evidence boundary.\n- Shared project knowledge: no verified shared facts yet.\n- Business domains: none established from governed sources yet.\n- Event and asset catalog: no certified entry assets yet.\n- Governance and provenance: source scope and update policy.\n\nThis is an empty knowledge skeleton. It does not establish business facts or authorize use of uncertified assets.\n`],
+  ['wiki-project-overview', 'wiki-page', 'wiki/project-overview.md', `# Project overview\n\nProject: ${projectName} (ID ${projectId}). Business positioning, audience, objects, relationships, and decision paths are not established by the current governed sources. Add verified project material before using this knowledge base for business conclusions.\n`],
+  ['common-index', 'common', 'wiki/common/index.md', '# Shared project knowledge\n\nNo verified project-wide knowledge is available yet. Human-authored material may be added under the project and business source directories with provenance and scope.\n'],
+  ['domain-index', 'domain', 'wiki/domains/index.md', '# Business domains\n\nNo business domain is established by the current governed sources. Do not infer domains from project names or unverified assets.\n'],
+  ['asset-index-index', 'asset-index', 'wiki/asset-index/index.md', '# Event and asset catalog\n\nNo certified entry asset is available in this governed snapshot. Do not switch to all visible assets without an explicit user request.\n'],
+  ['governance-index', 'governance', 'wiki/governance/index.md', `# Governance and provenance\n\nProject ID: ${projectId}. Source scope: governed. Certified entry assets: 0. Adopted personal semantics: 0. Business facts remain unknown until verified sources are added. A later refresh must replace this empty-source state when governed evidence becomes available and preserve unrelated human sources.\n`],
+];
+const refreshState = {
+  schema_version: '1.0',
+  empty_skeleton: true,
+  semantic_project_id: projectId,
+  source_snapshot_hash: snapshotHash,
+};
+facts.push(['refresh-state', 'refresh-state', 'refresh-state.md',
+  `# Project semantic refresh state\n\n<!-- pskb_refresh_state_base64\n${Buffer.from(JSON.stringify(refreshState)).toString('base64url')}\n-->\n`]);
+const sources = facts.map(([stem, sourceKind, sourcePath, content]) => {
+  const file = `${namespace}-${stem}.md`;
+  fs.writeFileSync(path.join(flatRoot, file), content);
+  return {
+    display_name: file, file, namespace, snapshot_hash: snapshotHash,
+    source_kind: sourceKind, asset_type: null, asset_key: null,
+    title: content.split('\n')[0].replace(/^# /, ''), source_path: sourcePath,
+    content_hash: createHash('sha256').update(normalizeSourceForHash(content)).digest('hex'),
+    semantic_plan_fragment_refs: [],
+  };
+});
+fs.writeFileSync(path.join(flatRoot, 'kb-upload-manifest.json'), JSON.stringify({
+  schema_version: '1.0',
+  manifest_kind: 'ae_project_semantic_kb_upload_sources',
+  navigation_taxonomy_version: 'empty-skeleton-1.0',
+  namespace,
+  semantic_project_id: projectId,
+  project_name: projectName,
+  snapshot_hash: snapshotHash,
+  semantic_plan_state: { schema_version: null, plan_hash: null, fragment_count: 0, fragments: [] },
+  source_count: sources.length,
+  sources,
+}, null, 2));
+const packager = path.join(import.meta.dirname, 'package-wiki-source-zip.mjs');
+const archive = path.join(outputRoot, 'empty-skeleton.zip');
+const tree = path.join(outputRoot, 'source-tree');
+const sourceManifest = path.join(outputRoot, 'source-tree-manifest.json');
+execFileSync(process.execPath, [packager, '--source-dir', flatRoot, '--tree-output', tree,
+  '--manifest-output', sourceManifest, '--output', archive, '--embed-refresh-state-baseline'], {
+  stdio: 'pipe',
+});
+process.stdout.write(JSON.stringify({
+  project_id: projectId, project_name: projectName, archive,
+  source_tree: tree, manifest: sourceManifest, source_count: sources.length,
+}, null, 2) + '\n');
+
+function required(name) {
+  if (!args[name]) throw new Error(`--${name} is required.`);
+  return args[name];
+}
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+function readJsonl(file) {
+  const rows = fs.readFileSync(file, 'utf8').split(/\r?\n/).filter(Boolean).map((line) => JSON.parse(line));
+  return rows.filter((row) => row.record_type !== 'header');
+}