@thinkingai/ae-cli 6.1.20 → 6.1.21

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

@@ -0,0 +1,214 @@
+# Project Semantic Knowledge Base Wiki
+
+Requires `project_semantic_enable=on` for the target project. If export returns `PROJECT_SEMANTIC_DISABLED`, report that this project must enable `project_semantic_enable` and stop this workflow. Do not bypass the disabled entry point with other export, metadata, or capability commands.
+
+Build one server-consumable project semantic source Wiki from one immutable Common asset-package snapshot and prove that the KB-compiled knowledge base can be browsed and consumed correctly. The asset package is the raw truth source. Default to a governed package; use an `all_visible` package only when the user explicitly asks for all assets or for uncertified assets to be included. The Agent summarizes the asset semantics once into editable Markdown sources; KB owns schema generation, final compilation, source lifecycle, and incremental maintenance.
+
+## Boundary
+
+- This command reference covers asset-package download, one Agent semantic-planning pass, deterministic Wiki-source rendering, validation, editable ZIP source upload, schema generation, compilation, server readback, and retrieval acceptance.
+- The default source scope is `governed`. If and only if the user explicitly requests all assets, use `all_visible`; keep uncertified assets visible but marked `certification_state=uncertified`, and do not present uncertified or conflicting assets as governed definitions.
+- The retired governed project-semantic candidate/review/enable/release lifecycle is not part of this workflow. A retrieval taxonomy or Wiki page is not automatically a governed project semantic.
+- The generated Wiki is a retrieval and evidence layer. Current counts, recent customers, and live usage still require report execution.
+- Do not use `kb +import` for this loop. `kb +import` imports an already compiled read-only snapshot; this workflow needs source upload followed by `kb +schema` and `kb +compile`.
+
+
+## Usage and Intake Gate
+
+When the user asks to build, update, refresh, rebuild, or sync a project semantic knowledge base from project assets, open this reference from `ae-analysis` and run the full loop here. Do not use this workflow for asset-certification or metric recommendations; those use `analysis-meta governance-recommendation export`.
+
+CLI Agent performs the main semantic precompilation: understand definitions and SQL, author complete asset meanings, domain relationships, recall boundaries, SQL business summaries, and evidence-backed conflicts, then render Markdown sources. Scripts only handle deterministic work: validation, IDs, links, packaging, source-tree diffs, and removal of parser/placeholder noise. They must not author business purpose, domain intent, SQL applicable questions, conflict interpretation, or visible rationale from templates. Upload those sources as an editable ZIP and let KB compile the final Wiki, integrate human context, maintain citations/navigation, and incrementally update affected pages. Never use `kb +import` for this workflow: a read-only snapshot cannot provide this source lifecycle.
+
+## Company-only target and permission boundary
+
+Use the `company-kb.mjs` wrapper below for project KB operations. It fixes scope to company, filters discovery to company results, verifies ZIP ownership before directory operations, and exits on any failed command. A company permission denial is terminal: report the server error and stop. Never create a personal KB, reuse a same-name personal KB, retry without scope, or continue to upload/schema/compile after failed creation.
+
+Resolve host and project first. Search company KBs across `compiled`, `idle`, `pending`, `compiling`, and `failed` build states with `+list --build-status <state>`. Deduplicate by identity. Prefer an exact project binding, otherwise the deterministic name `<project_name> 项目语义知识库`. If several company KBs match, ask for the exact target. Personal KBs are never candidates. If no company target exists, create one with the project binding. Do not ask the user to choose between "existing" and "new" when the target is unambiguous. Once target resolution succeeds, do not stop after local generation.
+
+The KB description is part of Agent auto-loading and source selection, not a casual note. Always write a normal business-facing description that states the project, asset scope, and intended Agent use. Do not mention temporary implementation details such as ZIP, test version numbers, source-tree packaging, or local build names in the description. Use this template:
+
+```text
+<project_name><asset_scope_label>项目语义知识库，用于辅助 Agent 在分析前召回业务域、资产口径、SQL 报表语义和治理边界。
+```
+
+For example:
+
+```text
+产品雷达已认证资产项目语义知识库，用于辅助 Agent 在分析前召回业务域、资产口径、SQL 报表语义和治理边界。
+```
+
+```bash
+KB_RUN=skills/ae-analysis/scripts/project-semantic-knowledge-wiki/company-kb.mjs
+node "$KB_RUN" +list --build-status compiled --host <host>
+node "$KB_RUN" +new --name '<company_kb_name>' \
+  --description '<project_name><asset_scope_label>项目语义知识库，用于辅助 Agent 在分析前召回业务域、资产口径、SQL 报表语义和治理边界。' \
+  --project-id <project_id> --project-name '<project_name>' --host <host>
+```
+
+The wrapper executes the installed `ae-cli`. Directory APIs lack a scope parameter, so it verifies the ZIP source belongs to the company KB before mutation. Permission denial stops the flow. An explicitly requested personal test uses the project CLI directly with `--scope personal` on scope-aware commands; this is never a permission fallback. Personal test KB creation follows the same description rule and must still use a business-facing description.
+
+## User-selected model
+
+Resolve the requested model with `ae-cli agent +list-models --host <host>` and retain its exact Model.id. Pass the same `--model <model_ref>` to Schema and compile, including incremental refreshes. Stop if the requested model is unavailable or ambiguous.
+
+## Source directory contract
+
+The first upload ZIP must create a real source tree. Empty directories are not a reliable contract, so each durable category contains a small `README.md` that declares filing rules and states that README files are not business evidence.
+
+```text
+sources/
+  README.md
+  project/
+  assets/
+    dashboards/
+    reports/
+    metrics/
+    metadata/
+  business/
+  meetings/
+  decisions/
+  corrections/
+  references/
+```
+
+CLI-managed asset facts go only under `sources/assets/**`. Human material goes under the other top-level categories. Asset refreshes may add, replace, or remove files owned by the generated asset package; they must not delete user material in `project/`, `business/`, `meetings/`, `decisions/`, `corrections/`, or `references/`.
+
+The intended compiled Wiki is organized by consumption, not by raw file shape:
+
+```text
+index.md
+wiki/project/
+wiki/domains/
+wiki/semantics/
+wiki/assets/
+wiki/decisions/
+wiki/review/
+```
+
+The source tree only classifies material. Authority still comes from explicit facts: decisions require confirmer, status, date, and scope; corrections require target, corrected content, reason, date, and scope.
+
+## First build: precompiled Markdown sources and KB compilation
+
+1. Export one complete schema 3.0 governed asset package with `ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope governed --output <package> --host <host>`. Require `truncated=false` and authenticated entry/dependency closure. Use `all_visible` only on explicit user request.
+2. Preserve the local planning and rendering stages. Read the compact knowledge indexes, including dashboard notes, and only the normalized details needed for ambiguous grouping, conflicts, SQL semantics, and recall-card choices. Author one snapshot-bound plan using [`project_semantic_knowledge_wiki_plan_schema.md`](project_semantic_knowledge_wiki_plan_schema.md). This is the run's only Agent synthesis pass. Do not create the plan with a generic script. If many summaries share the same template with only names or fields changed, discard the plan and have the Agent reread the relevant asset definitions.
+3. Render the locally precompiled material for review and generate Markdown sources. The review ZIP is a local artifact; upload the source ZIP from the next step:
+
+   ```bash
+   node skills/ae-analysis/scripts/project-semantic-knowledge-wiki/build-project-semantic-wiki.mjs \
+     --asset-package <tmp>/project-assets \
+     --semantic-plan <tmp>/project-semantic-wiki-plan.json \
+     --output <tmp>/project-semantic-wiki \
+     --archive <tmp>/project-semantic-wiki.zip \
+     --project-name '<project_name>'
+   ```
+
+   When the exported package is `asset_scope=all_visible`, pass `--allow-all-visible` to the builder. Do not pass this flag unless the user explicitly requested all visible assets.
+4. Review the local asset meanings, SQL summaries, domains, conflicts, and recall cards. Business-domain sources must contain the short `Agent 使用摘要` for first-hop routing: primary analysis goals, preferred entries, main events, main metrics, drilldown dimensions, and boundaries. SQL report sources must also use one `Agent 使用摘要`, but that single section must contain the complete Agent-authored SQL semantics: purpose, parameters, output fields, grain, filters, limits, question boundaries, and evidence locator. This section must be business language an Agent can use directly, not parser labels such as `SQL 输出字段`, `来源表达式`, `${Selector:...}`, `${PartDate:...}`, `C00`, or raw SQL fragments. All business analysis should be completed here; missing evidence remains explicitly unknown. Precompile affected assets and their dependent domains/cards only on refresh; reuse unchanged semantic plan entries.
+5. Package the builder's Markdown sources. Raw JSON indexes and raw SQL remain in the local review/evidence package; the KB input contains the precompiled meanings and structured calculation facts.
+
+Package the builder's prepared Markdown sources into the source tree:
+
+```bash
+node skills/ae-analysis/scripts/project-semantic-knowledge-wiki/package-wiki-source-zip.mjs \
+  --source-dir <output>-kb-upload-sources \
+  --tree-output <output>-kb-source-tree \
+  --manifest-output <output>-kb-source-tree-manifest.json \
+  --output <new-archive>.zip
+```
+
+Then upload and run KB compilation:
+
+```bash
+node "$KB_RUN" +add --name '<company_kb_name>' --files '["<new-archive>.zip"]' --host <host>
+node "$KB_RUN" +schema --name '<company_kb_name>' --model <model_ref> \
+  --custom-instructions-file skills/ae-analysis/scripts/project-semantic-knowledge-wiki/default-compile-rules.md --host <host>
+node "$KB_RUN" +status --name '<company_kb_name>' --host <host>
+# Run only after schema generation succeeds.
+node "$KB_RUN" +compile --name '<company_kb_name>' --mode full --model <model_ref> --host <host>
+```
+
+Poll `+status`; never poll by resubmitting Schema. Schema/compile failure stops the flow; do not switch to snapshot import. Start with a few representative assets before attempting the complete package.
+
+## Refresh: update changed Markdown sources
+
+Regenerate the local Wiki using the existing semantic-plan contract. Use normalized content hashes from the builder's upload manifests so snapshot-only header changes do not rewrite every asset:
+
+```bash
+node skills/ae-analysis/scripts/project-semantic-knowledge-wiki/package-wiki-source-zip.mjs \
+  --source-dir <next>-kb-upload-sources \
+  --tree-output <next>-kb-source-tree \
+  --manifest-output <next>-kb-source-tree-manifest.json \
+  --previous-manifest <previous>-kb-source-tree-manifest.json
+```
+
+The returned plan contains add/replace/remove actions and unchanged paths under `sources/...`, with `skip` or `incremental` compilation. Do not replace an existing ZIP parent. Before each write, verify the remote bytes still match the last applied local baseline; preserve unexpected manual edits and stop on conflicts. Retain unchanged baseline bytes and update the persisted source-tree manifest only after successful application. If interrupted, reconcile remote bytes before resuming. Compare by the stable ZIP-relative `sources/...` path; when the previous local files are unavailable, discover current paths with paginated `+source-ls` and compare via `+source-read`. Do not replace the ZIP parent or re-upload every file. Do not run the old flat-source uploader or `plan-kb-source-sync.mjs`.
+
+For each changed path, obtain the current revision and perform one existing command through the wrapper:
+
+```bash
+node "$KB_RUN" +source-ls --name '<company_kb_name>' --id <zip_source_id> --path '' --host <host>
+node "$KB_RUN" +source-put --name '<company_kb_name>' --id <zip_source_id> \
+  --path sources/assets/reports/pskb-p5-report-123.md --file <local-file> --action replace --expected-revision <revision> --host <host>
+node "$KB_RUN" +source-rm --name '<company_kb_name>' --id <zip_source_id> \
+  --path <removed-generated-path> --expected-revision <revision> --host <host>
+```
+
+Only remove files owned by this generated asset package. Preserve unrelated source material and unexpected manual edits; stop on conflicts. Keep deletion confirmation unless the exact refresh deletion scope is already authorized. Execute sequentially using returned revisions; a 409 requires fresh discovery and review, not blind retry. Failed writes stop compilation. On resume, compare current remote bytes again so already successful writes are not replayed. Unchanged files are not written. Apply changed Markdown manifest/index sources from the plan too; keep the JSON sync manifest local.
+
+After all source-tree changes succeed, call `+compile --mode incremental --model <model_ref>` exactly once. Reuse the existing Schema. Do not force full compilation based only on file count or percentage. No file changes means skip compilation unless the user explicitly requests rebuilding or compiler rules have changed. Schema/authority/taxonomy rule changes require an explicit rebuild decision; normal source updates do not.
+
+Compiled navigation must stay decision-oriented. The generated Wiki homepage should not list every report/dashboard file or bare numeric IDs. It should link to modules, business domains, recall cards, category indexes, governance/review pages, and a small set of representative titled entries only. Individual assets belong in their category index or domain context, with title-first link text and IDs as supporting identity.
+
+## Acceptance and readback
+
+Completion requires `status=wiki_compiled`, `buildStatus=compiled`, no failed or partial sources, and complete publication when exposed. Verify both a first build and an actual changed-source incremental compile; a local preview or successful upload is not acceptance.
+
+Use company-scoped retrieval through the wrapper:
+
+```bash
+node "$KB_RUN" +index --name '<company_kb_name>' --host <host>
+node "$KB_RUN" +grep --name '<company_kb_name>' --query '<business question or marker>' --paths '["<path copied from index>"]' --host <host>
+node "$KB_RUN" +read --name '<company_kb_name>' --path '<path copied from index or grep>' --host <host>
+```
+
+Do not assume the old local Wiki layout. Inspect actual server paths. Check asset IDs, SQL/calculation fidelity, certification, missing facts, cross-source conflict handling and provenance. Smoke-test a representative reusable asset. After refresh, verify additions, changed current definitions, removal of obsolete assertions and preservation of unchanged facts. Historical definitions may remain only when explicitly marked historical and evidenced. Publish statistics such as `reusedPages` are evidence; incremental mode alone does not prove lower model cost.
+
+Report target scope/name, requested model, ZIP source ID/revision, compile status/version, source counts and quality findings. Record observed compile duration and usage; small-sample success does not prove a full package will stay below turn limits.
+
+## Authority and retrieval rules
+
+Each asset page must expose:
+
+```yaml
+authority_role: canonical | dependency_only | appendix
+certification_state: certified | uncertified
+definition_state: valid | conflict | unknown
+runtime_policy: allow | warn | block
+standalone_recall: true | false
+canonical_asset_id: report:1234 | null
+```
+
+- `authenticated=true` maps only to `certification_state=certified`; it never overrides a definition conflict. In explicit `all_visible` mode, unauthenticated assets remain visible as `certification_state=uncertified` and must not be described as approved/governed semantics.
+- A detectable conflict always yields `runtime_policy=block` and `standalone_recall=false` until reviewed.
+- An unauthenticated child retained through a certified parent is `dependency_only`; it can support its parent but cannot independently become the answer.
+- Technical appendix, duplicate, demo, reproduction, and targeted-diagnostic assets are blocked from standalone recall.
+- Ranking order is: project/permission/status filter -> recall card -> canonical and valid assets -> certification -> semantic relevance and usage. Raw evidence never participates in first-round broad recall.
+
+## SQL report rules
+
+Every SQL report requires structured semantics grounded in the packaged SQL and parameters. The compiled Wiki must include one CLI Agent-authored `## Agent 使用摘要` for every SQL report. That single section is the primary SQL business source; do not create a second SQL-specific summary section. The local review retains `sql_semantic_facts` and raw SQL for audit. KB consumes the precompiled meanings and only reopens analysis for concrete inconsistencies or new human evidence. Apply `default-compile-rules.md` to preserve:
+- business purpose;
+- input parameters and their meaning;
+- output fields;
+- statistical grain;
+- key filters and exclusions;
+- default limits or saved time constraints;
+- applicable questions;
+- non-applicable questions;
+- evidence locator.
+
+The builder rejects a plan that omits any SQL report or contains mechanically generated SQL summaries that expose parser placeholders instead of Agent-authored business semantics. If the evidence cannot support one of these fields, state `unknown` explicitly and set the report to `definition_state=unknown`; the report cannot be presented as a determined business caliber. Never infer a formula, unit, join relationship, or parameter meaning from a report title alone. CLI owns the main semantic analysis; KB owns final integration and incremental maintenance. Preserve unknown and blocked authority states unless explicit evidence resolves them.
+
+## Existing flat-source knowledge bases
+
+Do not automatically migrate existing flat sources or read-only snapshots. Keep existing user material and resolve a separate migration scope when necessary. Source-tree refresh uses the recorded ZIP source ID and directory mutations above.

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

@@ -0,0 +1,93 @@
+# Project semantic knowledge Wiki plan
+
+The Agent authors exactly one plan per asset-package snapshot. The builder validates every referenced asset against the package.
+
+```json
+{
+  "schema_version": "2.0",
+  "source_snapshot_hash": "<asset package snapshot_hash>",
+  "generation_method": "agent_semantic_synthesis",
+  "domains": [
+    {
+      "domain_id": "stable-lowercase-id",
+      "title": "业务域名称",
+      "summary": "这个业务域主要解决什么问题",
+      "primary_questions": ["用户会怎样提问"],
+      "primary_metrics": [
+        "Agent 总结的核心指标、口径作用和适用问题；不要写脚本占位词，例如“自定义指标”。"
+      ],
+      "drilldown_dimensions": [
+        "Agent 总结的常用下钻维度、字段 key 和使用场景；不要写缺少业务解释的技术字段。"
+      ],
+      "merge_rationale": "跨物理空间归并或拆分的证据",
+      "dashboard_ids": ["dashboard resource_key"],
+      "recall_cards": [
+        {
+          "card_id": "stable-card-id",
+          "questions": ["主问法", "同义问法"],
+          "intent": "要解决的业务决策",
+          "preferred_asset_refs": [
+            {
+              "resource_type": "dashboard",
+              "resource_key": "1234",
+              "reason": "为什么它是首选入口"
+            }
+          ],
+          "fallback_asset_refs": [],
+          "excluded_asset_refs": [
+            {
+              "resource_type": "report",
+              "resource_key": "5678",
+              "reason": "副本、冲突或仅依赖使用",
+              "canonical_resource_key": "5677"
+            }
+          ],
+          "requires_live_execution": true,
+          "live_execution_reason": "需要当前客户或数量时必须执行报表"
+        }
+      ]
+    }
+  ],
+  "appendices": [
+    {
+      "appendix_id": "technical-or-temporary-assets",
+      "title": "测试、演示与临时探索资产",
+      "summary": "保留用途",
+      "selection_rationale": "为什么不能进入主召回",
+      "dashboard_ids": ["dashboard resource_key"]
+    }
+  ],
+  "sql_report_semantics": [
+    {
+      "report_id": "SQL report resource_key",
+      "business_purpose": "这张 SQL 报表解决什么业务问题",
+      "input_parameters": [
+        {"name": "parameter", "meaning": "业务含义", "required": true}
+      ],
+      "output_fields": [
+        {"name": "field", "meaning": "业务含义"}
+      ],
+      "statistical_grain": "一行或一次聚合代表什么",
+      "key_filters": ["关键过滤和排除条件"],
+      "default_limits": ["默认时间、行数或范围限制；没有则写 none"],
+      "applicable_questions": ["适用问题"],
+      "non_applicable_questions": ["不适用问题"],
+      "evidence_locator": "asset package detail locator",
+      "definition_state": "valid | unknown"
+    }
+  ]
+}
+```
+
+## Rules
+
+- Every dashboard occurs exactly once across `domains[].dashboard_ids` and `appendices[].dashboard_ids`.
+- Domain titles represent business retrieval topics, not physical dashboard-space names.
+- Every domain has at least one recall card. Preferred and fallback refs must belong to that domain's dashboard/report closure or be a reusable metric directly referenced by it.
+- Every excluded ref names a concrete reason. A duplicate should name its canonical resource when known.
+- Every SQL report in the package has exactly one `sql_report_semantics` row. Unknown evidence is represented explicitly; it is never filled from the title.
+- SQL semantics are Agent-authored after reading the report definition and SQL. Do not populate them by reusable sentence templates or deterministic parser output alone.
+- `sql_report_semantics[].evidence_locator` exactly equals that report's packaged `source_detail_path`; never cite an external or guessed SQL definition.
+- A SQL report with `definition_state=valid` has at least one output field, one applicable question and one non-applicable question. Use `unknown` when those boundaries cannot be proven.
+- Visible SQL fields must use business names and meanings. Do not expose parser/debug terms such as `SQL 输出字段`, `来源表达式`, `${Selector:...}`, `${PartDate:...}`, `where 条件`, `order by`, or operator codes.
+- The plan contains no query results, customer rows, users, tokens, credentials, or conversation text.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli project timezone get --project-id <project_id>
-ae-cli project timezone get --dry-run --project-id <project_id>
 ```
 
 Capability id: `project.timezone.get`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli project timezone overview --project-id <project_id>
-ae-cli project timezone overview --dry-run --project-id <project_id>
 ```
 
 Capability id: `project.timezone.overview`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli project timezone update --project-id <project_id> --item timezone_toggle --payload '{"toggle":true}'
-ae-cli project timezone update --project-id <project_id> --item timezone_toggle --payload '{"toggle":true}' --dry-run
 ```
 
 Capability id: `project.timezone.update`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli project user-id-items update --project-id <project_id> --payload <payload>
-ae-cli project user-id-items update --dry-run --project-id <project_id> --payload <payload>
 ```
 
 Capability id: `project.user_id_items.update`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta property changelog-list --project-id <project_id> --table-type <table_type> --prop-name <prop_name>
-ae-cli analysis-meta property changelog-list --dry-run
 ```
 
 Capability id: `metadata.property.changelog_list`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta property create --project-id <project_id> --table-type event --payload '{"prop_name":"amount","prop_desc":"Amount","select_type":"number","common_prop":false,"super_event_ids":[<event_id>]}'
-ae-cli analysis-meta property create --dry-run
 ```
 
 Capability id: `metadata.property.create`.

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

@@ -9,7 +9,6 @@ Command:
 ```bash
 ae-cli analysis-meta property export --project-id <project_id> --scope event --output <temporary_path>/properties.json
 ae-cli analysis-meta property export --project-id <project_id> --scope event --event-name purchase --queries '["amount"]' --fields '["prop_name","prop_desc"]' --output <temporary_path>/properties.json
-ae-cli analysis-meta property export --dry-run
 ```
 
 Capability id: `metadata.property.export`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta property get --project-id <project_id> --table-type <table_type> --prop-name <prop_name>
-ae-cli analysis-meta property get --dry-run
 ```
 
 Capability id: `metadata.property.get`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta property hide-update --project-id <project_id> --table-type event --prop-names '["amount"]' --is-hide true
-ae-cli analysis-meta property hide-update --dry-run
 ```
 
 Capability id: `metadata.property.hide_update`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta property influence-list --project-id <project_id> --table-type <table_type> --prop-name <prop_name>
-ae-cli analysis-meta property influence-list --dry-run
 ```
 
 Capability id: `metadata.property.influence_list`.

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

@@ -2,7 +2,7 @@
 
 Use when the user needs to browse or search event/user property metadata, including dimension-table and complex child properties.
 
-Do not use it for property values. Use this command only when the user explicitly wants to inspect metadata or when a prior compiler error asks for disambiguation.
+Do not use it for property values. Use it when the task needs property metadata that is not already available from a verified definition or prior response.
 
 Command:
 
@@ -10,14 +10,13 @@ Command:
 ae-cli analysis-meta property list --project-id <project_id>
 ae-cli analysis-meta property list --project-id <project_id> --scope event --event-name purchase --queries '["demo","sample"]'
 ae-cli analysis-meta property list --project-id <project_id> --queries '["demo","sample"]' --fields '["prop_id","prop_name","prop_desc","prop_remark","select_type","table_type","authentication_status"]' --limit 50 --offset 0
-ae-cli analysis-meta property list --dry-run
 ```
 
 Capability id: `metadata.property.list`.
 
 Input sends `project_id` and optional `table_type`, `scope`, `event_name`, `queries`, `fields`, `limit`, `offset`, and `authenticated_only`.
 
-Output always uses the directory envelope: `data.items[]`, `total`, `limit`, `offset`, `has_more`, and `next_offset`. Dimension-table and complex child properties are returned as independent flat rows, so keyword search, field projection, and pagination apply to them in the same way as top-level properties.
+Output always uses the directory envelope: `data.properties[]`, `total`, `limit`, `offset`, `has_more`, and `next_offset`. Dimension-table and complex child properties are returned as independent flat rows, so keyword search, field projection, and pagination apply to them in the same way as top-level properties.
 
 ## Parameters
 | Parameter | Required | Description |
@@ -36,5 +35,5 @@ Output always uses the directory envelope: `data.items[]`, `total`, `limit`, `of
 
 - Prefer `--scope event` or `--scope user` when the user needs a specific table type.
 - Use `--authenticated-only true` only when the user explicitly asks for authenticated assets.
-- For ad-hoc analysis, pass the user's property wording in the AI-facing `definition` instead of pre-querying property metadata.
+- For a missing event property, use `--scope event --event-name <verified_event_name>`; reuse properties already known from selected definitions.
 - For a complete result, use `analysis-meta property export`; do not page repeatedly to synthesize an export.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta property related-events --project-id <project_id> --prop-name <prop_name>
-ae-cli analysis-meta property related-events --dry-run
 ```
 
 Capability id: `metadata.property.related_events`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta property relation-update --project-id <project_id> --table-type event --payload '{"prop_name":"amount","select_type":"number","super_event_ids":[<event_id>]}'
-ae-cli analysis-meta property relation-update --dry-run
 ```
 
 Capability id: `metadata.property.relation_update`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta property update --project-id <project_id> --table-type <table_type> --prop-name <prop_name> --prop-desc <prop_desc> --prop-remark <prop_remark>
-ae-cli analysis-meta property update --dry-run
 ```
 
 Capability id: `metadata.property.update`.

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

@@ -12,11 +12,13 @@ Command:
 ae-cli analysis report create --project-id <project_id> --report-name "Demo" --model-type event --definition '{...}' [--resolutions '<confirmed_resolution_json>'] [--report-desc "..."] [--dashboard-ids "[1001]"]
 ```
 
+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.
+
 Input sends `project_id`, `report_name`, `model_type`, `definition`, optional user-confirmed `resolutions`, `report_desc`, `cache_seconds`, `query_duration_ms`, and `dashboard_ids`. `--resolutions` is not supported with `--model-type tag`.
 
 Output is the gateway envelope. `data` contains the created `report_id`, creation status, normalized `model_type`, AI QP `definition`, and optional resolution warnings.
 
-Report creation and its `--validate` / `--dry-run` paths use the same compiler contract. `AI_QP_COMPILE_FAILED` preserves the full structured error array. No report is created on this failure; follow [`../metadata_resolution.md`](../metadata_resolution.md), keep the definition unchanged, and pass `--resolutions` only after user confirmation.
+Report creation and its `--validate` / `--dry-run` paths use the same compiler contract. `AI_QP_COMPILE_FAILED` preserves the full structured error array. No report is created on this failure; follow [`metadata_resolution.md`](metadata_resolution.md), keep each bound field's path and original wording, fill confirmed model parameters, and pass `--resolutions` only after user confirmation.
 
 ## SQL dynamic parameter shortest path
 
@@ -28,6 +30,6 @@ ae-cli analysis report create --project-id <project_id> --report-name "Recent SQ
 
 `use_timezone` is an optional boolean definition field only for `part_date`; it defaults to `false`. `true` makes that parameter use the query's effective timezone. It is a saved definition field, so change it through report create/update `--definition`, never through report-data `--sql-params`.
 
-After creation, keep the `report_id` returned by this exact create response. To verify the report, query the saved default first with `analysis report-data run` and omit `--sql-params`; then make one second query with a value-only `--sql-params` override. Do not rebuild internal `sqlViewParams` or guess an ID.
+After creation, keep the `report_id` returned by this exact create response. If the user also requests report data, call `analysis report-data run` directly with the requested value-only `--sql-params` overrides, or omit that flag to use saved defaults. Do not rebuild internal `sqlViewParams` or guess an ID.
 
 After any successful report create, call `analysis-meta asset url-get` with that returned `report_id` and output its `markdown_link`.

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

@@ -2,11 +2,11 @@
 
 Submit saved report data as a downloadable async artifact. It covers the 12 analysis report models from `ai_models.md` plus tag report data; tags are report-data only and are not ad-hoc `model_type` values.
 
-Typical closed loop: verify saved report definition -> resolve exact filter values and physical query route when needed -> submit export -> preserve the returned run/artifact pair -> inspect to a successful terminal state -> download and verify artifact content.
+Reuse the verified report definition; resolve unknown filter values or an explicitly requested physical route, then export once with `--output <file>`.
 
-Before adding overrides, call `analysis report get` for every report. The model matrix is the same as `report-data run`: SQL accepts only saved `definition.params` names through `--sql-params`; non-SQL analysis models accept filters/group/time overrides; tag executes its saved definition. Never put generic overrides and `--sql-params` in one homogeneous-model request.
+Before adding overrides, read any target report definition not already verified in the current task with `analysis report get`. The model matrix is the same as `report-data run`: SQL accepts only saved `definition.params` names through `--sql-params`; non-SQL analysis models accept filters/group/time overrides; tag executes its saved definition. Never put generic overrides and `--sql-params` in one homogeneous-model request.
 
-Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `export` command instead of `report-data run`.
+For full data, read [export handling](analysis_data_export.md) and use this `export` command instead of `report-data run`.
 
 Do not use this command for bounded inline previews; use `report-data run` when the requested result fits the sync data retrieval rule.
 
@@ -14,13 +14,13 @@ Command:
 
 ```bash
 # Non-SQL analysis report
-ae-cli analysis report-data export --project-id <project_id> --report-ids '[1001]' --filters '{"relation":"and","items":[{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}' --artifact-format jsonl
+ae-cli analysis report-data export --project-id <project_id> --report-ids '[1001]' --filters '{"relation":"and","items":[{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}' --artifact-format jsonl --output <file>
 
-# SQL report
-ae-cli analysis report-data export --project-id <project_id> --report-ids '[2001]' --sql-params '[{"name":"platform","value":"ios"}]' --artifact-format jsonl
+# SQL report, after report get confirms options[].name=Production
+ae-cli analysis report-data export --project-id <project_id> --report-ids '[2001]' --sql-params '[{"name":"environment","value":"Production"}]' --artifact-format jsonl --output <file>
 
 # Global cross-cluster export for a supported non-SQL report
-ae-cli analysis report-data export --project-id <project_id> --report-ids '[1001]' --cluster-query-scope GLOBAL --artifact-format jsonl
+ae-cli analysis report-data export --project-id <project_id> --report-ids '[1001]' --cluster-query-scope GLOBAL --artifact-format jsonl --output <file>
 ```
 
 Input also accepts optional `cluster_query_scope` and conditional `slave_cluster_id`. Omit both for current-self data. Resolve allowed physical routes with `analysis query-cluster list`; SQL reports reject `GLOBAL`. Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`.
@@ -35,11 +35,13 @@ Override model:
 - `group-by`: AI-facing intent array `[{field:{name,type?}}]`. Use the same field model as report definitions. Do not pass raw `TaGroupByVo`. Time granularity is controlled by `--time-granularity`, not by `--group-by`.
 - `sql-params`: SQL report dynamic parameter value overrides. First read `analysis report get`; every name must exist in every target SQL report's `definition.params`. Time fields require a saved `part_date` or time parameter. Send only override values; do not send definition fields such as `type`, `options`, or `use_timezone`.
 
+For a selector, the override object's `value` must contain the exact UI option label from the live selector definition's `options[].name`. Never pass `options[].value`; it is the saved SQL expansion fragment. If `{"name":"Production","value":"AND is_dev = false"}` is one saved option, the runtime override is `{"name":"environment","value":"Production"}`. Re-read `analysis report get` instead of guessing or automatically rewriting an ambiguous label. Treat `INVALID_REPORT_DEFINITION` with `selectorName invalid` as an override-name diagnostic and do not repeat the unchanged export.
+
 Mixed-model export batches are best-effort rather than rejected only for being mixed. Prefer one model per overridden export because artifact formats cannot surface submission-time warnings as prominently as inline `meta.warnings`.
 
-Output is the gateway envelope. `data` contains opaque `run_id` and `artifact_id`, lifecycle status and expiration, and effective timeout/deadline fields. Exports do not create `query_context_id`. Inspect/download through the dedicated CLI commands using the IDs.
+Output is the gateway envelope. `data` contains opaque `run_id` and `artifact_id`, lifecycle status and expiration, and effective timeout/deadline fields. Exports do not create `query_context_id`. The CLI handles waiting and download with `--output`.
 
-Keep `run_id` and `artifact_id` from the same export response. Inspect that exact `run_id`, then download only that paired `artifact_id`; never combine IDs from different exports.
+To resume an interrupted export, use `ae-cli analysis run wait --run-id <run_id> --output <file>` with the `run_id` from the same export response; see [`run_wait.md`](run_wait.md).
 
 An empty artifact is a successful query and means the requested time range has no data. If every requested report explicitly fails, the run reaches `FAILED` instead of completing an error-only artifact. Mixed exports may contain explicit per-report error markers alongside successful report data.
 

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

@@ -2,7 +2,7 @@
 
 Execute bounded inline data from one or more saved reports.
 
-Typical closed loop: discover a saved report -> verify its definition -> resolve any unknown exact filter value with `analysis filter-value list` -> optionally resolve a physical route with `analysis query-cluster list` -> run -> inspect actual scope and warnings -> use the returned synchronous query context for drilldown.
+Typical closed loop: discover a saved report -> verify its definition -> resolve any unknown exact filter value with `analysis filter-value list` -> optionally resolve a physical route with `analysis query-cluster list` -> run -> inspect actual scope and warnings. Use query context only for a requested, supported follow-up action.
 
 Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `run` command instead of `report-data export`.
 
@@ -10,7 +10,7 @@ Do not use this command for full, unknown-size, larger than the current runtime
 
 This gateway report-data capability executes saved reports with model-specific overrides. It covers the 12 analysis report models from `ai_models.md` plus tag report data; tags are report-data only and are not ad-hoc `model_type` values.
 
-Before adding any query-condition override, call `analysis report get` for every `report_id` and branch on `data.model_type`:
+Before adding any query-condition override, reuse each report definition already read or call `analysis report get` for the missing `report_id` and branch on `data.model_type`:
 
 | Saved report model | Valid query-condition overrides |
 |---|---|
@@ -24,8 +24,8 @@ Command:
 # Non-SQL analysis report
 ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]' --filters '{"relation":"and","items":[{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}' --start-time 2026-07-01 --end-time 2026-07-09 --preview-rows 20
 
-# SQL report, after analysis report get confirms definition.params contains platform
-ae-cli analysis report-data run --project-id <project_id> --report-ids '[2001]' --sql-params '[{"name":"platform","value":"ios"}]' --preview-rows 20
+# SQL report, after analysis report get confirms a selector option has options[].name=Production
+ae-cli analysis report-data run --project-id <project_id> --report-ids '[2001]' --sql-params '[{"name":"environment","value":"Production"}]' --preview-rows 20
 
 # Explicit local-time mode (not UTC+99)
 ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]' --zone-offset 99 --preview-rows 20
@@ -47,14 +47,21 @@ Override model:
 
 - `filters`: AI-facing intent object `{relation:"and|or", items:[{field:{name,type?}, operator, values?}]}`. `field.type` supports `event_property`, `user_property`, `cluster`, and `tag`; omit it only when the field name is unambiguous. Use field names from `analysis report get` definition output or metadata commands. Do not pass raw QP fields such as `taFilters`, `junctionKind`, `columnName`, `tableType`, or `selectType`.
 - `group-by`: AI-facing intent array `[{field:{name,type?}}]`. Use the same field model as report definitions. Do not pass raw `TaGroupByVo`. Time granularity is controlled by `--time-granularity`, not by `--group-by`.
-- `sql-params`: SQL report dynamic parameter value overrides. First read `analysis report get`; saved SQL params are exposed as AI-facing `definition.params`. Every name must exist in every target SQL report because one batch shares the override. Send only override values for existing parameter names: `[{"name":"platform","value":"ios"}]`, `[{"name":"server_id","operator":"contains","value":"s1"}]`, `[{"name":"level","operator":"eq","values":["42"]}]`, `[{"name":"amount","operator":"between","values":["10","20"]}]`, `[{"name":"part_date","start_time":"2026-07-01 00:00:00","end_time":"2026-07-09 23:59:59"}]`, or `[{"name":"part_date","recent_day":"1-7"}]`. Time fields require a saved `part_date` or time parameter. Operators `eq`/`in`, `neq`/`not_in`, and `between` use `values`; comparison/like/contains operators use single `value`. Do not send definition fields such as `type`, `options`, or `use_timezone`; change them through report update.
+- `sql-params`: SQL report dynamic parameter value overrides. First read `analysis report get`; saved SQL params are exposed as AI-facing `definition.params`. Every name must exist in every target SQL report because one batch shares the override. Send only override values for existing parameter names: `[{"name":"environment","value":"Production"}]`, `[{"name":"server_id","operator":"contains","value":"s1"}]`, `[{"name":"level","operator":"eq","values":["42"]}]`, `[{"name":"amount","operator":"between","values":["10","20"]}]`, `[{"name":"part_date","start_time":"2026-07-01 00:00:00","end_time":"2026-07-09 23:59:59"}]`, or `[{"name":"part_date","recent_day":"1-7"}]`. Time fields require a saved `part_date` or time parameter. Operators `eq`/`in`, `neq`/`not_in`, and `between` use `values`; comparison/like/contains operators use single `value`. Do not send definition fields such as `type`, `options`, or `use_timezone`; change them through report update.
+
+Selector runtime contract:
+
+- Find the matching selector in the live `data.definition.params` returned by `analysis report get`.
+- The override object still uses the field named `value`, but its content must be the exact UI label from that selector's `options[].name`, including case and punctuation.
+- Never put `options[].value` in the runtime override. That field is the saved SQL expansion fragment, not the runtime selector name. For example, if an option is `{"name":"Production","value":"AND is_dev = false"}`, send `{"name":"environment","value":"Production"}`, not the SQL fragment.
+- Do not guess from a stale knowledge-base snapshot and do not automatically translate ambiguous labels. Re-read the live report definition. If execution returns `INVALID_REPORT_DEFINITION` with `selectorName invalid`, correct the override from `options[].name`; do not repeat the unchanged request.
 
 A homogeneous SQL request that includes `filters`, `group_by`, `start_time`, `end_time`, or `time_granularity` fails with `INVALID_OVERRIDE_FOR_MODEL`. A homogeneous non-SQL request with `sql_params` also fails. Mixed-model batches are best-effort: data still returns and `meta.warnings[]` uses `OVERRIDE_IGNORED_FOR_MODEL`, `model_type`, `report_ids`, and `ignored_fields` to identify fields that did not apply. Do not discard these warnings.
 
-For a newly created or updated dynamic SQL report, omit `--sql-params` to execute the saved default first. After that succeeds, then make one second call with `--sql-params` to change only the requested value. This separates a broken saved default from a broken override and avoids repeating the same query.
+For a SQL report query, pass the requested value overrides directly through `--sql-params`; omit it when the saved defaults are requested.
 
 Output is the gateway envelope. When at least one report exposes a follow-up action, `data` contains bounded inline report result items plus `query_context_id` and compact `sources[]` summaries. Each source includes `effective_zone_offset`, the timezone value actually used for that query. When `zone_offset` is omitted, this is the resolved current-user timezone when available, otherwise the project default; when `zone_offset` is explicit, this is its resolved effective value. SQL-only and otherwise non-drillable results omit query context entirely. Use `analysis query-context get` to read the selected source's full coordinate options.
 
 `meta.actual_cluster_query_scope`, optional `meta.actual_slave_cluster_id`, and `meta.cluster_query_scope_source` describe the actual physical route. Verify them before comparing or drilling down. An empty batch or report result with no rows is a successful query: it means the requested time range has no data. The command fails only when every returned report entry contains an explicit execution error.
 
-Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Call `analysis query-context get`, select only its returned row/column/metric options, and call only the advertised event, entity, or result-cluster action. Do not pass raw QP.
+Only when the user requests a supported follow-up action, read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Call `analysis query-context get`, select only its returned row/column/metric options, and call only the advertised event, entity, or result-cluster action. Do not pass raw QP.