@carlonicora/nextjs-jsonapi 3.12.0 → 3.14.0

package/src/components/containers/ReactMarkdownContainer.tsx

@@ -4,8 +4,34 @@ import { ChevronDown, ChevronUp } from "lucide-react";
 import { useTranslations } from "next-intl";
 import { useEffect, useRef, useState } from "react";
 import ReactMarkdown from "react-markdown";
+import rehypeSlug from "rehype-slug";
 import remarkGfm from "remark-gfm";
 
+import { cn } from "../../utils/cn";
+import { MermaidDiagram } from "./MermaidDiagram";
+
+/**
+ * The source of a ```mermaid fence, or `undefined` for any other `pre`.
+ *
+ * Reads react-markdown's hast node rather than the rendered children: the
+ * language lives in the inner `code` element's `language-*` class, and the
+ * source is its raw text. Pulling it off the React children would mean
+ * unpicking elements that the `code` override has already transformed.
+ */
+function mermaidSourceOf(node: unknown): string | undefined {
+  const pre = node as { children?: { tagName?: string; properties?: { className?: unknown }; children?: unknown[] }[] };
+  const code = pre?.children?.[0];
+  if (code?.tagName !== "code") return undefined;
+
+  const classNames = Array.isArray(code.properties?.className) ? (code.properties.className as string[]) : [];
+  if (!classNames.includes("language-mermaid")) return undefined;
+
+  const text = code.children?.[0] as { type?: string; value?: string } | undefined;
+  if (text?.type !== "text" || typeof text.value !== "string") return undefined;
+
+  return text.value;
+}
+
 type ReactMarkdownContainerProps = {
   content: string;
   collapsible?: boolean;
@@ -52,10 +78,34 @@ export function ReactMarkdownContainer({
         <div ref={contentRef} style={clampStyle} className="transition-all duration-300 ease-in-out">
           <ReactMarkdown
             remarkPlugins={[remarkGfm]}
+            // `rehype-slug` puts a stable `id` on every heading. Nothing linked
+            // to a heading before, so no markdown surface in the package could
+            // carry an in-page table of contents; the handbook reader's one
+            // reads these ids straight out of the DOM.
+            rehypePlugins={[rehypeSlug]}
             components={{
-              p: ({ children }) => <p className={size === "small" ? "text-xs" : ""}>{children}</p>,
-              li: ({ children }) => <li className={size === "small" ? "text-xs" : ""}>{children}</li>,
-              table: ({ children }) => <table className="w-full table-auto border-collapse border">{children}</table>,
+              // `overflow-wrap:anywhere`, not `break-words`: prose here is full
+              // of file paths, and there is no space in
+              // `packages/nestjs-neo4jsonapi/src/core/health.controller.ts` for
+              // `break-words` to break at. Without it one path widens the page
+              // and the whole layout scrolls sideways.
+              p: ({ children }) => (
+                <p className={cn("[overflow-wrap:anywhere]", size === "small" && "text-xs")}>{children}</p>
+              ),
+              li: ({ children }) => (
+                <li className={cn("[overflow-wrap:anywhere]", size === "small" && "text-xs")}>{children}</li>
+              ),
+              // Wrapped in its own scroller for the same reason as `pre`: a
+              // three-column table of file paths is wider than any reading
+              // column, and unwrapped it drags the page sideways with it.
+              table: ({ children }) => (
+                <div className="overflow-x-auto">
+                  {/* `min-w-max` so columns keep their natural width and the
+                      wrapper scrolls, rather than the table squeezing until a
+                      path breaks mid-word inside a cell. */}
+                  <table className="w-full min-w-max table-auto border-collapse border">{children}</table>
+                </div>
+              ),
               th: ({ children }) => (
                 <th className={`border px-4 py-2 text-start ${size === "small" ? "px-2 py-1 text-xs" : ""}`}>
                   {children}
@@ -73,37 +123,70 @@ export function ReactMarkdownContainer({
               // left-to-right in every locale, so both the fenced block and the
               // inline span are deliberate LTR islands. `node` is react-markdown's
               // hast node — it must not reach the DOM element.
+              // A ```mermaid fence is a DIAGRAM, not code. It is caught here on
+              // the `pre` rather than on the `code` inside it, because the
+              // diagram replaces the whole block — catching it a level down
+              // would leave it wrapped in the `pre` chrome it is not.
+              //
+              // A fenced block otherwise scrolls on its own rather than
+              // widening the page: a long command line is unbreakable, and
+              // without this the whole layout is pushed sideways.
               // rtl-ok: deliberate LTR island (code)
-              pre: ({ children, node: _node, ...props }) => (
-                <pre dir="ltr" {...props}>
-                  {children}
-                </pre>
-              ),
+              pre: ({ children, node, ...props }) => {
+                const diagram = mermaidSourceOf(node);
+                if (diagram !== undefined) return <MermaidDiagram chart={diagram} />;
+
+                return (
+                  <pre dir="ltr" {...props} className="overflow-x-auto">
+                    {children}
+                  </pre>
+                );
+              },
+              // No wrap rule HERE. The same component renders inline spans, the
+              // contents of fenced blocks and the contents of table cells; the
+              // last two live in their own scrollers, and breaking a path
+              // mid-word inside them is worse than scrolling to it. The rule
+              // that catches inline code sits on `p` and `li`, which is where
+              // inline code actually lives.
               // rtl-ok: deliberate LTR island (code)
               code: ({ children, node: _node, ...props }) => (
                 <code dir="ltr" {...props}>
                   {children}
                 </code>
               ),
-              h1: ({ children }) => (
-                <h1 className={size === "small" ? "my-1 mt-2 text-sm font-bold" : "my-2 mt-4 text-3xl font-semibold"}>
+              // The heading overrides spread the node's props, exactly as `pre`
+              // and `code` already do: dropping them would throw away the `id`
+              // rehype-slug just set and leave every heading unlinkable again.
+              // `node` is react-markdown's hast node — it must not reach the DOM.
+              h1: ({ children, node: _node, ...props }) => (
+                <h1
+                  {...props}
+                  className={size === "small" ? "my-1 mt-2 text-sm font-bold" : "my-2 mt-4 text-3xl font-semibold"}
+                >
                   {children}
                 </h1>
               ),
-              h2: ({ children }) => (
+              h2: ({ children, node: _node, ...props }) => (
                 <h2
+                  {...props}
                   className={size === "small" ? "my-1 mt-2 text-sm font-semibold" : "my-2 mt-4 text-2xl font-semibold"}
                 >
                   {children}
                 </h2>
               ),
-              h3: ({ children }) => (
-                <h3 className={size === "small" ? "my-1 mt-2 text-sm font-medium" : "my-2 mt-4 text-xl font-semibold"}>
+              h3: ({ children, node: _node, ...props }) => (
+                <h3
+                  {...props}
+                  className={size === "small" ? "my-1 mt-2 text-sm font-medium" : "my-2 mt-4 text-xl font-semibold"}
+                >
                   {children}
                 </h3>
               ),
-              h4: ({ children }) => (
-                <h4 className={size === "small" ? "my-1 mt-2 text-sm font-medium" : "my-2 mt-4 text-lg font-semibold"}>
+              h4: ({ children, node: _node, ...props }) => (
+                <h4
+                  {...props}
+                  className={size === "small" ? "my-1 mt-2 text-sm font-medium" : "my-2 mt-4 text-lg font-semibold"}
+                >
                   {children}
                 </h4>
               ),

package/src/components/containers/index.ts

@@ -1,5 +1,6 @@
 export * from "./PageContainer";
 export * from "./partitionTabs";
+export * from "./MermaidDiagram";
 export * from "./ReactMarkdownContainer";
 export * from "./RoundPageContainer";
 export * from "./RoundPageContainerTitle";

package/src/components/index.ts

@@ -26,6 +26,7 @@ export * from "../features/ai-connection";
 export * from "../features/company/components";
 export * from "../features/content/components";
 export * from "../features/how-to/components";
+export * from "../features/handbook/components";
 export * from "../features/assistant/components";
 export * from "../features/assistant-message/components";
 export * from "../features/assistant-action/components";

package/src/core/index.ts

@@ -67,6 +67,11 @@ export * from "../features/content/content.module";
 export * from "../features/content/data";
 export * from "../features/how-to/HowToModule";
 export * from "../features/how-to/data";
+export * from "../features/handbook/HandbookPageModule";
+export * from "../features/handbook/HandbookSectionModule";
+export * from "../features/handbook/HandbookThreadMessageModule";
+export * from "../features/handbook/HandbookThreadModule";
+export * from "../features/handbook/data";
 export * from "../features/assistant/AssistantModule";
 export * from "../features/assistant/data";
 export * from "../features/assistant-message/AssistantMessageModule";

package/src/core/registry/ModuleRegistry.ts

@@ -16,6 +16,10 @@ export interface FoundationModuleDefinitions {
   Module: ModuleWithPermissions;
   Content: ModuleWithPermissions;
   HowTo: ModuleWithPermissions;
+  HandbookPage: ModuleWithPermissions;
+  HandbookSection: ModuleWithPermissions;
+  HandbookThread: ModuleWithPermissions;
+  HandbookThreadMessage: ModuleWithPermissions;
   Assistant: ModuleWithPermissions;
   AssistantMessage: ModuleWithPermissions;
   AssistantAction: ModuleWithPermissions;

package/src/features/assistant/components/parts/AssistantComposer.tsx

@@ -10,9 +10,28 @@ interface Props {
   disabled?: boolean;
   value?: string;
   onValueChange?: (v: string) => void;
+  /**
+   * Textarea placeholder. Defaults to the assistant's own copy ("ask me about a
+   * matter, a client, a document…"), which is wrong on any surface that is not
+   * the law-firm assistant.
+   */
+  placeholder?: string;
+  /**
+   * Label of the send button. Defaults to `ui.buttons.save`, which reads
+   * "Salva" — correct nowhere in a chat, kept only so existing callers do not
+   * move.
+   */
+  sendLabel?: string;
 }
 
-export function AssistantComposer({ onSend, disabled, value: controlled, onValueChange }: Props) {
+export function AssistantComposer({
+  onSend,
+  disabled,
+  value: controlled,
+  onValueChange,
+  placeholder,
+  sendLabel,
+}: Props) {
   const t = useTranslations();
   const [internal, setInternal] = useState("");
   const value = controlled ?? internal;
@@ -41,13 +60,13 @@ export function AssistantComposer({ onSend, disabled, value: controlled, onValue
           value={value}
           onChange={(e) => setValue(e.target.value)}
           onKeyDown={onKeyDown}
-          placeholder={t("features.assistant.composer_placeholder")}
+          placeholder={placeholder ?? t("features.assistant.composer_placeholder")}
           disabled={disabled}
           rows={2}
           className="min-h-[48px] resize-none border-0 bg-transparent focus-visible:ring-0"
         />
         <Button onClick={submit} disabled={!canSend} size="sm" className="h-8">
-          <ArrowUp className="me-1 h-4 w-4" /> {t("features.assistant.send")}
+          <ArrowUp className="me-1 h-4 w-4" /> {sendLabel ?? t("features.assistant.send")}
         </Button>
       </div>
       <div className="text-muted-foreground text-end text-xs">{t("features.assistant.keyboard_hint")}</div>

package/src/features/assistant/components/parts/AssistantSidebar.tsx

@@ -12,9 +12,17 @@ interface Props {
   activeId?: string;
   onSelect: (id: string) => void;
   onNew: () => void;
+  /**
+   * Label of the "start a new thread" button. Defaults to the assistant's own
+   * copy; a surface that is not the assistant (the handbook chat) passes its
+   * own so the control does not read "New assistant" on a handbook page.
+   */
+  newLabel?: string;
+  /** Shown when there are no threads. Same rationale as `newLabel`. */
+  emptyLabel?: string;
 }
 
-export function AssistantSidebar({ threads, activeId, onSelect, onNew }: Props) {
+export function AssistantSidebar({ threads, activeId, onSelect, onNew, newLabel, emptyLabel }: Props) {
   const t = useTranslations();
   const groups = groupThreadsByBucket(threads);
 
@@ -44,12 +52,14 @@ export function AssistantSidebar({ threads, activeId, onSelect, onNew }: Props)
     <aside className="bg-muted/30 flex w-64 flex-col border-e">
       <div className="border-b p-3">
         <Button onClick={onNew} className="w-full" size="sm">
-          <Plus className="me-1 h-4 w-4" /> {t("features.assistant.new")}
+          <Plus className="me-1 h-4 w-4" /> {newLabel ?? t("features.assistant.new")}
         </Button>
       </div>
       <div className="flex-1 overflow-y-auto p-2">
         {threads.length === 0 ? (
-          <div className="text-muted-foreground mt-6 text-center text-xs">{t("features.assistant.empty_sidebar")}</div>
+          <div className="text-muted-foreground mt-6 text-center text-xs">
+            {emptyLabel ?? t("features.assistant.empty_sidebar")}
+          </div>
         ) : (
           <>
             {renderSection(t("features.assistant.bucket_today"), groups.today)}

package/src/features/assistant/components/parts/AssistantThreadHeader.tsx

@@ -21,9 +21,16 @@ interface Props {
   assistant: AssistantInterface;
   onRename: (title: string) => Promise<void>;
   onDelete: () => Promise<void>;
+  /**
+   * Placeholder of the rename field. Defaults to the assistant's own copy
+   * ("name this assistant"), which misnames the thread on any other surface.
+   */
+  renamePlaceholder?: string;
+  /** Body of the delete confirmation. Same rationale as `renamePlaceholder`. */
+  deleteConfirmLabel?: string;
 }
 
-export function AssistantThreadHeader({ assistant, onRename, onDelete }: Props) {
+export function AssistantThreadHeader({ assistant, onRename, onDelete, renamePlaceholder, deleteConfirmLabel }: Props) {
   const t = useTranslations();
   const [renameValue, setRenameValue] = useState(assistant.title);
   const [renameOpen, setRenameOpen] = useState(false);
@@ -56,7 +63,7 @@ export function AssistantThreadHeader({ assistant, onRename, onDelete }: Props)
             <Input
               value={renameValue}
               onChange={(e) => setRenameValue(e.target.value)}
-              placeholder={t("features.assistant.rename_placeholder")}
+              placeholder={renamePlaceholder ?? t("features.assistant.rename_placeholder")}
             />
             <Button onClick={handleRename} size="sm">
               {t("ui.buttons.save")}
@@ -73,7 +80,7 @@ export function AssistantThreadHeader({ assistant, onRename, onDelete }: Props)
           />
           <DialogContent>
             <DialogHeader>
-              <DialogTitle>{t("features.assistant.delete_confirm")}</DialogTitle>
+              <DialogTitle>{deleteConfirmLabel ?? t("features.assistant.delete_confirm")}</DialogTitle>
             </DialogHeader>
             <DialogFooter>
               <Button variant="outline" onClick={() => setDeleteOpen(false)}>

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

@@ -22,7 +22,13 @@ interface AssistantContextValue {
   failedMessageIds: Set<string>;
   sendMessage(
     content: string,
-    opts?: { howToMode?: boolean; limitToHowToId?: string; contentBlocks?: unknown[] },
+    opts?: {
+      howToMode?: boolean;
+      limitToHowToId?: string;
+      handbookMode?: boolean;
+      limitToHandbookPageId?: string;
+      contentBlocks?: unknown[];
+    },
   ): Promise<void>;
   retrySend(tempId: string): Promise<void>;
   selectThread(id: string): Promise<void>;
@@ -55,6 +61,13 @@ interface Props {
    * it, so a scoped surface never shows or creates cross-scope threads.
    */
   scope?: { type: string; id: string };
+  /**
+   * Confines every turn of this provider to one retrieval mode. The handbook
+   * surface sets `{ handbookMode: true }` so the flag does not have to be
+   * threaded through the composer on each send — the same reason `scope`
+   * exists on this provider.
+   */
+  retrievalMode?: { handbookMode?: boolean; limitToHandbookPageId?: string };
   /**
    * Builds the browser URL for a thread. Defaults to `/assistants/{id}` (or
    * `/assistants` when no thread is active), which is only correct for the
@@ -100,6 +113,7 @@ export function AssistantProvider({
   titleOverride,
   breadcrumbsOverride,
   scope,
+  retrievalMode,
   threadUrl,
 }: Props) {
   const t = useTranslations();
@@ -130,7 +144,16 @@ export function AssistantProvider({
   const { socket } = useSocketContext();
 
   const sendMessage = useCallback(
-    async (content: string, opts?: { howToMode?: boolean; limitToHowToId?: string; contentBlocks?: unknown[] }) => {
+    async (
+      content: string,
+      opts?: {
+        howToMode?: boolean;
+        limitToHowToId?: string;
+        handbookMode?: boolean;
+        limitToHandbookPageId?: string;
+        contentBlocks?: unknown[];
+      },
+    ) => {
       const trimmed = content.trim();
       if (!trimmed) return;
 
@@ -155,6 +178,8 @@ export function AssistantProvider({
             firstMessage: trimmed,
             howToMode: opts?.howToMode,
             limitToHowToId: opts?.limitToHowToId,
+            handbookMode: opts?.handbookMode ?? retrievalMode?.handbookMode,
+            limitToHandbookPageId: opts?.limitToHandbookPageId ?? retrievalMode?.limitToHandbookPageId,
             contentBlocks: opts?.contentBlocks,
             boundContent: scope,
           };
@@ -180,6 +205,8 @@ export function AssistantProvider({
                 content: trimmed,
                 howToMode: opts?.howToMode,
                 limitToHowToId: opts?.limitToHowToId,
+                handbookMode: opts?.handbookMode ?? retrievalMode?.handbookMode,
+                limitToHandbookPageId: opts?.limitToHandbookPageId ?? retrievalMode?.limitToHandbookPageId,
                 contentBlocks: opts?.contentBlocks,
               });
           setMessages((prev) => [...stripOptimistic(prev), ...result]);
@@ -196,7 +223,7 @@ export function AssistantProvider({
         setStatus(undefined);
       }
     },
-    [assistant, messages, socket, operatorMode, scope, manageUrl, resolveThreadUrl],
+    [assistant, messages, socket, operatorMode, scope, retrievalMode, manageUrl, resolveThreadUrl],
   );
 
   const appendResolvedMessage = useCallback((message: AssistantMessageInterface) => {

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

@@ -455,6 +455,38 @@ describe("AssistantContext", () => {
     );
   });
 
+  it("forwards handbookMode passed on the send", async () => {
+    const existing = buildAssistantDehydrated({ id: "a-3", 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("Come funziona il modulo chunk?", { handbookMode: true });
+    });
+
+    expect(AssistantService.appendMessage).toHaveBeenCalledWith(expect.objectContaining({ handbookMode: true }));
+  });
+
+  it("forwards the provider's retrievalMode when the send passes nothing", async () => {
+    const existing = buildAssistantDehydrated({ id: "a-4", title: "Existing" });
+    AssistantService.appendMessage = vi.fn().mockResolvedValue([]);
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => (
+        <AssistantProvider dehydratedAssistant={existing} retrievalMode={{ handbookMode: true }}>
+          {children}
+        </AssistantProvider>
+      ),
+    });
+    await act(async () => {
+      await result.current.sendMessage("Come funziona il modulo chunk?");
+    });
+
+    expect(AssistantService.appendMessage).toHaveBeenCalledWith(expect.objectContaining({ handbookMode: true }));
+  });
+
   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" });

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

@@ -58,6 +58,8 @@ export class Assistant extends AbstractApiData implements AssistantInterface {
           ...(data.title !== undefined ? { title: data.title } : {}),
           ...(data.howToMode !== undefined ? { howToMode: data.howToMode } : {}),
           ...(data.limitToHowToId !== undefined ? { limitToHowToId: data.limitToHowToId } : {}),
+          ...(data.handbookMode !== undefined ? { handbookMode: data.handbookMode } : {}),
+          ...(data.limitToHandbookPageId !== undefined ? { limitToHandbookPageId: data.limitToHandbookPageId } : {}),
         },
         ...(data.boundContent !== undefined
           ? {

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

@@ -5,6 +5,8 @@ export type AssistantInput = {
   title?: string;
   howToMode?: boolean;
   limitToHowToId?: string;
+  handbookMode?: boolean;
+  limitToHandbookPageId?: string;
   /**
    * BlockNote document behind `firstMessage`. Sent alongside the flattened
    * text so the server can re-derive the content and read `@`-mentions from

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

@@ -67,6 +67,8 @@ export class AssistantService extends AbstractService {
     content: string;
     howToMode?: boolean;
     limitToHowToId?: string;
+    handbookMode?: boolean;
+    limitToHandbookPageId?: string;
     /** BlockNote document. Serialised by the model into `content`; never its own attribute. */
     contentBlocks?: unknown[];
   }): Promise<AssistantMessageInterface[]> {
@@ -83,6 +85,8 @@ export class AssistantService extends AbstractService {
         content: params.content,
         howToMode: params.howToMode,
         limitToHowToId: params.limitToHowToId,
+        handbookMode: params.handbookMode,
+        limitToHandbookPageId: params.limitToHandbookPageId,
         contentBlocks: params.contentBlocks,
       }),
       overridesJsonApiCreation: true,

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

@@ -87,7 +87,11 @@ export function MessageSourcesContainer({ message, isLatestAssistant, onSelectFo
 
   useEffect(() => {
     if (groups.size === 0) {
-      setResolved([]);
+      // Functional update, and a no-op when it is already empty. A bare
+      // `setResolved([])` sets a NEW array on every run, so a caller whose
+      // `message.citations` identity changes per render loops here until React
+      // gives up with "Maximum update depth exceeded".
+      setResolved((current) => (current.length === 0 ? current : []));
       return;
     }
     let cancelled = false;

package/src/features/assistant-message/data/AssistantMessage.ts

@@ -129,6 +129,8 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
     content: string;
     howToMode?: boolean;
     limitToHowToId?: string;
+    handbookMode?: boolean;
+    limitToHandbookPageId?: string;
     contentBlocks?: unknown[];
   }) {
     return {
@@ -142,18 +144,41 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
           content: params.contentBlocks !== undefined ? JSON.stringify(params.contentBlocks) : params.content,
           ...(params.howToMode !== undefined ? { howToMode: params.howToMode } : {}),
           ...(params.limitToHowToId !== undefined ? { limitToHowToId: params.limitToHowToId } : {}),
+          ...(params.handbookMode !== undefined ? { handbookMode: params.handbookMode } : {}),
+          ...(params.limitToHandbookPageId !== undefined
+            ? { limitToHandbookPageId: params.limitToHandbookPageId }
+            : {}),
         },
       },
     };
   }
 
   static buildOptimistic(params: { content: string; position: number; assistantId?: string }): AssistantMessage {
+    return AssistantMessage.buildLocal({ ...params, role: "user", isOptimistic: true });
+  }
+
+  /**
+   * A message that exists only on the client, for a surface that renders the
+   * chat presentation without persisting a thread.
+   *
+   * `buildOptimistic` is the user-turn case and delegates here. The handbook
+   * ask surface is the other caller: it has no Assistant and no stored
+   * messages, but it renders through MessageList/MessageItem like every other
+   * chat in the product, so it needs both roles.
+   */
+  static buildLocal(params: {
+    role: AssistantMessageRole;
+    content: string;
+    position: number;
+    assistantId?: string;
+    isOptimistic?: boolean;
+  }): AssistantMessage {
     const msg = new AssistantMessage();
     const jsonApi: Record<string, unknown> = {
       id: uuidv4(),
       type: Modules.AssistantMessage.name,
       attributes: {
-        role: "user",
+        role: params.role,
         content: params.content,
         position: params.position,
       },
@@ -164,7 +189,7 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
       };
     }
     msg.rehydrate({ jsonApi: jsonApi as any, included: [] });
-    msg._isOptimistic = true;
+    msg._isOptimistic = params.isOptimistic ?? false;
     return msg;
   }
 }

package/src/features/content/data/content.interface.ts

@@ -5,7 +5,7 @@ export type ContentInput = {
   id: string;
   name?: string;
 
-  authorId: string;
+  authorId?: string;
   editorIds?: string[];
 };
 

package/src/features/handbook/HandbookPageModule.ts

@@ -0,0 +1,41 @@
+import { BookOpenIcon } from "lucide-react";
+import { createJsonApiInclusion } from "../../core";
+import { ModuleFactory } from "../../permissions";
+import { HandbookPage } from "./data/HandbookPage";
+
+export const HandbookPageModule = (factory: ModuleFactory) =>
+  factory({
+    moduleId: "b1f1c2d6-6a0e-4e93-9b6d-3f5f4a2c81e7",
+    pageUrl: "/administration/handbook",
+    name: "handbookpages",
+    model: HandbookPage,
+    icon: BookOpenIcon,
+    inclusions: {
+      lists: {
+        // `content` is deliberately omitted: the list renders titles and
+        // status, and a thousand pages of markdown do not belong in a list
+        // payload. `section`, `order` and `summary` are the index fields the
+        // contents page groups, orders and describes pages by, so they are the
+        // one part of the payload the list surface cannot do without.
+        //
+        // `displayTitle` and `displaySummary` are the translated halves of the
+        // two strings the contents page prints, and a sparse fieldset that
+        // omitted them would leave every row in English. `displayContent` is
+        // NOT here for the same reason `content` is not: it is the whole
+        // markdown body, and it belongs to the detail read alone.
+        fields: [
+          createJsonApiInclusion("handbookpages", [
+            "path",
+            "title",
+            "displayTitle",
+            "section",
+            "order",
+            "summary",
+            "displaySummary",
+            "wordCount",
+            "aiStatus",
+          ]),
+        ],
+      },
+    },
+  });

package/src/features/handbook/HandbookSectionModule.ts

@@ -0,0 +1,35 @@
+import { LibraryIcon } from "lucide-react";
+import { createJsonApiInclusion } from "../../core";
+import { ModuleFactory } from "../../permissions";
+import { HandbookSection } from "./data/HandbookSection";
+
+/**
+ * One top-level directory of the documentation tree. Like the thread message,
+ * it has no `pageUrl` — a section has no page of its own; it is a heading on
+ * the contents surface and nothing more.
+ */
+export const HandbookSectionModule = (factory: ModuleFactory) =>
+  factory({
+    moduleId: "6b0a2f74-1c53-4a0e-9c1d-2e7b4a9d6f30",
+    name: "handbooksections",
+    model: HandbookSection,
+    icon: LibraryIcon,
+    inclusions: {
+      lists: {
+        // `HandbookSectionService.findMany` is the ONLY read of this resource and
+        // it limits to these fields, so the translated halves have to be here:
+        // without them every section heading on the contents page and in the
+        // reader's navigator would stay English however good the translation is.
+        fields: [
+          createJsonApiInclusion("handbooksections", [
+            "key",
+            "title",
+            "displayTitle",
+            "summary",
+            "displaySummary",
+            "order",
+          ]),
+        ],
+      },
+    },
+  });