@thinkingai/ae-cli 6.0.45 → 6.0.46

package/dist/{te-community-HLC43QKH.js → te-community-5DMNKJWY.js}

@@ -1,25 +1,25 @@
 import {
   registerCapabilityGatewayRoute
-} from "./chunk-PTE56QPL.js";
+} from "./chunk-3KWQYGYI.js";
 import {
   internalCallSourceHeaders
 } from "./chunk-6EIJSNBD.js";
 import {
   clearCliToken,
   getCliToken
-} from "./chunk-4SGZG4XY.js";
+} from "./chunk-J2DEBMRF.js";
+import "./chunk-ZQKDZXDO.js";
 import {
   getActiveHost,
   safeJsonParse
-} from "./chunk-ZZUOD757.js";
+} from "./chunk-3FY3RJ26.js";
 import {
   CliValidationError,
   PermissionError
 } from "./chunk-UW5UN47B.js";
 import {
   logger
-} from "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+} from "./chunk-JHENBQ5B.js";
 
 // src/core/mcp.ts
 async function permissionDetails(resp) {

package/dist/{te-community-6HPBWJUZ.js → te-community-ISDQWJU7.js}

@@ -1,25 +1,25 @@
 import {
   registerCapabilityGatewayRoute
-} from "./chunk-PTE56QPL.js";
+} from "./chunk-3KWQYGYI.js";
 import {
   internalCallSourceHeaders
-} from "./chunk-C4MGVGJW.js";
+} from "./chunk-SERWF6G5.js";
 import {
   clearCliToken,
   getCliToken
-} from "./chunk-4SGZG4XY.js";
+} from "./chunk-J2DEBMRF.js";
+import "./chunk-ZQKDZXDO.js";
 import {
   getActiveHost,
   safeJsonParse
-} from "./chunk-ZZUOD757.js";
+} from "./chunk-3FY3RJ26.js";
 import {
   CliValidationError,
   PermissionError
 } from "./chunk-UW5UN47B.js";
 import {
   logger
-} from "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+} from "./chunk-JHENBQ5B.js";
 
 // src/core/mcp.ts
 async function permissionDetails(resp) {

package/dist/{te-dataops-HDRUXY4K.js → te-dataops-6P5IKWNJ.js}

@@ -1,25 +1,26 @@
 import {
   printError
-} from "./chunk-GT46FPXN.js";
+} from "./chunk-BYYS3ANB.js";
 import {
   internalCallSourceHeaders
-} from "./chunk-C4MGVGJW.js";
+} from "./chunk-SERWF6G5.js";
 import {
   clearCliToken,
   getCliToken
-} from "./chunk-4SGZG4XY.js";
+} from "./chunk-J2DEBMRF.js";
+import {
+  resolveHost
+} from "./chunk-ZQKDZXDO.js";
 import {
-  resolveHost,
   safeJsonParse
-} from "./chunk-ZZUOD757.js";
+} from "./chunk-3FY3RJ26.js";
 import {
   CliValidationError,
   PermissionError
 } from "./chunk-UW5UN47B.js";
 import {
   logger
-} from "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+} from "./chunk-JHENBQ5B.js";
 
 // src/commands/te-dataops/shared.ts
 import { randomBytes } from "crypto";

package/dist/{te-dataops-EJP56W3K.js → te-dataops-CVULXNVB.js}

@@ -1,25 +1,26 @@
 import {
   printError
-} from "./chunk-GT46FPXN.js";
+} from "./chunk-BYYS3ANB.js";
 import {
   internalCallSourceHeaders
 } from "./chunk-6EIJSNBD.js";
 import {
   clearCliToken,
   getCliToken
-} from "./chunk-4SGZG4XY.js";
+} from "./chunk-J2DEBMRF.js";
+import {
+  resolveHost
+} from "./chunk-ZQKDZXDO.js";
 import {
-  resolveHost,
   safeJsonParse
-} from "./chunk-ZZUOD757.js";
+} from "./chunk-3FY3RJ26.js";
 import {
   CliValidationError,
   PermissionError
 } from "./chunk-UW5UN47B.js";
 import {
   logger
-} from "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+} from "./chunk-JHENBQ5B.js";
 
 // src/commands/te-dataops/shared.ts
 import { randomBytes } from "crypto";

package/dist/{te-engage-UBHPAJCO.js → te-engage-ELA3C5BM.js}

@@ -1,29 +1,29 @@
 import {
   createCapabilityCommand
-} from "./chunk-QEFCIRNJ.js";
+} from "./chunk-2MN54X6H.js";
 import {
   printError,
   withOutputMetadata
-} from "./chunk-GT46FPXN.js";
+} from "./chunk-BYYS3ANB.js";
 import {
   CapabilityGatewayError,
   buildCapabilityGatewayUrl,
   fetchCapabilityGateway,
   requestCapabilityGateway,
   requestCapabilityGatewayWithEnvelope
-} from "./chunk-ILIU36SU.js";
+} from "./chunk-OMPRXM3V.js";
 import {
   registerCapabilityGatewayRoute,
   resolveGatewayDomain
-} from "./chunk-PTE56QPL.js";
+} from "./chunk-3KWQYGYI.js";
 import "./chunk-6EIJSNBD.js";
-import "./chunk-4SGZG4XY.js";
-import "./chunk-ZZUOD757.js";
+import "./chunk-J2DEBMRF.js";
+import "./chunk-ZQKDZXDO.js";
+import "./chunk-3FY3RJ26.js";
 import {
   CliValidationError
 } from "./chunk-UW5UN47B.js";
-import "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+import "./chunk-JHENBQ5B.js";
 
 // src/commands/te-engage/shared.ts
 function createEngageCapabilityCommand(cliService, config) {

package/dist/{te-engage-WLDTS5J5.js → te-engage-MC5IQZIU.js}

@@ -1,29 +1,29 @@
 import {
   createCapabilityCommand
-} from "./chunk-QI524WPY.js";
+} from "./chunk-XNVMVIUI.js";
 import {
   printError,
   withOutputMetadata
-} from "./chunk-GT46FPXN.js";
+} from "./chunk-BYYS3ANB.js";
 import {
   CapabilityGatewayError,
   buildCapabilityGatewayUrl,
   fetchCapabilityGateway,
   requestCapabilityGateway,
   requestCapabilityGatewayWithEnvelope
-} from "./chunk-P3FGXJTU.js";
+} from "./chunk-ZQ47LWTI.js";
 import {
   registerCapabilityGatewayRoute,
   resolveGatewayDomain
-} from "./chunk-PTE56QPL.js";
-import "./chunk-C4MGVGJW.js";
-import "./chunk-4SGZG4XY.js";
-import "./chunk-ZZUOD757.js";
+} from "./chunk-3KWQYGYI.js";
+import "./chunk-SERWF6G5.js";
+import "./chunk-J2DEBMRF.js";
+import "./chunk-ZQKDZXDO.js";
+import "./chunk-3FY3RJ26.js";
 import {
   CliValidationError
 } from "./chunk-UW5UN47B.js";
-import "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+import "./chunk-JHENBQ5B.js";
 
 // src/commands/te-engage/shared.ts
 function createEngageCapabilityCommand(cliService, config) {

package/dist/{te-kb-SQCLHG6X.js → te-kb-RCLSSH2Q.js}

@@ -1,17 +1,17 @@
 import {
   kbApi,
   kbUpload
-} from "./chunk-4KVPKXFX.js";
+} from "./chunk-RNAALWJK.js";
 import {
   printError
-} from "./chunk-GT46FPXN.js";
-import "./chunk-4SGZG4XY.js";
-import "./chunk-ZZUOD757.js";
+} from "./chunk-BYYS3ANB.js";
+import "./chunk-J2DEBMRF.js";
+import "./chunk-ZQKDZXDO.js";
+import "./chunk-3FY3RJ26.js";
 import {
   PermissionError
 } from "./chunk-UW5UN47B.js";
-import "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+import "./chunk-JHENBQ5B.js";
 
 // src/commands/te-kb/add.ts
 import { promises as fs } from "fs";
@@ -884,7 +884,7 @@ var url = {
     { name: "name", type: "string", required: true, desc: "Knowledge base name" },
     { name: "url", type: "string", required: true, desc: "Source URL to upload" },
     { name: "display-name", type: "string", required: false, desc: "Optional display name for the URL source" },
-    { name: "parse-instruction", type: "string", required: false, desc: "Optional parsing instruction for the URL source" }
+    { name: "parse-instruction", type: "string", required: false, desc: "Optional parsing instruction for the URL source; ignored for Lark/Feishu doc URLs (the server applies its own Feishu parsing)" }
   ],
   risk: "write",
   validate: (ctx) => {

package/dist/{te-system-Z77IKZFN.js → te-system-FXITO2JG.js}

@@ -7,17 +7,17 @@ import {
   putToMainApp,
   tryLoadTeAgentSandboxCredentials,
   uploadToMainApp
-} from "./chunk-VPKZ7I72.js";
+} from "./chunk-QNOLN2LJ.js";
 import "./chunk-6EIJSNBD.js";
-import "./chunk-4SGZG4XY.js";
+import "./chunk-J2DEBMRF.js";
+import "./chunk-ZQKDZXDO.js";
 import {
   safeJsonParse
-} from "./chunk-ZZUOD757.js";
+} from "./chunk-3FY3RJ26.js";
 import {
   CliValidationError
 } from "./chunk-UW5UN47B.js";
-import "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+import "./chunk-JHENBQ5B.js";
 
 // src/commands/te-system/shared.ts
 import { readFileSync } from "fs";

package/dist/{te-system-YARIK4S5.js → te-system-K2GYMCTB.js}

@@ -7,17 +7,17 @@ import {
   putToMainApp,
   tryLoadTeAgentSandboxCredentials,
   uploadToMainApp
-} from "./chunk-UOUS37JQ.js";
-import "./chunk-C4MGVGJW.js";
-import "./chunk-4SGZG4XY.js";
+} from "./chunk-4XXOWOTA.js";
+import "./chunk-SERWF6G5.js";
+import "./chunk-J2DEBMRF.js";
+import "./chunk-ZQKDZXDO.js";
 import {
   safeJsonParse
-} from "./chunk-ZZUOD757.js";
+} from "./chunk-3FY3RJ26.js";
 import {
   CliValidationError
 } from "./chunk-UW5UN47B.js";
-import "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+import "./chunk-JHENBQ5B.js";
 
 // src/commands/te-system/shared.ts
 import { readFileSync } from "fs";

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

@@ -1,16 +1,16 @@
 import {
   getAuthHeaders,
   kbApi
-} from "./chunk-4KVPKXFX.js";
+} from "./chunk-RNAALWJK.js";
 import {
   printError,
   printOutput
-} from "./chunk-GT46FPXN.js";
-import "./chunk-4SGZG4XY.js";
-import "./chunk-ZZUOD757.js";
+} from "./chunk-BYYS3ANB.js";
+import "./chunk-J2DEBMRF.js";
+import "./chunk-ZQKDZXDO.js";
+import "./chunk-3FY3RJ26.js";
 import "./chunk-UW5UN47B.js";
-import "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+import "./chunk-JHENBQ5B.js";
 
 // src/commands/te-team/shared.ts
 var API_PREFIX = process.env.AE_API_PREFIX ?? "/agent";

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

@@ -7,18 +7,19 @@ import {
   printError,
   printOutput,
   recordVersionSyncResult
-} from "./chunk-GT46FPXN.js";
+} from "./chunk-BYYS3ANB.js";
 import {
   peekCliToken
-} from "./chunk-4SGZG4XY.js";
+} from "./chunk-J2DEBMRF.js";
+import {
+  missingAeHostHint
+} from "./chunk-ZQKDZXDO.js";
 import {
   getActiveHost,
-  missingAeHostHint,
   normalizeUrl
-} from "./chunk-ZZUOD757.js";
+} from "./chunk-3FY3RJ26.js";
 import "./chunk-UW5UN47B.js";
-import "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+import "./chunk-JHENBQ5B.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.0.45",
+  "version": "6.0.46",
   "description": "CLI tool for ThinkingAI (AE) analytics platform",
   "type": "module",
   "bin": {

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,38 @@ 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.
 
+### 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.
+
+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. 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.
+
+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.
+
+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 +138,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.