@thinkingai/ae-cli 6.1.19 → 6.1.21

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

@@ -8,12 +8,42 @@ Command:
 
 ```bash
 ae-cli project role upsert --project-id <project_id> --payload <payload>
+ae-cli project role upsert --validate --project-id <project_id> --payload <payload>
 ae-cli project role upsert --dry-run --project-id <project_id> --payload <payload>
 ```
 
 Capability id: `project.role.upsert`.
 
-Input sends `project_id`, `payload`. Payload keys, JSON arrays, and projection fields must follow the common-service snake_case input schema.
+Input sends `project_id`, `payload`. Payload keys must use snake_case.
+
+## Payload contract
+
+`role_func_list` is required and must be a non-empty array of objects. Every item requires:
+
+- `function_name`: non-empty string. Resolve valid values with `ae-cli project function list` instead of guessing IDs or sending numeric function IDs.
+- `has_power`: integer `0` or `1` only. Use `1` to select the function and `0` to leave it unselected.
+
+For role creation, omit `role_name` and provide `role_desc` with 1 to 80 characters. For an update, provide the existing `role_name`; `role_desc` may remain omitted for compatibility.
+
+Functions omitted from `role_func_list` are completed by the service with their permission metadata and `has_power=0`. Do not attempt to replace an object item with a number or string.
+
+Create example:
+
+```bash
+ae-cli project role upsert \
+  --project-id 196 \
+  --payload '{"role_desc":"Data analyst","role_func_list":[{"function_name":"viewReport","has_power":1}]}'
+```
+
+Update example:
+
+```bash
+ae-cli project role upsert \
+  --project-id 196 \
+  --payload '{"role_name":"custom_role","role_func_list":[{"function_name":"viewReport","has_power":1}]}'
+```
+
+Run with `--validate` first when constructing the payload dynamically. Invalid item types, missing fields, an empty list, or a `has_power` value outside `0` and `1` return a validation error before the role is saved.
 
 Output uses the gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Preserve `request_id` and `invocation_id` when present.
 
@@ -21,4 +51,4 @@ Output uses the gateway envelope: success is `ok=true,data,meta`; failure is `ok
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
-| `--payload` | Yes | Role save payload matching RoleSaveRequestDTO in snake_case. |
+| `--payload` | Yes | Role payload with a non-empty `role_func_list` object array; each item contains `function_name` and `has_power` (`0` or `1`). |

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli project role-user list --project-id <project_id> --role-name <role_name>
-ae-cli project role-user list --dry-run --project-id <project_id> --role-name <role_name>
 ```
 
 Capability id: `project.role_user.list`.

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.