@infuro/cms-core 1.0.20 → 1.0.21

package/dist/index.js

@@ -2432,6 +2432,17 @@ function localStoragePlugin(config = {}) {
 }
 
 // src/plugins/llm/llm-service.ts
+function parseOpenAiEmbeddingJson(data) {
+  let embedding = data?.data?.[0]?.embedding;
+  if (!Array.isArray(embedding) && Array.isArray(data?.embedding)) {
+    embedding = data.embedding;
+  }
+  if (!Array.isArray(embedding) && Array.isArray(data?.data?.[0])) {
+    const first = data.data[0];
+    embedding = Array.isArray(first) ? first : first?.embedding;
+  }
+  return Array.isArray(embedding) ? embedding : null;
+}
 function parseHfInferenceEmbeddingBody(data) {
   if (data === null || data === void 0) return null;
   if (Array.isArray(data)) {
@@ -2453,28 +2464,59 @@ function parseHfInferenceEmbeddingBody(data) {
   }
   return null;
 }
+var FALLBACK_CHAT_MODEL_OPENAI_SHAPE = "openai/gpt-4o-mini";
+var FALLBACK_CHAT_MODEL_HUGGINGFACE = "meta-llama/Meta-Llama-3.1-8B-Instruct";
+function defaultChatModelForGateway(baseURL) {
+  const u = baseURL.toLowerCase();
+  if (u.includes("huggingface.co") || u.includes("hf.co") || u.includes("hf-inference")) {
+    return FALLBACK_CHAT_MODEL_HUGGINGFACE;
+  }
+  return FALLBACK_CHAT_MODEL_OPENAI_SHAPE;
+}
+function formatLlmGatewayError(status, bodyText, defaultChatModel) {
+  let hint = "";
+  try {
+    const j = JSON.parse(bodyText);
+    const code = j?.error?.code;
+    if (code === "model_not_supported" || code === "model_not_found" || /not supported by any provider|does not exist/i.test(j?.error?.message ?? "")) {
+      hint = ` Hint: set LLM_CHAT_MODEL (or CMS) to a model your gateway lists. HF router: Hub ids (e.g. "${FALLBACK_CHAT_MODEL_HUGGINGFACE}"); OpenRouter: e.g. "${FALLBACK_CHAT_MODEL_OPENAI_SHAPE}".`;
+    }
+  } catch {
+  }
+  return `LLM gateway error: ${status} ${bodyText}${hint}`;
+}
 var LlmService = class _LlmService {
   static embedHttpErrorLogged = false;
   static embedShapeErrorLogged = false;
   static embedSuccessLogged = false;
   static hfDimensionMismatchWarned = false;
+  static hfInferenceSdkErrorLogged = false;
   baseURL;
   apiKey;
   defaultEmbeddingModel;
   embeddingProvider;
   hfInferenceBaseURL;
   embeddingApiKey;
+  defaultChatModel;
   constructor(baseURL, apiKey, defaultEmbeddingModel, embedOpts) {
     this.baseURL = baseURL.replace(/\/$/, "");
     this.apiKey = apiKey;
     this.defaultEmbeddingModel = defaultEmbeddingModel;
     const p = (embedOpts?.embeddingProvider ?? "openai").toLowerCase();
     this.embeddingProvider = p === "huggingface" ? "huggingface" : "openai";
-    this.hfInferenceBaseURL = (embedOpts?.hfInferenceBaseUrl ?? "https://api-inference.huggingface.co").replace(
+    this.hfInferenceBaseURL = (embedOpts?.hfInferenceBaseUrl ?? "https://router.huggingface.co/v1").replace(
       /\/$/,
       ""
     );
     this.embeddingApiKey = (embedOpts?.embeddingApiKey ?? apiKey).trim();
+    const fromOpts = embedOpts?.defaultChatModel?.trim();
+    const fromEnv = typeof process !== "undefined" ? process.env.LLM_CHAT_MODEL?.trim() : "";
+    const auto = defaultChatModelForGateway(this.baseURL);
+    this.defaultChatModel = (fromOpts || fromEnv || auto).trim() || auto;
+  }
+  resolveChatModel(explicit) {
+    const m = (explicit?.trim() || this.defaultChatModel).trim();
+    return m || defaultChatModelForGateway(this.baseURL);
   }
   get base() {
     return this.baseURL.replace(/\/$/, "");
@@ -2514,7 +2556,7 @@ var LlmService = class _LlmService {
   }
   logChatCompletionsRequest(kind, messages, options, stream) {
     if (!this.llmDebugEnabled()) return;
-    const model = options.model ?? "meta-llama/Meta-Llama-3-8B-Instruct";
+    const model = this.resolveChatModel(options.model);
     console.log(`
 [LLM ${kind}] POST`, this.url);
     console.log("[Request options]", {
@@ -2532,7 +2574,12 @@ var LlmService = class _LlmService {
       return this.embedHuggingFaceInference(input, model2);
     }
     const model = options.model ?? this.defaultEmbeddingModel ?? "text-embedding-3-small";
-    const embedUrl = `${this.base}/v1/embeddings`;
+    return this.fetchOpenAiShapeEmbeddings(`${this.base}/v1/embeddings`, model, input, this.apiKey);
+  }
+  /**
+   * POST `{ url }` with OpenAI-style `{ model, input }` and Bearer token; parses `{ data:[{embedding}] }`.
+   */
+  async fetchOpenAiShapeEmbeddings(embedUrl, model, input, bearerToken) {
     if (this.embedDebugEnabled()) {
       console.info("[LLM embed] request", { url: embedUrl, model, inputChars: input.length });
     }
@@ -2540,7 +2587,7 @@ var LlmService = class _LlmService {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`
+        Authorization: `Bearer ${bearerToken}`
       },
       body: JSON.stringify({
         model,
@@ -2549,7 +2596,7 @@ var LlmService = class _LlmService {
     });
     if (!res.ok) {
       const body = await res.text();
-      const hint404 = res.status === 404 ? "This base URL does not expose OpenAI-compatible POST /v1/embeddings (e.g. router.huggingface.co). Set EMBEDDING_PROVIDER=huggingface and EMBEDDING_MODEL to a HF Inference\u2013supported embedding model, or use a host with /v1/embeddings." : "Embeddings HTTP error \u2014 knowledge_base_chunks.embedding will stay NULL for failed calls.";
+      const hint404 = res.status === 404 ? "This base URL does not expose OpenAI-compatible POST /v1/embeddings. For Hugging Face embeddings, set EMBEDDING_PROVIDER=huggingface and an HF token (EMBEDDING_API_KEY); the server uses @huggingface/inference (router /v1/embeddings is chat-only and is not used)." : "Embeddings HTTP error \u2014 knowledge_base_chunks.embedding will stay NULL for failed calls.";
       if (!_LlmService.embedHttpErrorLogged) {
         _LlmService.embedHttpErrorLogged = true;
         console.error("[LLM embed]", hint404, {
@@ -2573,15 +2620,8 @@ var LlmService = class _LlmService {
       }
       return [];
     }
-    let embedding = data?.data?.[0]?.embedding;
-    if (!Array.isArray(embedding) && Array.isArray(data?.embedding)) {
-      embedding = data.embedding;
-    }
-    if (!Array.isArray(embedding) && Array.isArray(data?.data?.[0])) {
-      const first = data.data[0];
-      embedding = Array.isArray(first) ? first : first?.embedding;
-    }
-    if (!Array.isArray(embedding)) {
+    const embedding = parseOpenAiEmbeddingJson(data);
+    if (!embedding) {
       if (!_LlmService.embedShapeErrorLogged) {
         _LlmService.embedShapeErrorLogged = true;
         console.error(
@@ -2603,96 +2643,201 @@ var LlmService = class _LlmService {
     }
     return embedding;
   }
-  async embedHuggingFaceInference(input, model) {
-    const normalizedBase = this.hfInferenceBaseURL.replace(/\/$/, "");
-    const baseWithProvider = /router\.huggingface\.co\/hf-inference$/i.test(normalizedBase) ? normalizedBase : /router\.huggingface\.co$/i.test(normalizedBase) ? `${normalizedBase}/hf-inference` : normalizedBase;
-    const requestBody = JSON.stringify({
-      inputs: input,
-      options: { wait_for_model: true }
-    });
-    const pipelineUrl = `${baseWithProvider}/pipeline/feature-extraction/${model}`;
-    const modelUrl = `${baseWithProvider}/models/${model}`;
-    if (this.embedDebugEnabled()) {
-      console.info("[LLM embed HF]", { url: pipelineUrl, model, inputChars: input.length });
-    }
-    let embedUrl = pipelineUrl;
-    let res = await fetch(embedUrl, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.embeddingApiKey}`
-      },
-      body: requestBody
-    });
-    let bodyText = await res.text();
-    if (res.status === 404) {
-      embedUrl = modelUrl;
-      if (this.embedDebugEnabled()) {
-        console.warn("[LLM embed HF] /pipeline route returned 404; retrying with /models.", {
-          model,
-          fallbackUrl: embedUrl
-        });
-      }
-      res = await fetch(embedUrl, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.embeddingApiKey}`
-        },
-        body: requestBody
+  /**
+   * Hugging Face–recommended path: Hub resolves a provider that supports `feature-extraction` for the model.
+   */
+  async embedViaHuggingfaceInferenceSdk(input, model) {
+    const token = this.embeddingApiKey.trim();
+    if (!token) return null;
+    try {
+      const { InferenceClient } = await import("@huggingface/inference");
+      const hf = new InferenceClient(token);
+      const raw = await hf.featureExtraction({
+        model,
+        inputs: input
       });
-      bodyText = await res.text();
-    }
-    if (!res.ok) {
-      if (!_LlmService.embedHttpErrorLogged) {
-        _LlmService.embedHttpErrorLogged = true;
-        console.error(
-          "[LLM embed HF] Hugging Face Inference request failed \u2014 knowledge chunks stay without vectors.",
-          {
-            url: embedUrl,
-            status: res.status,
-            statusText: res.statusText,
-            bodyPreview: bodyText.slice(0, 800),
-            hint: res.status === 410 || res.status === 404 ? "Model or route unavailable on Inference API; pick another EMBEDDING_MODEL (e.g. sentence-transformers/all-MiniLM-L6-v2)." : void 0
-          }
+      const embedding = parseHfInferenceEmbeddingBody(raw);
+      if (!embedding?.length) {
+        if (this.embedDebugEnabled()) {
+          console.warn("[LLM embed HF] Inference SDK returned no parseable vector", {
+            model,
+            shape: Array.isArray(raw) ? `array(len=${raw.length})` : typeof raw
+          });
+        }
+        return null;
+      }
+      return embedding;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (!_LlmService.hfInferenceSdkErrorLogged) {
+        _LlmService.hfInferenceSdkErrorLogged = true;
+        console.warn(
+          "[LLM embed HF] @huggingface/inference featureExtraction failed \u2014 trying legacy HTTP URLs.",
+          { model, message: message.slice(0, 500) }
         );
       } else if (this.embedDebugEnabled()) {
-        console.warn("[LLM embed HF] repeat HTTP error", { status: res.status, bodyPreview: bodyText.slice(0, 200) });
+        console.warn("[LLM embed HF] repeat Inference SDK failure", { message: message.slice(0, 200) });
       }
-      return [];
+      return null;
     }
-    let data;
-    try {
-      data = JSON.parse(bodyText);
-    } catch {
-      if (!_LlmService.embedShapeErrorLogged) {
-        _LlmService.embedShapeErrorLogged = true;
-        console.error("[LLM embed HF] Response is not JSON \u2014 treating as no embedding.");
-      }
-      return [];
+  }
+  /** Base URL for legacy `…/pipeline/…` and `…/models/{model}` tries (HF router only). */
+  hfLegacyInferenceBase(normalizedBase) {
+    if (/router\.huggingface\.co|api-inference\.huggingface\.co/i.test(normalizedBase)) {
+      return "https://router.huggingface.co/hf-inference";
     }
-    const embedding = parseHfInferenceEmbeddingBody(data);
-    if (!embedding?.length) {
-      if (!_LlmService.embedShapeErrorLogged) {
-        _LlmService.embedShapeErrorLogged = true;
-        const preview = typeof data === "object" && data !== null && !Array.isArray(data) ? Object.keys(data) : typeof data;
-        console.error("[LLM embed HF] Unrecognized embedding shape from Inference API.", { url: embedUrl, preview });
+    return normalizedBase;
+  }
+  /**
+   * Hugging Face embeddings: `@huggingface/inference` (Hub-routed feature extraction), then
+   * legacy direct `hf-inference` HTTP tries. Note: `https://router.huggingface.co/v1/embeddings` is not
+   * offered for embeddings (OpenAI-compatible `/v1` on HF is chat-only).
+   */
+  async embedHuggingFaceInference(input, model) {
+    const normalizedBase = this.hfInferenceBaseURL.replace(/\/$/, "");
+    const fromSdk = await this.embedViaHuggingfaceInferenceSdk(input, model);
+    if (fromSdk?.length) {
+      if (!_LlmService.embedSuccessLogged) {
+        _LlmService.embedSuccessLogged = true;
+        console.info("[LLM embed HF] first success", { dimension: fromSdk.length, model, via: "@huggingface/inference" });
+        if (!_LlmService.hfDimensionMismatchWarned && fromSdk.length !== 1536) {
+          _LlmService.hfDimensionMismatchWarned = true;
+          console.warn(
+            `[LLM embed HF] Embedding dimensions=${fromSdk.length}; ensure knowledge_base_chunks.embedding uses vector(${fromSdk.length}) (see migrations).`
+          );
+        }
+      } else if (this.embedDebugEnabled()) {
+        console.info("[LLM embed HF] ok", { dimension: fromSdk.length, via: "@huggingface/inference" });
       }
-      return [];
+      return fromSdk;
     }
-    if (!_LlmService.embedSuccessLogged) {
-      _LlmService.embedSuccessLogged = true;
-      console.info("[LLM embed HF] first success", { dimension: embedding.length, model });
-      if (!_LlmService.hfDimensionMismatchWarned && embedding.length !== 1536) {
-        _LlmService.hfDimensionMismatchWarned = true;
-        console.warn(
-          `[LLM embed HF] Embedding dimensions=${embedding.length}; default CMS migration uses vector(1536). If pgvector updates fail, alter the column, e.g. ALTER TABLE knowledge_base_chunks ALTER COLUMN embedding TYPE vector(${embedding.length});`
-        );
+    const legacyBase = this.hfLegacyInferenceBase(normalizedBase);
+    const baseWithProvider = /\/hf-inference$/i.test(legacyBase) || !/router\.huggingface\.co/i.test(legacyBase) ? legacyBase : `${legacyBase.replace(/\/$/, "")}/hf-inference`;
+    const bodyVariants = [
+      {
+        label: "inputs_parameters_mean_normalize",
+        body: JSON.stringify({
+          inputs: input,
+          parameters: { pooling: "mean", normalize: true },
+          options: { wait_for_model: true }
+        })
+      },
+      {
+        label: "inputs_string",
+        body: JSON.stringify({ inputs: input, options: { wait_for_model: true } })
+      },
+      {
+        label: "inputs_string_array",
+        body: JSON.stringify({ inputs: [input], options: { wait_for_model: true } })
+      },
+      {
+        label: "inputs_wrapped_sentences",
+        body: JSON.stringify({ inputs: { sentences: [input] }, options: { wait_for_model: true } })
+      },
+      {
+        label: "top_level_sentences",
+        body: JSON.stringify({ sentences: [input], options: { wait_for_model: true } })
       }
+    ];
+    const headers = {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${this.embeddingApiKey}`
+    };
+    const candidateUrls = [];
+    const pushUrl = (u) => {
+      if (!candidateUrls.includes(u)) candidateUrls.push(u);
+    };
+    pushUrl(`${baseWithProvider}/pipeline/feature-extraction/${model}`);
+    pushUrl(`${baseWithProvider}/models/${model}`);
+    let lastUrl = "";
+    let lastStatus = 0;
+    let lastBodyPreview = "";
+    let lastAttempt = "";
+    for (const embedUrl of candidateUrls) {
+      for (const { label, body } of bodyVariants) {
+        if (this.embedDebugEnabled()) {
+          console.info("[LLM embed HF] attempt", { url: embedUrl, model, inputChars: input.length, body: label });
+        }
+        const res = await fetch(embedUrl, {
+          method: "POST",
+          headers,
+          body
+        });
+        const bodyText = await res.text();
+        lastUrl = embedUrl;
+        lastStatus = res.status;
+        lastBodyPreview = bodyText.slice(0, 800);
+        lastAttempt = `${embedUrl} (${label})`;
+        if (!res.ok) {
+          if (this.embedDebugEnabled()) {
+            console.warn("[LLM embed HF] attempt failed, trying next if any", {
+              url: embedUrl,
+              body: label,
+              status: res.status,
+              bodyPreview: bodyText.slice(0, 200)
+            });
+          }
+          continue;
+        }
+        let data;
+        try {
+          data = JSON.parse(bodyText);
+        } catch {
+          if (this.embedDebugEnabled()) {
+            console.warn("[LLM embed HF] response not JSON, trying next if any", { url: embedUrl, body: label });
+          }
+          continue;
+        }
+        const embedding = parseHfInferenceEmbeddingBody(data);
+        if (!embedding?.length) {
+          if (this.embedDebugEnabled()) {
+            const preview = typeof data === "object" && data !== null && !Array.isArray(data) ? Object.keys(data) : typeof data;
+            console.warn("[LLM embed HF] no parseable embedding, trying next if any", {
+              url: embedUrl,
+              body: label,
+              preview
+            });
+          }
+          continue;
+        }
+        if (!_LlmService.embedSuccessLogged) {
+          _LlmService.embedSuccessLogged = true;
+          console.info("[LLM embed HF] first success", { dimension: embedding.length, model, url: embedUrl, body: label });
+          if (!_LlmService.hfDimensionMismatchWarned && embedding.length !== 1536) {
+            _LlmService.hfDimensionMismatchWarned = true;
+            console.warn(
+              `[LLM embed HF] Embedding dimensions=${embedding.length}; ensure knowledge_base_chunks.embedding uses vector(${embedding.length}) (see migrations).`
+            );
+          }
+        } else if (this.embedDebugEnabled()) {
+          console.info("[LLM embed HF] ok", { dimension: embedding.length, url: embedUrl, body: label });
+        }
+        return embedding;
+      }
+    }
+    if (!_LlmService.embedHttpErrorLogged) {
+      _LlmService.embedHttpErrorLogged = true;
+      console.error(
+        "[LLM embed HF] All Hugging Face embedding attempts failed \u2014 knowledge chunks stay without vectors.",
+        {
+          triedInferenceSdk: true,
+          triedLegacyHttp: candidateUrls,
+          lastAttempt,
+          lastUrl,
+          lastStatus,
+          lastBodyPreview,
+          hint: "Use an HF token with permission to call Inference Providers / Hub API mapping. Install ships @huggingface/inference; EMBEDDING_MODEL defaults to sentence-transformers/all-MiniLM-L6-v2. Router OpenAI /v1/embeddings is not used (chat-only)."
+        }
+      );
     } else if (this.embedDebugEnabled()) {
-      console.info("[LLM embed HF] ok", { dimension: embedding.length });
+      console.warn("[LLM embed HF] repeat failure (all attempts)", {
+        lastAttempt,
+        lastUrl,
+        lastStatus,
+        bodyPreview: lastBodyPreview.slice(0, 200)
+      });
     }
-    return embedding;
+    return [];
   }
   buildAgentMessages(options) {
     const { systemPrompt, userPrompt, history = [], context } = options;
@@ -2736,7 +2881,7 @@ ${context}`;
         Authorization: `Bearer ${this.apiKey}`
       },
       body: JSON.stringify({
-        model: options.model ?? "meta-llama/Meta-Llama-3-8B-Instruct",
+        model: this.resolveChatModel(options.model),
         messages,
         stream: false,
         temperature: options.temperature,
@@ -2745,7 +2890,7 @@ ${context}`;
     });
     if (!res.ok) {
       const text = await res.text();
-      throw new Error(`LLM gateway error: ${res.status} ${text}`);
+      throw new Error(formatLlmGatewayError(res.status, text, this.defaultChatModel));
     }
     const data = await res.json();
     const content = data.choices?.[0]?.message?.content ?? "";
@@ -2763,7 +2908,7 @@ ${context}`;
         Authorization: `Bearer ${this.apiKey}`
       },
       body: JSON.stringify({
-        model: options.model ?? "meta-llama/Meta-Llama-3-8B-Instruct",
+        model: this.resolveChatModel(options.model),
         messages,
         stream: true,
         temperature: options.temperature,
@@ -2772,7 +2917,7 @@ ${context}`;
     });
     if (!res.ok) {
       const text = await res.text();
-      throw new Error(`LLM gateway error: ${res.status} ${text}`);
+      throw new Error(formatLlmGatewayError(res.status, text, this.defaultChatModel));
     }
     const reader = res.body?.getReader();
     if (!reader) return;
@@ -2825,6 +2970,7 @@ function llmPlugin(config = {}) {
         return void 0;
       }
       const embeddingModel = config.embeddingModel ?? context.config.EMBEDDING_MODEL;
+      const defaultChatModel = config.defaultChatModel?.trim() || (typeof context.config.LLM_CHAT_MODEL === "string" ? context.config.LLM_CHAT_MODEL.trim() : "") || void 0;
       const embeddingProvider = normalizeEmbeddingProvider(
         config.embeddingProvider ?? context.config.EMBEDDING_PROVIDER
       );
@@ -2833,7 +2979,8 @@ function llmPlugin(config = {}) {
       return new LlmService(baseURL.replace(/\/$/, ""), apiKey, embeddingModel, {
         embeddingProvider,
         hfInferenceBaseUrl,
-        embeddingApiKey
+        embeddingApiKey,
+        defaultChatModel
       });
     }
   };
@@ -8363,6 +8510,13 @@ function getNextAuthOptions(config) {
 
 // src/api/crud.ts
 import { Brackets, ILike as ILike2, MoreThan as MoreThan2 } from "typeorm";
+var CRUD_LOG = "[cms-crud]";
+function logCrudClientError(op, detail) {
+  console.warn(CRUD_LOG, op, detail);
+}
+function logCrudServerError(op, detail) {
+  console.error(CRUD_LOG, op, detail);
+}
 var DATE_COLUMN_TYPES = /* @__PURE__ */ new Set([
   "date",
   "datetime",
@@ -8474,6 +8628,13 @@ function createCrudHandler(dataSource, entityMap, options) {
       if (authError) return authError;
       const entity = entityMap[resource];
       if (!resource || !entity) {
+        logCrudClientError("GET list", {
+          reason: "invalid_resource",
+          resource,
+          hasEntity: Boolean(entity),
+          entityMapHasLlmAgents: Boolean(entityMap.llm_agents),
+          entityMapKeyCount: Object.keys(entityMap).length
+        });
         return json({ error: "Invalid resource" }, { status: 400 });
       }
       const { searchParams } = new URL(req.url);
@@ -8681,12 +8842,22 @@ function createCrudHandler(dataSource, entityMap, options) {
         }
       }
       where = mergeDeletedFalseWhere(repo, where);
-      const [data, total] = await repo.findAndCount({
-        skip,
-        take: limit,
-        order: { [sortField]: sortOrder },
-        where
-      });
+      let data;
+      let total;
+      try {
+        const r = await repo.findAndCount({
+          skip,
+          take: limit,
+          order: { [sortField]: sortOrder },
+          where
+        });
+        data = r[0];
+        total = r[1];
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logCrudServerError("GET list query failed", { resource, sortField, sortOrder, message });
+        throw err;
+      }
       return json({ total, page, limit, totalPages: Math.ceil(total / limit), data });
     },
     async POST(req, resource) {
@@ -8694,12 +8865,25 @@ function createCrudHandler(dataSource, entityMap, options) {
       if (authError) return authError;
       const entity = entityMap[resource];
       if (!resource || !entity) {
+        logCrudClientError("POST create", {
+          reason: "invalid_resource",
+          resource,
+          hasEntity: Boolean(entity),
+          entityMapHasLlmAgents: Boolean(entityMap.llm_agents)
+        });
         return json({ error: "Invalid resource" }, { status: 400 });
       }
-      const body = await req.json();
-      if (!body || typeof body !== "object" || Object.keys(body).length === 0) {
+      const rawPostBody = await req.json();
+      if (!rawPostBody || typeof rawPostBody !== "object" || Object.keys(rawPostBody).length === 0) {
+        logCrudClientError("POST create", {
+          reason: "invalid_request_payload",
+          resource,
+          rawType: rawPostBody == null ? "nullish" : typeof rawPostBody,
+          keyCount: rawPostBody && typeof rawPostBody === "object" ? Object.keys(rawPostBody).length : 0
+        });
         return json({ error: "Invalid request payload" }, { status: 400 });
       }
+      const body = rawPostBody;
       if (resource === "media") {
         const b = body;
         const kind = b.kind === "folder" ? "folder" : "file";
@@ -8733,8 +8917,24 @@ function createCrudHandler(dataSource, entityMap, options) {
         }
       }
       const repo = dataSource.getRepository(entity);
-      sanitizeBodyForEntity(repo, body);
-      const created = await repo.save(repo.create(body));
+      const persistBody = resource === "media" ? body : pickColumnUpdates(repo, body);
+      if (resource !== "media" && Object.keys(persistBody).length === 0) {
+        logCrudClientError("POST create", {
+          reason: "no_scalar_columns_after_pick",
+          resource,
+          incomingKeys: Object.keys(body)
+        });
+        return json({ error: "Invalid request payload" }, { status: 400 });
+      }
+      sanitizeBodyForEntity(repo, persistBody);
+      let created;
+      try {
+        created = await repo.save(repo.create(persistBody));
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logCrudServerError("POST create save failed", { resource, message, persistKeys: Object.keys(persistBody) });
+        throw err;
+      }
       if (resource === "contacts") {
         await syncContactRowToErp(created);
       }
@@ -8749,6 +8949,7 @@ function createCrudHandler(dataSource, entityMap, options) {
       if (authError) return authError;
       const entity = entityMap[resource];
       if (!resource || !entity) {
+        logCrudClientError("GET_METADATA", { reason: "invalid_resource", resource });
         return json({ error: "Invalid resource" }, { status: 400 });
       }
       const repo = dataSource.getRepository(entity);
@@ -8780,11 +8981,18 @@ function createCrudHandler(dataSource, entityMap, options) {
       if (authError) return authError;
       const entity = entityMap[resource];
       if (!resource || !entity) {
+        logCrudClientError("BULK_POST", { reason: "invalid_resource", resource });
         return json({ error: "Invalid resource" }, { status: 400 });
       }
       const body = await req.json();
       const { records, upsertKey = "id" } = body;
       if (!Array.isArray(records) || records.length === 0) {
+        logCrudClientError("BULK_POST", {
+          reason: "records_required",
+          resource,
+          recordsIsArray: Array.isArray(records),
+          recordCount: Array.isArray(records) ? records.length : 0
+        });
         return json({ error: "Records array is required" }, { status: 400 });
       }
       const repo = dataSource.getRepository(entity);
@@ -8803,6 +9011,7 @@ function createCrudHandler(dataSource, entityMap, options) {
         });
       } catch (error) {
         const message = error instanceof Error ? error.message : "Bulk import failed";
+        logCrudClientError("BULK_POST upsert failed", { resource, upsertKey, message });
         return json({ error: message }, { status: 400 });
       }
     },
@@ -8811,6 +9020,7 @@ function createCrudHandler(dataSource, entityMap, options) {
       if (authError) return authError;
       const entity = entityMap[resource];
       if (!resource || !entity) {
+        logCrudClientError("GET_EXPORT", { reason: "invalid_resource", resource });
         return json({ error: "Invalid resource" }, { status: 400 });
       }
       const { searchParams } = new URL(req.url);
@@ -8865,7 +9075,10 @@ function createCrudByIdHandler(dataSource, entityMap, options) {
       const authError = await authz(req, resource, "read");
       if (authError) return authError;
       const entity = entityMap[resource];
-      if (!entity) return json({ error: "Invalid resource" }, { status: 400 });
+      if (!entity) {
+        logCrudClientError("GET by id", { reason: "invalid_resource", resource, id });
+        return json({ error: "Invalid resource" }, { status: 400 });
+      }
       const repo = dataSource.getRepository(entity);
       if (resource === "orders") {
         const order = await repo.findOne({
@@ -8924,7 +9137,10 @@ function createCrudByIdHandler(dataSource, entityMap, options) {
       const authError = await authz(req, resource, "update");
       if (authError) return authError;
       const entity = entityMap[resource];
-      if (!entity) return json({ error: "Invalid resource" }, { status: 400 });
+      if (!entity) {
+        logCrudClientError("PUT by id", { reason: "invalid_resource", resource, id });
+        return json({ error: "Invalid resource" }, { status: 400 });
+      }
       const rawBody = await req.json();
       const repo = dataSource.getRepository(entity);
       const numericId = Number(id);
@@ -9037,7 +9253,10 @@ function createCrudByIdHandler(dataSource, entityMap, options) {
       const authError = await authz(req, resource, "delete");
       if (authError) return authError;
       const entity = entityMap[resource];
-      if (!entity) return json({ error: "Invalid resource" }, { status: 400 });
+      if (!entity) {
+        logCrudClientError("DELETE by id", { reason: "invalid_resource", resource, id });
+        return json({ error: "Invalid resource" }, { status: 400 });
+      }
       const repo = dataSource.getRepository(entity);
       const numericId = Number(id);
       if (entityHasSoftDelete(repo)) {
@@ -9207,6 +9426,9 @@ var EMBED_CONCURRENCY = 5;
 var MAX_PDF_BYTES = 25 * 1024 * 1024;
 var TEXT_FILE_TYPES = /* @__PURE__ */ new Set(["text/plain", "text/markdown", "application/json"]);
 var KB_LOG = "[llm-agent-knowledge]";
+function logKbPipeline(step, meta) {
+  console.info(`${KB_LOG} pipeline`, { step, ...meta });
+}
 function llmEmbedDebug() {
   const v = process.env.LLM_EMBED_DEBUG?.toLowerCase();
   return v === "1" || v === "true" || v === "yes";
@@ -9221,11 +9443,29 @@ async function extractTextFromPdf(buffer) {
   const data = await pdfParse(buffer);
   return (data?.text ?? "").trim();
 }
-async function writeEmbeddingsConcurrent(dataSource, embed, chunks, concurrency) {
+async function loadChunksMissingEmbeddings(dataSource, documentId, slug) {
+  const rows = await dataSource.query(
+    `SELECT id, content FROM knowledge_base_chunks WHERE "documentId" = $1 AND embedding IS NULL ORDER BY "chunkIndex" ASC`,
+    [documentId]
+  );
+  const list = rows ?? [];
+  logKbPipeline("07_query_chunks_missing_embedding", {
+    slug,
+    documentId,
+    missingEmbeddingCount: list.length
+  });
+  return list;
+}
+async function writeEmbeddingsConcurrent(dataSource, embed, chunks, concurrency, slug) {
   let next = 0;
   let written = 0;
   let failed = 0;
   let skippedEmpty = 0;
+  logKbPipeline("09_embedding_workers_start", {
+    slug,
+    chunkCount: chunks.length,
+    concurrency: Math.max(1, Math.min(concurrency, chunks.length))
+  });
   async function worker() {
     for (; ; ) {
       const i = next++;
@@ -9264,9 +9504,12 @@ async function writeEmbeddingsConcurrent(dataSource, embed, chunks, concurrency)
     skippedEmpty
   };
   if (skippedEmpty > 0 && written === 0) {
-    summary.hint = "embed() returned empty vectors \u2014 see [LLM embed] logs (often HTTP 404 on /v1/embeddings, or wrong response shape).";
+    summary.hint = "embed() returned empty vectors \u2014 see [LLM embed] / [LLM embed HF] logs (OpenAI gateway vs @huggingface/inference + legacy HTTP).";
+  }
+  logKbPipeline("10_embedding_workers_finished", { slug, ...summary });
+  if (failed > 0 || skippedEmpty > 0 && written === 0) {
+    console.error(`${KB_LOG} embedding pass finished with issues`, summary);
   }
-  console.error(`${KB_LOG} embedding pass finished`, summary);
   return { written, failed };
 }
 function splitIntoChunks(text, maxLen) {
@@ -9302,6 +9545,58 @@ function createLlmAgentKnowledgeHandlers(config) {
     }
     return null;
   }
+  async function runEmbeddingPass(slug, savedChunks) {
+    let embeddingsWritten = 0;
+    let embeddingsFailed = 0;
+    try {
+      logKbPipeline("08_resolve_llm_plugin", { slug, chunkCount: savedChunks.length });
+      const cms = await getCms();
+      const llm = cms.getPlugin("llm");
+      if (llm?.embed && savedChunks.length > 0) {
+        logKbPipeline("08b_embed_fn_available", {
+          slug,
+          chunkCount: savedChunks.length,
+          firstChunkId: savedChunks[0]?.id,
+          lastChunkId: savedChunks[savedChunks.length - 1]?.id
+        });
+        const embedBound = (text) => llm.embed(text);
+        const { written, failed } = await writeEmbeddingsConcurrent(
+          dataSource,
+          embedBound,
+          savedChunks,
+          EMBED_CONCURRENCY,
+          slug
+        );
+        embeddingsWritten = written;
+        embeddingsFailed = failed;
+      } else {
+        logKbPipeline("08c_embed_skipped", {
+          slug,
+          hasLlmPlugin: !!llm,
+          hasEmbed: typeof llm?.embed === "function",
+          chunkCount: savedChunks.length,
+          reason: savedChunks.length === 0 ? "no_chunks" : !llm ? "no_llm_plugin" : "no_embed_method"
+        });
+        console.error(`${KB_LOG} embeddings skipped`, {
+          slug,
+          hasLlmPlugin: !!llm,
+          hasEmbed: typeof llm?.embed === "function",
+          chunkCount: savedChunks.length,
+          hint: !llm || typeof llm.embed !== "function" ? "LLM plugin missing or no embed(); check LLM_GATEWAY_URL + LLM_API_KEY so llm plugin initializes." : void 0
+        });
+      }
+    } catch (embErr) {
+      const detail = embErr instanceof Error ? embErr.message : String(embErr);
+      logKbPipeline("08d_embed_pass_exception", { slug, detail });
+      console.error(`${KB_LOG} embedding step threw before/during batch`, { slug, detail, embErr });
+      return {
+        embeddingsWritten: 0,
+        embeddingsFailed: savedChunks.length,
+        embedError: detail
+      };
+    }
+    return { embeddingsWritten, embeddingsFailed };
+  }
   return {
     async list(req, slug) {
       const denied = await gate(req, "read");
@@ -9330,8 +9625,11 @@ function createLlmAgentKnowledgeHandlers(config) {
       const denied = await gate(req, "update");
       if (denied) return denied;
       try {
+        const ct0 = req.headers.get("content-type") || "";
+        logKbPipeline("01_request", { slug, contentType: ct0.slice(0, 80) });
         const agent = await findAgentBySlug(dataSource, llmAgents, slug);
         if (!agent) return json({ error: "Agent not found" }, { status: 404 });
+        logKbPipeline("02_agent_loaded", { slug, agentId: agent.id });
         let name = "";
         let text = "";
         let sourceUrl = null;
@@ -9343,6 +9641,14 @@ function createLlmAgentKnowledgeHandlers(config) {
           name = (body?.name ?? "").trim();
           text = (body?.text ?? "").trim();
           sourceUrl = typeof body?.sourceUrl === "string" && body.sourceUrl.trim() ? body.sourceUrl.trim() : null;
+          logKbPipeline("03_body_parsed", {
+            slug,
+            mode: "json",
+            existingDocumentId,
+            nameLen: name.length,
+            textChars: text.length,
+            hasSourceUrl: !!sourceUrl
+          });
         } else if (ct.includes("multipart/form-data")) {
           const form = await req.formData();
           name = form.get("name")?.trim() ?? "";
@@ -9352,9 +9658,17 @@ function createLlmAgentKnowledgeHandlers(config) {
             const f = file;
             const mime = (f.type || "").split(";")[0].trim().toLowerCase();
             const buf = Buffer.from(await f.arrayBuffer());
+            logKbPipeline("03_body_parsed", {
+              slug,
+              mode: "multipart",
+              fileName: f.name || "(no name)",
+              mime,
+              fileBytes: buf.length
+            });
             if (TEXT_FILE_TYPES.has(mime)) {
               const decoded = buf.toString("utf8");
               if (!text) text = decoded;
+              logKbPipeline("04_file_decoded_text", { slug, mime, textChars: text.length });
             } else if (isPdfUpload(mime, f.name || "")) {
               if (buf.length > MAX_PDF_BYTES) {
                 return json(
@@ -9363,8 +9677,10 @@ function createLlmAgentKnowledgeHandlers(config) {
                 );
               }
               try {
+                logKbPipeline("04_pdf_extract_start", { slug, fileBytes: buf.length });
                 const extracted = await extractTextFromPdf(buf);
                 if (!text) text = extracted;
+                logKbPipeline("04_pdf_extract_done", { slug, textChars: text.length });
               } catch {
                 return json(
                   { error: "Could not read PDF text (file may be encrypted, corrupt, or image-only)" },
@@ -9380,12 +9696,15 @@ function createLlmAgentKnowledgeHandlers(config) {
               );
             }
             if (!name && f.name) name = f.name.replace(/\.[^/.]+$/, "") || f.name;
+          } else {
+            logKbPipeline("03_body_parsed", { slug, mode: "multipart", hasFile: false, textChars: text.length });
           }
         } else {
           return json({ error: "Use application/json or multipart/form-data" }, { status: 400 });
         }
         const linkRepo = dataSource.getRepository(junction);
         if (existingDocumentId != null) {
+          logKbPipeline("05_branch", { slug, branch: "link_existing_document", documentId: existingDocumentId });
           const docRepo2 = dataSource.getRepository(kbDoc);
           const existing = await docRepo2.findOne({ where: { id: existingDocumentId } });
           if (!existing) return json({ error: "documentId not found" }, { status: 404 });
@@ -9394,9 +9713,137 @@ function createLlmAgentKnowledgeHandlers(config) {
           });
           if (!dup2) {
             await linkRepo.save(linkRepo.create({ agentId: agent.id, documentId: existingDocumentId }));
+            logKbPipeline("06_junction_link_created", {
+              slug,
+              agentId: agent.id,
+              documentId: existingDocumentId
+            });
+          } else {
+            logKbPipeline("06_junction_link_exists", {
+              slug,
+              agentId: agent.id,
+              documentId: existingDocumentId
+            });
           }
-          return json({ documentId: existingDocumentId, linked: true, created: false });
+          const chunkRepo2 = dataSource.getRepository(kbChunk);
+          const docRow = existing;
+          const chunkCount = await chunkRepo2.count({ where: { documentId: existingDocumentId } });
+          logKbPipeline("06b_chunks_existing_count", {
+            slug,
+            documentId: existingDocumentId,
+            chunkCount
+          });
+          let chunksToEmbed = [];
+          let chunksCreated = 0;
+          if (chunkCount === 0) {
+            const text2 = (docRow.content ?? "").trim();
+            if (!text2) {
+              logKbPipeline("07_ingest_aborted_empty_document", { slug, documentId: existingDocumentId });
+              return json({
+                documentId: existingDocumentId,
+                linked: true,
+                created: false,
+                chunkCount: 0,
+                embeddingsWritten: 0,
+                embeddingsFailed: 0,
+                warning: "Document has no text content; add content then attach again to build chunks and embeddings."
+              });
+            }
+            const parts2 = splitIntoChunks(text2, INGEST_CHUNK_CHARS);
+            if (parts2.length > MAX_CHUNKS_PER_UPLOAD) {
+              return json(
+                {
+                  error: `Document is too large for one ingest (${parts2.length} chunks; max ${MAX_CHUNKS_PER_UPLOAD}). Split into smaller files.`
+                },
+                { status: 413 }
+              );
+            }
+            logKbPipeline("07_chunk_split", {
+              slug,
+              documentId: existingDocumentId,
+              partCount: parts2.length,
+              maxChunkChars: INGEST_CHUNK_CHARS,
+              totalChars: text2.length
+            });
+            const now2 = /* @__PURE__ */ new Date();
+            const chunkRows2 = parts2.map(
+              (content, i) => chunkRepo2.create({
+                documentId: existingDocumentId,
+                content,
+                chunkIndex: i,
+                createdAt: now2
+              })
+            );
+            const savedList2 = await chunkRepo2.save(chunkRows2);
+            chunksCreated = savedList2.length;
+            chunksToEmbed = savedList2.map((row, i) => ({
+              id: row.id,
+              content: parts2[i]
+            }));
+            logKbPipeline("07b_chunks_persisted", {
+              slug,
+              documentId: existingDocumentId,
+              rowsInserted: chunksCreated
+            });
+          } else {
+            chunksToEmbed = await loadChunksMissingEmbeddings(dataSource, existingDocumentId, slug);
+            if (chunksToEmbed.length === 0) {
+              logKbPipeline("08_skip_embed_all_chunks_have_vectors", {
+                slug,
+                documentId: existingDocumentId,
+                existingChunkCount: chunkCount
+              });
+            }
+          }
+          const embedResult2 = chunksToEmbed.length > 0 ? await runEmbeddingPass(slug, chunksToEmbed) : { embeddingsWritten: 0, embeddingsFailed: 0 };
+          if (embedResult2.embedError) {
+            logKbPipeline("11_response", {
+              slug,
+              branch: "link",
+              documentId: existingDocumentId,
+              ok: false,
+              embeddingError: true
+            });
+            return json(
+              {
+                documentId: existingDocumentId,
+                linked: true,
+                created: false,
+                chunkCount: chunkCount + chunksCreated,
+                chunksCreated,
+                embeddingAttempted: true,
+                embeddingsWritten: 0,
+                embeddingsFailed: chunksToEmbed.length,
+                warning: "Document linked; embedding step failed. Fix LLM/embed config and attach again (or unlink and re-attach) to retry NULL embeddings.",
+                detail: embedResult2.embedError
+              },
+              { status: 201 }
+            );
+          }
+          logKbPipeline("11_response", {
+            slug,
+            branch: "link",
+            documentId: existingDocumentId,
+            ok: true,
+            chunkCount: chunkCount + chunksCreated,
+            chunksCreated,
+            chunksQueuedForEmbedding: chunksToEmbed.length,
+            embeddingsWritten: embedResult2.embeddingsWritten,
+            embeddingsFailed: embedResult2.embeddingsFailed
+          });
+          return json({
+            documentId: existingDocumentId,
+            linked: true,
+            created: false,
+            chunkCount: chunkCount + chunksCreated,
+            chunksCreated: chunksCreated || void 0,
+            chunksQueuedForEmbedding: chunksToEmbed.length,
+            embeddingAttempted: chunksToEmbed.length > 0,
+            embeddingsWritten: embedResult2.embeddingsWritten,
+            embeddingsFailed: embedResult2.embeddingsFailed
+          });
         }
+        logKbPipeline("05_branch", { slug, branch: "new_upload_ingest" });
         if (!text) return json({ error: "text or file with text content is required" }, { status: 400 });
         if (!name) name = "Untitled";
         const parts = splitIntoChunks(text, INGEST_CHUNK_CHARS);
@@ -9411,6 +9858,13 @@ function createLlmAgentKnowledgeHandlers(config) {
             { status: 413 }
           );
         }
+        logKbPipeline("07_chunk_split", {
+          slug,
+          partCount: parts.length,
+          maxChunkChars: INGEST_CHUNK_CHARS,
+          totalChars: text.length,
+          documentName: name
+        });
         const docRepo = dataSource.getRepository(kbDoc);
         const chunkRepo = dataSource.getRepository(kbChunk);
         const now = /* @__PURE__ */ new Date();
@@ -9418,6 +9872,13 @@ function createLlmAgentKnowledgeHandlers(config) {
           docRepo.create({ name, content: text, sourceUrl, createdAt: now, updatedAt: now })
         );
         const docId = doc.id;
+        logKbPipeline("06_knowledge_document_saved", {
+          slug,
+          documentId: docId,
+          name,
+          contentChars: text.length,
+          hasSourceUrl: !!sourceUrl
+        });
         const chunkRows = parts.map(
           (content, i) => chunkRepo.create({ documentId: docId, content, chunkIndex: i, createdAt: now })
         );
@@ -9428,63 +9889,66 @@ function createLlmAgentKnowledgeHandlers(config) {
             content: parts[i]
           })
         );
+        logKbPipeline("07b_chunks_persisted", {
+          slug,
+          documentId: docId,
+          rowsInserted: savedChunks.length,
+          firstChunkId: savedChunks[0]?.id,
+          lastChunkId: savedChunks[savedChunks.length - 1]?.id
+        });
         const dup = await linkRepo.findOne({ where: { agentId: agent.id, documentId: docId } });
         if (!dup) {
           await linkRepo.save(linkRepo.create({ agentId: agent.id, documentId: docId }));
+          logKbPipeline("06c_junction_link_created", { slug, agentId: agent.id, documentId: docId });
+        } else {
+          logKbPipeline("06c_junction_link_exists", { slug, agentId: agent.id, documentId: docId });
         }
-        let embeddingsWritten = 0;
-        let embeddingsFailed = 0;
-        try {
-          const cms = await getCms();
-          const llm = cms.getPlugin("llm");
-          if (llm?.embed && savedChunks.length > 0) {
-            console.info(`${KB_LOG} starting embedding pass`, { slug, chunkCount: savedChunks.length });
-            const embedBound = (text2) => llm.embed(text2);
-            const { written, failed } = await writeEmbeddingsConcurrent(
-              dataSource,
-              embedBound,
-              savedChunks,
-              EMBED_CONCURRENCY
-            );
-            embeddingsWritten = written;
-            embeddingsFailed = failed;
-          } else {
-            console.error(`${KB_LOG} embeddings skipped`, {
-              slug,
-              hasLlmPlugin: !!llm,
-              hasEmbed: typeof llm?.embed === "function",
-              chunkCount: savedChunks.length,
-              hint: !llm || typeof llm.embed !== "function" ? "LLM plugin missing or no embed(); check LLM_GATEWAY_URL + LLM_API_KEY so llm plugin initializes." : void 0
-            });
-          }
-        } catch (embErr) {
-          const detail = embErr instanceof Error ? embErr.message : String(embErr);
-          console.error(`${KB_LOG} embedding step threw before/during batch`, { slug, detail, embErr });
+        const embedResult = await runEmbeddingPass(slug, savedChunks);
+        if (embedResult.embedError) {
+          logKbPipeline("11_response", {
+            slug,
+            branch: "ingest",
+            documentId: docId,
+            ok: false,
+            embeddingError: true
+          });
           return json(
             {
               documentId: docId,
               chunkCount: savedChunks.length,
+              embeddingAttempted: true,
               created: true,
               linked: true,
               embeddingsWritten: 0,
               embeddingsFailed: savedChunks.length,
               warning: "Document saved and linked; embedding step failed.",
-              detail
+              detail: embedResult.embedError
             },
             { status: 201 }
           );
         }
+        logKbPipeline("11_response", {
+          slug,
+          branch: "ingest",
+          documentId: docId,
+          ok: true,
+          chunkCount: savedChunks.length,
+          embeddingsWritten: embedResult.embeddingsWritten,
+          embeddingsFailed: embedResult.embeddingsFailed
+        });
         return json({
           documentId: docId,
           chunkCount: savedChunks.length,
+          embeddingAttempted: savedChunks.length > 0,
           created: true,
           linked: true,
-          embeddingsWritten,
-          embeddingsFailed
+          embeddingsWritten: embedResult.embeddingsWritten,
+          embeddingsFailed: embedResult.embeddingsFailed
         });
       } catch (err) {
         const msg = err instanceof Error ? err.message : "Failed to ingest knowledge";
         const name = err instanceof Error ? err.name : "";
+        logKbPipeline("99_pipeline_error", { slug, errorName: name, message: msg });
         return json({ error: msg, errorName: name || void 0 }, { status: 500 });
       }
     },
@@ -9496,6 +9960,7 @@ function createLlmAgentKnowledgeHandlers(config) {
       try {
         const agent = await findAgentBySlug(dataSource, llmAgents, slug);
         if (!agent) return json({ error: "Agent not found" }, { status: 404 });
+        logKbPipeline("unlink_junction", { slug, agentId: agent.id, documentId });
         const linkRepo = dataSource.getRepository(junction);
         await linkRepo.delete({ agentId: agent.id, documentId });
         return json({ ok: true });
@@ -9757,6 +10222,28 @@ function createAdminRolesHandlers(config) {
 
 // src/api/cms-api-handler.ts
 var KNOWLEDGE_SUFFIX = "knowledge";
+var CMS_API_LOG = "[cms-api]";
+function withLlmKnowledgeEntityFallbacks(base) {
+  const keys = [
+    "llm_agents",
+    "llm_agent_knowledge_documents",
+    "knowledge_base_documents",
+    "knowledge_base_chunks"
+  ];
+  const patch = {};
+  for (const key of keys) {
+    if (!(key in base) || base[key] == null) {
+      const fallback = CMS_ENTITY_MAP[key];
+      if (fallback) patch[key] = fallback;
+    }
+  }
+  const merged = Object.keys(patch).length > 0 ? { ...base, ...patch } : base;
+  if (!merged.llm_agents) {
+    const agent = CMS_ENTITY_MAP.llm_agents ?? LlmAgent;
+    return { ...merged, llm_agents: agent };
+  }
+  return merged;
+}
 function matchLlmAgentKnowledgeRoute(path) {
   const p = path[0] === "api" ? path.slice(1) : path;
   if (p[0] !== "llm_agents" || p.length < 2) return null;
@@ -9794,9 +10281,9 @@ var DEFAULT_EXCLUDE = /* @__PURE__ */ new Set([
 function createCmsApiHandler(config) {
   const {
     dataSource,
-    entityMap,
+    entityMap: rawEntityMap,
     pathToModel = (s) => s,
-    crudResources = Object.keys(entityMap).filter((k) => !DEFAULT_EXCLUDE.has(k)),
+    crudResources: crudResourcesOverride,
     getCms,
     userAuth: userAuthConfig,
     dashboard,
@@ -9817,6 +10304,9 @@ function createCmsApiHandler(config) {
     requireEntityPermission: userRequireEntityPermission,
     getSessionUser
   } = config;
+  const entityMap = withLlmKnowledgeEntityFallbacks(rawEntityMap);
+  const baseCrudResources = crudResourcesOverride ?? Object.keys(entityMap).filter((k) => !DEFAULT_EXCLUDE.has(k));
+  const crudResources = entityMap.llm_agents && !baseCrudResources.includes("llm_agents") ? [...baseCrudResources, "llm_agents"] : baseCrudResources;
   const requireEntityPermissionEffective = userRequireEntityPermission ?? (async (_req, entity, action) => config.json({ error: "Forbidden", reason: "entity_rbac_required", entity, action }, { status: 403 }));
   const analytics = analyticsConfig ?? (getCms ? {
     json: config.json,
@@ -9923,7 +10413,7 @@ function createCmsApiHandler(config) {
   const chatHandlers = chatConfig ? createChatHandlers(chatConfig) : null;
   const llmAgentKnowledgeMerged = llmAgentKnowledgeConfig ?? (chatConfig ? {
     dataSource: chatConfig.dataSource,
-    entityMap: chatConfig.entityMap,
+    entityMap: withLlmKnowledgeEntityFallbacks(chatConfig.entityMap ?? rawEntityMap),
     getCms: chatConfig.getCms,
     json: chatConfig.json,
     requireAuth: chatConfig.requireAuth
@@ -9937,7 +10427,9 @@ function createCmsApiHandler(config) {
     return crudResources.includes(model) ? model : segment;
   }
   return {
-    async handle(method, path, req) {
+    async handle(method, pathInput, req) {
+      const m = typeof method === "string" ? method.toUpperCase() : "GET";
+      const path = pathInput.length > 0 && pathInput[0] === "api" ? pathInput.slice(1) : pathInput;
       async function analyticsGate() {
         const a = await config.requireAuth(req);
         if (a) return a;
@@ -9945,86 +10437,86 @@ function createCmsApiHandler(config) {
       }
       if (path[0] === "admin" && path[1] === "roles") {
         if (!adminRoles) return config.json({ error: "Not found" }, { status: 404 });
-        if (path.length === 2 && method === "GET") return adminRoles.list();
-        if (path.length === 2 && method === "POST") return adminRoles.createGroup(req);
-        if (path.length === 3 && method === "PATCH") return adminRoles.patchGroup(req, path[2]);
-        if (path.length === 3 && method === "DELETE") return adminRoles.deleteGroup(path[2]);
-        if (path.length === 4 && path[3] === "permissions" && method === "PUT") return adminRoles.putPermissions(req, path[2]);
+        if (path.length === 2 && m === "GET") return adminRoles.list();
+        if (path.length === 2 && m === "POST") return adminRoles.createGroup(req);
+        if (path.length === 3 && m === "PATCH") return adminRoles.patchGroup(req, path[2]);
+        if (path.length === 3 && m === "DELETE") return adminRoles.deleteGroup(path[2]);
+        if (path.length === 4 && path[3] === "permissions" && m === "PUT") return adminRoles.putPermissions(req, path[2]);
         return config.json({ error: "Not found" }, { status: 404 });
       }
-      if (path[0] === "dashboard" && path[1] === "stats" && path.length === 2 && method === "GET" && dashboardGet) {
+      if (path[0] === "dashboard" && path[1] === "stats" && path.length === 2 && m === "GET" && dashboardGet) {
         return dashboardGet(req);
       }
-      if (path[0] === "dashboard" && path[1] === "ecommerce" && path.length === 2 && method === "GET" && ecommerceAnalyticsGet) {
+      if (path[0] === "dashboard" && path[1] === "ecommerce" && path.length === 2 && m === "GET" && ecommerceAnalyticsGet) {
         const g = await analyticsGate();
         if (g) return g;
         return ecommerceAnalyticsGet(req);
       }
       if (path[0] === "analytics" && analyticsHandlers) {
-        if (path.length === 1 && method === "GET") {
+        if (path.length === 1 && m === "GET") {
           const g = await analyticsGate();
           if (g) return g;
           return analyticsHandlers.GET(req);
         }
-        if (path.length === 2 && path[1] === "property-id" && method === "GET") {
+        if (path.length === 2 && path[1] === "property-id" && m === "GET") {
           const g = await analyticsGate();
           if (g) return g;
           return analyticsHandlers.propertyId();
         }
-        if (path.length === 2 && path[1] === "permissions" && method === "GET") {
+        if (path.length === 2 && path[1] === "permissions" && m === "GET") {
           const g = await analyticsGate();
           if (g) return g;
           return analyticsHandlers.permissions();
         }
       }
-      if (path[0] === "upload" && path.length === 1 && method === "POST" && uploadPost) return uploadPost(req);
-      if (path[0] === "media" && path[1] === "extract" && path.length === 3 && method === "POST" && zipExtractPost) {
+      if (path[0] === "upload" && path.length === 1 && m === "POST" && uploadPost) return uploadPost(req);
+      if (path[0] === "media" && path[1] === "extract" && path.length === 3 && m === "POST" && zipExtractPost) {
         return zipExtractPost(req, path[2]);
       }
-      if (path[0] === "blogs" && path[1] === "slug" && path.length === 3 && method === "GET" && blogBySlugGet) {
+      if (path[0] === "blogs" && path[1] === "slug" && path.length === 3 && m === "GET" && blogBySlugGet) {
         return blogBySlugGet(req, path[2]);
       }
-      if (path[0] === "forms" && path[1] === "slug" && path.length === 3 && method === "GET" && formBySlugGet) {
+      if (path[0] === "forms" && path[1] === "slug" && path.length === 3 && m === "GET" && formBySlugGet) {
         return formBySlugGet(req, path[2]);
       }
       if (path[0] === "form-submissions") {
         if (path.length === 1) {
-          if (method === "GET" && formSubmissionList) return formSubmissionList(req);
-          if (method === "POST" && formSubmissionPost) return formSubmissionPost(req);
+          if (m === "GET" && formSubmissionList) return formSubmissionList(req);
+          if (m === "POST" && formSubmissionPost) return formSubmissionPost(req);
         }
-        if (path.length === 2 && method === "GET" && formSubmissionGetById) return formSubmissionGetById(req, path[1]);
+        if (path.length === 2 && m === "GET" && formSubmissionGetById) return formSubmissionGetById(req, path[1]);
       }
       if (path[0] === "forms" && formSaveHandlers) {
-        if (path.length === 1 && method === "POST") return formSaveHandlers.POST(req);
+        if (path.length === 1 && m === "POST") return formSaveHandlers.POST(req);
         if (path.length === 2) {
-          if (method === "GET") return formSaveHandlers.GET(req, path[1]);
-          if (method === "PUT" || method === "PATCH") return formSaveHandlers.PUT(req, path[1]);
+          if (m === "GET") return formSaveHandlers.GET(req, path[1]);
+          if (m === "PUT" || m === "PATCH") return formSaveHandlers.PUT(req, path[1]);
         }
       }
       if (path[0] === "users" && usersHandlers) {
         if (path.length === 1) {
-          if (method === "GET") return usersHandlers.list(req);
-          if (method === "POST") return usersHandlers.create(req);
+          if (m === "GET") return usersHandlers.list(req);
+          if (m === "POST") return usersHandlers.create(req);
         }
         if (path.length === 2) {
-          if (path[1] === "avatar" && method === "POST" && avatarPost) return avatarPost(req);
-          if (path[1] === "profile" && method === "PUT" && profilePut) return profilePut(req);
+          if (path[1] === "avatar" && m === "POST" && avatarPost) return avatarPost(req);
+          if (path[1] === "profile" && m === "PUT" && profilePut) return profilePut(req);
           const id = path[1];
-          if (method === "GET") return usersHandlers.getById(req, id);
-          if (method === "PUT" || method === "PATCH") return usersHandlers.update(req, id);
-          if (method === "DELETE") return usersHandlers.delete(req, id);
+          if (m === "GET") return usersHandlers.getById(req, id);
+          if (m === "PUT" || m === "PATCH") return usersHandlers.update(req, id);
+          if (m === "DELETE") return usersHandlers.delete(req, id);
         }
-        if (path.length === 3 && path[2] === "regenerate-invite" && method === "POST") {
+        if (path.length === 3 && path[2] === "regenerate-invite" && m === "POST") {
           return usersHandlers.regenerateInvite(req, path[1]);
         }
       }
-      if (path[0] === "users" && path.length === 2 && userAuthRouter && method === "POST") {
+      if (path[0] === "users" && path.length === 2 && userAuthRouter && m === "POST") {
         return userAuthRouter.POST(req, path[1]);
       }
       if (path[0] === "settings" && path.length === 2 && settingsHandlers) {
         const group = path[1];
         const isPublic = settingsConfig?.publicGetGroups?.includes(group);
-        if (method === "GET") {
+        if (m === "GET") {
           if (!isPublic) {
             const a = await config.requireAuth(req);
             if (a) return a;
@@ -10033,15 +10525,38 @@ function createCmsApiHandler(config) {
           }
           return settingsHandlers.GET(req, group);
         }
-        if (method === "PUT") {
+        if (m === "PUT") {
           const pe = await requireEntityPermissionEffective(req, "settings", "update");
           if (pe) return pe;
           return settingsHandlers.PUT(req, group);
         }
       }
       if (path[0] === "message-templates" && path[1] === "sms" && path.length === 2) {
-        if (method === "GET") return smsMessageTemplateHandlers.GET(req);
-        if (method === "PUT") return smsMessageTemplateHandlers.PUT(req);
+        if (m === "GET") return smsMessageTemplateHandlers.GET(req);
+        if (m === "PUT") return smsMessageTemplateHandlers.PUT(req);
+      }
+      if (path[0] === "llm_agents") {
+        if (!entityMap.llm_agents) {
+          console.error(CMS_API_LOG, "llm_agents route: entity missing after merge", {
+            method: m,
+            pathJoined: path.join("/"),
+            entityMapKeyCount: Object.keys(entityMap).length
+          });
+          return config.json(
+            { error: "LlmAgent entity is not registered", hint: "Ensure migrations ran and entities include LlmAgent." },
+            { status: 503 }
+          );
+        }
+        if (path.length === 1) {
+          if (m === "GET") return crud.GET(req, "llm_agents");
+          if (m === "POST") return crud.POST(req, "llm_agents");
+        }
+        if (path.length === 2 && !path[1]?.includes("knowledge")) {
+          const id = path[1];
+          if (m === "GET") return crudById.GET(req, "llm_agents", id);
+          if (m === "PUT" || m === "PATCH") return crudById.PUT(req, "llm_agents", id);
+          if (m === "DELETE") return crudById.DELETE(req, "llm_agents", id);
+        }
       }
       {
         const kbMatch = matchLlmAgentKnowledgeRoute(path);
@@ -10056,24 +10571,24 @@ function createCmsApiHandler(config) {
             );
           }
           const { slug, documentId } = kbMatch;
-          if (method === "DELETE" && documentId != null && documentId !== "") {
+          if (m === "DELETE" && documentId != null && documentId !== "") {
             return llmAgentKnowledgeHandlers.unlink(req, slug, documentId);
           }
-          if (method === "GET" && (documentId == null || documentId === "")) {
+          if (m === "GET" && (documentId == null || documentId === "")) {
             return llmAgentKnowledgeHandlers.list(req, slug);
           }
-          if (method === "POST" && (documentId == null || documentId === "")) {
+          if (m === "POST" && (documentId == null || documentId === "")) {
             return llmAgentKnowledgeHandlers.post(req, slug);
           }
         }
       }
       if (path[0] === "chat" && chatHandlers) {
-        if (path.length === 2 && path[1] === "config" && method === "GET") return chatHandlers.publicConfig(req);
-        if (path.length === 2 && path[1] === "identify" && method === "POST") return chatHandlers.identify(req);
-        if (path.length === 4 && path[1] === "conversations" && path[3] === "messages" && method === "GET") return chatHandlers.getMessages(req, path[2]);
-        if (path.length === 2 && path[1] === "messages" && method === "POST") return chatHandlers.postMessage(req);
+        if (path.length === 2 && path[1] === "config" && m === "GET") return chatHandlers.publicConfig(req);
+        if (path.length === 2 && path[1] === "identify" && m === "POST") return chatHandlers.identify(req);
+        if (path.length === 4 && path[1] === "conversations" && path[3] === "messages" && m === "GET") return chatHandlers.getMessages(req, path[2]);
+        if (path.length === 2 && path[1] === "messages" && m === "POST") return chatHandlers.postMessage(req);
       }
-      if (path[0] === "orders" && path.length === 3 && path[2] === "invoice" && method === "GET" && getCms) {
+      if (path[0] === "orders" && path.length === 3 && path[2] === "invoice" && m === "GET" && getCms) {
         const a = await config.requireAuth(req);
         if (a) return a;
         const pe = await requireEntityPermissionEffective(req, "orders", "read");
@@ -10087,17 +10602,17 @@ function createCmsApiHandler(config) {
       if (path[0] === "orders" && path.length === 3 && path[2] === "repost-erp" && getCms) {
         const a = await config.requireAuth(req);
         if (a) return a;
-        const pe = await requireEntityPermissionEffective(req, "orders", method === "GET" ? "read" : "update");
+        const pe = await requireEntityPermissionEffective(req, "orders", m === "GET" ? "read" : "update");
         if (pe) return pe;
         const oid = Number(path[1]);
         if (!Number.isFinite(oid)) return config.json({ error: "Invalid id" }, { status: 400 });
         const cms = await getCms();
         const { isErpIntegrationEnabled: isErpIntegrationEnabled3 } = await Promise.resolve().then(() => (init_erp_config_enabled(), erp_config_enabled_exports));
         const enabled = await isErpIntegrationEnabled3(cms, dataSource, entityMap);
-        if (method === "GET") {
+        if (m === "GET") {
           return config.json({ enabled });
         }
-        if (method === "POST") {
+        if (m === "POST") {
           if (!enabled) return config.json({ error: "ERP integration is disabled" }, { status: 409 });
           const { queueErpPaidOrderForOrderId: queueErpPaidOrderForOrderId2 } = await Promise.resolve().then(() => (init_paid_order_erp(), paid_order_erp_exports));
           await queueErpPaidOrderForOrderId2(cms, dataSource, entityMap, oid);
@@ -10107,28 +10622,39 @@ function createCmsApiHandler(config) {
       }
       if (path.length === 0) return config.json({ error: "Not found" }, { status: 404 });
       const resource = resolveResource(path[0]);
-      if (!crudResources.includes(resource)) return config.json({ error: "Invalid resource" }, { status: 400 });
+      if (!crudResources.includes(resource)) {
+        console.warn(CMS_API_LOG, "generic CRUD gate: Invalid resource (not in crudResources)", {
+          method: m,
+          pathJoined: path.join("/"),
+          pathSegments: path,
+          resource,
+          hasLlmAgentsEntity: Boolean(entityMap.llm_agents),
+          crudResourcesHasResource: crudResources.includes(resource),
+          crudResourcesLength: crudResources.length
+        });
+        return config.json({ error: "Invalid resource" }, { status: 400 });
+      }
       if (path.length === 2) {
-        if (path[1] === "metadata" && method === "GET") {
+        if (path[1] === "metadata" && m === "GET") {
           return crud.GET_METADATA(req, resource);
         }
-        if (path[1] === "bulk" && method === "POST") {
+        if (path[1] === "bulk" && m === "POST") {
           return crud.BULK_POST(req, resource);
         }
-        if (path[1] === "export" && method === "GET") {
+        if (path[1] === "export" && m === "GET") {
           return crud.GET_EXPORT(req, resource);
         }
       }
       if (path.length === 1) {
-        if (method === "GET") return crud.GET(req, resource);
-        if (method === "POST") return crud.POST(req, resource);
+        if (m === "GET") return crud.GET(req, resource);
+        if (m === "POST") return crud.POST(req, resource);
         return config.json({ error: "Method not allowed" }, { status: 405 });
       }
       if (path.length === 2) {
         const id = path[1];
-        if (method === "GET") return crudById.GET(req, resource, id);
-        if (method === "PUT" || method === "PATCH") return crudById.PUT(req, resource, id);
-        if (method === "DELETE") return crudById.DELETE(req, resource, id);
+        if (m === "GET") return crudById.GET(req, resource, id);
+        if (m === "PUT" || m === "PATCH") return crudById.PUT(req, resource, id);
+        if (m === "DELETE") return crudById.DELETE(req, resource, id);
         return config.json({ error: "Method not allowed" }, { status: 405 });
       }
       return config.json({ error: "Not found" }, { status: 404 });