@thinkingai/ae-cli 6.1.17 → 6.1.19

package/dist/{te-team-EFKWYKMK.js → te-team-XMP47YXE.js}

@@ -1,16 +1,19 @@
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   getAuthHeaders,
   kbApi
-} from "./chunk-4KVPKXFX.js";
+} from "./chunk-JYMGHGCE.js";
 import {
   printError,
   printOutput
-} from "./chunk-GT46FPXN.js";
-import "./chunk-4SGZG4XY.js";
-import "./chunk-ZZUOD757.js";
-import "./chunk-UW5UN47B.js";
-import "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+} from "./chunk-KEWVSO64.js";
+import "./chunk-GJXRF7Y6.js";
+import "./chunk-Y74WTIKJ.js";
+import "./chunk-RWXIXOZG.js";
+import "./chunk-O6K2ODUE.js";
+import "./chunk-KZ6ZHF5J.js";
+import "./chunk-533JK3YX.js";
+import "./chunk-FR2EDAQM.js";
 
 // src/commands/te-team/shared.ts
 var API_PREFIX = process.env.AE_API_PREFIX ?? "/agent";

package/dist/{update-OGPSZM5A.js → update-UODFOZ4P.js}

@@ -1,3 +1,4 @@
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   buildVersionInstallPlan,
   fetchCliConfig,
@@ -7,18 +8,19 @@ import {
   printError,
   printOutput,
   recordVersionSyncResult
-} from "./chunk-GT46FPXN.js";
+} from "./chunk-KEWVSO64.js";
 import {
   peekCliToken
-} from "./chunk-4SGZG4XY.js";
+} from "./chunk-RWXIXOZG.js";
+import {
+  missingAeHostHint
+} from "./chunk-O6K2ODUE.js";
 import {
   getActiveHost,
-  missingAeHostHint,
   normalizeUrl
-} from "./chunk-ZZUOD757.js";
-import "./chunk-UW5UN47B.js";
-import "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+} from "./chunk-KZ6ZHF5J.js";
+import "./chunk-533JK3YX.js";
+import "./chunk-FR2EDAQM.js";
 
 // src/commands/update.ts
 var HOST_OPTION_DESC = "Override active AE host URL (e.g., https://ta.thinkingdata.cn)";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingai/ae-cli",
-  "version": "6.1.17",
+  "version": "6.1.19",
   "description": "CLI tool for ThinkingAI (AE) analytics platform",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "dev": "tsx src/index.ts",
-    "build": "tsup src/index.ts --format esm --outDir dist && node scripts/copy-tracking-assets.mjs",
+    "build": "tsup src/index.ts --format esm --outDir dist --clean --config tsup.config.ts && node scripts/copy-tracking-assets.mjs",
     "generate:analysis-skill": "tsx scripts/generate-analysis-skill-index.mts",
     "verify:config": "node test/config-commands.test.mjs",
     "verify:json-utils": "npx tsx tests/json-utils.test.ts",
@@ -42,15 +42,17 @@
     "verify:agent-tools": "node --test test/agent-command-registry.test.mjs && tsx tests/te-agent-credentials.test.ts && tsx tests/te-agent-unified-auth.test.ts && tsx tests/te-agent-conversations.test.ts && tsx scripts/verify-agent-tools.mjs && npm run verify:approval && npm run verify:sandbox-tools",
     "verify:approval": "tsx tests/approval-command.test.ts && tsx tests/approval-cli-client.test.ts && tsx tests/approval-skill.test.ts",
     "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/te-agent-download.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/channel-cli-http.test.ts && npx tsx tests/te-agent-download.test.ts && npx tsx tests/sandbox-tool-package.test.ts",
     "verify:kb-skill": "node test/kb-skill-query-workflow.test.mjs",
+    "verify:kb-sources": "tsx test/kb-list-sources-command.test.mjs",
     "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 && tsx tests/local-data-inspect-convert.test.ts && tsx tests/local-data-upload-client.test.ts && tsx tests/local-data-upload-command.test.ts && tsx tests/local-data-encoding-sniff.test.ts && tsx tests/local-data-time-formats.test.ts && tsx tests/local-data-eight-types.test.ts && tsx tests/local-data-mapping-extras.test.ts && tsx tests/local-data-plan.test.ts && tsx tests/local-data-handoff.test.ts && tsx tests/local-data-reuse.test.ts && tsx tests/local-data-conflicts-resolutions.test.ts && tsx tests/runner-variadic-flags.test.ts && node test/local-data-skill.test.mjs",
+    "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 && tsx tests/local-data-inspect-convert.test.ts && tsx tests/local-data-upload-client.test.ts && tsx tests/local-data-upload-command.test.ts && tsx tests/local-data-encoding-sniff.test.ts && tsx tests/local-data-time-formats.test.ts && tsx tests/local-data-xlsx-dates.test.ts && tsx tests/local-data-xlsx-hidden-sheets.test.ts && tsx tests/local-data-xlsx-formulas.test.ts && tsx tests/local-data-title-rows.test.ts && tsx tests/local-data-xlsx-merged-cells.test.ts && tsx tests/local-data-xlsx-shared-strings.test.ts && tsx tests/local-data-xlsx-namespace-prefix.test.ts && tsx tests/local-data-value-distribution.test.ts && tsx tests/local-data-summary-rows.test.ts && tsx tests/local-data-duplicate-keys.test.ts && tsx tests/local-data-row-balance.test.ts && tsx tests/local-data-eight-types.test.ts && tsx tests/local-data-mapping-extras.test.ts && tsx tests/local-data-plan.test.ts && tsx tests/local-data-handoff.test.ts && tsx tests/local-data-reuse.test.ts && tsx tests/local-data-conflicts-resolutions.test.ts && tsx tests/runner-variadic-flags.test.ts && node test/local-data-skill.test.mjs",
     "verify:self-check-overlay": "node test/self-check-overlay.test.mjs",
     "verify:update-check": "npx tsx test/update-check.test.mjs",
     "verify:version-sync": "npx tsx tests/version-sync.test.ts",
+    "verify:dependency-hygiene": "node --test test/dependency-hygiene.test.mjs",
     "qa-changed": "node scripts/qa-changed.mjs",
     "self-check": "node self-check/scan.mjs",
     "check:release": "node self-check/release-gate.mjs",
@@ -59,7 +61,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:retired-api-command && npm run verify:sandbox-tools"
+    "test": "npx tsx src/index.ts --help && npm run verify:retired-api-command && npm run verify:sandbox-tools && npm run verify:dependency-hygiene"
   },
   "repository": {
     "type": "git",
@@ -77,11 +79,10 @@
   },
   "dependencies": {
     "@types/json-bigint": "^1.0.4",
-    "archiver": "^5.3.2",
+    "archiver": "^8.0.0",
     "cli-table3": "^0.6.5",
     "commander": "^12.1.0",
     "csv-parse": "^7.0.2",
-    "exceljs": "^4.4.0",
     "iconv-lite": "^0.7.3",
     "jq-wasm": "^3.0.0-jq-1.8.2",
     "jschardet": "^3.1.4",
@@ -95,16 +96,24 @@
     "xlsx": "^0.18.5"
   },
   "devDependencies": {
-    "@types/archiver": "^5.3.4",
-    "@types/iconv-lite": "^0.0.1",
+    "@types/archiver": "^8.0.0",
     "@types/node": "^22.0.0",
     "@types/stream-json": "^1.7.8",
     "@types/turndown": "^5.0.6",
     "@types/unzipper": "^0.10.11",
     "@types/ws": "^8.5.0",
+    "exceljs": "^4.4.0",
     "jszip": "^3.10.1",
     "tsup": "^8.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.5.0"
+  },
+  "overrides": {
+    "exceljs": {
+      "archiver": "8.0.0",
+      "fast-csv": "5.0.7",
+      "unzipper": "0.12.5",
+      "uuid": "11.1.1"
+    }
   }
 }

package/skills/ae-agent/SKILL.md

@@ -74,7 +74,7 @@ Use `ae-agent` for all Agent platform resource work:
 
 If the user's intent is data analysis, audience management, metadata governance, TeamRuns, or knowledge bases, switch to `ae-analysis` / `ae-engage` / `ae-dataops` / `ae-team` / `ae-kb`.
 
-## Tool Groups (82 commands)
+## Tool Groups (81 commands)
 
 ### Agents (5)
 
@@ -128,7 +128,7 @@ If the user's intent is data analysis, audience management, metadata governance,
 - `+del-skill` ([doc](references/del-skill.md)) — delete a personal Skill (physical delete)
 - `+toggle-skill` ([doc](references/toggle-skill.md)) — enable or disable a Skill
 
-### Skill content & assets (16)
+### Skill content & assets (15)
 
 - `+edit-skill` ([doc](references/edit-skill.md)) — edit a Skill's content (name/description/instructions/category/icon)
 - `+get-skill-content` ([doc](references/get-skill-content.md)) — read a Skill's SKILL.md source
@@ -145,7 +145,6 @@ If the user's intent is data analysis, audience management, metadata governance,
 - `+read-skill-script` ([doc](references/read-skill-script.md)) — read a script file (binary-safe with `--output`)
 - `+del-skill-script` ([doc](references/del-skill-script.md)) — delete a script file
 - `+upload-skill` ([doc](references/upload-skill.md)) — create/replace a Skill from a ZIP package (parses SKILL.md; 5MB)
-- `+rescan-skills` ([doc](references/rescan-skills.md)) — rescan local filesystem and sync Skills to DB (root only)
 
 ### Market (browse) (2)
 
@@ -261,7 +260,7 @@ For a local Agent, a successful `+mark-used` response means only that the dedupl
 - **MCP connectivity**: `+add-mcp` does NOT validate server connectivity — an unreachable URL is accepted at create time and only fails when the agent calls the MCP at runtime. Double-check the URL.
 - **Attachments**: upload supports files up to 50MB each, with a 1GB user quota. Batch uploads support partial success — individual file failures don't affect others.
 - **Skill `--instructions @-`**: reads from stdin, useful for piping long instruction text.
-- **Skill content versions**: `+add-skill` accepts optional `--version`; `+edit-skill` content changes and `+upload-skill --replace-skill-id` require a higher `major.minor` version.
+- **Skill content versions**: `+add-skill` accepts optional `--version`; `+edit-skill` content changes and `+upload-skill --replace-skill-id` require a higher `major.minor` version. On `SKILL_VERSION_CONFLICT`, read `meta.currentVersion` and retry with a strictly higher version. On `SKILL_HISTORY_CONFLICT`, stop retrying and tell the user that the Skill cannot be safely updated right now and that they should contact their administrator. Never recommend internal maintenance commands or expose diagnostic payloads in a customer-facing response.
 - **Skill sync push**: each selected Skill is uploaded as a ZIP to the versioned server endpoint. The server commits the canonical package before success; the CLI no longer copies it after the response.
 - **Market category keys**: `ae_preset | dev_tool | search_tool | data_query | content_gen | enterprise | life | automation | other`. Sort options: `newest | calls | likes` (`calls` sorts MCP by call count, Skill by download count). Market scope: `all | system | company | custom` (`custom` = personal).
 - **Meta on create/copy**: `+add-mcp` / `+add-skill` / `+copy-skill` accept optional `--category / --icon-emoji / --icon-color`; these are applied via a follow-up meta PATCH after creation. MCP creation still does NOT validate server connectivity.

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

@@ -68,6 +68,9 @@ ae-cli agent +edit-skill --dry-run --id <skill-cuid> --name new-name --version 2
 
 - `404` / not found: re-run `+list-skills` to verify the Skill ID and scope.
 - `409` / name conflict: use `--name` with a different name, or consider `+upload-skill` with `--auto-rename`.
+- `SKILL_VERSION_CONFLICT`: read `meta.currentVersion`, choose a strictly higher `major.minor` value, and retry the same command with `--version`.
+- `SKILL_HISTORY_CONFLICT`: stop retrying and tell the user, "The Skill cannot be safely updated right now. Please contact your administrator."
+- Do not recommend internal maintenance commands or expose diagnostic payloads in a customer-facing response.
 
 ## Recommended Chaining
 

package/skills/ae-agent/references/get-skill-content.md

@@ -30,7 +30,7 @@ ae-cli agent +get-skill-content --dry-run --id <skill-cuid>
 
 ## Next Steps on Failure
 - `404` / not found: re-run `+list-skills` to verify the Skill ID.
-- `file_not_found`: the Skill record exists but the SKILL.md file is missing on disk — use `+rescan-skills` (root) to sync.
+- `file_not_found`: the Skill content is unavailable. Ask the user to contact their administrator; do not recommend internal maintenance commands.
 
 ## Recommended Chaining
 - `+list-skills` → confirm `id` → `+get-skill-content` → `+edit-skill` (if changes needed)

package/skills/ae-agent/references/rescan-skills.md

@@ -1,24 +1,26 @@
-# agent +rescan-skills (Rescan Skills)
+# agent +rescan-skills (Internal Compatibility Reference)
 
 > **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
 
-Domain: **Skills / write**
+Domain: **Skills / internal write**
 
 ## Use Cases
-- Rescan Skill files on the server filesystem and sync them to the database.
+- Preserve compatibility for privileged administrators who already use the legacy command.
 - Endpoint: `POST /api/sandbox/agent/skills/rescan`.
-- **Root-only**: requires root privileges; non-root users get a 403.
-- No flags — the scan covers all Skill directories on the server.
+- The endpoint synchronizes system-scope Skills only.
+- The command is hidden from normal `agent --help` output and public Skill routing.
 
 ## Mandatory Rules (MUST)
 - This command takes no flags.
-- **Root-only operation**: non-root users will receive a 403 error.
+- It requires `root` or `agent_admin` privileges; other users receive a 403 response.
+- Never use it to recover a personal or company Skill.
+- Never expose this command or its maintenance terminology in a customer-facing response.
 - This is an ordinary `write` operation and does not require CLI confirmation.
 - Prefer `--dry-run` before executing — rescan has filesystem side effects.
 
 ## Command
 ```bash
-# Rescan and sync
+# Internal administrator use only
 ae-cli agent +rescan-skills
 
 # Dry-run to inspect the request before executing
@@ -31,14 +33,14 @@ ae-cli agent +rescan-skills --dry-run
 | _(none)_ | — | This command takes no flags |
 
 ## Decision Rules
-- Use this command when Skill files on disk are out of sync with the database (e.g. after manual filesystem changes or migration).
-- This is a root-only operation — confirm the user has root privileges before running.
-- The scan covers all Skill directories (system, company, personal) on the server.
+- Use this command only for an explicitly authorized system-Skill maintenance task.
+- Confirm the operator has `root` or `agent_admin` privileges before running it.
+- Do not route ordinary Skill update failures to this command.
 - Use `--dry-run` first to verify the request shape before executing.
 
 ## Next Steps on Failure
-- `403` / 无权限: the current user is not root — rescan requires root privileges.
-- `扫描同步失败`: the scan encountered filesystem errors — check server logs and Skill directory permissions.
+- `403`: the current operator lacks the required administrator role.
+- Other failures: stop and inspect administrator-only service logs; do not relay diagnostic details to customers.
 
 ## Recommended Chaining
-- `+rescan-skills` → `+list-skills` (verify the synced state)
+- `+rescan-skills` → `+list-skills` (verify system Skills only)

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

@@ -87,11 +87,14 @@ ae-cli agent +upload-skill --dry-run --file ./my-skill.zip
 
 - `File not found`: verify the local file path.
 - `--file must be a .zip file`: only ZIP format is supported.
-- `ZIP 中缺少 SKILL.md`: ensure the ZIP contains a `SKILL.md` file.
-- `缺少名称或内容`: the SKILL.md is missing the `name` field or content — fix the ZIP.
-- `缺少描述`: the SKILL.md is missing the description — fix the ZIP or use `--description`.
-- `数据库写入失败`: DB write failed — retry or check server logs.
+- Missing `SKILL.md`: ensure the ZIP contains a `SKILL.md` file.
+- Missing name or content: add the `name` field and Skill content to `SKILL.md`.
+- Missing description: add a description to `SKILL.md` or use `--description`.
+- The upload could not be saved: retry once, then contact the administrator if it still fails.
 - `409` / name conflict: use `--auto-rename` or choose a different `--name`.
+- `SKILL_VERSION_CONFLICT`: read `meta.currentVersion`, choose a strictly higher `major.minor` value, and retry the same replacement with `--version`.
+- `SKILL_HISTORY_CONFLICT`: stop retrying and tell the user, "The Skill cannot be safely updated right now. Please contact your administrator."
+- Do not recommend internal maintenance commands or expose diagnostic payloads in a customer-facing response.
 
 ## Recommended Chaining
 

package/skills/ae-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-analysis
-version: 4.2.2
+version: 4.2.3
 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."
 ---
 
@@ -16,6 +16,7 @@ This is the single entry skill for analysis intent and command execution.
 2. Read the selected command's dedicated reference before composing it:
    - `event list` -> `references/event_list.md`
    - `analysis dashboard list` -> `references/dashboard_list.md`
+   - `personal-semantic-preference list` -> `references/personal_semantic_preference_list.md`
    - replace hyphens with underscores in gateway filenames.
 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).
@@ -32,6 +33,7 @@ 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.
+- `personal-semantic-preference`: current user's project-scoped personal semantic preferences. Use it as agent context before resolving ambiguous business wording, asset choices, or recurring user preferences.
 
 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.
 
@@ -97,15 +99,54 @@ Before a project-scoped command:
 3. If there are multiple plausible projects, the host is unclear, or no project matches, show the candidates and ask; never guess.
 4. Re-verify after the user changes project, host, or environment.
 
+### Project Semantics
+
+Before answering project-scoped analysis or asset-governance requests, call `ae-cli project-semantic list --project-id <project_id>` once after the project is resolved. This is the governed project semantic catalog. The list is already filtered to active, fresh project semantics and sorted by heat, so do not page or search the database yourself.
+
+If one project semantic is actually adopted to interpret the user's wording, asset selection, metric definition, calculation convention, or project-wide business rule, fetch it with `ae-cli project-semantic get --project-id <project_id> --id <semantic_id> --mark-used`. Do not pass `--mark-used` for project semantics that were only inspected or rejected.
+
+For project semantic recommendation, switch to the `ae-project-semantic` skill. This skill only consumes published project semantics during analysis tasks.
+
+Published project semantics are the formal project-wide authority. A current-turn user instruction may request a different analysis, but the result must be labeled as an explicit non-formal deviation rather than silently replacing the published definition.
+
+### Personal Semantic Preferences
+
+Before answering project-scoped analysis or asset-governance requests, call `ae-cli personal-semantic-preference list --project-id <project_id>` once per host, authenticated user, project, and conversation after the project is resolved. Keep that lightweight directory in conversation context; do not page it, search the database, or call list again for each question. The backend returns at most 200 entries using `HOT_160_PLUS_RECENT_40` and may return fewer to keep the payload within its size limit.
+
+Use the returned compact catalog only as context. If one item is actually adopted to interpret the user's wording, asset selection, metric preference, or output style, fetch it with `ae-cli personal-semantic-preference get --project-id <project_id> --id <preference_id> --mark-used`. This also applies when the matched item is being used as the target for an `update`. Do not pass `--mark-used` for items that were only inspected or rejected.
+
+Apply the two catalogs by authority and purpose, not as one flat ranking. Published project semantics define the formal business meaning. Personal semantics supply the current user's defaults, interpretation corrections, asset choices, and output preferences where they do not conflict. If a personal semantic conflicts with a published project semantic, use the project semantic for the formal result and explicitly disclose the difference; never silently overwrite the personal record. If the user explicitly requests the personal alternative for the current task, execute it as a labeled non-formal variation.
+
+The Agent owns the personal preference capture trigger. Choose `context_type` by meaning:
+
+- `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.
+- `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. During a project task, collect durable current-user preferences, stable interpretation corrections, reusable asset-selection choices, recurring output preferences, and current-user working definitions that have not become approved project semantics. A working definition remains eligible for personal storage even when it would also benefit other project users. Store it only as the current user's preference; never describe it as approved project authority or copy a bound asset definition into its content. Keep future governance or lifecycle instructions out of the stored content. Do not save transient task details, one-off analysis results, company knowledge, standalone metadata facts, reports, or dashboards as personal preferences.
+
+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.
+
+Personal capture and project recommendation are independent. Save or update the personal semantic first when its evidence gate is met. If the same content looks reusable as a formal project-wide definition, finish the current task and then ask whether the user wants to recommend it as a project semantic candidate. Do not make project recommendation a prerequisite for personal capture, do not submit a candidate without that user choice, and never approve or publish on behalf of an ordinary user.
+
+After a successful add, update, or delete, merge that response into the conversation's cached directory locally. Do not call list again merely to observe the write.
+
+When a later published project semantic matches a personal semantic, treat the project semantic as formal and allow the personal record to become redundant, expire, or merge through the supported lifecycle. When they conflict, keep the project semantic formal, disclose the conflict, and preserve the personal record unless the user explicitly changes or deletes it. These are consumption and lifecycle rules; do not append them to the stored personal semantic content.
+
+Stale or expired preferences are automatically hidden by list filtering and backend maintenance. Do not look for or invent a separate command for that behavior.
+
 ### 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. 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.
+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 saved assets outside the analysis metadata catalog, broaden the keyword batch up to two times, then list all candidates. If no resource exists, stop instead of fabricating one.
+
+For ordinary event, property, metric, cluster, and tag metadata discovery, keep one discovery budget per host, project, authenticated principal, and Agent conversation. Put the user's phrase and its useful synonyms in one `--queries` JSON array; matching is OR across at most 20 keywords. A successful remote search round with no confirmable candidate consumes one miss. A candidate stops discovery and requires user confirmation; it is not a miss. Validation, permission, network, and server errors are failures: they do not consume the budget and must not trigger a full export. After at most two ordinary miss rounds, the third remote discovery round must be one aggregate `analysis-meta catalog list` using the accumulated deduplicated queries and the union of applicable resource types. If that aggregate search is still unresolved, export the complete unified catalog exactly once and reuse it locally as defined in `metadata_resolution.md`. Once a valid complete catalog exists, do not call online resource-specific metadata list/search commands or `analysis-meta catalog list|export` again in that scope.
 
 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.
+The ordinary discovery budget does not replace the entry path for 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
 
@@ -113,7 +154,7 @@ When the request can map to a saved business definition:
 
 1. Extract metric, dimensions, filters, time window, and comparison semantics.
 2. Search reports; use dashboard search only to discover candidate embedded reports.
-3. Before querying a selected dashboard's report data, call `analysis dashboard get` exactly once with the verified project and dashboard IDs. Preserve non-empty `location.folder_name`, `dashboard_name`, `remark`, and `notes[].note_title/description` as authored dashboard context for all results from that dashboard. Do not repeat the detail call per report.
+3. Before querying a selected dashboard's report data, call `analysis dashboard get` exactly once with the verified project and dashboard IDs. Inspect `effective_settings` and `filter_config`; dashboard default, dashboard business, and space business filters are already applied and call-time filters add AND conditions. Honor the saved fixed time unless the user explicitly supplies a supported time override. Preserve non-empty `location.folder_name`, `dashboard_name`, `remark`, and `notes[].note_title/description` as authored dashboard context for all results from that dashboard. Do not repeat the detail call per report.
 4. Read the candidate definition and verify semantic equality, not merely a similar name.
 5. Use report/dashboard data when the definition matches.
 6. Use `analysis adhoc run|export` when no definition matches, the user explicitly requests ad-hoc exploration, or custom grouping/filtering is required.

package/skills/ae-analysis/metadata_resolution.md

@@ -1,6 +1,11 @@
-# Structured AI-QP metadata resolution
+# Analysis 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:
+Enter this workflow through either path:
+
+1. `analysis adhoc run|export`, report create, or report update fails with `AI_QP_COMPILE_FAILED` and its metadata errors contain the structured fields below.
+2. Ordinary event, property, metric, cluster, or tag metadata discovery has completed two successful remote miss rounds in the same host, project, authenticated principal, and Agent conversation, and a third remote discovery round would otherwise be needed.
+
+For the structured compiler path, the metadata errors contain:
 
 - `path`
 - `slot_kind`
@@ -10,7 +15,7 @@ Use this workflow only when `analysis adhoc run|export`, report create, or repor
 - `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`.
+The Common compiler returns every unresolved slot from the same compile attempt. Treat that complete error array as one resolution plan. Do not run the structured path 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.
 
@@ -65,6 +70,35 @@ Before reuse, require both files and verify:
 
 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.
 
+## Ordinary discovery workflow
+
+1. Keep one miss budget for the current host, project, authenticated principal, and Agent conversation.
+2. One ordinary discovery round is one successful remote event, property, metric, cluster, or tag list/search request. Put the current phrase and its useful synonyms in one `--queries` array instead of issuing one request per synonym.
+3. A round consumes one miss only when it returns no confirmable candidate. A plausible candidate stops discovery and requires explicit user confirmation; it is not a miss.
+4. Project lookup, exact `get`, filter-value lookup, and data queries do not consume this metadata-discovery budget. Validation, permission, network, and server errors are failures, do not consume a miss, and must not trigger the full-catalog fallback.
+5. After at most two ordinary miss rounds, do not issue a third resource-specific list/search. The third remote metadata-discovery round must be exactly one aggregate search using every accumulated deduplicated query and the union of applicable resource types:
+
+```bash
+ae-cli analysis-meta catalog list \
+  --project-id <project_id> \
+  --queries '["<all accumulated deduplicated queries>"]' \
+  --resource-types '["<union of applicable resource types>"]' \
+  --limit-per-type 20
+```
+
+6. If the aggregate response contains a confirmable candidate, stop and ask for confirmation. If it remains unresolved or returns `has_more=true` without a candidate, download the complete catalog exactly once:
+
+```bash
+ae-cli analysis-meta catalog export \
+  --project-id <project_id> \
+  --output "<catalog_dir>/catalog.jsonl"
+```
+
+7. Search the complete JSONL locally, return only a small candidate subset to model context, and require confirmation before binding. A local no-match is a complete negative result for that snapshot.
+8. Once the valid complete catalog exists, use it for every later metadata discovery in the same scope. Do not call online resource-specific metadata list/search commands or `analysis-meta catalog list|export` again. An exact `get` for details not present in the catalog remains outside the discovery budget.
+
+This caps ordinary online metadata discovery at three successful remote rounds before the full-catalog fallback becomes eligible: at most two resource-specific misses followed by one aggregate catalog search. Errors never advance that counter.
+
 ## Compile-wide workflow
 
 1. Read the complete compiler error array.
@@ -112,7 +146,7 @@ ae-cli analysis-meta catalog export \
 
 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.
+Do not call event, property, metric, cluster, or tag list commands after entering the 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.
 

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

@@ -26,6 +26,35 @@ This policy does not apply to:
 - `analysis-meta`, metadata, DataOps, Community, Engage, or other business modules.
 - Report/dashboard/BI asset list commands, catalog exports, definition import/export, or management commands.
 
+## Cache policy for report and ad-hoc data
+
+Apply this cache policy to `analysis adhoc run|export` and
+`analysis report-data run|export`:
+
+- For an ordinary query, omit `--use-cache`; its effective default is `true`.
+  This allows a cache read but does not prove that the query actually hit a
+  cache.
+- Pass `--use-cache false` only when the user explicitly asks for fresh data,
+  a refresh or recomputation, to bypass/disable cache, or says the underlying
+  data was just updated. Words such as "latest" or "current" trigger this only
+  when they refer to data freshness, not merely to a selected time window.
+- When the user explicitly compares with a freshly refreshed analysis UI,
+  pass `--use-cache false`. A request that merely mentions a report or UI does
+  not imply this freshness requirement.
+- If the user reports that CLI/Agent data differs from the analysis UI, repeat
+  the same semantic query exactly once with `--use-cache false`. Preserve the
+  project, asset or model definition, filters, time range, timezone, cluster
+  route, and other query inputs. Explain that any difference may come from
+  cache policy or refresh timing; do not enter a retry loop.
+
+The Agent cannot observe whether another browser session is open, whether a UI
+query used cache, or whether the user is demonstrating the product. Never infer
+a demo scenario and never change cache policy based only on the audience or
+interface. `--use-cache` controls whether cache reads are allowed for this CLI
+query; it neither changes the saved asset/UI configuration nor exposes an
+actual cache-hit result. Do not claim cache hit or miss unless the response
+contains explicit backend evidence.
+
 ## Decision rule
 
 Synchronous data commands use `--preview-rows` for the maximum business rows

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

@@ -145,7 +145,7 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. Analys
 | `user-cluster-member list` | `analysis.user_cluster_member.list` | Bounded inline cluster members | `--cluster-name`, optional properties/fields/query/limit/offset | Member rows |
 | `user-cluster-member export` | `analysis.user_cluster_member.export` | Stream native full cluster members as csv.gz | `--cluster-name`, optional properties | Async artifact descriptor |
 | `user-cluster create` | `analysis.user_cluster.create` | Create condition/sql cluster directly from semantic intent | `--cluster-name`, `--display-name`, `--definition-request` | Create result and canonical request |
-| `user-cluster update` | `analysis.user_cluster.update` | Update condition/sql cluster | `--cluster-name`, fields to change, optional `--definition-request` | Update result |
+| `user-cluster update` | `analysis.user_cluster.update` | Update condition/sql cluster after confirmation without changing its type or analysis entity | `--cluster-name`, fields to change, optional `--definition-request` with the existing type, then `--yes` after dry-run and explicit confirmation | Update result |
 | `user-cluster create-id` | `analysis.user_cluster.create_id` | Map imported values to an entity and create a cluster | `--display-name`, `--entity-id`, exactly one input source, conditional `--association-property` | Processing state; poll get for final match summary |
 | `user-cluster update-id` | `analysis.user_cluster.update_id` | Remap imported values for an ID cluster | `--cluster-name`, exactly one input source, conditional `--association-property` | Processing state; poll get for final match summary |
 | `user-cluster refresh` | `analysis.user_cluster.refresh` | Trigger cluster recompute | `--cluster-name` | Refresh result |

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

@@ -0,0 +1,22 @@
+# analysis-governance asset-authentication export
+
+Use for complete offline processing of project asset-authentication rows.
+
+Do not use it for interactive preview or let the CLI loop over `list`; this command invokes the complete export capability once.
+
+Command:
+
+```bash
+ae-cli analysis-governance asset-authentication export --project-id <project_id> --asset-types '["dashboard","report"]' --output /tmp/assets.jsonl
+```
+
+Capability id: `governance.asset_authentication.export`.
+
+The command does not accept `limit` or `offset` and performs exactly one complete server export call. It validates `complete`, `total`, `stat_as_of`, and `snapshot_hash`, then atomically publishes both:
+
+- `<output>`: private-mode JSONL rows.
+- `<output>.meta.json`: `complete`, `project_id`, `total`, `stat_as_of`, `snapshot_hash`, and the local file SHA-256 `checksum`.
+
+Export projection always retains `resource_type`, `resource_key`, `display_name`, `authentication_status`, `heat_count90d`, `user_count90d`, and `impact_degree`; `--fields` can add or remove only optional descriptive and owner fields.
+
+Use the sidecar `snapshot_hash` with `update --expected-snapshot-hash` when the selected asset set was derived from this export.

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

@@ -1,25 +1,29 @@
-# analysis-meta asset-authentication list
+# analysis-governance asset-authentication list
 
-Use when the user needs to list authenticatable project assets and authentication status.
+Use for bounded online preview, search, and filtering of project asset-authentication rows.
 
-Do not use it as a complete asset search or to change status; use `asset search` or `asset authentication-update` respectively.
+This command filters on the server before sorting and pagination. Use `export` for a complete offline dataset and `update` for an explicit typed asset set.
+
+Do not use it to synthesize a complete catalog by paging or to change authentication state.
 
 Command:
 
 ```bash
-ae-cli analysis-meta asset-authentication list --project-id <project_id> --limit 50 --offset 0
-ae-cli analysis-meta asset-authentication list --dry-run
+ae-cli analysis-governance asset-authentication list --project-id <project_id> --asset-types '["dashboard","report"]' --authentication-status 0 --heat-count-gt 50 --user-count-gt 5 --match any --limit 100
 ```
 
-Capability id: `metadata.asset_authentication.list`.
+Capability id: `governance.asset_authentication.list`.
+
+`match=any|all` combines only the supplied numeric thresholds. Asset types, authentication status, and keyword queries are always AND filters. `queries` matches any supplied keyword.
+
+Output uses `data.items[]`, `total`, `limit`, `offset`, `has_more`, and `next_offset`. Row identity is always `resource_type + resource_key`; dashboard and report keys are numeric IDs encoded as strings, while metadata assets use business names.
 
-Input sends `project_id`, `limit`, and `offset`.
+## analysis-meta asset-authentication list
 
-Output always uses the directory envelope: `data.items[]`, `total`, `limit`, `offset`, `has_more`, and `next_offset`.
+The legacy command remains available for one release cycle and returns the old row shape.
+
+```bash
+ae-cli analysis-meta asset-authentication list --project-id <project_id> --limit 50 --offset 0
+```
 
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project-id` | Yes | Numeric project ID. |
-| `--limit` / `-l` | No | Page size. Default: 50, maximum: 200. |
-| `--offset` / `-o` | No | Zero-based page offset. Default: 0. |
+Legacy Input is `project_id`, `limit`, and `offset`. Legacy Output uses the same directory envelope with the old asset field names.