@ema.co/mcp-toolkit 2026.3.25-4 → 2026.4.9-1

package/dist/auth/credentials.js

@@ -125,5 +125,8 @@ export function extractTokenMetadata(token) {
             : typeof payload.user_id === "string"
                 ? payload.user_id
                 : undefined,
+        issuer: typeof payload.iss === "string"
+            ? payload.iss
+            : undefined,
     };
 }

package/dist/auth/login.js

@@ -38,7 +38,7 @@ const WELL_KNOWN_APP_URLS = {
 function resolveApiUrl(envName, explicit) {
     if (explicit)
         return explicit.replace(/\/$/, "");
-    return WELL_KNOWN_API_URLS[envName] ?? WELL_KNOWN_API_URLS.prod;
+    return WELL_KNOWN_API_URLS[envName] ?? `https://api.${envName}.ema.co`;
 }
 function resolveAppUrl(envName, explicit) {
     if (explicit)

package/dist/config/profile.js

@@ -23,7 +23,7 @@ export function slugify(name) {
         .replace(/^-|-$/g, "");
 }
 export function profileName(tenantSlug, env) {
-    return `${tenantSlug}-${env}`;
+    return `${tenantSlug}-${slugify(env)}`;
 }
 export function displayName(tenantName, env, store) {
     const sameTenantCount = Object.values(store.profiles).filter((p) => p.tenant.name === tenantName).length;
@@ -227,6 +227,18 @@ export function resolveProfile(nameOrAlias, dir) {
     // 3. No match in config.json
     return null;
 }
+/** Smart color default based on environment name. */
+export function defaultColorForEnv(envName) {
+    if (envName === "prod")
+        return "red";
+    if (envName === "staging")
+        return "yellow";
+    if (envName === "dev")
+        return "cyan";
+    if (envName === "demo")
+        return "green";
+    return "blue";
+}
 /**
  * Get the active profile with display info and auth status.
  * Returns null if no config or no current profile is set.
@@ -299,6 +311,9 @@ export function getActiveProfile(dir) {
         tenant: profile.tenant.name,
         tenant_id: profile.tenant.id,
         env: profile.environment.name,
+        base_url: profile.environment.url,
+        ...(profile.environment.app_url ? { app_url: profile.environment.app_url } : {}),
+        color: profile.color ?? defaultColorForEnv(profile.environment.name),
         knowledge_scopes: knowledgeScopes,
         auth_expires_in: authExpiresIn,
         knowledge_search_available: searchAvailable,

package/dist/config/tool-guidance.js

@@ -15,12 +15,18 @@ export const TOOL_GUIDANCE = {
         operations: [
             { name: "Status", description: "Show current profile, auth status, GCP auth", example: "config()" },
             { name: "Login", description: "Authenticate via browser OAuth", example: 'config(method="login")' },
-            { name: "Login (token)", description: "Agent-mediated login — user pastes JWT in chat", example: 'config(method="login", token="eyJ...")' },
+            { name: "Login (token)", description: "Agent-mediated login — env auto-detected from JWT tenant_id or issuer", example: 'config(method="login", token="eyJ...")' },
             { name: "GCP login", description: "Standalone Google auth for knowledge search", example: 'config(method="gcp_login")' },
             { name: "GCP login (token)", description: "Agent-mediated GCP auth — user pastes token in chat", example: 'config(method="gcp_login", gcp_token="ya29...")' },
             { name: "Switch profile", description: "Switch active profile", example: 'config(method="use", profile="acme-corp-prod")' },
             { name: "List profiles", description: "List all profiles with auth status", example: 'config(method="profiles")' },
             { name: "Set default env", description: "Set default login environment", example: 'config(method="set", key="default_env", value="prod")' },
+            { name: "Login (custom URL)", description: "Login to custom tenant environment (e.g. sub-tenant staging)", example: 'config(method="login", app_url="https://staging.acme.ema.co")' },
+            { name: "Login (custom + API URL)", description: "Login with explicit API URL override", example: 'config(method="login", app_url="https://staging.acme.ema.co", api_url="https://api.staging.acme.ema.co")' },
+            { name: "Set API URL", description: "Update current profile's API endpoint", example: 'config(method="set", key="api_url", value="https://api.custom.ema.co")' },
+            { name: "Set app URL", description: "Update current profile's frontend URL", example: 'config(method="set", key="app_url", value="https://custom.ema.co")' },
+            { name: "Login (non-ema.co)", description: "Custom domain login (api_url required for non-ema.co)", example: 'config(method="login", app_url="https://ai.acme.com", api_url="https://api.acme.com")' },
+            { name: "Set profile color", description: "Set visual color for active profile (agent applies to IDE)", example: 'config(method="set", key="color", value="red")' },
         ],
         nextSteps: {
             status: "If auth is missing or expired, run login. If GCP auth is missing, run gcp_login. Both are required.",
@@ -115,7 +121,7 @@ export const TOOL_GUIDANCE = {
             },
             {
                 name: "Get AI answer",
-                description: "AI-generated summary with citations",
+                description: "AI-generated summary with citations. Response includes _warning about fabrication risk and _next_step for verification.",
                 example: 'knowledge("how to add HITL", detail="answer")',
             },
             {
@@ -176,13 +182,13 @@ export const TOOL_GUIDANCE = {
         operations: [
             { name: "Get", description: "Fetch current workflow_def + generation schema", example: 'workflow(mode="get", persona_id="...")' },
             { name: "Get (slim)", description: "Fetch slimmed workflow_def for large workflows (strips displaySettings, truncates long values, ~60-70% smaller)", example: 'workflow(mode="get", persona_id="...", slim=true)' },
-            { name: "Deploy", description: "Deploy LLM-generated workflow_def", example: 'workflow(mode="deploy", persona_id="...", workflow_def={...})' },
+            { name: "Deploy", description: "Deploy LLM-generated workflow_def. Deploy outcomes automatically feed knowledge quality — failures demote consulted docs. Test with conversation() after deploy to validate intent alignment.", example: 'workflow(mode="deploy", persona_id="...", workflow_def={...})' },
             { name: "Validate", description: "Static validation with path enumeration", example: 'workflow(mode="validate", persona_id="...")' },
             { name: "Optimize", description: "Structural graph optimization", example: 'workflow(mode="optimize", persona_id="...")' },
         ],
         nextSteps: {
             get: "Build a workflow_def based on the generation_schema and deploy it.",
-            deploy: "Verify deployment: workflow(mode='get', persona_id='...')",
+            deploy: "Test with conversation() to validate intent alignment. Deploy success only means the API accepted it — conversation testing validates the persona actually works.",
             validate: "Fix any reported issues, then deploy.",
             optimize: "Review optimized workflow_def, then deploy if acceptable.",
         },

package/dist/knowledge/extractors/openapi-endpoints.js

@@ -1,3 +1,139 @@
+const MAX_RESOLVE_DEPTH = 6;
+/** Resolve a $ref string like "#/components/schemas/Foo" against the spec */
+function resolveRef(ref, spec) {
+    const parts = ref.replace(/^#\//, "").split("/");
+    let current = spec;
+    for (const part of parts) {
+        if (typeof current !== "object" || !current)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/** Get a human-readable type string for a schema node */
+function schemaTypeString(node, spec, visited, depth) {
+    if (node.$ref) {
+        const refName = node.$ref.split("/").pop() ?? "object";
+        if (visited.has(node.$ref) || depth >= MAX_RESOLVE_DEPTH)
+            return refName;
+        const resolved = resolveRef(node.$ref, spec);
+        if (!resolved)
+            return refName;
+        return schemaTypeString(resolved, spec, new Set([...visited, node.$ref]), depth + 1);
+    }
+    if (node.enum)
+        return `enum(${node.enum.join("|")})`;
+    if (node.anyOf) {
+        const types = node.anyOf
+            .filter((s) => s.type !== "null")
+            .map((s) => schemaTypeString(s, spec, visited, depth + 1));
+        const hasNull = node.anyOf.some((s) => s.type === "null");
+        const base = types.length === 1 ? types[0] : `(${types.join(" | ")})`;
+        return hasNull ? `${base} | null` : base;
+    }
+    if (node.allOf) {
+        return node.allOf.map((s) => schemaTypeString(s, spec, visited, depth + 1)).join(" & ");
+    }
+    if (node.type === "array" && node.items) {
+        return `${schemaTypeString(node.items, spec, visited, depth + 1)}[]`;
+    }
+    if (node.format)
+        return `${node.type ?? "string"}(${node.format})`;
+    return node.type ?? "object";
+}
+/** Resolve a schema to a flat list of fields (one level deep, with type strings) */
+function resolveSchemaFields(schema, spec, visited = new Set(), depth = 0) {
+    if (depth >= MAX_RESOLVE_DEPTH)
+        return [];
+    // Follow $ref
+    if (schema.$ref) {
+        if (visited.has(schema.$ref))
+            return [{ name: "(circular)", type: schema.$ref.split("/").pop() ?? "object", required: false }];
+        const resolved = resolveRef(schema.$ref, spec);
+        if (!resolved)
+            return [];
+        return resolveSchemaFields(resolved, spec, new Set([...visited, schema.$ref]), depth + 1);
+    }
+    // Merge allOf — deduplicate by field name (last-wins, matching JSON Schema merge semantics)
+    if (schema.allOf) {
+        const merged = schema.allOf.flatMap((s) => resolveSchemaFields(s, spec, visited, depth + 1));
+        const seen = new Map();
+        for (const f of merged)
+            seen.set(f.name, f);
+        return [...seen.values()];
+    }
+    // Handle top-level anyOf (e.g., discriminator unions)
+    if (schema.anyOf) {
+        const nonNull = schema.anyOf.filter((s) => s.type !== "null");
+        return nonNull.flatMap((s) => resolveSchemaFields(s, spec, visited, depth + 1));
+    }
+    // Object with properties
+    if (schema.properties) {
+        const required = new Set(schema.required ?? []);
+        return Object.entries(schema.properties).map(([name, prop]) => ({
+            name,
+            type: schemaTypeString(prop, spec, visited, depth + 1),
+            required: required.has(name),
+            description: prop.description,
+        }));
+    }
+    return [];
+}
+/** Format resolved fields as a readable markdown-style block */
+function formatFields(fields) {
+    if (fields.length === 0)
+        return "";
+    return fields
+        .map((f) => {
+        const req = f.required ? " (required)" : "";
+        const desc = f.description ? ` — ${f.description}` : "";
+        return `  - ${f.name}: ${f.type}${req}${desc}`;
+    })
+        .join("\n");
+}
+function buildRequestBodySection(op, spec) {
+    if (!op.requestBody?.content)
+        return "";
+    const lines = ["", "Request Body:"];
+    if (op.requestBody.description)
+        lines.push(`  ${op.requestBody.description}`);
+    if (op.requestBody.required)
+        lines.push("  (required)");
+    for (const [contentType, media] of Object.entries(op.requestBody.content)) {
+        lines.push(`  Content-Type: ${contentType}`);
+        if (media.schema) {
+            const fields = resolveSchemaFields(media.schema, spec);
+            if (fields.length > 0) {
+                lines.push("  Fields:");
+                lines.push(formatFields(fields));
+            }
+        }
+    }
+    return lines.join("\n");
+}
+function buildResponsesSection(op, spec) {
+    if (!op.responses)
+        return "";
+    const lines = ["", "Responses:"];
+    for (const [statusCode, response] of Object.entries(op.responses)) {
+        lines.push(`  ${statusCode}: ${response.description ?? ""}`);
+        if (response.content) {
+            for (const [contentType, media] of Object.entries(response.content)) {
+                if (media.schema) {
+                    const fields = resolveSchemaFields(media.schema, spec);
+                    if (fields.length > 0) {
+                        lines.push(`    ${contentType}:`);
+                        lines.push(formatFields(fields));
+                    }
+                }
+            }
+        }
+    }
+    return lines.join("\n");
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Main extractor
+// ─────────────────────────────────────────────────────────────────────────────
 export async function extractOpenAPIEndpoints(config) {
     const specPath = config.from ?? "src/sdk/generated/openapi.json";
     const { createRequire } = await import("node:module");
@@ -7,22 +143,39 @@ export async function extractOpenAPIEndpoints(config) {
         const fullPath = resolve(process.cwd(), specPath);
         const spec = require(fullPath);
         const docs = [];
-        const paths = spec.paths ?? {};
+        const paths = (spec.paths ?? {});
+        let schemasResolved = 0;
+        const HTTP_METHODS = new Set(["get", "put", "post", "delete", "options", "head", "patch", "trace"]);
         for (const [path, methods] of Object.entries(paths)) {
             for (const [method, op] of Object.entries(methods)) {
+                if (!HTTP_METHODS.has(method))
+                    continue;
                 if (typeof op !== "object" || !op)
                     continue;
                 const operation = op;
                 const opId = operation.operationId ?? `${method}_${path.replace(/\//g, "_")}`;
+                // Build rich content with resolved schemas
                 const content = [
                     `${method.toUpperCase()} ${path}`,
                     operation.summary ?? "",
                     operation.description ?? "",
                     operation.tags?.length ? `Tags: ${operation.tags.join(", ")}` : "",
+                    // Parameters with descriptions
                     operation.parameters?.length
-                        ? `Parameters: ${operation.parameters.map((p) => `${p.name} (${p.in}${p.required ? ", required" : ""})`).join(", ")}`
+                        ? `Parameters:\n${operation.parameters.map((p) => {
+                            const typeStr = p.schema ? schemaTypeString(p.schema, spec, new Set(), 0) : "";
+                            const desc = p.description ? ` — ${p.description}` : "";
+                            return `  - ${p.name} (${p.in}${p.required ? ", required" : ""}${typeStr ? `: ${typeStr}` : ""})${desc}`;
+                        }).join("\n")}`
                         : "",
+                    // Request body with resolved schema fields
+                    buildRequestBodySection(operation, spec),
+                    // Response bodies with resolved schema fields
+                    buildResponsesSection(operation, spec),
                 ].filter(Boolean).join("\n");
+                // Track schema resolution metrics
+                if (operation.requestBody?.content || operation.responses)
+                    schemasResolved++;
                 docs.push({
                     id: `endpoint:${opId}`,
                     structData: {
@@ -49,10 +202,15 @@ export async function extractOpenAPIEndpoints(config) {
                         source_path: specPath,
                         http_method: method.toUpperCase(),
                         http_path: path,
+                        protocol: "rest",
+                        visibility: "external",
+                        has_request_schema: !!operation.requestBody?.content,
+                        has_response_schema: !!operation.responses,
                     },
                 });
             }
         }
+        process.stderr.write(`  OpenAPI: ${docs.length} endpoints, ${schemasResolved} with resolved schemas\n`);
         return { documents: docs, edges: [] };
     }
     catch (err) {

package/dist/knowledge/guidance-cache.js

@@ -212,7 +212,8 @@ export class GuidanceCache {
                     case "structural-invariant":
                         this.invariants.push(data);
                         break;
-                    case "contextual-guidance": {
+                    case "contextual-guidance":
+                    case "guide": {
                         const atom = data;
                         const key = atom.key
                             ?? `${atom.tool ?? "*"}.${atom.method ?? "*"}.${atom.result_shape ?? "*"}`;
@@ -244,10 +245,10 @@ export class GuidanceCache {
             return "qualifying-question";
         if (tags.includes("structural-invariant"))
             return "structural-invariant";
-        if (tags.includes("structural-invariant"))
-            return "structural-invariant";
         if (tags.includes("contextual-guidance"))
             return "contextual-guidance";
+        if (tags.includes("guide"))
+            return "guide";
         if (name.includes("tool-guidance"))
             return "tool-guidance";
         if (name.startsWith("invariant-"))

package/dist/knowledge/search-client.js

@@ -29,9 +29,11 @@ import { getActiveScopes } from "./scopes.js";
  */
 const PROMOTED_FIELDS = new Set([
     // Promoted to top-level fields in search results
-    "id", "name", "summary", "description", "type", "doc_type", "scope",
-    "source", "status", "confidence", "confidence_score",
-    "provenance", "tags", "tier", "severity", "category", "when_to_use",
+    "id", "name", "description", "summary", "type", "doc_type", "scope", "scopes",
+    "source", "sources", "status",
+    // Legacy v2 fields (still on ~829 MCP-extracted docs)
+    "confidence", "confidence_score", "provenance", "tags",
+    "tier", "severity", "category", "when_to_use",
     "domain", "audience", "source_repo",
     // Heavy text — already in content.rawBytes, not needed in results
     "content",
@@ -121,22 +123,32 @@ export async function ensureGcpAuth() {
 // ─────────────────────────────────────────────────────────────────────────────
 // Filter building — dynamic scope filters (DE static controls can't vary per-query)
 // ─────────────────────────────────────────────────────────────────────────────
-const FILTERABLE_KEYS = new Set(["type", "source", "tier", "severity", "category", "tags", "scope", "envs", "status", "doc_type", "provenance", "domain"]);
+// v3 structData: name, description, scopes (array), audience (array), source, sources, status, signals.
+// Documents have a mix of scope (singular string), scopes (plural array), and audience (v3).
+// Filter must OR across all three to catch all docs.
+// source for provenance, status for lifecycle.
+const FILTERABLE_KEYS = new Set(["scope", "scopes", "audience", "source", "status"]);
 function buildFilterExpression(filters, elevate) {
     const parts = [];
-    // Scope filter: use active scopes from profile/env (never hardcode "internal").
-    // elevate=true removes the scope filter entirely (e.g., for admin access).
-    // Callers can pass explicit scope filters to override.
+    // Documents have a mix of field names: scope (singular), scopes (plural array), audience (v3).
+    // OR across all three to catch every doc regardless of which field it uses.
+    // elevate=true removes scope filter (admin access).
     const hasExplicitScope = filters?.scope && filters.scope.length > 0;
     if (!elevate && !hasExplicitScope) {
         const scopes = getActiveScopes();
         const quoted = scopes.map((s) => `"${s}"`).join(",");
-        parts.push(`scope: ANY(${quoted})`);
+        parts.push(`(scope: ANY(${quoted}) OR scopes: ANY(${quoted}) OR audience: ANY(${quoted}))`);
     }
     if (filters) {
         for (const [key, values] of Object.entries(filters)) {
             if (!values || values.length === 0)
                 continue;
+            // Map caller's "scope" to all three field variants (OR)
+            if (key === "scope") {
+                const quoted = values.map((v) => `"${v}"`).join(",");
+                parts.push(`(scope: ANY(${quoted}) OR scopes: ANY(${quoted}) OR audience: ANY(${quoted}))`);
+                continue;
+            }
             if (!FILTERABLE_KEYS.has(key))
                 continue;
             const quoted = values.map((v) => `"${v}"`).join(",");
@@ -168,13 +180,30 @@ const QUERY_SIGNALS = [
 // ─────────────────────────────────────────────────────────────────────────────
 // Dynamic Preamble — context-aware system instructions for :answer endpoint
 // ─────────────────────────────────────────────────────────────────────────────
-/** Base preamble applied to all answer queries. */
+/**
+ * Base preamble applied to all answer queries.
+ *
+ * The Ema-specific context line applies to the primary use case (Ema platform knowledge).
+ * The code-accuracy rules are domain-agnostic and apply to ANY knowledge corpus that
+ * contains code examples, API formats, or structured data — they prevent the generative
+ * model from fabricating structures that look plausible but are wrong.
+ */
 const BASE_PREAMBLE = [
+    // Domain context (Ema-specific — other corpora would swap this line)
     "You are answering questions about the Ema AI Employee platform — a workflow orchestration system.",
-    "When referencing actions or nodes, use their exact actionType names (e.g., chat_categorizer, respond_with_sources).",
-    "When showing fixes, include concrete workflow_def JSON snippets when available in the source documents.",
+    "When referencing actions or nodes, use their exact names (e.g., chat_categorizer, respond_with_sources).",
+    // Code accuracy (domain-agnostic — applies to any technical corpus)
+    "CRITICAL — code accuracy rules:",
+    "1. NEVER assemble, fabricate, or synthesize complete code examples (JSON, YAML, config). The risk of structural errors is too high.",
+    "2. For code formats: REFERENCE the source document by name/ID and tell the user to fetch it directly. Example: 'See schema/workflow-def for the complete deployable example.'",
+    "3. You MAY quote SHORT code fragments (under 5 lines) verbatim from source documents with attribution.",
+    "4. You MAY describe the structure in words (e.g., 'actions is an array of objects, each with name, action, and inputs').",
+    "5. For canonical formats, direct users to the authoritative source rather than reproducing it.",
     "Cite specific document IDs when available.",
-].join(" ");
+    // Contextual guidance (extracted into structured fields by the handler)
+    "When documents have 'when_to_use' guidance, consider it when selecting which sources to cite — prefer documents whose when_to_use matches the query context.",
+    "Include relevant tips, hints, or next steps naturally within your answer based on the context and cited documents. Reference specific document IDs the reader can fetch for full details.",
+].join("\n");
 /** Query-pattern-specific preamble additions. */
 const PREAMBLE_SIGNALS = [
     {
@@ -183,7 +212,7 @@ const PREAMBLE_SIGNALS = [
     },
     {
         pattern: /\b(how to|how do|pattern|example|wire|connect|build)\b/i,
-        addition: "Provide step-by-step instructions with workflow_def JSON examples where available.",
+        addition: "Provide step-by-step instructions. For complete code examples, reference the source document (e.g., 'see schema/workflow-def for the deployable example') rather than reproducing it. The agent will fetch the document directly.",
     },
     {
         pattern: /\b(rule|constraint|invariant|must|require|validate)\b/i,
@@ -246,25 +275,15 @@ function transformDeResponse(deResponse, mode) {
             document: {
                 id: (structData.id ?? doc.id ?? ""),
                 name: (structData.name ?? ""),
+                // v3: description is the summary. Fall back to v2 fields for legacy docs.
                 type: (structData.type ?? structData.doc_type ?? ""),
                 scope: (structData.scope ?? "public"),
                 source: (structData.source ?? ""),
-                summary: (structData.summary ?? ""),
-                confidence_score: (structData.confidence_score ?? 0),
+                summary: (structData.description ?? structData.summary ?? ""),
                 status: (structData.status ?? "active"),
-                // Optional fields — omit when empty to save tokens
-                ...(structData.description ? { description: structData.description } : {}),
-                ...(structData.confidence ? { confidence: structData.confidence } : {}),
-                ...(structData.category ? { category: structData.category } : {}),
-                ...(structData.when_to_use ? { when_to_use: structData.when_to_use } : {}),
-                ...(structData.tier ? { tier: structData.tier } : {}),
-                ...(structData.severity ? { severity: structData.severity } : {}),
-                ...(structData.provenance ? { provenance: structData.provenance } : {}),
-                ...(Array.isArray(structData.tags) ? { tags: structData.tags } : {}),
-                // Domain isolation + audience targeting
-                ...(structData.domain ? { domain: structData.domain } : {}),
-                ...(Array.isArray(structData.audience) ? { audience: structData.audience } : {}),
-                ...(structData.source_repo ? { source_repo: structData.source_repo } : {}),
+                // v3 fields
+                ...(Array.isArray(structData.scopes) ? { scopes: structData.scopes } : {}),
+                ...(Array.isArray(structData.sources) ? { sources: structData.sources } : {}),
                 // Non-promoted metadata only (no duplication)
                 structData: stripPromotedFields(structData),
             },
@@ -478,22 +497,12 @@ async function searchDirect(query, options) {
     // Dynamic domain boost — if query signals a specific platform, boost its domain
     // and demote the other. DE serves both platforms; this keeps results focused.
     const queryBoost = buildQueryBoostSpec(query, filters);
-    // Confidence boost — always applied. Verified docs rank higher, low-confidence lower.
-    // This makes the feedback loop visible at search time: downgraded docs get demoted
-    // regardless of relevance. DE boost values are additive to relevance score.
-    // Values calibrated against signal viewer: semantic relevance spreads 0.07-0.99,
-    // so boosts must be large enough to move docs across that range.
-    const confidenceBoosts = [
-        { condition: 'confidence: ANY("verified")', boost: 0.5 },
-        { condition: 'confidence: ANY("inferred")', boost: -0.2 },
-        { condition: 'confidence: ANY("low-confidence")', boost: -0.8 },
-    ];
+    // v3: confidence removed from structData. DE text matching handles relevance.
+    // Query-specific boosts (domain targeting) still apply.
     const querySpecs = (queryBoost?.conditionBoostSpecs ?? []);
-    const allBoosts = [
-        ...querySpecs,
-        ...confidenceBoosts,
-    ];
-    body.boostSpec = { conditionBoostSpecs: allBoosts };
+    if (querySpecs.length > 0) {
+        body.boostSpec = { conditionBoostSpecs: querySpecs };
+    }
     // Always request snippets — works with chunked datastores.
     // (Extractive answers do NOT work with chunking, only snippets.)
     // For answer mode, also request summary with citations.
@@ -653,6 +662,8 @@ export async function browseDocuments(options = {}) {
 // ─────────────────────────────────────────────────────────────────────────────
 // User Event Tracking
 // ─────────────────────────────────────────────────────────────────────────────
+/** Counters for UserEvent pipeline health — exposed via feedback(method="analyze"). */
+export const userEventCounters = { sent: 0, failed: 0 };
 export async function writeUserEvent(event) {
     if (!isVertexEventsEnabled())
         return;
@@ -661,15 +672,24 @@ export async function writeUserEvent(event) {
     if (!headers)
         return;
     try {
-        await fetch(`${de.baseUrl}/${de.datastorePath}/userEvents:write`, {
+        const resp = await fetch(`${de.baseUrl}/${de.datastorePath}/userEvents:write`, {
             method: "POST",
             headers,
             body: JSON.stringify(event),
             signal: AbortSignal.timeout(5_000),
         });
+        if (!resp.ok) {
+            userEventCounters.failed++;
+            const detail = await resp.text().catch(() => "");
+            console.error(`[SEARCH-CLIENT] UserEvent write failed: ${resp.status} — ${detail.slice(0, 200)}`);
+        }
+        else {
+            userEventCounters.sent++;
+        }
     }
     catch {
-        // Fire-and-forget
+        userEventCounters.failed++;
+        // Fire-and-forget — timeout or network error
     }
 }
 /**
@@ -925,7 +945,12 @@ export async function gcsFallbackSearch(query, options = {}) {
             return false;
         }
         // Apply scope filter (matches DE behavior — default to active scopes)
-        if (!activeScopes.includes(doc.scope ?? "public")) {
+        // Check both scope (legacy) and audience (v3) fields
+        const docScope = doc.scope ?? "public";
+        const docAudience = "audience" in doc ? doc.audience : undefined;
+        const scopeMatch = activeScopes.includes(docScope);
+        const audienceMatch = docAudience?.some(a => activeScopes.includes(a)) ?? false;
+        if (!scopeMatch && !audienceMatch) {
             return false;
         }
         return true;

package/dist/knowledge/search-config.js

@@ -38,8 +38,9 @@ export function getSearchBackend() {
 export function isDiscoveryEngineEnabled() {
     return getSearchBackend() === "discovery-engine";
 }
+/** UserEvent tracking is ON by default. Set EMA_VERTEX_EVENTS=false to opt out. */
 export function isVertexEventsEnabled() {
-    return process.env.EMA_VERTEX_EVENTS?.trim().toLowerCase() === "true";
+    return process.env.EMA_VERTEX_EVENTS?.trim().toLowerCase() !== "false";
 }
 export function getDeConfig() {
     const project = process.env.EMA_GCP_PROJECT?.trim() || DEFAULT_PROJECT;