@thinkingai/ae-cli 6.1.23 → 6.1.25

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

@@ -11,6 +11,16 @@ Do not load project semantics, project KB, or personal semantic preferences befo
 
 Hard output gate: a final answer is invalid if it is grouped by asset type, backend array order, raw `work_units`, source dashboard, source report, or separate top-level asset and metric sections. The final answer must follow the fixed business-domain review display below.
 
+## Intent Routing
+
+There are three separate user intents. Do not merge them.
+
+- Recommendation only: call `analysis-meta governance-recommendation export`, present the evidence-backed recommendations, and stop. Do not check the automatic certification project config, do not submit to the review page, and do not certify assets.
+- Recommendation plus page submission: call `analysis-meta governance-recommendation export`, build the review material, then call `analysis-meta agent-review submit-to-page` only after that submission intent is explicit. Do not check the automatic certification project config and do not certify assets.
+- Automatic review or automatic certification: call `analysis-meta governance-recommendation auto-review`. This command validates both `agent_auto_asset_certification_enabled` and `project_semantic_enable` before collecting recommendations. If it returns `PROJECT_AUTO_CERTIFICATION_DISABLED` or `PROJECT_SEMANTIC_DISABLED`, tell the user which project config is disabled and stop. Do not fall back to page submission or ordinary approval commands.
+
+`analysis-meta governance-recommendation auto-review` only certifies eligible asset candidates from its current recommendation batch. When `--limit` is omitted, the CLI mirrors the recurring page-review bounded expansion flow by read-only probing top-20/top-50/top-100 pending material, then the CLI Agent builds one automatic decision set from the final selected material and submits it for execution/audit. It does not create recommended metrics. Assets that return `decision:"SKIP"` remain for manual review and must not be described as certified. Automatic decision rows must provide reviewer-readable reasons; semantic-duplicate skips must name concrete conflicting asset targets. Keep raw source/rule traces only in debug output, and preserve the returned `auto_review_expansion` when reporting or auditing the result. If the user later asks to submit the remaining uncertified assets to the page, use `manual_review_handoff` from the auto-review result rather than drafting a fresh all-candidate page batch.
+
 Command:
 
 ```bash
@@ -103,6 +113,7 @@ Use this fixed review skeleton:
 ## Related Commands
 
 - `analysis-meta agent-review submit-to-page` submits existing-asset proposals for review after user choice or preauthorized submission-only task intent; it does not approve or certify. Read `agent_review_submit_to_page.md` for deduplication and unattended-task rules.
+- `analysis-meta governance-recommendation auto-review` automatically certifies only eligible recommended asset candidates when the user explicitly asks for automatic review/certification and the project switches are enabled. Without an explicit `--limit`, it performs CLI-side bounded expansion and writes only once. Read `governance_recommendation_auto_review.md`.
 - `analysis-meta governance-recommendation submit`
 - `analysis-meta governance-recommendation decisions`
 - `analysis-meta asset-authentication list` only inspects certification state and is not the recommendation workflow.

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

@@ -4,14 +4,14 @@ Reuse verified assets, canonical names and business meanings in the current proj
 
 ## Find a reusable definition
 
-For an unknown business measure, search relevant saved metrics and reports. A named asset needs only its own family; already known definitions go directly to execution. Read the selected [metric](metric_list.md) and [report](report_list.md) command references together, then issue independent searches in the same model turn:
+For an unknown business measure, search relevant saved metrics and readable analysis assets. A named asset needs only its own family; already known definitions go directly to execution. Read the selected [metric](metric_list.md) and [asset search](asset_search.md) command references together, then issue independent searches in the same model turn:
 
 ```bash
 ae-cli analysis-meta metric list \
   --project-id <project_id> \
   --queries '["<user phrase>","<related English term>"]'
 
-ae-cli analysis report list \
+ae-cli analysis asset search \
   --project-id <project_id> \
   --queries '["<user phrase>","<related English term>"]'
 ```
@@ -20,7 +20,7 @@ Use the user's business terms and a few relevant English terms in the same `--qu
 
 Read metrics from `data.metrics`. With `--queries` and no `--fields`, the response includes `metric_events` and `metric_params` as JSON strings. Inspect those returned definitions directly; use `metric get` only for missing details. Field projection cannot select these two definition fields. A verified saved metric is referenced by `metric_name` in `metrics[].event` and supplies its own aggregation and property.
 
-Read report summaries from `data.items`. Report search matches names and descriptions. For a suitable candidate, use `analysis report get --project-id <project_id> --report-id <report_id>` to read `data.model_type` and `data.definition`; reuse a definition already read.
+Read saved-asset summaries from `data.items`; report and dashboard search matches names and descriptions. For a suitable report candidate, pass its `asset_numeric_id` to `analysis report get --project-id <project_id> --report-id <report_id>` to read `data.model_type` and `data.definition`; reuse a definition already read.
 
 Compare the candidate's events, aggregation, filters, groups and time semantics with the request. An applicable report goes directly to [report-data run](report_data_run.md) with the supported requested overrides. A custom combination reuses suitable definitions in an AI-facing model. Saved metric JSON describes its measure; it is not itself a complete ad-hoc definition. Discover only the pieces still missing below.
 

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

@@ -13,7 +13,9 @@ ae-cli analysis-meta metric export --project-id <project_id> --queries '["pay","
 
 Capability id: `metadata.metric.export`.
 
-Input: the gateway receives `project_id` plus optional `ignore_authentication`, `queries`, `fields`, and `authenticated_only`; `output` is local-only.
+Input: the gateway receives `project_id` plus optional `ignore_authentication`, `queries`, `fields`, `authenticated_only`, and `certification_scope`; `output` is local-only.
+
+Use `--certification-scope project|certified|all` consistently with the corresponding list command. The default `project` follows the project switch; `certified` exports only certified assets; `all` exports every accessible asset. This scope never bypasses access permissions.
 
 Output: a successful response must prove `complete=true` and `total` equal to the row count before the CLI atomically publishes a private-mode `.json` array.
 

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

@@ -31,7 +31,7 @@ Output always uses the directory envelope: `data.metrics[]`, `total`, `limit`, `
 | `--authenticated-only` | No | When true, return only authenticated metrics. |
 
 ## Decision Rules
-- For an unknown business measure, use this with relevant `report list` search as the saved-definition discovery path in [`metadata_resolution.md`](metadata_resolution.md). Reuse a verified saved metric name directly.
+- For an unknown business measure, use this with `analysis asset search` as the saved-definition discovery path in [`metadata_resolution.md`](metadata_resolution.md). Reuse a verified saved metric name directly.
 - Use `--fields` when its projected fields are sufficient. When searching with `--queries`, omit `--fields` to keep `metric_events` and `metric_params` as JSON strings. Read their content in this response; these two fields are not in the projection whitelist.
 - Use `analysis-meta metric get` only when a required definition detail is absent from the returned row.
 - For a complete result, use `analysis-meta metric export`; do not page repeatedly to synthesize an export.

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

@@ -22,3 +22,13 @@ Output `data` is an async XLSX descriptor with `run_id`, `artifact_id`, status,
 | --project-id | Yes | Numeric project ID. |
 | --record-id | No | Operation record ID; required unless provided inside payload. |
 | --payload | No | Optional JSON object merged into top-level input. Use schema-declared snake_case fields; explicit flags take precedence. `node_ids`, `searchs`, and `status` are arrays; `rule` is an object when supplied. |
+
+## Asynchronous export
+
+This capability starts an asynchronous artifact export. Use `--wait --output <path>` to wait and download, or keep the returned `run_id` for query status and cancellation. `--force` allows overwriting the selected local output file.
+
+- `--artifact-format xlsx` selects the logical data format. Follow the returned descriptor for compression and content type.
+- `--request-id cli_<32 lowercase hex>` assigns a stable request identifier.
+- `--timeout-seconds` accepts 1–7200 (server default: 3600).
+- `--wait-timeout-seconds` controls how long this CLI invocation waits; it does not change the server runtime limit.
+- Explicit flags override corresponding `--payload` fields; omitted options preserve payload values.

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

@@ -2,7 +2,7 @@
 
 Add one personal semantic preference for the authenticated user in one project.
 
-Use this when the user explicitly asks to save a personal semantic preference, or when the current project task contains an explicit stable statement, correction, or confirmation that should become a reusable current-user preference. A current-user working definition remains eligible even when the same content may benefit other users. A second "save" confirmation is not required after that evidence gate is met, unless the target meaning is ambiguous.
+Use this when the user explicitly asks to save a personal semantic preference, or when the current project task contains an explicit stable statement, correction, reusable workflow, or confirmation that should become a reusable current-user preference. When a project scope is active, requests such as "remember the above workflow", "save this process for this project", or "以后按这个流程" are project-scoped personal semantics, not global memory; store reusable workflows with `context_type=experience`. A current-user working definition remains eligible even when the same content may benefit other users. A second "save" confirmation is not required after that evidence gate is met, unless the target meaning is ambiguous.
 
 Command:
 
@@ -10,7 +10,7 @@ Command:
 ae-cli personal-semantic-preference add --project-id <project_id> --context-type <context_type> --title <title> --summary <summary> --content <content> [--keywords '["keyword"]'] [--resource-refs '[{"resource_type":"report","resource_key":"101","display_name":"Revenue daily report"}]'] [--fresh-until-at "yyyy-MM-dd HH:mm:ss"] [--request-id <id>]
 ```
 
-Use `preference` for durable interpretation/output preferences, `asset_context` for durable wording or intent bound to exact assets, `experience` for confirmed reusable work methods, and `background` for stable personal context. `--resource-refs` is required and non-empty only for `asset_context`; for every other type it must be absent or empty.
+Use `preference` for durable interpretation/output preferences, `asset_context` for durable wording or intent bound to exact assets, `experience` for confirmed reusable project work methods or analysis workflows, and `background` for stable personal context. `--resource-refs` is required and non-empty only for `asset_context`; for every other type it must be absent or empty.
 
 `--resource-refs` accepts 1 to 50 ordered objects. Each object contains exactly `resource_type`, string `resource_key`, and `display_name`; `(resource_type, resource_key)` must be unique. `resource_type` is generic lower snake_case rather than a report-only enum, so events, properties, metrics, tags, clusters, reports, dashboards, data tables, and later asset types share the same shape. Array order is the user's intended priority.
 

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

@@ -2,18 +2,18 @@
 
 Get one personal semantic preference by ID.
 
-Use this command after `personal-semantic-preference list` identifies a likely current-user preference. Pass `--mark-used` when the preference is adopted for the answer, query path, or as the matched target for an update.
+Use this command after `personal-semantic-preference list` identifies a likely current-user preference. Pass the returned directory title with `--title`; it is telemetry context only, and the lookup still uses `id`. Pass `--mark-used` when the preference is adopted for the answer, query path, or as the matched target for an update.
 
 Command:
 
 ```bash
-ae-cli personal-semantic-preference get --project-id <project_id> --id <preference_id> [--mark-used]
+ae-cli personal-semantic-preference get --project-id <project_id> --id <preference_id> --title <title_from_list> [--mark-used]
 ```
 
-Input uses `project_id`, `id`, and optional `mark_used`. `id` must be the exact `preference_<id>` value returned by list/add.
+Input uses `project_id`, `id`, required `title`, and optional `mark_used`. `id` must be the exact `preference_<id>` value returned by list/add. `title` must be copied from the matching list item; do not invent it.
 
 Do not use this command as a keyword search, project semantics lookup, or asset catalog lookup. Do not call it repeatedly for every catalog row. Do not use `--mark-used` for a candidate that turns out not to match the user's intent or is only inspected and then rejected.
 
-When a published project semantic conflicts with the personal item, the project semantic is the formal definition. Fetch and mark the personal item only when it materially affects the response, such as an explicitly requested non-formal alternative; never silently use it to override the project semantic.
+Fetch and mark the personal item only when it materially affects the response. When its asset or calculation wording differs from the current saved definition, explain the difference and use the saved definition for execution unless the user explicitly requests a different calculation.
 
 Output is the gateway envelope. `data.preference` contains the full personal preference, including content, complete ordered `resource_refs`, and revision. When `--mark-used` is set, the backend increments `heat_count` and updates `last_used_at` for that record.

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

@@ -16,9 +16,9 @@ Do not use this command for project semantics, shared knowledge, metadata catalo
 
 Output is the gateway envelope. `data.items[]` contains only `id`, `context_type`, `title`, truncated `summary`, limited `keywords`, `resource_ref_count`, distinct `resource_types`, and `revision`; it deliberately omits content, full asset references, heat, and timestamps. `data.returned_count` is at most 200, `data.truncated` says whether entries were omitted, and `data.selection_policy` is `HOT_160_PLUS_RECENT_40`: up to 160 highest-heat items plus up to 40 recently changed items not already selected. The backend may return fewer items to keep the data payload within 64 KiB.
 
-If one returned item is actually adopted to interpret the user's request, call `ae-cli personal-semantic-preference get --project-id <project_id> --id <preference_id> --mark-used` before using its full content. Do not mark an item used when it was only inspected or rejected.
+If one returned item is actually adopted to interpret the user's request, call `ae-cli personal-semantic-preference get --project-id <project_id> --id <preference_id> --title <title_from_list> --mark-used` before using its full content. The `--title` value is telemetry context only; the backend lookup is still keyed by `id`. Do not mark an item used when it was only inspected or rejected.
 
-Compare a likely match with the published project semantic catalog. Published project semantics remain the formal project-wide authority; personal items provide current-user defaults and working interpretations. If they conflict, use the project semantic for the formal result, explicitly disclose the personal difference, and do not mark the personal item used unless the user explicitly adopts it as a labeled alternative.
+Use a likely match only as the current user's working interpretation. Verify any chosen asset or calculation against its saved definition before execution. A personal preference does not replace the asset's current definition.
 
 ## Capture a durable preference
 
@@ -26,10 +26,10 @@ The Agent owns the personal preference capture trigger. Choose `context_type` by
 
 - `preference`: durable interpretation or output preference without an exact asset binding.
 - `asset_context`: durable user wording or intent bound to one or more exact project assets. Send the complete ordered `resource_refs` array; each item has `resource_type`, string `resource_key`, and `display_name`. This identity is generic across reports, dashboards, events, properties, metrics, tags, clusters, data tables, and future asset types.
-- `experience`: a confirmed reusable work method without an exact asset binding.
+- `experience`: a confirmed reusable project work method or analysis workflow without an exact asset binding.
 - `background`: stable personal context without an exact asset binding.
 
-Any stable choice of a concrete asset, including an event-selection scenario, must use `asset_context`; do not encode asset IDs only in prose. A current-user working definition remains eligible for personal storage even when it would also benefit other users. Store it only as the current user's preference; do not copy the bound asset definition into its content or imply that it is shared authority. Keep future governance or lifecycle instructions out of the stored content. Do not save transient task details, one-off analysis results, company knowledge, or standalone metadata facts.
+Any stable choice of a concrete asset, including an event-selection scenario, must use `asset_context`; do not encode asset IDs only in prose. In an active project scope, a user request such as "remember the above workflow", "save this process for this project", or "以后按这个流程" should be captured here as `context_type=experience`, not through `ae-cli memory`. A current-user working definition remains eligible for personal storage even when it would also benefit other users. Store it only as the current user's preference; do not copy the bound asset definition into its content or imply that it is shared authority. Keep future governance or lifecycle instructions out of the stored content. Do not save transient task details, one-off analysis results, company knowledge, or standalone metadata facts.
 
 An explicit stable statement, correction, or confirmation that passes that evidence gate authorizes `personal-semantic-preference add` or `update` without a second "save" confirmation. Compare against the already loaded catalog first; when one existing preference matches, fetch it with `--mark-used`, update that existing preference, and avoid creating a duplicate. Otherwise add a new one. An explicit instruction not to retain it always wins. Delete remains high risk and requires explicit user confirmation.
 

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

@@ -1,9 +1,11 @@
 # 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.
+Asset-package export requires access to the target project. Neither the retired `project_semantic_enable` project switch nor the company switch for automatic knowledge-base discovery gates an explicit build or refresh. If project access or company KB permission is denied, report the error and stop; do not switch to a different project, scope, or export path.
 
 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.
 
+The first product goal is not an asset directory. The Wiki must teach the user and Agent how this project observes business: what business system it covers, who uses it, what business objects exist, how those objects relate, which judgment chains users follow, and which assets play primary, supporting, drilldown, or exclusion roles in those chains. Asset pages, report formulas and metadata pages hang under that business judgment model. A Wiki that only lists domains, reports, metrics, dimensions, recall cards, counts, or source containers is an incomplete project semantic KB even if it compiles.
+
 ## 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.
@@ -17,7 +19,7 @@ Build one server-consumable project semantic source Wiki from one immutable Comm
 
 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.
+CLI Agent performs the main semantic precompilation: understand definitions and SQL, author a project-level business model, complete asset meanings, domain judgment models, 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 positioning, business objects, judgment chains, 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
 
@@ -31,10 +33,10 @@ The KB description is part of Agent auto-loading and source selection, not a cas
 <project_name><asset_scope_label>项目语义知识库，用于辅助 Agent 在分析前召回业务域、资产口径、SQL 报表语义和治理边界。
 ```
 
-For example:
+For example, using a fictional project name:
 
 ```text
-产品雷达已认证资产项目语义知识库，用于辅助 Agent 在分析前召回业务域、资产口径、SQL 报表语义和治理边界。
+示例项目已认证资产项目语义知识库，用于辅助 Agent 在分析前召回业务域、资产口径、SQL 报表语义和治理边界。
 ```
 
 ```bash
@@ -90,7 +92,7 @@ The source tree only classifies material. Authority still comes from explicit fa
 ## 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.
+2. Preserve the local planning and rendering stages. Read the compact knowledge indexes, including dashboard notes, and only the normalized details needed for project positioning, business objects, object relationships, judgment chains, 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. Do not hardcode project names, business domains, asset IDs, event names, metric names, or example decision chains into the workflow; examples are illustrative only, and the Agent must derive the current project's model from the current package. 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
@@ -103,7 +105,7 @@ The source tree only classifies material. Authority still comes from explicit fa
    ```
 
    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.
+4. Review the local project business model, domain judgment models, asset meanings, SQL summaries, domains, conflicts, and recall cards. The project overview must start with business positioning, business objects, object relationships, judgment chains, and non-goals; asset counts and snapshot metadata come later. Business-domain sources must contain the judgment model plus the short `Agent 使用摘要` for first-hop routing: business state judged, objects, signals, decision path, asset roles, primary analysis goals, preferred entries, main events, main metrics, drilldown dimensions, and boundaries. Non-SQL report summaries must not repeat the same generated sentence as both purpose and applicable question; they should expose the report's business use, usable questions, metrics/outputs, drilldown dimensions, filters and boundaries from structured asset evidence, and use "return to source report to confirm" wording for missing fields instead of parser-style `未识别/未发现` placeholders. 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`, raw SQL fragments, or visible build-process phrases such as `CLI Agent 基于同一资产快照生成`, `摘要来源`, `semantic_plan`, `builder`, `parser fallback`. 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:
@@ -131,17 +133,33 @@ Poll `+status`; never poll by resubmitting Schema. Schema/compile failure stops
 
 ## 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:
+Regenerate the local Wiki using the existing semantic-plan contract. On refresh, reuse unchanged semantic-plan entries instead of asking the Agent to rewrite them. The builder persists the reusable semantic plan and fragment-level state in `sources/project/<namespace>-refresh-state.md`, and records each Markdown source's fragment dependencies. A changed recall card, SQL summary, domain model, appendix, or project model affects only sources that reference that fragment; never treat the whole semantic-plan file hash as a full-source rewrite trigger. When the asset package snapshot hash changes but the existing plan is intentionally reused, pass `--allow-semantic-plan-snapshot-drift`; the builder still validates current project, domain, asset, recall-card and SQL-report references against the new package and stops if the closure no longer matches. Do not use this flag for first build or to bypass real asset additions/removals. 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/build-project-semantic-wiki.mjs \
+  --asset-package <tmp>/project-assets-next \
+  --semantic-plan <previous-or-updated-semantic-plan.json> \
+  --output <next>/project-semantic-wiki \
+  --archive <next>/project-semantic-wiki.zip \
+  --project-name '<project_name>' \
+  --allow-semantic-plan-snapshot-drift
+```
 
 ```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
+  --previous-refresh-state <remote-refresh-state.md> \
+  --embed-refresh-state-baseline \
+  --baseline-source-id <zip_source_id> \
+  --baseline-content-revision <current_content_revision> \
+  --baseline-published-version-id <published_version_id>
 ```
 
-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`.
+The normal refresh baseline is remote managed state, not the local filesystem. Read `+list-sources` once to get the ZIP source ID and current `contentRevision`, then read only `sources/project/<namespace>-refresh-state.md`. The refresh state hidden payload contains the previous semantic plan, fragment state, source-tree manifest, source ID, content revision, published version ID, and manifest hash. If `contentRevision` matches the saved baseline, use `--previous-refresh-state` and compare against the saved source-tree manifest; do not page through every remote file and do not run full `+source-read` over the ZIP. If it differs, treat the baseline as potentially stale but still start from `--previous-refresh-state`; verify only paths that would be written or removed before mutating them, and escalate to a full source-tree read only when the refresh state is missing, corrupt, or cannot explain the required conflict check. A local `<previous>-kb-source-tree-manifest.json` with `--previous-manifest` is a compatibility fallback for manual repair runs, not the scheduled path.
+
+The returned plan contains add/replace/remove actions and unchanged paths under `sources/...`, with `skip` or `incremental` compilation. `--previous-tree-root` lets a repair run re-hash the last applied local baseline with the current normalizer, so harmless compiler/normalization-rule changes do not create a one-time false delta. Do not replace an existing ZIP parent. Before each write, verify the target remote bytes still match the saved source-tree manifest hash for that path; preserve unexpected manual edits and stop on conflicts. After successful writes, replace the managed refresh-state source with the new payload produced by `--embed-refresh-state-baseline` so the next run remains independent of local state. Compare by the stable ZIP-relative `sources/...` path. 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:
 
@@ -153,11 +171,11 @@ 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.
+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. A refresh-state-only baseline update is a managed-state write and does not by itself require compilation.
 
 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.
+Compiled navigation must stay decision-oriented. The generated Wiki homepage should first point to the project business model, then business domains, recall cards, category indexes, governance/review pages, and a small set of representative titled entries only. It should not list every report/dashboard file or bare numeric IDs. Individual assets belong in their category index or domain context, with title-first link text and IDs as supporting identity.
 
 ## Acceptance and readback
 
@@ -171,7 +189,7 @@ node "$KB_RUN" +grep --name '<company_kb_name>' --query '<business question or m
 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.
+Do not assume the old local Wiki layout. Inspect actual server paths. Check the project overview can answer: what business system this project observes, who uses it, what business objects exist, how objects relate, what decision chains exist, which assets attach to each chain, and what cannot be answered without live execution. Then check domain judgment models, 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.
 

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

@@ -7,6 +7,46 @@ The Agent authors exactly one plan per asset-package snapshot. The builder valid
   "schema_version": "2.0",
   "source_snapshot_hash": "<asset package snapshot_hash>",
   "generation_method": "agent_semantic_synthesis",
+  "project_business_model": {
+    "business_positioning": "该项目观察的业务系统、服务对象和决策范围。必须从当前资产包证据归纳，不得写项目特化模板。",
+    "audience_roles": ["会使用这个项目做业务判断的角色"],
+    "business_objects": [
+      {
+        "object_id": "stable-object-id",
+        "name": "业务对象名称",
+        "meaning": "对象在本项目中的业务含义",
+        "evidence_refs": [
+          {"resource_type": "dashboard", "resource_key": "1234"}
+        ]
+      }
+    ],
+    "object_relationships": [
+      {
+        "from_object": "业务对象A",
+        "to_object": "业务对象B",
+        "relationship": "两个对象如何形成判断链路",
+        "evidence_refs": [
+          {"resource_type": "report", "resource_key": "5678"}
+        ]
+      }
+    ],
+    "decision_chains": [
+      {
+        "chain_id": "stable-chain-id",
+        "title": "业务判断链路名称",
+        "decision_question": "这条链路帮助用户判断什么",
+        "signals": ["判断信号、指标、状态或维度"],
+        "decision_steps": ["先看什么", "再看什么", "如何下钻或停止"],
+        "preferred_domain_ids": ["domain-id"],
+        "asset_refs": [
+          {"resource_type": "dashboard", "resource_key": "1234"}
+        ],
+        "requires_live_execution": true,
+        "boundaries": ["不能由知识库直接回答的边界"]
+      }
+    ],
+    "non_goals": ["本知识库不承载的内容"]
+  },
   "domains": [
     {
       "domain_id": "stable-lowercase-id",
@@ -19,6 +59,20 @@ The Agent authors exactly one plan per asset-package snapshot. The builder valid
       "drilldown_dimensions": [
         "Agent 总结的常用下钻维度、字段 key 和使用场景；不要写缺少业务解释的技术字段。"
       ],
+      "domain_judgment_model": {
+        "business_state_judged": "这个业务域判断什么业务状态",
+        "main_objects": ["涉及的业务对象"],
+        "signals": ["这个域使用的判断信号"],
+        "decision_path": ["域内判断步骤"],
+        "asset_attachment_logic": [
+          {
+            "asset_ref": {"resource_type": "dashboard", "resource_key": "1234"},
+            "role": "primary_entry | supporting_evidence | drilldown | exclusion",
+            "reason": "为什么这个资产挂在该业务判断链路上"
+          }
+        ],
+        "boundaries": ["这个域不能直接回答或必须实时执行的边界"]
+      },
       "merge_rationale": "跨物理空间归并或拆分的证据",
       "dashboard_ids": ["dashboard resource_key"],
       "recall_cards": [
@@ -82,7 +136,11 @@ The Agent authors exactly one plan per asset-package snapshot. The builder valid
 ## Rules
 
 - Every dashboard occurs exactly once across `domains[].dashboard_ids` and `appendices[].dashboard_ids`.
+- `project_business_model` is required. It must explain how the project observes business before listing assets: positioning, audience roles, business objects, object relationships, decision chains, and non-goals.
+- `project_business_model` and every `domain_judgment_model` must be derived from current asset-package evidence. Do not hardcode project names, business domains, asset IDs, event names, metric names, or example decision chains into the workflow.
+- Every business object, object relationship and decision chain must cite concrete `dashboard`, `report`, or `metric` refs from the current package. A decision chain must reference existing domain IDs and explain when live execution is required.
 - Domain titles represent business retrieval topics, not physical dashboard-space names.
+- Every domain has one `domain_judgment_model` describing the business state judged, objects, signals, decision path, asset roles and boundaries. A domain that only lists questions, events, metrics, dimensions and assets is not acceptable.
 - 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.
@@ -90,4 +148,5 @@ The Agent authors exactly one plan per asset-package snapshot. The builder valid
 - `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 generated Markdown must not expose build-process markers such as `CLI Agent 基于同一资产快照生成`, `摘要来源`, `semantic_plan`, parser fallback labels, or builder/debug terminology. Keep those only in local artifacts when needed for audit.
 - The plan contains no query results, customer rows, users, tokens, credentials, or conversation text.

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

@@ -13,7 +13,9 @@ ae-cli analysis-meta property export --project-id <project_id> --scope event --e
 
 Capability id: `metadata.property.export`.
 
-Input: the gateway receives `project_id` plus optional `table_type`, `scope`, `event_name`, `queries`, `fields`, and `authenticated_only`; `output` is local-only.
+Input: the gateway receives `project_id` plus optional `table_type`, `scope`, `event_name`, `queries`, `fields`, `authenticated_only`, and `certification_scope`; `output` is local-only.
+
+Use `--certification-scope project|certified|all` consistently with the corresponding list command. The default `project` follows the project switch; `certified` exports only certified assets; `all` exports every accessible asset. This scope never bypasses access permissions.
 
 Output: a successful response must prove `complete=true` and `total` equal to the row count before the CLI atomically publishes a private-mode `.json` array.
 

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

@@ -4,7 +4,7 @@ Use when the user explicitly wants to create a saved analysis report from an AI
 
 Do not use raw QP, `analysis_query`, `events`, `event_view`, or `visual_view`. The gateway accepts `model_type` plus AI QP `definition`.
 
-Read [`ai_models.md`](ai_models.md) for the single AI-facing model registry. Report create 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 create supports the 13 analysis models plus `tag` for saved tag report data.
 
 Command:
 
@@ -16,6 +16,8 @@ When the caller supplies an existing snapshot, optional `--intent-snapshot` acce
 
 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`.
 
+Saved report definitions follow the filter write boundary in [`ai_models.md`](ai_models.md): one compound group level with leaf-only, non-empty `items`. A deeper tree or empty group is rejected by the capability schema as `INVALID_CAPABILITY_INPUT`; use the returned field path or schema keyword to correct it, and never flatten a deeper tree.
+
 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 each bound field's path and original wording, fill confirmed model parameters, and pass `--resolutions` only after user confirmation.
@@ -33,3 +35,5 @@ ae-cli analysis report create --project-id <project_id> --report-name "Recent SQ
 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`.
+
+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 may additionally carry `display_name`. Inspect the report capability itself for the full saved-report definition schema.

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

@@ -25,6 +25,12 @@ ae-cli analysis report-data export --project-id <project_id> --report-ids '[1001
 
 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>`.
 
+Path exports contain native graph node and link records. `record_type` distinguishes `node` and `link`; `step` is one-based, and `source`/`target` refer to native node IDs. The saved maximum steps and nodes per step still define the graph, including native More aggregation and wastage links. Export includes every computed node and link without the synchronous `preview_rows` cap.
+
+An empty path follows synchronous query semantics: native `PROJECT_NO_DATA` becomes an empty result. Other native failures, including identity and permission failures, still fail the export. JSONL uses `empty` when no data rows were produced, even when a native printer emitted only a header.
+
+Saved-report JSONL records (`schema`, `row`, `empty`, `error`) carry `report_id`; each report has an independent schema. CSV batches use `# report_id=...` boundary comments. Empty reports retain an explicit marker instead of disappearing from a mixed batch.
+
 The downloaded report-data artifact contains report rows and per-report markers, not `actual_cluster_query_scope` metadata. Therefore resolve an allowed route first, keep the submitted scope/ID with the run record, and do not infer route from row contents.
 
 Timezone contract is identical to `report-data run`: omit `--zone-offset` to match the current user's report UI timezone (falling back to the project default); use an enabled integer from `-12` through `14` for a fixed UTC offset; use `--zone-offset 99` for local-time mode, where rows are not converted to one fixed UTC offset. `99` is a mode identifier, not `UTC+99`, and the option is not persisted.

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

@@ -16,6 +16,8 @@ This command reads saved definition metadata and deliberately has no `--use-cach
 
 Output is the gateway envelope. `data` contains `version`, `model_type`, `definition`, report metadata, and dashboard membership in snake_case. Use `data.version` as `--report-version` when updating the same report. Raw frontend `events`, `event_view`, `visual_view`, and raw QP are not returned.
 
+Reads preserve historical filter trees without flattening, including definitions deeper than the current analysis page can author. Follow the read/write boundary in [`ai_models.md`](ai_models.md): omit `definition` for metadata-only changes, and never feed an unsupported historical tree back as a definition update.
+
 For saved tag/cluster filters, `data.definition` preserves `field.type` and the persisted `cluster_date_policy`: `AUTO` means dynamic matching by analysis date, `LATEST` means the latest computed result, and `SPECIFIED` requires `specified_cluster_date`. Do not infer dynamic matching from the tag name or `field.type` alone; if a legacy report has no readable policy, state that the saved date semantics are unknown rather than claiming `AUTO`.
 
 For a saved non-SQL report with a time granularity, `data.definition` returns the agent-facing `time_particle_size` spelling, such as `day`, `hour`, or `total`; internal `T0` through `T9` codes must never leak. If `time_particle_size` is absent, the saved definition has no readable granularity. Do not infer a granularity from the number of result rows; execute the saved report as-is or use an explicit ad-hoc definition when the user requires a specific granularity.

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

@@ -1,19 +1,19 @@
 # analysis report list
 
-Use when the user needs to find reports they can access in a project, with optional keyword search, semantic model filtering, field projection, and inline pagination.
+Use when the user needs a directory of reports they can edit or manage in a project, with optional keyword search, semantic model filtering, certification filtering, field projection, and inline pagination. The result includes both self-created and shared reports when effective report-edit permission is present; it excludes shared read-only reports.
 
-Do not use for report data execution or report definition writes. Use `report-data run/export` for data and `report create/update` for writes.
+Do not use for readable asset discovery: use `analysis asset search`, which includes shared read-only reports and dashboards. Do not use for report data execution or report definition writes. Use `report-data run/export` for data and `report create/update` for writes.
 
 Command:
 
 ```bash
-ae-cli analysis report list --project-id <project_id> [--queries '["growth","retention"]'] [--model-types '["event","sql","tag","revenue"]'] [--fields '["report_id","report_name","report_desc","report_model","version"]'] [--limit 50] [--offset 0]
+ae-cli analysis report list --project-id <project_id> [--queries '["growth","retention"]'] [--model-types '["event","sql","tag","revenue"]'] [--fields '["report_id","report_name","report_desc","report_model","version"]'] [--certification-scope project|certified|all] [--limit 50] [--offset 0]
 ```
 
-Input sends `project_id`, optional `queries`, `model_types`, `fields`, `limit`, and `offset` as snake_case gateway input. `queries` is a JSON array of 1 to 20 non-empty strings with OR semantics; matching rows include `matched_queries` and `matched_fields`. The legacy singular `query` is not accepted. `limit` defaults to 50 and must be 1..200; out-of-range values are rejected rather than silently clamped.
+Input sends `project_id`, optional `queries`, `model_types`, `fields`, `certification_scope`, `limit`, and `offset` as snake_case gateway input. `queries` is a JSON array of 1 to 20 non-empty strings with OR semantics; matching rows include `matched_queries` and `matched_fields`. The legacy singular `query` is not accepted. `limit` defaults to 50 and must be 1..200; out-of-range values are rejected rather than silently clamped.
 
 Output is the gateway envelope. `data` contains report summaries, `total`, effective `limit`, `offset`, `has_more`, and nullable `next_offset`. When `has_more` is true, use exactly `next_offset` for the next call; stop when it is false. Include `version` in `--fields` when the next step is `analysis report update`.
 
-When locating reports, group known names into one `--queries` call or narrow with `--model-types` before paging. Stop when the required reports are found; do not issue one list call per name.
+When locating manageable reports for an edit or management workflow, group known names into one `--queries` call or narrow with `--model-types` before paging. Stop when the required reports are found; do not issue one list call per name.
 
 Search matches report names and descriptions, not events inside definitions. Inspect a suitable candidate with `report get` when its definition is not already available; use [metadata resolution](metadata_resolution.md) for a business-measure lookup.

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

@@ -4,7 +4,7 @@ Use when the user explicitly wants to update saved report metadata or replace it
 
 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:
 
@@ -17,6 +17,8 @@ When the caller supplies an existing snapshot, optional `--intent-snapshot` acce
 
 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`.
 
+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.
 
 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 +28,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 may additionally carry `display_name`. 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.