@ema.co/mcp-toolkit 2026.3.29-1 → 2026.4.9

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;

package/dist/config/tool-guidance.js

@@ -21,6 +21,10 @@ export const TOOL_GUIDANCE = {
             { 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")' },
         ],
         nextSteps: {
             status: "If auth is missing or expired, run login. If GCP auth is missing, run gcp_login. Both are required.",
@@ -115,7 +119,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")',
             },
             {

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,26 +123,29 @@ 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), source, sources, status, signals.
+// scopes for access filtering, source for provenance, status for lifecycle.
+const FILTERABLE_KEYS = new Set(["scopes", "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.
+    // Scope filter on scopes (array field). DE ANY() matches array elements.
+    // 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(`scopes: ANY(${quoted})`);
     }
     if (filters) {
         for (const [key, values] of Object.entries(filters)) {
             if (!values || values.length === 0)
                 continue;
-            if (!FILTERABLE_KEYS.has(key))
+            // Map caller's "scope" to v3's "scopes" field name
+            const deField = key === "scope" ? "scopes" : key;
+            if (!FILTERABLE_KEYS.has(deField))
                 continue;
             const quoted = values.map((v) => `"${v}"`).join(",");
-            parts.push(`${key}: ANY(${quoted})`);
+            parts.push(`${deField}: ANY(${quoted})`);
         }
     }
     return parts.join(" AND ");
@@ -168,13 +173,27 @@ 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(" ");
+].join("\n");
 /** Query-pattern-specific preamble additions. */
 const PREAMBLE_SIGNALS = [
     {
@@ -183,7 +202,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 +265,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 +487,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.

package/dist/mcp/handlers/config/index.js

@@ -7,6 +7,57 @@
 import { loadConfig, saveConfig, addProfile, removeProfile, setCurrentProfile, listProfiles, getActiveProfile, slugify, profileName, } from "../../../config/profile.js";
 import { invalidateEnvCache } from "../env/config.js";
 import { tryGcloudAuth } from "../../../auth/gcloud.js";
+/**
+ * Derive API URL, app URL, and environment name from a custom app URL.
+ * Supports any `*.ema.co` hostname. Returns null for non-ema.co domains.
+ */
+function deriveFromAppUrl(appUrl) {
+    try {
+        const url = new URL(appUrl.includes("://") ? appUrl : `https://${appUrl}`);
+        const hostname = url.hostname;
+        // Match *.ema.co pattern
+        const match = hostname.match(/^(.+)\.ema\.co$/);
+        if (!match)
+            return null;
+        const subdomain = match[1]; // e.g., "staging.acme", "app", "demo"
+        // Well-known frontends map to standard envs
+        if (subdomain === "app") {
+            return { apiUrl: "https://api.ema.co", appUrl: "https://app.ema.co", envName: "prod" };
+        }
+        if (["demo", "staging", "dev"].includes(subdomain)) {
+            return {
+                apiUrl: `https://api.${subdomain}.ema.co`,
+                appUrl: `https://${subdomain}.ema.co`,
+                envName: subdomain,
+            };
+        }
+        // Custom subdomain: derive API URL by prepending "api."
+        return {
+            apiUrl: `https://api.${subdomain}.ema.co`,
+            appUrl: `https://${subdomain}.ema.co`,
+            envName: subdomain,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Probe an API URL to check reachability. Returns true if the endpoint
+ * responds (even with 401/403 — means it's reachable but auth-gated).
+ */
+async function probeApiUrl(apiUrl) {
+    try {
+        const resp = await fetch(`${apiUrl.replace(/\/$/, "")}/api/health`, {
+            method: "HEAD",
+            signal: AbortSignal.timeout(5000),
+        });
+        return resp.ok || resp.status === 401 || resp.status === 403;
+    }
+    catch {
+        return false;
+    }
+}
 export async function handleConfig(args) {
     const method = args.method;
     switch (method) {
@@ -161,14 +212,56 @@ async function handleStatus() {
 // Login
 // ─────────────────────────────────────────────────────────────────────────────
 async function handleLogin(args) {
-    // Use explicit env > preference default_env > "prod"
-    const envName = args.env || loadConfig().preferences.default_env || "prod";
+    const customAppUrl = args.app_url;
+    const customApiUrl = args.api_url;
     const tenantHint = args.tenant;
     const directToken = args.token;
+    // Resolve URLs and env name from custom app_url or standard env
+    let envName;
+    let resolvedApiUrl;
+    let resolvedAppUrl;
+    let probeWarning;
+    if (customAppUrl) {
+        const derived = deriveFromAppUrl(customAppUrl);
+        if (derived) {
+            envName = args.env || derived.envName;
+            resolvedApiUrl = customApiUrl?.replace(/\/$/, "") ?? derived.apiUrl;
+            resolvedAppUrl = derived.appUrl;
+        }
+        else {
+            // Non-ema.co domain — derive env from hostname, require api_url if not provided
+            const parsed = new URL(customAppUrl.includes("://") ? customAppUrl : `https://${customAppUrl}`);
+            envName = args.env || slugify(parsed.hostname.split(".")[0]);
+            resolvedAppUrl = `${parsed.protocol}//${parsed.host}`;
+            if (customApiUrl) {
+                resolvedApiUrl = customApiUrl.replace(/\/$/, "");
+            }
+            else {
+                // Best guess: api.{hostname}
+                resolvedApiUrl = `${parsed.protocol}//api.${parsed.host}`;
+            }
+        }
+        // Probe the API URL — warn but don't block if unreachable
+        const reachable = await probeApiUrl(resolvedApiUrl);
+        if (!reachable) {
+            probeWarning =
+                `Derived API URL (${resolvedApiUrl}) did not respond. ` +
+                    `Login will proceed with this URL, but if auth fails, verify the correct API URL ` +
+                    `and retry with: config(method="login", app_url="${customAppUrl}", api_url="<correct_url>")`;
+        }
+    }
+    else {
+        // Standard flow: explicit env > preference default_env > "prod"
+        envName = args.env || loadConfig().preferences.default_env || "prod";
+        resolvedApiUrl = customApiUrl?.replace(/\/$/, "")
+            ?? (envName === "prod" ? "https://api.ema.co" : `https://api.${envName}.ema.co`);
+    }
     try {
         const { login } = await import("../../../auth/login.js");
         const result = await login({
             environment: envName,
+            baseUrl: resolvedApiUrl,
+            ...(resolvedAppUrl ? { appUrl: resolvedAppUrl } : {}),
             tenantId: tenantHint,
             token: directToken,
         });
@@ -183,7 +276,8 @@ async function handleLogin(args) {
             },
             environment: {
                 name: envName,
-                url: `https://api${envName === "prod" ? "" : `.${envName}`}.ema.co`,
+                url: resolvedApiUrl,
+                ...(resolvedAppUrl ? { app_url: resolvedAppUrl } : {}),
             },
             user: { email: result.userEmail ?? "" },
             created_at: new Date().toISOString(),
@@ -225,6 +319,7 @@ async function handleLogin(args) {
                 profile_name: profileName(slugify(t.company_name), envName),
                 active: t.tenant_id === result.tenantId,
             })),
+            ...(probeWarning ? { _warning: probeWarning } : {}),
             _tip: "Token stored. All tools will now use this profile automatically.",
             _next_step: `persona(method="list", profile="${name}")`,
         };
@@ -362,7 +457,7 @@ async function handleUse(args) {
 // ─────────────────────────────────────────────────────────────────────────────
 // Set / Get preferences
 // ─────────────────────────────────────────────────────────────────────────────
-const ALLOWED_KEYS = ["debug", "default_env", "resource_source"];
+const ALLOWED_KEYS = ["debug", "default_env", "resource_source", "api_url", "app_url"];
 async function handleSet(args) {
     const key = args.key;
     const value = args.value;
@@ -372,11 +467,14 @@ async function handleSet(args) {
             error: `Unknown preference key: ${key}. Available: ${ALLOWED_KEYS.join(", ")}`,
         };
     }
-    // Validate default_env values
+    // Validate default_env values — accept well-known envs + any env from existing profiles
     if (key === "default_env") {
-        const valid = ["prod", "staging", "dev", "demo"];
-        if (!valid.includes(value)) {
-            return { error: `Invalid default_env: ${value}. Must be one of: ${valid.join(", ")}` };
+        const config = loadConfig();
+        const wellKnown = ["prod", "staging", "dev", "demo"];
+        const profileEnvNames = Object.values(config.profiles).map(p => p.environment.name);
+        const allValid = [...new Set([...wellKnown, ...profileEnvNames])];
+        if (!allValid.includes(value)) {
+            return { error: `Invalid default_env: ${value}. Must be one of: ${allValid.join(", ")}` };
         }
     }
     // Validate resource_source values
@@ -386,6 +484,24 @@ async function handleSet(args) {
             return { error: `Invalid resource_source: ${value}. Must be one of: ${valid.join(", ")}` };
         }
     }
+    // api_url and app_url update the current profile's environment URLs
+    if (key === "api_url" || key === "app_url") {
+        const config = loadConfig();
+        const profile = config.profiles[config.current_profile];
+        if (!profile) {
+            return { error: "No active profile. Log in first.", _tip: 'config(method="login")' };
+        }
+        const previous = key === "api_url" ? profile.environment.url : profile.environment.app_url;
+        if (key === "api_url") {
+            profile.environment.url = value;
+        }
+        else {
+            profile.environment.app_url = value;
+        }
+        saveConfig(config);
+        invalidateEnvCache();
+        return { set: { key, value, previous, profile: config.current_profile } };
+    }
     const config = loadConfig();
     const previous = config.preferences[key];
     config.preferences[key] = value;

package/dist/mcp/handlers/knowledge/index.js

@@ -570,7 +570,8 @@ async function handleQuery(args) {
         if (response.generativeAnswer) {
             result.generative_answer = response.generativeAnswer;
             result.citations = response.citations;
-            result._warning = "Generative answer is AI-synthesized. Verify against source documents.";
+            result._warning = "Generative answer is AI-synthesized. Code examples may be fabricated or simplified — NEVER copy JSON without verification.";
+            result._next_step = 'Use workflow(mode="get") for canonical workflow_def format, or knowledge("schema/workflow-def", detail="excerpts") for validated examples.';
         }
         // Follow-up token for multi-turn answer conversations
         if (response.answerQueryToken) {