@thinkingai/ae-cli 6.1.12 → 6.1.13

package/dist/{te-team-BZRDV2CM.js → te-team-GZPU6UWA.js}

@@ -1,14 +1,14 @@
 import {
   getAuthHeaders,
   kbApi
-} from "./chunk-VTXHDCBW.js";
+} from "./chunk-AFXA7BRK.js";
 import {
   printError,
   printOutput
-} from "./chunk-YTG6Q75E.js";
-import "./chunk-Z3OXWCIA.js";
-import "./chunk-YV52FB5G.js";
-import "./chunk-GJJA4CQZ.js";
+} from "./chunk-WZRX4KOH.js";
+import "./chunk-S5NTSDBS.js";
+import "./chunk-ZQKDZXDO.js";
+import "./chunk-3FY3RJ26.js";
 import "./chunk-AXDXJTPC.js";
 import "./chunk-JHENBQ5B.js";
 

package/dist/{update-HEDXGOJH.js → update-TOBFXF2V.js}

@@ -7,17 +7,17 @@ import {
   printError,
   printOutput,
   recordVersionSyncResult
-} from "./chunk-YTG6Q75E.js";
+} from "./chunk-WZRX4KOH.js";
 import {
   peekCliToken
-} from "./chunk-Z3OXWCIA.js";
+} from "./chunk-S5NTSDBS.js";
 import {
   missingAeHostHint
-} from "./chunk-YV52FB5G.js";
+} from "./chunk-ZQKDZXDO.js";
 import {
   getActiveHost,
   normalizeUrl
-} from "./chunk-GJJA4CQZ.js";
+} from "./chunk-3FY3RJ26.js";
 import "./chunk-JHENBQ5B.js";
 
 // src/commands/update.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingai/ae-cli",
-  "version": "6.1.12",
+  "version": "6.1.13",
   "description": "CLI tool for ThinkingAI (AE) analytics platform",
   "type": "module",
   "bin": {
@@ -30,21 +30,21 @@
     "verify:analysis-system": "tsx tests/analysis-system-capability-command.test.ts",
     "verify:output-contract": "tsx tests/output-contract.test.ts",
     "verify:analysis-cluster-routing": "node scripts/verify-analysis-cluster-routing.mjs",
-    "verify:multi-cluster-mode": "node test/multi-cluster-mode.test.mjs",
     "verify:metadata-capability": "npx tsx test/metadata-capability-commands.test.mjs",
     "verify:community-capability": "node test/community-capability-routing.test.mjs",
     "verify:community-report": "npx tsx tests/community-report-standard-v5.test.ts && npx tsx tests/community-report-client.test.ts && npx tsx tests/community-report-framework.test.ts && npx tsx tests/community-data-report-command.test.ts && node test/community-data-report-skill.test.mjs",
     "verify:engage-capability": "tsx test/engage/engage-capability-command.test.mjs && tsx test/engage/semantic-qp-validation.test.mjs && node test/engage/engage-skill-capability.test.mjs",
     "verify:retired-analysis-commands": "node --test test/retired-analysis-commands.test.mjs",
-    "verify:analysis-meta-tools": "node scripts/verify-te-meta-tools.mjs",
+    "verify:retired-api-command": "node --test test/retired-api-command.test.mjs",
     "verify:analysis-common-tools": "node scripts/verify-te-common-tools.mjs",
     "verify:experiment-tools": "node scripts/verify-te-experiment-tools.mjs && node --import tsx test/experiment/experiment-capability-command.test.mjs",
     "verify:team-tools": "node scripts/verify-te-team-tools.mjs",
     "verify:agent-tools": "node scripts/verify-agent-tools.mjs && npm run verify:sandbox-tools",
     "verify:memory": "tsx tests/memory-command.test.ts && tsx tests/memory-cli-client.test.ts && tsx tests/memory-skill.test.ts",
-    "verify:system-tools": "node scripts/verify-system-tools.mjs && npx tsx tests/system-domain.test.ts && npx tsx tests/sandbox-tool-package.test.ts",
+    "verify:system-tools": "node scripts/verify-system-tools.mjs && npx tsx tests/system-domain.test.ts && npx tsx tests/te-agent-download.test.ts && npx tsx tests/sandbox-tool-package.test.ts",
     "verify:sandbox-tools": "tsx test/sandbox-tools.test.ts",
     "verify:skill-version-management": "tsx tests/skill-version-management.test.ts",
+    "verify:skill-reference-files": "tsx tests/skill-reference-files.test.ts",
     "verify:tracking-tools": "tsx test/tracking-client.test.mjs && tsx test/tracking-skill-flow.test.mjs && node test/tracking-commands.test.mjs && tsx tests/tracking-display-name-sync.test.ts",
     "verify:self-check-overlay": "node test/self-check-overlay.test.mjs",
     "verify:update-check": "npx tsx test/update-check.test.mjs",
@@ -57,7 +57,7 @@
     "check:agents-docs": "node scripts/check-agents-docs-sync.mjs",
     "prepublishOnly": "npm run check:release && npm run build",
     "start": "node dist/index.js",
-    "test": "npx tsx src/index.ts --help && npm run verify:sandbox-tools"
+    "test": "npx tsx src/index.ts --help && npm run verify:retired-api-command && npm run verify:sandbox-tools"
   },
   "repository": {
     "type": "git",

package/skills/ae-agent/SKILL.md

@@ -133,9 +133,9 @@ If the user's intent is data analysis, audience management, metadata governance,
 - `+upload-skill-asset` ([doc](references/upload-skill-asset.md)) — upload an asset file (`isDangerousFile` checked; 1MB)
 - `+read-skill-asset` ([doc](references/read-skill-asset.md)) — read an asset file (binary-safe with `--output`)
 - `+del-skill-asset` ([doc](references/del-skill-asset.md)) — delete an asset file
-- `+list-skill-references` ([doc](references/list-skill-references.md)) — list reference files (`.md` only)
-- `+upload-skill-reference` ([doc](references/upload-skill-reference.md)) — upload a reference file (`.md` only; 1MB)
-- `+read-skill-reference` ([doc](references/read-skill-reference.md)) — read a reference file
+- `+list-skill-references` ([doc](references/list-skill-references.md)) — list all reference files
+- `+upload-skill-reference` ([doc](references/upload-skill-reference.md)) — upload a non-dangerous reference file (1MB)
+- `+read-skill-reference` ([doc](references/read-skill-reference.md)) — read text directly or save binary content with `--output`
 - `+del-skill-reference` ([doc](references/del-skill-reference.md)) — delete a reference file
 - `+list-skill-scripts` ([doc](references/list-skill-scripts.md)) — list script files of a Skill
 - `+upload-skill-script` ([doc](references/upload-skill-script.md)) — upload a script file (`isDangerousFile` checked; 1MB)

package/skills/ae-agent/references/list-skill-references.md

@@ -5,10 +5,10 @@
 Domain: **Skills / read**
 
 ## Use Cases
-- List all `.md` files in a Skill's `references` directory.
+- List all files in a Skill's `references` directory.
 - Endpoint: `GET /api/sandbox/agent/skills/[id]/references`.
-- Returns `{ items: [...] }` with file metadata (name, size, etc.).
-- Only `.md` files are listed (references directory is markdown-only).
+- Returns `{ items: [{ name, path }] }`.
+- Text and non-text files are both listed.
 
 ## Mandatory Rules (MUST)
 - `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
@@ -27,7 +27,7 @@ ae-cli agent +list-skill-references --dry-run --id <skill-cuid>
 ## Decision Rules
 - Use `+list-skills` to confirm the Skill ID before listing references.
 - Read operation: no confirmation prompt needed.
-- References are `.md` files that provide additional context for the Skill.
+- References may be text files such as Markdown/CSV or non-text files such as spreadsheets and PDFs.
 
 ## Next Steps on Failure
 - `404` / not found: re-run `+list-skills` to verify the Skill ID and scope.

package/skills/ae-agent/references/read-skill-reference.md

@@ -5,10 +5,10 @@
 Domain: **Skills / read**
 
 ## Use Cases
-- Read a Skill reference `.md` file's raw content (binary-safe).
+- Read or download a Skill reference file.
 - Endpoint: `GET /api/sandbox/agent/skills/[id]/references/[...path]`.
-- By default returns `{ content, fileName }` where content is UTF-8 text.
-- Use `--output <path>` to save the raw content to a local file.
+- Text responses return `{ content, fileName }` by default.
+- Non-text responses require `--output <path>` to preserve the original bytes.
 
 ## Mandatory Rules (MUST)
 - `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
@@ -22,6 +22,9 @@ ae-cli agent +read-skill-reference --id <skill-cuid> --path guide.md
 # Save reference to local file
 ae-cli agent +read-skill-reference --id <skill-cuid> --path guide.md --output ./guide.md
 
+# Download a non-text reference (required for spreadsheets, PDFs, and other binary files)
+ae-cli agent +read-skill-reference --id <skill-cuid> --path metrics.xlsx --output ./metrics.xlsx
+
 # Read from a sub-directory
 ae-cli agent +read-skill-reference --id <skill-cuid> --path "advanced/tips.md"
 
@@ -34,17 +37,17 @@ ae-cli agent +read-skill-reference --dry-run --id <skill-cuid> --path guide.md
 |---|---|---|
 | `--id` | Yes | Skill record ID (CUID) |
 | `--path` | Yes | Relative file path within references (e.g. `"guide.md"` or `"advanced/tips.md"`) |
-| `--output` | No | Write content to a local file |
+| `--output` | No | Write the original bytes to a local file; required for non-text files |
 
 ## Decision Rules
 - Use `+list-skill-references` to discover available file paths before reading.
-- References are `.md` files — the default JSON output `{ content }` is usually sufficient.
-- Use `--output` to save the content to a local file for editing or backup.
+- Use the default JSON output only for text references.
+- Always use `--output` for spreadsheets, PDFs, archives, images, and other non-text files.
 - Read operation: no confirmation prompt needed.
 
 ## Next Steps on Failure
 - `404` / not found: re-run `+list-skill-references` to verify the file path.
-- `文件不存在`: the file path does not exist in the references directory.
+- `output_required`: re-run with `--output <path>` to preserve binary content.
 
 ## Recommended Chaining
 - `+list-skill-references` → confirm `path` → `+read-skill-reference` → `+del-skill-reference` (if cleanup needed)

package/skills/ae-agent/references/upload-skill-reference.md

@@ -5,15 +5,14 @@
 Domain: **Skills / write**
 
 ## Use Cases
-- Upload a single `.md` file to a Skill's `references` directory (multipart upload).
+- Upload a single file to a Skill's `references` directory (multipart upload).
 - Endpoint: `POST /api/sandbox/agent/skills/[id]/references` (multipart/form-data).
 - Max file size: 1MB per file.
-- **Only `.md` files are allowed** — other extensions are rejected.
+- Markdown, text, CSV, spreadsheet, PDF, and other non-dangerous file types are supported.
 
 ## Mandatory Rules (MUST)
 - `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
-- `--file` is required, must be an existing local `.md` file.
-- Non-`.md` files are rejected — use `+upload-skill-asset` for other file types.
+- `--file` is required and must be an existing local file.
 - Max 1MB per file; server enforces `isDangerousFile` checks.
 - This is an ordinary `write` operation and does not require CLI confirmation.
 
@@ -25,6 +24,9 @@ ae-cli agent +upload-skill-reference --id <skill-cuid> --file ./guide.md
 # Upload to a sub-directory
 ae-cli agent +upload-skill-reference --id <skill-cuid> --file ./advanced.md --sub-path "advanced/"
 
+# Upload a spreadsheet reference
+ae-cli agent +upload-skill-reference --id <skill-cuid> --file ./metrics.xlsx
+
 # Dry-run to inspect the request before executing
 ae-cli agent +upload-skill-reference --dry-run --id <skill-cuid> --file ./guide.md
 ```
@@ -33,19 +35,19 @@ ae-cli agent +upload-skill-reference --dry-run --id <skill-cuid> --file ./guide.
 | Parameter | Required | Description |
 |---|---|---|
 | `--id` | Yes | Skill record ID (CUID) |
-| `--file` | Yes | Local `.md` file path to upload (max 1MB) |
+| `--file` | Yes | Local file path to upload (max 1MB) |
 | `--sub-path` | No | Sub-directory under references (e.g. `"advanced/"`) |
 
 ## Decision Rules
-- Verify the file exists locally and has a `.md` extension before uploading.
-- For non-markdown files, use `+upload-skill-asset` instead.
+- Verify the file exists locally and does not exceed 1MB before uploading.
+- Keep supporting material in `references`; use `assets` for files consumed as presentation or runtime assets.
 - Use `--sub-path` to organize references into sub-directories.
 - Use `--dry-run` first to verify the request shape before executing.
 
 ## Next Steps on Failure
 - `File not found`: verify the local file path.
-- `--file must be a .md file for references`: use `+upload-skill-asset` for non-markdown files.
-- `文件过大（上限 1MB）`: the file exceeds the 1MB limit — split the markdown.
+- File-too-large API error: the file exceeds the 1MB limit — reduce or split the file.
+- Dangerous-file API error: the file type is blocked by the server safety policy.
 
 ## Recommended Chaining
 - `+list-skills` → `+list-skill-references` → `+upload-skill-reference` → `+list-skill-references` (verify)

package/skills/ae-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-analysis
-version: 4.0.4
+version: 4.2.0
 description: "Use ae-cli for AE/TE analysis-side data questions, asset operations, and asset governance: reports, analysis boards, BI dashboards, ad-hoc models, drilldown, detail data, alerts, clusters, tags, metrics, metadata, project configuration, tracking plans, governance asset lists/rules/lineage/impact/dependency, batch asset operations, projects, and resource links. Use when the user asks to query data, explain a change, export evidence, or inspect/create/update/govern analysis assets."
 ---
 
@@ -18,6 +18,7 @@ This is the single entry skill for analysis intent and command execution.
 3. For an AI-facing ad-hoc definition, also read [`references/ai_models.md`](references/ai_models.md).
 4. For cluster/tag `--definition-request`, also read the matching [`references/user_cluster_models.md`](references/user_cluster_models.md) or [`references/user_tag_models.md`](references/user_tag_models.md). Shared primitives live in [`references/audience_models.md`](references/audience_models.md).
 5. For analysis data retrieval, choose `run` or `export` using [`references/analysis_data_retrieval.md`](references/analysis_data_retrieval.md).
+6. When an AI-QP compile failure contains `slot_kind`, `allowed_resource_types`, `search_targets`, and `next_action`, read and follow [`metadata_resolution.md`](metadata_resolution.md).
 
 The generated command index is exhaustive. This file contains routing and workflow rules only; do not duplicate a hand-maintained command inventory here.
 
@@ -29,11 +30,10 @@ Use this skill for these CLI services:
 - `analysis-meta`: gateway metadata assets, events, properties, virtual metadata, metrics, data tables, exchange rules, and super metadata.
 - `analysis-governance`: gateway asset governance operations, including governed asset lists/exports, lineage, dependency, impact, query history, rule schema/list/create/update/delete, batch asset actions, and operation records. Use this service for asset governance workflows, not for metadata event/property/metric CRUD.
 - `tracking`: gateway tracking plan, checking, ingest, live-data, and event blacklist operations.
-- `analysis_meta`: legacy MCP metadata commands. Prefer `analysis-meta` gateway commands whenever the generated index contains the needed operation.
 
 For metadata gateway detail outside the commands in the generated index, use the metadata skill. For Engage, DataOps, or Community work, use the corresponding skill.
 
-Use `ae-cli` first. Fall back to te-mcp only for command-not-found, not-supported/not-implemented, a confirmed capability gap, or repeated failures that are not caused by parameters, types, time formats, permissions, timeout choice, or payload construction. State the fallback reason. A validation error or `need_clarification` is a reason to correct the input, not to switch tools.
+Use `ae-cli` as the only execution path for this skill. If a command is missing, unsupported, not implemented, or a capability gap is confirmed, report the gap and stop or provide framework-level guidance; do not switch to direct MCP execution. Repeated failures are not evidence of a capability gap until parameters, types, time formats, permissions, timeout choice, and payload construction have been checked. A validation error or `need_clarification` is a reason to correct the input, not to switch tools.
 
 For tags and audience clusters, use the native `analysis user-tag ...` and `analysis user-cluster ...` gateway commands.
 
@@ -42,8 +42,6 @@ For tags and audience clusters, use the native `analysis user-tag ...` and `anal
 Command forms:
 
 ```bash
-ae-cli analysis +<command> [options]
-ae-cli analysis_meta +<command> [options]
 ae-cli analysis <resource> <action> [options]
 ae-cli analysis-meta <resource> <action> [options]
 ae-cli analysis-governance <resource> <action> [options]
@@ -51,7 +49,6 @@ ae-cli tracking <resource> <action> [options]
 ae-cli capability search|inspect|validate|dry-run|run [options]
 ```
 
-- Legacy `+` commands use underscore flags such as `--project_id`.
 - Gateway commands use kebab-case flags such as `--project-id`; the CLI sends snake_case JSON.
 - JSON values must be JSON string literals.
 - Global flags include `--host`, `--format json|table`, `--jq`, `--validate`, `--dry-run`, and `--yes`. Use `--validate` alone to normalize complex capability input; use `--dry-run` alone for execution or risk preview.
@@ -100,9 +97,13 @@ Before a project-scoped command:
 
 ### C. FUZZY_SEARCH_FALLBACK
 
-For saved-asset operations on reports, dashboards, metrics, clusters, tags, and alerts, use the relevant list/search command first unless an exact ID or canonical asset name was already verified. Search the user's phrase, broaden it up to two times, then list all candidates. If no resource exists, stop instead of fabricating one.
+For saved-asset operations on reports, dashboards, metrics, clusters, tags, and alerts, use the relevant list/search command first unless an exact ID or canonical asset name was already verified. For event, property, metric, cluster, and tag catalogs, put the user's phrase and its useful synonyms in one `--queries` JSON array; matching is OR across at most 20 keywords. For ordinary asset discovery, broaden the keyword batch up to two times, then list all candidates. If no resource exists, stop instead of fabricating one.
 
-Do not pre-list events or properties before constructing an AI-facing intent model. Pass the user's wording directly in `definition`; the backend resolves it and returns `resolved` evidence. Call event/property metadata commands only when the user explicitly asks to inspect metadata, the compiler returns `need_clarification` with candidates, or the compiler reports an explicit metadata-resolution capability gap.
+Only when explicitly complete event, property, metric, cluster, or tag metadata is needed, use that resource's `export --output <temporary_path>/<resource>` command. Event/property/metric exports use `.json`; cluster/tag exports use `.jsonl` and an integrity sidecar. Search the temporary file locally and keep the full rows out of model context. Do not page repeatedly to synthesize a complete catalog.
+
+Do not pre-list events or properties before constructing an AI-facing intent model. Pass the user's wording directly in `definition`; the backend resolves it and returns `resolved` evidence. Call event/property metadata commands only when the user explicitly asks to inspect metadata, a structured compiler error instructs `next_action=search_candidates`, or the compiler reports an explicit metadata-resolution capability gap. When compiler candidates already exist, ask the user to confirm without another metadata call. If the user explicitly rejects every candidate for that path, treat the rejected set as exhausted and continue through the one aggregate-search workflow in `metadata_resolution.md`; do not terminate the original task or repeat the rejected candidates.
+
+The generic saved-asset search rule above does not control structured AI-QP metadata failures. For those failures, `allowed_resource_types` is authoritative: collect the whole compiler error array and follow the one aggregate online search, optional full-catalog, conversation-reuse workflow in `metadata_resolution.md`. Never use a candidate from either path without user confirmation.
 
 ### Existing business asset before ad-hoc
 
@@ -121,18 +122,20 @@ Do not call removed QP builders or schema helpers for ad-hoc analysis. `--defini
 - Metric value, trend, comparison, or anomaly -> saved report/dashboard first, then ad-hoc data.
 - Metric definition search/create/update -> metadata commands.
 - Event/entity rows -> `event-detail run|export` or `entity-detail run|export`.
-- Events/entities from a query result -> pass the original `--project-id`, then follow the returned synchronous `query_context_id` and `sources[].drilldown`; never reconstruct raw QP or use export rows as coordinates.
+- Events/entities from a query result -> pass the original `--project-id`, follow the returned synchronous `query_context_id` and compact source action summary, then call `analysis query-context get` for full coordinate options; never reconstruct raw QP or use export rows as coordinates.
 - Cluster/tag definition -> matching gateway cluster/tag commands and matching model reference.
 - Tag/cluster candidate values, including requests phrased as "latest version" or "latest result" -> resolve the exact asset, then use `analysis filter-value list` with `cluster_date_policy=LATEST`. This means the latest computed data snapshot, never a definition or configuration release; do not invent version lists, version IDs, draft states, or publish states.
 - Alert/configuration/tracking-plan requests -> the dedicated gateway command reference from the index.
 
 ### Run, export, and follow-up
 
-- `run` is a bounded inline preview for known-small work that can complete within the synchronous limits.
+- `run` is a bounded inline preview for work that can complete within the synchronous limits. Agents should normally pass `--preview-rows 100`; omitting it deliberately uses the model's current cluster-configured synchronous limit. User tag/cluster member list commands are the exception: omission defaults to 1000 rows, matching the UI member query.
 - `export` is for complete, unknown-size, over-limit, or long-running results. It returns `run_id` and `artifact_id`.
 - Drilldown event/entity/user-event exports are `csv.gz` full-download streams bounded by `model_full_download_limit`; never pass or simulate `limit`, `offset`, `page_num`, or `page_size`.
-- Inspect with `analysis run inspect`, download with `analysis artifact download`, and cancel with `analysis query cancel`. Do not call raw lifecycle URLs.
-- Drilldown requires the original `--project-id`, a synchronous preview context, and the selected source's returned row/column/metric coordinate options. Common rejects a project ID that does not match the stored context. If the context/options are absent or the action is not advertised, report that drilldown/result-cluster creation is unavailable.
+- Plain `export` submits only. Add `--wait` to wait for terminal state, or `--output <file>` to wait and atomically stream the completed artifact; `--output` implies wait. Existing files require explicit `--force`.
+- Resume detached or interrupted work with `analysis run wait --run-id <run_id> [--output <file>]`. Local interruption never cancels the remote run; cancel only through the explicit `analysis query cancel` command.
+- `analysis run inspect` and `analysis artifact download` remain primitive lifecycle commands. Do not call raw lifecycle URLs. Use `--wait-timeout-seconds` only to bound local waiting; it never changes or cancels the remote runtime.
+- Drilldown requires the original `--project-id`, a synchronous preview context, and row/column/metric coordinate options fetched with `analysis query-context get`. Common rejects a project ID that does not match the stored context. If the context/options are absent or the action is not advertised, report that drilldown/result-cluster creation is unavailable.
 
 ### Writes and destructive operations
 

package/skills/ae-analysis/metadata_resolution.md

@@ -0,0 +1,150 @@
+# Structured AI-QP metadata resolution
+
+Use this workflow only when `analysis adhoc run|export`, report create, or report update fails with `AI_QP_COMPILE_FAILED` and metadata errors contain:
+
+- `path`
+- `slot_kind`
+- `raw_value`
+- `allowed_resource_types`
+- `search_targets`
+- `candidates`
+- `next_action`
+
+The Common compiler returns every unresolved slot from the same compile attempt. Treat that complete error array as one resolution plan. Do not run this workflow independently for each `path`.
+
+`allowed_resource_types` and `search_targets` are authoritative for their exact paths. Do not add, remove, prioritize, or reinterpret resource types. `search_targets[].constraints` must be applied when filtering local rows.
+
+## One catalog for the conversation
+
+The complete analysis metadata catalog contains these resource types in one JSONL file:
+
+- `event`
+- `metric`
+- `event_property`
+- `user_property`
+- `cluster`
+- `tag`
+
+Use the current Agent conversation context as the catalog base:
+
+1. If the Agent host exposes a private artifact or workspace directory scoped to the current conversation, use it as `<agent-conversation-root>`.
+2. Use:
+
+```text
+<agent-conversation-root>/ae-cli/analysis-metadata/
+```
+
+Do not assume a product-specific environment variable, Agent implementation, or launcher contract.
+
+If the host has no stable conversation-scoped directory, create one private fallback root once:
+
+```bash
+mktemp -d "${TMPDIR:-/tmp}/ae-cli-analysis-metadata.XXXXXX"
+```
+
+Retain that absolute path in the current conversation state. Never create a new root per error, command, or turn.
+
+Normalize the AE host to its lowercase URL origin without a trailing slash. Set `host-key` to the first 16 lowercase hex characters of the origin SHA-256. Use:
+
+```text
+<session-root>/<host-key>/project-<project_id>/catalog.jsonl
+<session-root>/<host-key>/project-<project_id>/catalog.meta.json
+```
+
+Create the directory with mode `0700`. Do not put a token, user name, or user ID in its path.
+
+Before reuse, require both files and verify:
+
+- `schema_version=1`
+- `resource_type=analysis_metadata`
+- `complete=true`
+- `host` and `project_id` match the current request
+- `principal_fingerprint` is present
+- JSONL SHA-256 equals `content_sha256`
+- the authenticated principal has not changed during the conversation
+
+If any check fails, discard the cached pair for this workflow and fetch it again. A `.part` file or JSONL without the completed metadata sidecar is never valid.
+
+## Compile-wide workflow
+
+1. Read the complete compiler error array.
+2. Keep existing compiler `candidates` for their exact paths. They require confirmation and no metadata lookup unless the user explicitly rejects every candidate for that path. After an explicit reject-all response, discard that rejected set and treat the path as requiring `next_action=search_candidates`, using its existing `raw_value`, `allowed_resource_types`, and `search_targets`.
+3. Collect every empty-candidate path with `next_action=search_candidates`.
+4. If at least one such path exists, check the one conversation catalog above.
+5. If a valid complete catalog exists, skip every online metadata call and search it locally as described below.
+6. If no valid catalog exists:
+   - Generate useful synonyms for every empty-candidate path from its `raw_value` and `slot_kind`.
+   - Deduplicate the synonyms from all paths into one `queries` array.
+   - Take the union of those paths' `allowed_resource_types` into one `resource-types` array. Do not add other types.
+   - Invoke exactly one aggregate online search:
+
+```bash
+ae-cli analysis-meta catalog list \
+  --project-id <project_id> \
+  --queries '["<all deduplicated synonyms>"]' \
+  --resource-types '["<union of allowed resource types>"]' \
+  --limit-per-type 20
+```
+
+7. Split the online rows back across paths:
+   - Accept a row for a path only when its `resource_type` is allowed by that path.
+   - Apply that path's `search_targets[].constraints`.
+   - Prefer the server-provided exact matches before contained matches.
+   - Deduplicate by `resource_type + resource_key`.
+8. If every searched path now has at least one candidate, skip the full catalog and continue to confirmation.
+9. If any searched path still has no candidate, download the complete catalog exactly once:
+
+```bash
+ae-cli analysis-meta catalog export \
+  --project-id <project_id> \
+  --output "<catalog_dir>/catalog.jsonl"
+```
+
+10. Search the one JSONL locally for every path still without a candidate:
+   - Generate useful synonyms from that path's `raw_value` and `slot_kind`.
+   - Filter rows by `search_targets[].resource_type`.
+   - Apply every target `constraints` field.
+   - Prefer exact `resource_key`, then exact `display_name`, then contained display name or remark.
+   - Deduplicate by `resource_type + resource_key`.
+   - Return only a small candidate subset to model context; never read the full catalog into context.
+11. Aggregate candidates for all paths and ask the user to confirm each selected candidate in one interaction.
+12. Keep the original definition unchanged. Build one `resolutions` object keyed by compiler path and rerun the original command once with `--resolutions`.
+
+A reject-all response is a state transition, not task cancellation. Run the aggregate online search at most once for the rejected path set, then use the same complete-catalog fallback above if needed. Never repeat candidates the user already rejected. If the complete catalog has no different candidate, ask for an exact canonical name or a changed business definition.
+
+Do not call event, property, metric, cluster, or tag list commands in this structured workflow. Do not run `--queries` synonym rounds: the aggregate online search is one call for the whole compile error array, never one call per path or resource type. The unified catalog capability replaces both repeated online searches and per-resource full exports.
+
+Once a valid complete catalog exists for the current host, project, principal, and conversation, never call `analysis-meta catalog list` again in that scope, and never call `analysis-meta catalog export` again either. Search the complete local snapshot instead; a local no-match is a complete negative result for this snapshot.
+
+An online response with `has_more=true` is bounded discovery, not a complete negative result. If any path remains unresolved after that response, use the one complete-catalog fallback instead of paging or broadening online queries. Permission, network, and server errors are failures, not empty search results, and must not trigger the full-catalog fallback.
+
+## Confirmation and deterministic binding
+
+Never use a compiler or local candidate without explicit user confirmation.
+
+For each confirmed path, pass:
+
+```json
+{
+  "resolutions": {
+    "request.metrics[0].event": {
+      "raw_value": "付费事件",
+      "resource_type": "event",
+      "resource_key": "payment"
+    }
+  }
+}
+```
+
+The server verifies that:
+
+- the path still exists in the unchanged definition;
+- `raw_value` still matches that path;
+- `resource_type` is allowed for that path;
+- `resource_key` is currently accessible in the project and identity scope.
+
+Handle `RESOLUTION_STALE`, `RESOLUTION_TYPE_NOT_ALLOWED`, and `RESOLUTION_PATH_INVALID` as deterministic validation failures. Do not retry the same resolution unchanged.
+
+If the complete local catalog has no candidate for a path, ask the user for an exact canonical name or a different business definition. Never fabricate an entity.
+
+Permission, network, and server errors are not empty catalogs. Report them and do not publish or reuse a failed catalog.

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

@@ -13,6 +13,7 @@ ae-cli analysis adhoc export \
   --project-id <project_id> \
   --model-type <model_type> \
   --definition '<json>' \
+  [--resolutions '<confirmed_resolution_json>'] \
   [--request-id cli_<32 lowercase hex>] \
   [--use-cache true|false] \
   [--zone-offset <hours>] \
@@ -20,7 +21,11 @@ ae-cli analysis adhoc export \
   [--cluster-query-scope GLOBAL|SLAVE] \
   [--slave-cluster-id <id>] \
   [--artifact-format jsonl|csv] \
-  [--timeout-seconds <n>]
+  [--timeout-seconds <n>] \
+  [--wait] \
+  [--wait-timeout-seconds <n>] \
+  [--output <file>] \
+  [--force]
 ```
 
 ## AI models
@@ -40,6 +45,7 @@ Rules:
 - `--project-id`: target project ID.
 - `--model-type`: one of the 12 AI-facing model names from [`ai_models.md`](ai_models.md). Do not pass `scenario`, `history_tag`, or `cluster`; tags and cohorts/clusters are separate capabilities.
 - `--definition`: model-specific AI-facing definition JSON.
+- `--resolutions`: only after user confirmation, pass deterministic bindings keyed by compiler error path while keeping `--definition` unchanged. Follow [`../metadata_resolution.md`](../metadata_resolution.md).
 - `--artifact-format`: `jsonl` or `csv`.
 
 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>`. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
@@ -63,16 +69,25 @@ The response is an async artifact descriptor:
 
 Preserve the `run_id` and `artifact_id` from this exact submit response as one pair. Do not infer either ID from a path or reuse an ID from another export.
 
-Export submission compiles the definition before creating an artifact or run. The execute, `--validate`, and `--dry-run` paths return `AI_QP_COMPILE_FAILED` immediately when clarification is required, with `meta.compile_status`, full `meta.errors[]` (including `candidates` and `suggestions`), `meta.resolved`, and `meta.warnings`. A compile failure has no `run_id` or `artifact_id`; resolve the ambiguity and submit a new request.
+Export submission compiles the definition before creating an artifact or run. The execute, `--validate`, and `--dry-run` paths return `AI_QP_COMPILE_FAILED` immediately when clarification is required, with `meta.compile_status`, full structured `meta.errors[]`, `meta.resolved`, and `meta.warnings`. Follow [`../metadata_resolution.md`](../metadata_resolution.md), confirm candidates, then retry with `--resolutions`. A compile failure has no `run_id` or `artifact_id`.
 
 Use:
 
 ```bash
+ae-cli analysis adhoc export ... --wait
+ae-cli analysis adhoc export ... --output <file>
+ae-cli analysis run wait --run-id <run_id> [--output <file>]
 ae-cli analysis run inspect --run-id <run_id>
 ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output <file>
 ae-cli analysis query cancel --run-id <run_id>
 ```
 
+Plain export submits only. `--output` implies `--wait`;
+`--wait-timeout-seconds` defaults to 600 seconds and controls only the local
+CLI wait. `--force` is valid only
+with `--output` and permits atomic replacement of an existing file. Local wait
+interruption or deadline does not cancel the remote run.
+
 If query execution fails, `run inspect` reaches `FAILED`; it must not produce a completed empty artifact. Download only after the successful terminal states documented in `analysis_data_retrieval.md`.
 
 Exported rows are durable data, not interactive preview coordinates. Never drill down or create a result cluster from the submit response or downloaded artifact. Run a bounded synchronous preview containing the desired cell first.

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

@@ -15,13 +15,14 @@ ae-cli analysis adhoc run \
   --project-id <project_id> \
   --model-type <model_type> \
   --definition '<json>' \
+  [--resolutions '<confirmed_resolution_json>'] \
   [--request-id cli_<32 lowercase hex>] \
   [--use-cache true|false] \
   [--zone-offset <hours>] \
   [--fields '["列名"]'] \
   [--cluster-query-scope GLOBAL|SLAVE] \
   [--slave-cluster-id <id>] \
-  [--limit <n>] \
+  [--preview-rows <n>] \
   [--timeout-seconds <n>]
 ```
 
@@ -36,10 +37,13 @@ For SQL model definitions, do not invent table or column names. If the table ref
 - `--project-id`: target project ID.
 - `--model-type`: one of the 12 AI-facing model names from [`ai_models.md`](ai_models.md). Do not pass `scenario`, `history_tag`, or `cluster`; tags and cohorts/clusters are separate capabilities.
 - `--definition`: model-specific AI-facing definition JSON.
+- `--resolutions`: only after user confirmation, pass deterministic bindings keyed by compiler error path. Keep `--definition` unchanged; follow [`../metadata_resolution.md`](../metadata_resolution.md).
 
-Control defaults: `--limit` default 100 / max 1000, `--timeout-seconds` default 60 / max 180. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+Omit `--preview-rows` to use the current model and cluster synchronous row limit. An explicit value must be positive and cannot exceed that runtime limit; agents should normally pass 100 to bound context. `--timeout-seconds` defaults to 120 and has a maximum of 180. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
 
-If the user asks for more than 1000 rows, or the SQL text requests `LIMIT 2000` (or any limit above 1000), go directly to `analysis adhoc export`. Do not lower the SQL limit to 1000, run a truncated sync query first, or loop over repeated `run` calls.
+For `model_type=path`, `preview_rows` follows the analysis UI's graph contract: it limits real nodes per path level, not total nodes across the graph. Nodes beyond the per-level boundary are combined into a `more` node. `result.nodes` retains that synthesized node for graph structure and drilldown coordinates. `returned_rows` counts real business nodes actually returned across all levels; it excludes synthesized `more` nodes and the real nodes folded into them. The count may still exceed `preview_rows` because the boundary applies independently to each level. `has_more=true` means at least one level contains real nodes folded into `more`.
+
+If the requested result exceeds the current runtime synchronous maximum, go directly to `analysis adhoc export`. Do not lower the requested row count, run a partial sync query first, or loop over repeated `run` calls.
 
 Do not use raw QP, `events`, `event_view`, `visual_view`, removed ad-hoc QP builder outputs, or schema helper outputs as `--definition`.
 
@@ -52,14 +56,14 @@ Cluster routing: omit both routing flags for current-self data. Before `GLOBAL`
 The response may include:
 
 - `query_context_id`: Redis-backed context for follow-ups from this bounded synchronous preview.
-- `sources[].drilldown`: finite row, column, and metric options plus allowed actions. The preview `limit` is the selection boundary.
-- `title` / `rows` / `total` / `returned_rows` / `truncated`: tabular preview fields. When truncated, use `adhoc export`; there is no next-page request.
-- `result`: direct result for non-tabular models.
+- `sources[].drilldown`: compact allowed-action summary. Detailed coordinate options are read lazily with `analysis query-context get`; `preview_rows` remains the selection boundary.
+- `title` / `rows` / `returned_rows` / `has_more`: tabular preview fields. `total` appears only when the backend supplies an exact total. When `has_more` is true, use `adhoc export`; there is no next-page request.
+- `result`: direct result for non-tabular models. Path results also return top-level `returned_rows` and `has_more` using the per-level node contract above.
 - `request_id`: lifecycle request id.
 - `actual_cluster_query_scope`, optional `actual_slave_cluster_id`, and `cluster_query_scope_source`: actual physical data route. Verify these before comparing results or following the query context.
 
 Execution failures are returned as command failures with `request_id`; only the explicit project-no-data condition is a successful empty result. Do not interpret an empty object as evidence that a failed query succeeded.
 
-The execute, `--validate`, and `--dry-run` paths all compile the AI-facing definition. If metadata resolution needs clarification, the command fails with `AI_QP_COMPILE_FAILED`; inspect `meta.compile_status`, `meta.errors[]`, `meta.resolved`, and `meta.warnings`. Each error retains `path`, `message`, `code`, `candidates`, and `suggestions`. Select an exact candidate from this response or ask the user; do not guess from display text.
+The execute, `--validate`, and `--dry-run` paths all compile the AI-facing definition. If metadata resolution needs clarification, the command fails with `AI_QP_COMPILE_FAILED`; inspect `meta.compile_status`, `meta.errors[]`, `meta.resolved`, and `meta.warnings`. Each metadata error retains `path`, `slot_kind`, `raw_value`, `allowed_resource_types`, `search_targets`, and `candidates`. Follow [`../metadata_resolution.md`](../metadata_resolution.md); do not guess from display text.
 
-Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Use the context only with an action advertised by the selected source/metric, and assemble the coordinate only from returned option fragments. Do not pass raw QP or infer a coordinate from display text.
+Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Use the context only with an action advertised by the selected source, call `analysis query-context get`, and assemble the coordinate only from its returned option fragments. Do not pass raw QP or infer a coordinate from display text.