@carlonicora/nextjs-jsonapi 1.107.1 → 1.109.0

package/dist/types-DHOxe8rc.d.ts

@@ -0,0 +1,101 @@
+import { LucideIcon } from 'lucide-react';
+import { A as ApiRequestDataTypeInterface, F as FieldSelector } from './ApiRequestDataTypeInterface-CYEcRUrh.js';
+
+/**
+ * Permission actions
+ */
+declare enum Action {
+    Read = "read",
+    Create = "create",
+    Update = "update",
+    Delete = "delete"
+}
+/**
+ * Generic permission check type.
+ * Can be a boolean or a function that checks permissions dynamically.
+ * @template T - The data type being checked
+ * @template U - The user type (defaults to PermissionUser)
+ */
+type PermissionCheck<T, U = PermissionUser> = boolean | ((user?: U | string, data?: T) => boolean);
+/**
+ * Page URL configuration for modules
+ */
+type PageUrl = {
+    pageUrl?: string;
+};
+/**
+ * Module permission definition wrapper
+ */
+type ModulePermissionDefinition<T> = {
+    interface: T;
+};
+/**
+ * Base module definition
+ */
+type ModuleDefinition = {
+    pageUrl?: string;
+    name: string;
+    model: any;
+    feature?: string;
+    moduleId?: string;
+};
+/**
+ * Permission configuration for a module.
+ * Can be a boolean (allow/deny all) or a string path for dynamic checks.
+ */
+interface PermissionConfig {
+    create: boolean | string;
+    read: boolean | string;
+    update: boolean | string;
+    delete: boolean | string;
+}
+/**
+ * Generic interface for a module that has permissions.
+ * Apps should ensure their Module class implements this.
+ */
+interface PermissionModule {
+    id: string;
+    permissions: PermissionConfig;
+}
+/**
+ * Generic interface for a user that has modules with permissions.
+ * Apps should ensure their User class implements this.
+ */
+interface PermissionUser {
+    id: string;
+    modules: PermissionModule[];
+}
+/**
+ * Module definition with permissions - extends ApiRequestDataTypeInterface
+ */
+type ModuleWithPermissions = ApiRequestDataTypeInterface & {
+    pageUrl?: string;
+    feature?: string;
+    moduleId?: string;
+    icon?: LucideIcon;
+    inclusions?: Record<string, {
+        types?: string[];
+        fields?: FieldSelector<any>[];
+        include?: string[];
+    }>;
+};
+/**
+ * Factory type for creating module definitions
+ */
+type ModuleFactory = (params: {
+    pageUrl?: string;
+    name: string;
+    cache?: string | "days" | "default" | "hours" | "max" | "minutes" | "seconds" | "weeks";
+    model: any;
+    feature?: string;
+    moduleId?: string;
+    icon?: LucideIcon;
+    identifier?: string[];
+    inclusions?: Record<string, {
+        types?: string[];
+        fields?: FieldSelector<any>[];
+        include?: string[];
+    }>;
+}) => ModuleWithPermissions;
+
+export { Action as A, type ModuleWithPermissions as M, type PageUrl as P, type PermissionCheck as a, type ModulePermissionDefinition as b, type ModuleDefinition as c, type PermissionConfig as d, type PermissionModule as e, type PermissionUser as f, type ModuleFactory as g };

package/dist/usePageUrlGenerator-tjq2mlDV.d.ts

@@ -0,0 +1,14 @@
+import { P as PageUrl } from './types-DHOxe8rc.js';
+
+declare function usePageUrlGenerator(): (params: {
+    page?: PageUrl | string;
+    id?: string;
+    childPage?: PageUrl | string;
+    childId?: string;
+    additionalParameters?: {
+        [key: string]: string | string[] | undefined;
+    };
+    language?: string;
+}) => string;
+
+export { usePageUrlGenerator as u };

package/dist/usePageUrlGenerator-uOnyJ6j2.d.mts

@@ -0,0 +1,14 @@
+import { P as PageUrl } from './types-CQSjy7et.mjs';
+
+declare function usePageUrlGenerator(): (params: {
+    page?: PageUrl | string;
+    id?: string;
+    childPage?: PageUrl | string;
+    childId?: string;
+    additionalParameters?: {
+        [key: string]: string | string[] | undefined;
+    };
+    language?: string;
+}) => string;
+
+export { usePageUrlGenerator as u };

package/dist/{useSocket-BkxHHujj.d.mts → useSocket-B1fMIr17.d.mts}

@@ -1,4 +1,4 @@
-import { N as NotificationInterface } from './notification.interface-DLZGtV7Z.mjs';
+import { N as NotificationInterface } from './notification.interface-DIxR23eS.mjs';
 
 interface UseSocketOptions {
     token: string;

package/dist/{useSocket-CMDjWFYm.d.ts → useSocket-BdJTBXKv.d.ts}

@@ -1,4 +1,4 @@
-import { N as NotificationInterface } from './notification.interface-aLEJbA_g.js';
+import { N as NotificationInterface } from './notification.interface-C1T1C2ee.js';
 
 interface UseSocketOptions {
     token: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "1.107.1",
+  "version": "1.109.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",
@@ -52,6 +52,21 @@
       "types": "./dist/billing/index.d.ts",
       "import": "./dist/billing/index.mjs",
       "require": "./dist/billing/index.js"
+    },
+    "./help-asset-route": {
+      "types": "./dist/features/help/server/createHelpAssetRouteHandler.d.ts",
+      "import": "./dist/features/help/server/createHelpAssetRouteHandler.mjs",
+      "require": "./dist/features/help/server/createHelpAssetRouteHandler.js"
+    },
+    "./help": {
+      "types": "./dist/features/help/index.d.ts",
+      "import": "./dist/features/help/index.mjs",
+      "require": "./dist/features/help/index.js"
+    },
+    "./help/server": {
+      "types": "./dist/features/help/server.d.ts",
+      "import": "./dist/features/help/server.mjs",
+      "require": "./dist/features/help/server.js"
     }
   },
   "scripts": {
@@ -139,6 +154,10 @@
     "react-markdown": "^10.1.0",
     "react-resizable-panels": "^4.11.1",
     "recharts": "^3.8.1",
+    "fuse.js": "^7.0.0",
+    "next-mdx-remote": "^5.0.0",
+    "rehype-autolink-headings": "^7.1.0",
+    "rehype-slug": "^6.0.0",
     "remark-gfm": "^4.0.1",
     "shadcn": "^4.8.0",
     "shepherd.js": "^15.2.2",

package/src/client/config.ts

@@ -2,6 +2,8 @@
 
 import { ModuleWithPermissions } from "../permissions/types";
 import { setBootstrapper } from "../core/registry/bootstrapStore";
+import { _setStaticHelpContent } from "../core/registry/helpStore";
+import type { HelpContentConfig } from "../features/help/interfaces/help-content-config.interface";
 
 // Config storage for client-side contexts
 let _clientConfig: {
@@ -16,6 +18,7 @@ let _clientConfig: {
 /**
  * Configure the JSON:API client. This is the main configuration function.
  * This is typically called during app initialization.
+ * @param config.helpContent - Optional help-content config (manifest, brand, redirects). Forwarded to the help feature's globalThis-backed store; not stored on the client config.
  */
 export function configureJsonApi(config: {
   apiUrl: string;
@@ -24,8 +27,13 @@ export function configureJsonApi(config: {
   bootstrapper?: () => void;
   additionalHeaders?: Record<string, string>;
   stripePublishableKey?: string;
+  helpContent?: HelpContentConfig;
 }): void {
-  _clientConfig = config;
+  const { helpContent, ...rest } = config;
+  _clientConfig = rest;
+  if (helpContent) {
+    _setStaticHelpContent(helpContent);
+  }
   // Register and call bootstrapper to register all modules
   if (config.bootstrapper) {
     setBootstrapper(config.bootstrapper);

package/src/core/registry/helpStore.ts

@@ -0,0 +1,45 @@
+/**
+ * Centralized help-content store accessible from client and server contexts.
+ * Uses globalThis Symbol keys to persist across HMR/Turbopack reloads and to
+ * bridge between the client-side `configureJsonApi` (in `client/config.ts`)
+ * and server-side consumers (HelpProvider, getHelpContent, serializeHelpArticle).
+ *
+ * NO external dependencies to avoid circular imports.
+ *
+ * Pattern mirrors `bootstrapStore.ts`.
+ */
+
+// Help content config shape is duplicated here as `unknown` to avoid pulling
+// the help feature into this core file. Callers cast on read.
+type HelpReader = (article: { path: string }) => Promise<string>;
+
+const HELP_CONTENT_KEY = Symbol.for("nextjs-jsonapi:helpContent");
+const HELP_READER_KEY = Symbol.for("nextjs-jsonapi:helpReader");
+
+const globalStore = globalThis as unknown as {
+  [HELP_CONTENT_KEY]?: unknown | null;
+  [HELP_READER_KEY]?: HelpReader | null;
+};
+
+if (globalStore[HELP_CONTENT_KEY] === undefined) {
+  globalStore[HELP_CONTENT_KEY] = null;
+}
+if (globalStore[HELP_READER_KEY] === undefined) {
+  globalStore[HELP_READER_KEY] = null;
+}
+
+export function _setStaticHelpContent(cfg: unknown | null): void {
+  globalStore[HELP_CONTENT_KEY] = cfg;
+}
+
+export function _getStaticHelpContent<T = unknown>(): T | null {
+  return (globalStore[HELP_CONTENT_KEY] as T | null) ?? null;
+}
+
+export function setHelpReader(reader: HelpReader): void {
+  globalStore[HELP_READER_KEY] = reader;
+}
+
+export function _getStaticHelpReader(): HelpReader | null {
+  return globalStore[HELP_READER_KEY] ?? null;
+}

package/src/features/assistant/contexts/AssistantContext.tsx

@@ -20,7 +20,7 @@ interface AssistantContextValue {
   sending: boolean;
   status?: string;
   failedMessageIds: Set<string>;
-  sendMessage(content: string): Promise<void>;
+  sendMessage(content: string, opts?: { howToMode?: boolean; limitToHowToId?: string }): Promise<void>;
   retrySend(tempId: string): Promise<void>;
   selectThread(id: string): Promise<void>;
   startNew(): void;
@@ -34,10 +34,17 @@ interface Props {
   children: React.ReactNode;
   dehydratedAssistant?: JsonApiHydratedDataInterface;
   dehydratedMessages?: JsonApiHydratedDataInterface[];
+  /**
+   * When `true` (default), the provider mutates the browser URL on
+   * create/selectThread/startNew (e.g. `/assistants/{id}`). Set to `false`
+   * when the assistant is hosted inside a sheet / overlay so the user's
+   * current route is preserved.
+   */
+  manageUrl?: boolean;
 }
 
 function stripOptimistic(list: AssistantMessageInterface[]): AssistantMessageInterface[] {
-  return list.filter((m) => !m.id.startsWith("tmp-"));
+  return list.filter((m) => !m.isOptimistic);
 }
 
 function nextPosition(list: AssistantMessageInterface[]): number {
@@ -55,7 +62,7 @@ function withPatchedTitle(source: AssistantInterface, title: string): AssistantI
   });
 }
 
-export function AssistantProvider({ children, dehydratedAssistant, dehydratedMessages }: Props) {
+export function AssistantProvider({ children, dehydratedAssistant, dehydratedMessages, manageUrl = true }: Props) {
   const t = useTranslations();
   const generateUrl = usePageUrlGenerator();
 
@@ -73,7 +80,7 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
   const { socket } = useSocketContext();
 
   const sendMessage = useCallback(
-    async (content: string) => {
+    async (content: string, opts?: { howToMode?: boolean; limitToHowToId?: string }) => {
       const trimmed = content.trim();
       if (!trimmed) return;
 
@@ -94,18 +101,24 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
 
       try {
         if (!assistant) {
-          const created = await AssistantService.create({ firstMessage: trimmed });
+          const created = await AssistantService.create({
+            firstMessage: trimmed,
+            howToMode: opts?.howToMode,
+            limitToHowToId: opts?.limitToHowToId,
+          });
           const msgs = await AssistantMessageService.findByAssistant({ assistantId: created.id });
           setAssistant(created);
           setMessages(msgs);
           setThreads((prev) => [created, ...prev]);
-          if (typeof window !== "undefined") {
+          if (manageUrl && typeof window !== "undefined") {
             window.history.replaceState(null, "", `/assistants/${created.id}`);
           }
         } else {
           const result = await AssistantService.appendMessage({
             assistantId: assistant.id,
             content: trimmed,
+            howToMode: opts?.howToMode,
+            limitToHowToId: opts?.limitToHowToId,
           });
           setMessages((prev) => [...stripOptimistic(prev), ...result]);
         }
@@ -142,17 +155,20 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
     [messages, sendMessage],
   );
 
-  const selectThread = useCallback(async (id: string) => {
-    const [target, msgs] = await Promise.all([
-      AssistantService.findOne({ id }),
-      AssistantMessageService.findByAssistant({ assistantId: id }),
-    ]);
-    setAssistant(target);
-    setMessages(msgs);
-    if (typeof window !== "undefined") {
-      window.history.replaceState(null, "", `/assistants/${id}`);
-    }
-  }, []);
+  const selectThread = useCallback(
+    async (id: string) => {
+      const [target, msgs] = await Promise.all([
+        AssistantService.findOne({ id }),
+        AssistantMessageService.findByAssistant({ assistantId: id }),
+      ]);
+      setAssistant(target);
+      setMessages(msgs);
+      if (manageUrl && typeof window !== "undefined") {
+        window.history.replaceState(null, "", `/assistants/${id}`);
+      }
+    },
+    [manageUrl],
+  );
 
   const renameThread = useCallback(async (id: string, title: string) => {
     await AssistantService.rename({ id, title });
@@ -164,10 +180,10 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
     setAssistant(undefined);
     setMessages([]);
     setFailedMessageIds(new Set());
-    if (typeof window !== "undefined") {
+    if (manageUrl && typeof window !== "undefined") {
       window.history.replaceState(null, "", "/assistants");
     }
-  }, []);
+  }, [manageUrl]);
 
   const deleteThread = useCallback(async (id: string) => {
     await AssistantService.delete({ id });

package/src/features/assistant/contexts/__tests__/AssistantContext.spec.tsx

@@ -264,7 +264,7 @@ describe("AssistantContext", () => {
 
     // Before the server responds, the optimistic user bubble must be visible.
     expect(result.current.messages.map((m) => m.content)).toContain("follow-up");
-    expect(result.current.messages.some((m) => m.id.startsWith("tmp-") && m.role === "user")).toBe(true);
+    expect(result.current.messages.some((m) => m.isOptimistic && m.role === "user")).toBe(true);
     expect(result.current.sending).toBe(true);
 
     await act(async () => {
@@ -276,7 +276,7 @@ describe("AssistantContext", () => {
     });
 
     // After reconciliation, no tmp-* remains, and server messages are appended.
-    expect(result.current.messages.some((m) => m.id.startsWith("tmp-"))).toBe(false);
+    expect(result.current.messages.some((m) => m.isOptimistic)).toBe(false);
     expect(result.current.messages.map((m) => m.content)).toEqual(["follow-up", "reply"]);
     expect(result.current.sending).toBe(false);
   });
@@ -307,7 +307,7 @@ describe("AssistantContext", () => {
 
     // Before the server responds: thread has exactly the optimistic user bubble.
     expect(result.current.messages).toHaveLength(1);
-    expect(result.current.messages[0].id.startsWith("tmp-")).toBe(true);
+    expect(result.current.messages[0].isOptimistic).toBe(true);
     expect(result.current.messages[0].content).toBe("first question");
     expect(result.current.assistant).toBeUndefined();
     expect(result.current.sending).toBe(true);
@@ -319,11 +319,71 @@ describe("AssistantContext", () => {
 
     // After reconciliation: assistant set, URL replaced, server messages only.
     expect(result.current.assistant?.id).toBe("a-1");
-    expect(result.current.messages.some((m) => m.id.startsWith("tmp-"))).toBe(false);
+    expect(result.current.messages.some((m) => m.isOptimistic)).toBe(false);
     expect(result.current.messages).toHaveLength(2);
     expect(replaceState).toHaveBeenCalledWith(null, "", "/assistants/a-1");
   });
 
+  it("forwards howToMode to AssistantService.create on first send", async () => {
+    const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+    const created = buildAssistantStub({ id: "a-1" });
+    AssistantService.create = vi.fn().mockResolvedValue(created);
+    AssistantMessageService.findByAssistant = vi.fn().mockResolvedValue([]);
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider>{children}</AssistantProvider>,
+    });
+    await act(async () => {
+      await result.current.sendMessage("hi", { howToMode: true });
+    });
+
+    expect(AssistantService.create).toHaveBeenCalledWith(
+      expect.objectContaining({ firstMessage: "hi", howToMode: true }),
+    );
+    replaceState.mockRestore();
+  });
+
+  it("forwards howToMode to AssistantService.appendMessage on follow-up send", async () => {
+    const existing = buildAssistantDehydrated({ id: "a-2", title: "Existing" });
+    AssistantService.appendMessage = vi.fn().mockResolvedValue([]);
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider dehydratedAssistant={existing}>{children}</AssistantProvider>,
+    });
+    await act(async () => {
+      await result.current.sendMessage("follow up", { howToMode: true, limitToHowToId: "ht-1" });
+    });
+
+    expect(AssistantService.appendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        assistantId: "a-2",
+        content: "follow up",
+        howToMode: true,
+        limitToHowToId: "ht-1",
+      }),
+    );
+  });
+
+  it("calls service without opts when called with content only (regression)", async () => {
+    const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+    const created = buildAssistantStub({ id: "a-1" });
+    AssistantService.create = vi.fn().mockResolvedValue(created);
+    AssistantMessageService.findByAssistant = vi.fn().mockResolvedValue([]);
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider>{children}</AssistantProvider>,
+    });
+    await act(async () => {
+      await result.current.sendMessage("hi");
+    });
+
+    expect(AssistantService.create).toHaveBeenCalledWith(expect.objectContaining({ firstMessage: "hi" }));
+    const call = (AssistantService.create as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    expect(call.howToMode).toBeUndefined();
+    expect(call.limitToHowToId).toBeUndefined();
+    replaceState.mockRestore();
+  });
+
   it("sendMessage failure: optimistic message stays and its id lands in failedMessageIds", async () => {
     const existing = buildAssistantDehydrated({ id: "a-x", title: "Ex" });
     AssistantService.appendMessage = vi.fn().mockRejectedValue(new Error("boom"));
@@ -335,7 +395,7 @@ describe("AssistantContext", () => {
       await result.current.sendMessage("oops").catch(() => {});
     });
 
-    const optimistic = result.current.messages.find((m) => m.id.startsWith("tmp-"));
+    const optimistic = result.current.messages.find((m) => m.isOptimistic);
     expect(optimistic).toBeDefined();
     expect(optimistic!.content).toBe("oops");
     expect(result.current.failedMessageIds.has(optimistic!.id)).toBe(true);
@@ -368,7 +428,7 @@ describe("AssistantContext", () => {
     });
 
     expect(result.current.failedMessageIds.has(failedId!)).toBe(false);
-    expect(result.current.messages.some((m) => m.id.startsWith("tmp-"))).toBe(false);
+    expect(result.current.messages.some((m) => m.isOptimistic)).toBe(false);
     expect(result.current.messages.map((m) => m.content)).toEqual(["retry-me", "ok"]);
     expect(appendMock).toHaveBeenCalledTimes(2);
   });

package/src/features/assistant/data/Assistant.ts

@@ -29,6 +29,8 @@ export class Assistant extends AbstractApiData implements AssistantInterface {
         attributes: {
           content: data.firstMessage,
           ...(data.title !== undefined ? { title: data.title } : {}),
+          ...(data.howToMode !== undefined ? { howToMode: data.howToMode } : {}),
+          ...(data.limitToHowToId !== undefined ? { limitToHowToId: data.limitToHowToId } : {}),
         },
       },
       included: [],

package/src/features/assistant/data/AssistantInterface.ts

@@ -3,6 +3,8 @@ import { ApiDataInterface } from "../../../core";
 export type AssistantInput = {
   firstMessage: string;
   title?: string;
+  howToMode?: boolean;
+  limitToHowToId?: string;
 };
 
 export interface AssistantInterface extends ApiDataInterface {

package/src/features/assistant/data/AssistantService.ts

@@ -1,6 +1,7 @@
 import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
-import { AssistantInput, AssistantInterface } from "./AssistantInterface";
+import { AssistantMessage } from "../../assistant-message/data/AssistantMessage";
 import { AssistantMessageInterface } from "../../assistant-message/data/AssistantMessageInterface";
+import { AssistantInput, AssistantInterface } from "./AssistantInterface";
 
 export class AssistantService extends AbstractService {
   static async findOne(params: { id: string }): Promise<AssistantInterface> {
@@ -33,8 +34,18 @@ export class AssistantService extends AbstractService {
   /**
    * Sends a new user message to an existing assistant thread. The agent turn
    * runs synchronously; the response is a two-element list: [user, assistant].
+   *
+   * Uses the dedicated AssistantMessage.createAppendMessageJsonApi method to
+   * build the JSON:API envelope; this is the architecture-compliant pairing
+   * with `overridesJsonApiCreation: true`.
    */
-  static async appendMessage(params: { assistantId: string; content: string }): Promise<AssistantMessageInterface[]> {
+  static async appendMessage(params: {
+    assistantId: string;
+    content: string;
+    howToMode?: boolean;
+    limitToHowToId?: string;
+  }): Promise<AssistantMessageInterface[]> {
+    const message = new AssistantMessage();
     return this.callApi<AssistantMessageInterface[]>({
       type: Modules.AssistantMessage,
       method: HttpMethod.POST,
@@ -43,12 +54,11 @@ export class AssistantService extends AbstractService {
         id: params.assistantId,
         childEndpoint: Modules.AssistantMessage,
       }).generate(),
-      input: {
-        data: {
-          type: Modules.AssistantMessage.name,
-          attributes: { content: params.content },
-        },
-      },
+      input: message.createAppendMessageJsonApi({
+        content: params.content,
+        howToMode: params.howToMode,
+        limitToHowToId: params.limitToHowToId,
+      }),
       overridesJsonApiCreation: true,
     });
   }

package/src/features/assistant-message/components/parts/MessageSourcesPanel.tsx

@@ -55,12 +55,14 @@ export function MessageSourcesPanel({ message, isLatestAssistant, onSelectFollow
   const suggestionsCount = isLatestAssistant ? message.suggestedQuestions.length : 0;
 
   const contentsCount = useMemo(() => {
-    if (sources) return sources.size;
-    // Fallback: derive from unique nodeId on chunks when sources haven't been
-    // supplied yet (e.g., during the initial fetch).
+    // Count unique nodeIds across citations. Mirrors what ContentsTab actually
+    // renders (one row per cited source), instead of `sources.size` which can
+    // include entities the fetch returned but no citation references.
     const ids = new Set<string>();
     for (const c of message.citations) {
-      if (c.nodeId) ids.add(c.nodeId);
+      if (!c.nodeId) continue;
+      if (sources && !sources.has(c.nodeId)) continue;
+      ids.add(c.nodeId);
     }
     return ids.size;
   }, [message.citations, sources]);

package/src/features/assistant-message/components/parts/tabs/ContentsTab.tsx

@@ -64,7 +64,11 @@ export function ContentsTab({ citations, sources }: Props) {
           } catch {
             return null;
           }
-          const href = generate({ page: module, id: source.id });
+          // Help-content HowTos are public articles, not admin records: route to
+          // /help/<mode>/<slug> instead of the module's /administration/howtos
+          // page when the entity carries a helpContentSlug.
+          const helpContentSlug = (source as any).helpContentSlug as string | undefined;
+          const href = helpContentSlug ? `/help/${helpContentSlug}` : generate({ page: module, id: source.id });
           const name = (source as any).name ?? source.identifier;
           return (
             <TableRow key={`${source.type}/${source.id}`}>

package/src/features/assistant-message/components/parts/tabs/ReferencesTab.tsx

@@ -33,7 +33,8 @@ export function ReferencesTab({ references }: Props) {
           } catch {
             return null;
           }
-          const href = generate({ page: module, id: ref.id });
+          const helpContentSlug = (ref as any).helpContentSlug as string | undefined;
+          const href = helpContentSlug ? `/help/${helpContentSlug}` : generate({ page: module, id: ref.id });
           return (
             <TableRow key={`${ref.type}/${ref.id}`}>
               <TableCell>