@thinkingai/ae-cli 1.0.18 → 1.0.21

package/dist/te-kb-EHHYPYBN.js

@@ -0,0 +1,407 @@
+import {
+  httpDelete,
+  httpUpload
+} from "./chunk-7G2F7IVO.js";
+import "./chunk-OVMQFFC2.js";
+import "./chunk-TMMUBSKW.js";
+
+// src/commands/te-kb/query.ts
+var API_PATH = "/agent/api/external/knowledge-bases/query";
+function buildBody(ctx) {
+  const body = {
+    query: ctx.str("query"),
+    sources: ctx.json("sources")
+  };
+  const modelId = ctx.str("model-id");
+  if (modelId) body.modelId = modelId;
+  const maxTurnsRaw = ctx.str("max-turns");
+  if (maxTurnsRaw !== "") body.maxTurns = ctx.num("max-turns");
+  return body;
+}
+var query = {
+  service: "kb",
+  command: "+query",
+  description: "Query knowledge.",
+  flags: [
+    { name: "query", type: "string", required: true, alias: "q", desc: "Natural language question to query against the knowledge bases" },
+    { name: "sources", type: "json", required: true, desc: 'JSON array of knowledge base refs, e.g. [{"scope":"company","name":"engineering-handbook"}]' },
+    { name: "model-id", type: "string", required: false, default: "AE-Auto", desc: "Model identifier (default: AE-Auto)" },
+    { name: "max-turns", type: "number", required: false, default: 6, desc: "Maximum reasoning turns (default: 6)" }
+  ],
+  risk: "read",
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH}`,
+    body: buildBody(ctx)
+  }),
+  execute: async (ctx) => ctx.api("POST", API_PATH, {}, buildBody(ctx))
+};
+
+// src/commands/te-kb/add.ts
+import { promises as fs } from "fs";
+import * as path from "path";
+import TurndownService from "turndown";
+var API_PATH2 = "/agent/api/external/knowledge-bases/sources/upload";
+var MD_EXT = /* @__PURE__ */ new Set([".md", ".markdown"]);
+function normalizeFilesInput(raw) {
+  if (!Array.isArray(raw)) {
+    throw new Error(`--files must be a JSON array of strings, e.g. '["./a.md","./docs","https://example.com/page"]'`);
+  }
+  const items = [];
+  for (const v of raw) {
+    if (typeof v !== "string") {
+      throw new Error(`--files entries must be strings (got: ${JSON.stringify(v)})`);
+    }
+    const trimmed = v.trim();
+    if (trimmed) items.push(trimmed);
+  }
+  return items;
+}
+function isUrl(s) {
+  return /^https?:\/\//i.test(s);
+}
+function classifyInput(item) {
+  return isUrl(item) ? "url" : "path";
+}
+function sanitizeFilename(name) {
+  const cleaned = name.replace(/[\\/:*?"<>|\s]+/g, "-").replace(/^-+|-+$/g, "");
+  return cleaned || "document";
+}
+async function readLocalFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (!MD_EXT.has(ext)) {
+    throw new Error(`Not a markdown file (only .md / .markdown allowed): ${filePath}`);
+  }
+  const content = await fs.readFile(filePath, "utf8");
+  return { filename: path.basename(filePath), content, origin: "file", source: filePath };
+}
+async function readDirectory(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const ext = path.extname(entry.name).toLowerCase();
+    if (!MD_EXT.has(ext)) continue;
+    const full = path.join(dir, entry.name);
+    const content = await fs.readFile(full, "utf8");
+    files.push({ filename: entry.name, content, origin: "dir", source: full });
+  }
+  if (files.length === 0) {
+    throw new Error(`No .md / .markdown files found in directory: ${dir}`);
+  }
+  return files;
+}
+function deriveFilenameFromUrl(rawUrl) {
+  try {
+    const u = new URL(rawUrl);
+    const lastSeg = u.pathname.split("/").filter(Boolean).pop();
+    const base = lastSeg ? lastSeg.replace(/\.[^.]+$/, "") : u.hostname;
+    return `${sanitizeFilename(base)}.md`;
+  } catch {
+    return `${sanitizeFilename(rawUrl)}.md`;
+  }
+}
+async function fetchAsMarkdown(rawUrl) {
+  const resp = await fetch(rawUrl);
+  if (!resp.ok) {
+    throw new Error(`Failed to fetch ${rawUrl}: HTTP ${resp.status}`);
+  }
+  const html = await resp.text();
+  const turndown = new TurndownService({ headingStyle: "atx", codeBlockStyle: "fenced" });
+  const markdown = turndown.turndown(html);
+  return {
+    filename: deriveFilenameFromUrl(rawUrl),
+    content: markdown,
+    origin: "url",
+    source: rawUrl
+  };
+}
+async function resolveLocalPath(p) {
+  const abs = path.resolve(p);
+  let stat;
+  try {
+    stat = await fs.stat(abs);
+  } catch {
+    throw new Error(`Path not found: ${p}`);
+  }
+  if (stat.isDirectory()) {
+    return readDirectory(abs);
+  }
+  if (stat.isFile()) {
+    return [await readLocalFile(abs)];
+  }
+  throw new Error(`Unsupported path (not file or directory): ${p}`);
+}
+async function collectFiles(ctx) {
+  const items = normalizeFilesInput(ctx.json("files"));
+  if (items.length === 0) {
+    throw new Error("--files must contain at least one entry");
+  }
+  const collected = [];
+  for (const item of items) {
+    if (classifyInput(item) === "url") {
+      collected.push(await fetchAsMarkdown(item));
+    } else {
+      collected.push(...await resolveLocalPath(item));
+    }
+  }
+  if (collected.length === 0) {
+    throw new Error("No markdown files collected from the given inputs");
+  }
+  return dedupeByFilename(collected);
+}
+function dedupeByFilename(files) {
+  const used = /* @__PURE__ */ new Map();
+  return files.map((f) => {
+    const count = used.get(f.filename) ?? 0;
+    used.set(f.filename, count + 1);
+    if (count === 0) return f;
+    const ext = path.extname(f.filename);
+    const stem = f.filename.slice(0, f.filename.length - ext.length);
+    return { ...f, filename: `${stem}-${count}${ext}` };
+  });
+}
+function buildForm(name, files) {
+  const form = new FormData();
+  form.append("name", name);
+  for (const f of files) {
+    form.append("files", new Blob([f.content], { type: "text/markdown" }), f.filename);
+  }
+  return form;
+}
+var add = {
+  service: "kb",
+  command: "+add",
+  description: "Upload markdown sources to a knowledge. --files accepts a JSON array; each entry can be a .md/.markdown file path, a directory path (all .md/.markdown inside, non-recursive), or an http(s) URL (HTML auto-converted to markdown).",
+  flags: [
+    { name: "name", type: "string", required: true, desc: "Knowledge base name" },
+    {
+      name: "files",
+      type: "json",
+      required: true,
+      desc: `JSON array of strings. Each entry can be a .md/.markdown file path, a directory path, or an http(s) URL. Example: '["./a.md","./docs","https://example.com/page"]'`
+    }
+  ],
+  risk: "write",
+  validate: (ctx) => {
+    normalizeFilesInput(ctx.json("files"));
+  },
+  dryRun: (ctx) => {
+    const items = normalizeFilesInput(ctx.json("files"));
+    return {
+      method: "POST",
+      url: `${ctx.host().replace(/\/$/, "")}${API_PATH2}`,
+      body: {
+        name: ctx.str("name"),
+        files: items.map((item) => ({ value: item, type: classifyInput(item) })),
+        contentType: "multipart/form-data"
+      }
+    };
+  },
+  execute: async (ctx) => {
+    const name = ctx.str("name");
+    const files = await collectFiles(ctx);
+    const form = buildForm(name, files);
+    const result = await httpUpload(API_PATH2, form, {}, ctx.host());
+    return {
+      uploaded: files.map((f) => ({ filename: f.filename, origin: f.origin, source: f.source })),
+      result
+    };
+  }
+};
+
+// src/commands/te-kb/compile.ts
+var API_PATH3 = "/agent/api/external/knowledge-bases/compile";
+var VALID_MODES = /* @__PURE__ */ new Set(["incremental", "full"]);
+function getMode(ctx) {
+  const mode = ctx.str("mode") || "incremental";
+  if (!VALID_MODES.has(mode)) {
+    throw new Error(`Invalid --mode: ${mode}. Must be one of: incremental | full`);
+  }
+  return mode;
+}
+function buildBody2(ctx) {
+  return {
+    name: ctx.str("name"),
+    mode: getMode(ctx)
+  };
+}
+var compile = {
+  service: "kb",
+  command: "+compile",
+  description: "Compile a knowledge.",
+  flags: [
+    { name: "name", type: "string", required: true, desc: "Knowledge base name" },
+    { name: "mode", type: "string", required: false, default: "incremental", desc: "Compile mode: incremental | full (default: incremental)" }
+  ],
+  risk: "write",
+  validate: (ctx) => {
+    getMode(ctx);
+  },
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH3}`,
+    body: buildBody2(ctx)
+  }),
+  execute: async (ctx) => ctx.api("POST", API_PATH3, {}, buildBody2(ctx))
+};
+
+// src/commands/te-kb/remove.ts
+var API_PATH4 = "/agent/api/external/knowledge-bases";
+function buildBody3(ctx) {
+  return { name: ctx.str("name") };
+}
+var remove = {
+  service: "kb",
+  command: "+remove",
+  description: "Delete an entire knowledge.",
+  flags: [
+    { name: "name", type: "string", required: true, desc: "Knowledge base name to delete" }
+  ],
+  risk: "write",
+  dryRun: (ctx) => ({
+    method: "DELETE",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH4}`,
+    body: buildBody3(ctx)
+  }),
+  execute: async (ctx) => httpDelete(API_PATH4, {}, buildBody3(ctx), ctx.host())
+};
+
+// src/commands/te-kb/create.ts
+var API_PATH5 = "/agent/api/external/knowledge-bases/create";
+var VALID_SCOPES = /* @__PURE__ */ new Set(["personal", "company"]);
+function validateScope(scope) {
+  if (!VALID_SCOPES.has(scope)) {
+    throw new Error(`Invalid --scope: ${scope}. Must be one of: personal | company`);
+  }
+}
+function normalizeTags(raw) {
+  if (raw === void 0 || raw === null) return void 0;
+  if (!Array.isArray(raw)) {
+    throw new Error(`--tags must be a JSON array of strings, e.g. '["t1","t2"]'`);
+  }
+  const tags = [];
+  for (const v of raw) {
+    if (typeof v !== "string") {
+      throw new Error(`--tags entries must be strings (got: ${JSON.stringify(v)})`);
+    }
+    const t = v.trim();
+    if (t) tags.push(t);
+  }
+  return tags;
+}
+function buildBody4(ctx) {
+  const body = {
+    scope: ctx.str("scope"),
+    name: ctx.str("name")
+  };
+  const description = ctx.str("description");
+  if (description) body.description = description;
+  const tags = normalizeTags(ctx.json("tags"));
+  if (tags && tags.length > 0) body.tags = tags;
+  const projectId = ctx.str("project-id");
+  if (projectId) body.projectId = projectId;
+  const projectName = ctx.str("project-name");
+  if (projectName) body.projectName = projectName;
+  return body;
+}
+var create = {
+  service: "kb",
+  command: "+new",
+  description: "Create a new knowledge.",
+  flags: [
+    { name: "scope", type: "string", required: true, desc: "Knowledge base scope: personal | company" },
+    { name: "name", type: "string", required: true, desc: "Knowledge base name (\u226430 chars, unique per scope)" },
+    { name: "description", type: "string", required: false, desc: "Optional description (\u2264200 chars)" },
+    { name: "tags", type: "json", required: false, desc: `Optional JSON array of tags (max 2, each \u226415 chars). Example: '["t1","t2"]'` },
+    { name: "project-id", type: "string", required: false, desc: "Optional project ID to bind" },
+    { name: "project-name", type: "string", required: false, desc: "Optional project display name" }
+  ],
+  risk: "write",
+  validate: (ctx) => {
+    validateScope(ctx.str("scope"));
+    normalizeTags(ctx.json("tags"));
+  },
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH5}`,
+    body: buildBody4(ctx)
+  }),
+  execute: async (ctx) => ctx.api("POST", API_PATH5, {}, buildBody4(ctx))
+};
+
+// src/commands/te-kb/rm-source.ts
+var API_PATH6 = "/agent/api/external/knowledge-bases/sources";
+function buildBody5(ctx) {
+  return {
+    name: ctx.str("name"),
+    displayName: ctx.str("display-name")
+  };
+}
+var rmSource = {
+  service: "kb",
+  command: "+rm-source",
+  description: "Delete a single source file inside a knowledge.",
+  flags: [
+    { name: "name", type: "string", required: true, desc: "Knowledge base name (looked up personal \u2192 company)" },
+    { name: "display-name", type: "string", required: true, desc: "Source file display name as uploaded (e.g. kb-1780046712-foo.md)" }
+  ],
+  risk: "write",
+  dryRun: (ctx) => ({
+    method: "DELETE",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH6}`,
+    body: buildBody5(ctx)
+  }),
+  execute: async (ctx) => httpDelete(API_PATH6, {}, buildBody5(ctx), ctx.host())
+};
+
+// src/commands/te-kb/schema.ts
+var API_PATH7 = "/agent/api/external/knowledge-bases/schema";
+function buildBody6(ctx) {
+  const body = {
+    name: ctx.str("name")
+  };
+  if (ctx.bool("force")) body.force = true;
+  const model = ctx.str("model");
+  if (model) body.model = model;
+  return body;
+}
+var schema = {
+  service: "kb",
+  command: "+schema",
+  description: "Generate the compile schema for a knowledge base via POST /agent/api/external/knowledge-bases/schema.",
+  flags: [
+    { name: "name", type: "string", required: true, desc: "Knowledge base name (looked up personal \u2192 company)" },
+    { name: "force", type: "boolean", required: false, desc: "Preempt generation even when status is `generating` (use only for stuck recovery)" },
+    { name: "model", type: "string", required: false, desc: "Optional model displayName to use for schema generation" }
+  ],
+  risk: "write",
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH7}`,
+    body: buildBody6(ctx)
+  }),
+  execute: async (ctx) => ctx.api("POST", API_PATH7, {}, buildBody6(ctx))
+};
+
+// src/commands/te-kb/index.ts
+var commands = [
+  query,
+  add,
+  compile,
+  remove,
+  create,
+  rmSource,
+  schema
+];
+var te_kb_default = commands;
+export {
+  add,
+  compile,
+  create,
+  te_kb_default as default,
+  query,
+  remove,
+  rmSource,
+  schema
+};

package/dist/{te-meta-MGO5BCMG.js → te-meta-BO45GW32.js}

@@ -2,9 +2,9 @@ import {
   callMcpTool,
   parseMcpResult,
   resolveMcpUrl
-} from "./chunk-7QBNU44L.js";
-import "./chunk-4KQ7H7DY.js";
-import "./chunk-MR57UIKC.js";
+} from "./chunk-5CCFSPAF.js";
+import "./chunk-OVMQFFC2.js";
+import "./chunk-TMMUBSKW.js";
 
 // src/commands/te-meta/shared.ts
 function createMcpCommand(config) {
@@ -58,7 +58,7 @@ function requiredJsonString(ctx, name) {
 // src/commands/te-meta/meta/list-events.ts
 var listEvents = createMcpCommand({
   command: "+list_events",
-  description: "List events in the project. Query performs fuzzy matching on eventName, eventDesc and aiRemark. Supports fields/limit/offset payload governance.",
+  description: "List events in the project. Use for explicit metadata inspection, not as a pre-step for event/retention/funnel/prop_analysis ad-hoc builders; the builders resolve event names internally. Query performs fuzzy matching on eventName, eventDesc and aiRemark. Supports fields/limit/offset payload governance.",
   flags: [
     { name: "project_id", type: "number", required: true, desc: "Project ID", alias: "p" },
     { name: "query", type: "string", required: false, desc: "Optional keyword filter. Fuzzy match is applied to eventName, eventDesc, and aiRemark; if omitted, all events are returned.", alias: "q" },
@@ -79,7 +79,7 @@ var listEvents = createMcpCommand({
 // src/commands/te-meta/meta/list-properties.ts
 var listProperties = createMcpCommand({
   command: "+list_properties",
-  description: "List properties in the project. Query performs fuzzy matching on propName, propDesc and aiRemark. Supports fields/limit/offset payload governance.",
+  description: "List properties in the project. Use for explicit metadata inspection, not as a pre-step for event/retention/funnel/prop_analysis ad-hoc builders; the builders resolve property names internally. Query performs fuzzy matching on propName, propDesc and aiRemark. Supports fields/limit/offset payload governance.",
   flags: [
     { name: "project_id", type: "number", required: true, desc: "Project ID", alias: "p" },
     { name: "scope", type: "string", required: false, desc: "Property scope: event or user" },
@@ -198,7 +198,7 @@ var createVirtualProperty = createMcpCommand({
 // src/commands/te-meta/meta/list-metrics.ts
 var listMetrics = createMcpCommand({
   command: "+list_metrics",
-  description: "List metric metadata in the project. Query performs fuzzy matching on metricName, metricDesc, and metricRemark. Supports fields/limit/offset pagination.",
+  description: "List metric metadata in the project. Use for metric metadata inspection/management, not as a pre-step for event/retention/funnel/prop_analysis ad-hoc builders. For event saved metric queries, pass the metric name directly to +build_event_analysis_qp in metrics[].event. Query performs fuzzy matching on metricName, metricDesc, and metricRemark. Supports fields/limit/offset pagination.",
   flags: [
     { name: "project_id", type: "number", required: true, alias: "p", desc: "Project ID" },
     { name: "query", type: "string", required: false, alias: "q", desc: "Optional keyword filter. Fuzzy match on metricName, metricDesc, metricRemark." },
@@ -220,7 +220,7 @@ var listMetrics = createMcpCommand({
 // src/commands/te-meta/meta/get-metric.ts
 var getMetric = createMcpCommand({
   command: "+get_metric",
-  description: "Get the definition details of a single metric",
+  description: "Get the definition details of a single metric. Use for metric metadata inspection/management, not as a pre-step for event ad-hoc builder; pass saved metric names directly to +build_event_analysis_qp in metrics[].event.",
   flags: [
     { name: "project_id", type: "number", required: true, alias: "p", desc: "Project ID" },
     { name: "metric_id", type: "number", required: true, alias: "m", desc: "Metric ID" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingai/ae-cli",
-  "version": "1.0.18",
+  "version": "1.0.21",
   "description": "CLI tool for ThinkingAI (AE) analytics platform",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
     "dev": "tsx src/index.ts",
     "build": "tsup src/index.ts --format esm --outDir dist",
     "verify:analysis-tools": "node scripts/verify-te-analysis-tools.mjs",
+    "verify:analysis-builder-dry-run": "node scripts/verify-te-analysis-builder-dry-run.mjs",
     "verify:analysis-audience-tools": "node scripts/verify-te-audience-tools.mjs",
     "verify:analysis-meta-tools": "node scripts/verify-te-meta-tools.mjs",
     "verify:analysis-common-tools": "node scripts/verify-te-common-tools.mjs",
@@ -43,10 +44,12 @@
     "cli-table3": "^0.6.5",
     "commander": "^12.1.0",
     "json-bigint": "^1.0.0",
+    "turndown": "^7.2.4",
     "ws": "^8.18.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/turndown": "^5.0.6",
     "@types/ws": "^8.5.0",
     "tsup": "^8.0.0",
     "tsx": "^4.0.0",

package/skills/ae-analysis/SKILL.md

@@ -2,10 +2,6 @@
 name: ae-analysis
 version: 3.0.0
 description: "AE/TE/ThinkingEngine/ThinkingAI ae-cli manual for analysis-side tasks in the AE system or analysis platform: reports, dashboards, alerts, ad hoc analysis, drilldown, audience clusters, tags, tag members, metrics and metric definitions, events, properties, virtual events, virtual properties, metadata, project configuration, tracking plans, event tracking, mark times, project lists, and resource links. Use when the user asks to query, create, update, refresh, inspect, troubleshoot, govern, or manage these AE analysis assets. Must use ae-cli, read the matching references/<tool_name>.md command manual before composing commands, and never guess command names, flags, JSON payloads, project_id, resource IDs, or parameter formats."
-metadata:
-  requires:
-    bins: ["ae-cli"]
-  cliHelp: "ae-cli --help"
 ---
 
 # ae-analysis
@@ -19,49 +15,23 @@ metadata:
 
 AE CLI (`ae-cli`) is the command-line tool for the AE / TE / ThinkingEngine analysis platform. For AE analysis-side requests, prefer `ae-cli` and this skill's reference docs over model memory.
 
-Authentication priority:
-1. `TE_TOKEN` environment variable.
-2. Cached token in `~/.ae-cli/tokens.json`, usually valid for 20 hours.
-3. macOS Chrome token extraction via `ae-cli auth login`.
-
-Useful authentication commands:
-
-```bash
-ae-cli auth login
-ae-cli auth status
-ae-cli auth logout
-```
-
 Global parameters:
 
 | Parameter | Description |
 |---|---|
-| `--host <host>` | Target AE host. Use when the environment is not the default host. |
-| `--format <json|table>` | Output format. Default is JSON. |
+| `--format <json\|table>` | Output format. Default is JSON. |
 | `--jq <expr>` | jq filter expression for JSON output. |
-| `--dry-run` | Preview the request without executing it. |
-| `--yes` | Skip confirmation for write operations. Use only when the user intent is explicit or automation requires it. |
 
 Output and errors:
 - Successful commands return machine-readable JSON by default.
 - Failed commands return `{ "ok": false, "error": { "type": "...", "message": "...", "hint": "..." } }` and exit non-zero.
-- On auth/config errors, check `ae-cli auth status`, host configuration, and the target environment before retrying.
 
 Safety constraints:
 - Read commands can execute directly after required IDs and references are verified.
 - Write commands require explicit user intent and normally keep the confirmation prompt.
-- Use `--dry-run` before risky or complex writes.
-- Never invent command names, flags, JSON payloads, `project_id`, resource IDs, field names, event names, property names, metric definitions, or date formats. Read the matching command reference and discover real project metadata first.
+- Never invent command names, flags, JSON payloads, `project_id`, resource IDs, field names, event names, property names, metric definitions, or date formats. For builder-supported ad-hoc models (`event`, `retention`, `funnel`, `prop_analysis`), do not pre-discover metadata; pass the user's event/property/metric wording to the matching QP builder and let the builder resolve metadata or return clarification. For non-builder/manual workflows, read the matching command reference and discover real project metadata first.
 - **NEVER fabricate or guess resource names** (reports, dashboards, events, properties, metrics, clusters, tags, alerts). Always use list commands to discover real resources first. If a resource is not found after fuzzy search and full list fallback, explicitly tell the user "resource not found" and stop - do not proceed with fabricated names.
 
-Language consistency:
-- **Input-output language matching**: Always respond in the same language as the user's input.
-  - User asks in Chinese → Respond in Chinese, including result interpretation and error messages
-  - User asks in English → Respond in English
-- **CLI output handling**: CLI returns JSON in English, but your interpretation and summary MUST match user's language
-- **Resource names**: Keep original resource names as-is (don't translate), but descriptions and explanations should match user's language
-- **Error messages**: Translate CLI error messages to user's language when presenting results
-
 ## When to Use
 
 Use `ae-analysis` for all AE analysis-side work below:
@@ -147,7 +117,7 @@ Before executing ad-hoc queries (`query_adhoc`), MUST check for existing reports
 2. **Search existing reports** - Use `list_reports --query <keyword>` to find matching reports
 3. **Search existing dashboards** - Use `list_dashboards --query <keyword>` to find matching dashboards
 4. **If found** - Use `query_report_data` or `query_dashboard_report_data` to get data from existing assets
-5. **If not found** - Only then use `query_adhoc` for ad-hoc analysis
+5. **If not found** - For QP builder-supported models (`event`, `retention`, `funnel`, `prop_analysis`), call the matching builder first and then call `query_adhoc` with builder `qp`; do not call schema or metadata tools between the report/dashboard miss and the builder. For all other `query_adhoc` models, use the legacy schema/metadata path.
 
 **Rationale:**
 - **Performance**: Existing reports are pre-computed and faster
@@ -167,9 +137,67 @@ Before executing ad-hoc queries (`query_adhoc`), MUST check for existing reports
 - User is exploring data for new insights (exploratory analysis)
 - No matching reports found after search + fallback
 
-## Tool Groups (69)
+### E. QP_BUILDER_SUPPORTED_MODELS_ONLY
+
+QP builder supports exactly four ad-hoc model types: `event`, `retention`, `funnel`, and `prop_analysis`.
+
+For these four model types, QP builder is mandatory before `query_adhoc`. Do not handcraft QP from `get_analysis_query_schema`, examples, or prior knowledge.
+
+1. `event` -> `+build_event_analysis_qp`
+2. `retention` -> `+build_retention_analysis_qp`
+3. `funnel` -> `+build_funnel_analysis_qp`
+4. `prop_analysis` -> `+build_prop_analysis_qp`
+
+Builder-supported model routing is:
+1. Search existing reports/dashboards if `QUERY_EXISTING_FIRST` applies.
+2. If no existing asset is used, read the matching builder reference.
+3. Call the matching builder with complete required parameters.
+4. Call `query_adhoc` only when builder returns `status=generated`.
+
+Do not insert metadata/schema calls between steps 2 and 3 for builder-supported models. Specifically, do not call `get_analysis_query_schema`, `list_events`, `list_properties`, `list_metrics`, `get_metric`, or `get_report_definition` to prepare the builder payload. The builder resolves event/property/metric metadata internally and returns `need_clarification` when it cannot.
+
+Event metric shortcut:
+- If the user asks to query a saved/business metric through event analysis, pass the metric name/display name/remark directly as an event metric target: `--metrics '[{"event":"<metric name>"}]'`.
+- Do not call `analysis_meta +list_metrics` or `analysis_meta +get_metric` first just to expand the metric definition.
+- If the user provides an explicit formula, pass the formula and dependencies to `+build_event_analysis_qp`; do not convert it by reading schema or metric metadata first.
+
+Metric result vs metric metadata:
+- "Query metric result/value/trend over a time range" is an ad-hoc analysis request. Use report/dashboard search first when applicable, then builder -> `query_adhoc`.
+- "Inspect/search/update/create metric definition" is metadata/governance. Only then use `analysis_meta +list_metrics`, `+get_metric`, `+create_metric`, or `+update_metric`.
+
+For all other `query_adhoc` model types (`distribution`, `attribution`, `heat_map`, `interval`, `path`, `rank_list`, `sql`), QP builder is not supported. Use the legacy path: read `query_adhoc.md`, fetch schema/metadata as required, then construct QP manually according to the relevant schema.
+
+Execution rule:
+- If builder result `status=generated`, call `+query_adhoc` with the same `model_type` and the returned `qp`.
+- If builder returns non-generated status (`need_clarification`, `invalid_argument`, `unsupported_feature`, `validation_error`), stop and ask the user for clarification instead of calling `query_adhoc`.
+- Never bypass a failed builder by manually assembling QP for `event`, `retention`, `funnel`, or `prop_analysis`.
+
+Builder payload rules:
+- Before composing any builder JSON, read the matching builder reference doc. The builder references contain the required JSON shape and model-specific field differences.
+- CLI flag names use snake_case, but nested JSON keys use the service DTO field names in camelCase. Correct: `startTime`, `endTime`, `relationEventPropertyName`, `eventPropertyName`. Wrong: `start_date`, `start_time`, `relation_property`, `fieldName`.
+- Builder dry-run still requires the normal required flags. Do not run builder dry-run by itself.
+- Do not pass placeholder `{}` or `[]` for required nested structures except when intentionally checking CLI validation. Fill required inner fields before calling the command.
+- Use enum values exactly as documented. Examples: `mode=start_to_yesterday`, `operator=exists`, `relation=or`, `field.type=event_property`.
+- For `exists`, `not_exists`, `is_true`, and `is_false`, omit `values`. For `between`, provide exactly two values. For other value-based operators, provide a non-empty `values` array.
+- Builder tools do not execute the query and do not take `zone_offset`. Pass time zone to `+query_adhoc` with `--zone_offset` after the builder returns `status=generated`.
+- If the user's request lacks a required business element such as time range, event, metric, funnel window, property, or relation field, stop and ask for clarification. If the request supplies a name but it may be a metadata ambiguity, call the builder and let it return candidates. Do not invent names or handcraft QP.
+
+Supported builder chain:
+1. Read the builder reference for the target model.
+2. Build structured JSON from the user's request. Use user-provided event/property/metric names as-is; do not pre-query metadata for these names.
+3. Run the matching `+build_*_analysis_qp` command.
+4. If `status=generated`, call `+query_adhoc --model_type <same_model> --qp '<response.qp>'`.
+5. If status is not `generated`, report the structured error or ask the user for the missing information; do not continue to `query_adhoc`.
+
+Legacy query_adhoc chain:
+1. Use only for `distribution`, `attribution`, `heat_map`, `interval`, `path`, `rank_list`, or `sql`.
+2. Read `references/query_adhoc.md` and required schema/metadata references.
+3. Build QP manually from the documented schema and verified project metadata.
+4. Call `+query_adhoc`.
+
+## Tool Groups (73)
 
-### analysis (31)
+### analysis (35)
 
 Alerts (5):
 - `+get_alert_definition_schema` ([doc](references/get_alert_definition_schema.md))
@@ -193,7 +221,11 @@ Reports and Dashboards (13):
 - `+create_public_access_link` ([doc](references/create_public_access_link.md))
 - `+update_public_access_link` ([doc](references/update_public_access_link.md))
 
-Model Analysis (6):
+Model Analysis (10):
+- `+build_event_analysis_qp` ([doc](references/build_event_analysis_qp.md))
+- `+build_retention_analysis_qp` ([doc](references/build_retention_analysis_qp.md))
+- `+build_funnel_analysis_qp` ([doc](references/build_funnel_analysis_qp.md))
+- `+build_prop_analysis_qp` ([doc](references/build_prop_analysis_qp.md))
 - `+query_adhoc` ([doc](references/query_adhoc.md))
 - `+drilldown_users` ([doc](references/drilldown_users.md))
 - `+drilldown_user_events` ([doc](references/drilldown_user_events.md))
@@ -284,4 +316,4 @@ npm run verify:analysis-common-tools
 
 ## Reference Docs
 
-See the unified `references/` directory (69 command docs total).
+See the unified `references/` directory (73 command docs total).