@carlonicora/nextjs-jsonapi 1.109.0 → 1.111.0

package/scripts/generate-web-module/templates/table-hook.template.ts

@@ -5,7 +5,7 @@
  */
 
 import { FrontendTemplateData, FrontendField } from "../types/template-data.interface";
-import { toCamelCase } from "../transformers/name-transformer";
+import { toCamelCase, pluralize } from "../transformers/name-transformer";
 
 /**
  * Generate the table structure hook file content
@@ -96,7 +96,7 @@ registerTableGenerator(Modules.${names.pascalCase}, use${names.pascalCase}TableS
  * Generate field column map entries
  */
 function generateFieldColumnEntries(data: FrontendTemplateData): string {
-  const { names, fields, extendsContent } = data;
+  const { names, fields, extendsContent, relationships } = data;
   const entries: string[] = [];
 
   // Name field (with link and tooltip for tldr if Content-extending)
@@ -183,8 +183,37 @@ function generateFieldColumnEntries(data: FrontendTemplateData): string {
       enableSorting: false,
       enableHiding: false,
     }),`);
+    } else if (field.type === "date" || field.type === "datetime") {
+      entries.push(`    [${names.pascalCase}Fields.${field.name}]: () =>
+      cellDate({
+        name: "${field.name}",
+        title: t(\`features.${names.camelCase}.fields.${field.name}.label\`),
+      }),`);
     }
   });
 
+  // Relationship columns (rendered when flagged for table display)
+  relationships
+    .filter((rel) => rel.showInTable)
+    .forEach((rel) => {
+      const key = rel.single
+        ? toCamelCase(rel.alias || rel.variant || rel.name)
+        : pluralize(toCamelCase(rel.alias || rel.name));
+      const accessor = rel.single
+        ? `${names.camelCase}.${key}?.name ?? ""`
+        : `${names.camelCase}.${key}.map((r) => r.name).join(", ")`;
+      entries.push(`    [${names.pascalCase}Fields.${key}]: () => ({
+      id: "${key}",
+      accessorKey: "${key}",
+      header: t(\`generic.relationships.${key}.label\`),
+      cell: ({ row }: { row: TableContent<${names.pascalCase}Interface> }) => {
+        const ${names.camelCase}: ${names.pascalCase}Interface = row.original.jsonApiData;
+        return <span>{${accessor}}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),`);
+    });
+
   return entries.join("\n");
 }

package/scripts/generate-web-module/transformers/import-resolver.ts

@@ -177,7 +177,6 @@ export interface ModuleFilePaths {
   selector: string;
   multiSelector: string;
   list: string;
-  details: string;
   content: string;
   container: string;
   listContainer: string;
@@ -220,7 +219,6 @@ export function buildFilePaths(
     selector: `${basePath}/components/forms/${names.pascalCase}Selector.tsx`,
     multiSelector: `${basePath}/components/forms/${names.pascalCase}MultiSelector.tsx`,
     list: `${basePath}/components/lists/${names.pascalCase}List.tsx`,
-    details: `${basePath}/components/details/${names.pascalCase}Details.tsx`,
     content: `${basePath}/components/details/${names.pascalCase}Content.tsx`,
     container: `${basePath}/components/containers/${names.pascalCase}Container.tsx`,
     listContainer: `${basePath}/components/containers/${names.pascalCase}ListContainer.tsx`,

package/scripts/generate-web-module/transformers/relationship-key.ts

@@ -0,0 +1,18 @@
+import { FrontendRelationship } from "../types/template-data.interface";
+import { toKebabCase, pluralize } from "./name-transformer";
+
+/** JSON:API wire key for a relationship. Schema dtoKey wins; otherwise derive
+ *  identically to the backend mapper so both sides of the wire agree. */
+export function resolveRelationshipKey(rel: FrontendRelationship): string {
+  if (rel.dtoKey) return rel.dtoKey;
+  // NOTE: Author relationships are normally NOT serialized through this helper — the backend
+  // special-cases Author via contextKey/currentUser and the model template skips Author
+  // serialization, so callers must not rely on this helper for Author wire keys.
+  if (rel.variant) {
+    return rel.single ? rel.variant.toLowerCase() : pluralize(rel.variant.toLowerCase());
+  }
+  if (rel.alias) {
+    return rel.single ? toKebabCase(rel.alias) : pluralize(toKebabCase(rel.alias));
+  }
+  return rel.single ? rel.name.toLowerCase() : pluralize(rel.name.toLowerCase());
+}

package/scripts/generate-web-module/transformers/relationship-resolver.ts

@@ -122,6 +122,8 @@ export function resolveRelationship(rel: JsonRelationshipDefinition, targetHasNa
     modelKebab,
     fields,
     targetHasName: targetHasNameMap?.get(rel.name) ?? true, // Foundation entities default to true
+    dtoKey: rel.dtoKey ?? "",
+    showInTable: rel.showInTable === true,
   };
 }
 

package/scripts/generate-web-module/types/json-schema.interface.ts

@@ -13,6 +13,7 @@ export interface JsonFieldDefinition {
   name: string;
   type: string;
   nullable: boolean;
+  readOnly?: boolean;
 }
 
 /**
@@ -29,6 +30,10 @@ export interface JsonRelationshipDefinition {
   toNode: boolean; // Backend-specific, ignored in frontend
   nullable: boolean;
   fields?: JsonFieldDefinition[]; // Relationship property fields (stored on edges)
+  /** Explicit JSON:API wire key. When absent it is derived identically to the backend mapper. */
+  dtoKey?: string;
+  description?: string;
+  showInTable?: boolean;
 }
 
 /**
@@ -44,4 +49,8 @@ export interface JsonModuleDefinition {
   relationships: JsonRelationshipDefinition[];
   /** Explicitly set whether this module extends Content. If not set, auto-detects based on fields. */
   extendsContent?: boolean;
+  featureId?: string;
+  displayProp?: string;
+  containerTabs?: { activity?: boolean; relations?: { module: string; listProp: string; directory: string }[] };
+  inclusions?: { related?: { endpoint: string; fields: string[] }[] };
 }

package/scripts/generate-web-module/types/template-data.interface.ts

@@ -30,6 +30,7 @@ export interface FrontendField {
   formComponent: FormComponentType;
   nullable: boolean;
   isContentField: boolean; // Indicates BlockNoteEditor
+  readOnly?: boolean;
 }
 
 /**
@@ -68,6 +69,8 @@ export interface FrontendRelationship {
   modelKebab: string; // e.g., "user"
   fields?: FrontendField[]; // Relationship property fields (stored on edges)
   targetHasName: boolean; // Whether the target entity has a "name" field (or extends Content)
+  dtoKey: string;       // resolved wire key; "" means derive at use-site
+  showInTable: boolean;
 }
 
 /**
@@ -153,6 +156,10 @@ export interface FrontendTemplateData {
 
   // For service generation
   relationshipServiceMethods: RelationshipServiceMethod[];
+  featureId?: string;
+  displayProp: string;
+  containerTabs: { activity: boolean; relations: { module: string; listProp: string; directory: string }[] };
+  relatedInclusions: { endpoint: string; fields: string[] }[];
 }
 
 /**

package/src/client/config.ts

@@ -18,7 +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.
+ * @param config.helpContent - Optional help-content config (brand only). Forwarded to the help feature's globalThis-backed store; not stored on the client config.
  */
 export function configureJsonApi(config: {
   apiUrl: string;

package/src/components/index.ts

@@ -6,6 +6,7 @@ export * from "./containers";
 export * from "./contents";
 export * from "./details";
 export * from "./editors";
+export { BlockNoteViewerContainer } from "./viewers/BlockNoteViewerContainer";
 export * from "./errors";
 export * from "./forms";
 export * from "./navigations";

package/src/components/viewers/BlockNoteViewer.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+import { useCreateBlockNote } from "@blocknote/react";
+import type { PartialBlock } from "@blocknote/core";
+// Mirror BlockNoteEditor.tsx's BlockNoteView import + style.css. Default schema
+// only — no useCurrentUserContext, uploadImage, AI, or custom inline specs, so
+// this can render on auth-free public pages.
+import { BlockNoteView } from "@blocknote/shadcn";
+import "@blocknote/shadcn/style.css";
+
+function normalize(content: unknown): PartialBlock[] | undefined {
+  if (Array.isArray(content) && content.length > 0) return content as PartialBlock[];
+  if (typeof content === "string" && content.trim()) {
+    try {
+      const parsed = JSON.parse(content);
+      if (Array.isArray(parsed) && parsed.length > 0) return parsed as PartialBlock[];
+    } catch {
+      /* plain string — fall through to undefined (rendered as empty) */
+    }
+  }
+  return undefined;
+}
+
+export function BlockNoteViewer({ content }: { content: unknown }) {
+  const editor = useCreateBlockNote({ initialContent: normalize(content) });
+  return <BlockNoteView editor={editor} editable={false} theme="light" />;
+}

package/src/components/viewers/BlockNoteViewerContainer.tsx

@@ -0,0 +1,10 @@
+"use client";
+
+import dynamic from "next/dynamic";
+import React from "react";
+
+const BlockNoteViewer = dynamic(() => import("./BlockNoteViewer").then((m) => m.BlockNoteViewer), { ssr: false });
+
+export const BlockNoteViewerContainer = React.memo(function ViewerContainer(props: { content: unknown }) {
+  return <BlockNoteViewer {...props} />;
+});

package/src/core/registry/helpStore.ts

@@ -1,32 +1,23 @@
 /**
  * Centralized help-content store accessible from client and server contexts.
- * Uses globalThis Symbol keys to persist across HMR/Turbopack reloads and to
+ * Uses a globalThis Symbol key 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).
+ * and the HelpProvider context. Holds the brand-only HelpContentConfig.
  *
  * 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;
@@ -35,11 +26,3 @@ export function _setStaticHelpContent(cfg: unknown | null): void {
 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-message/components/parts/MessageSourcesContainer.tsx

@@ -20,6 +20,10 @@ class SourcesFetcher extends ClientAbstractService {
   }): Promise<ApiDataInterface[]> {
     const endpoint = new EndpointCreator({ endpoint: params.module });
     endpoint.addAdditionalParam(params.idsParam, params.ids.join(","));
+    // The list endpoint paginates and does not honour the `<x>Ids` filter, so a cited
+    // entity beyond the default first page never comes back and its citation falls back
+    // to "<Type> <id>". Request the full set and resolve client-side by id.
+    endpoint.addAdditionalParam("fetchAll", "true");
     if (params.module.inclusions?.lists?.fields) endpoint.limitToFields(params.module.inclusions.lists.fields);
     if (params.module.inclusions?.lists?.types) endpoint.limitToType(params.module.inclusions.lists.types);
     return this.callApi<ApiDataInterface[]>({

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

@@ -64,11 +64,11 @@ export function ContentsTab({ citations, sources }: Props) {
           } catch {
             return null;
           }
-          // 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 });
+          // Help HowTos are public articles, not admin records: route to
+          // /help/<mode>/<slug> instead of the module's /administration/howtos page.
+          const howToType = (source as any).howToType as string | undefined;
+          const slug = (source as any).slug as string | undefined;
+          const href = howToType && slug ? `/help/${howToType}/${slug}` : 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,8 +33,9 @@ export function ReferencesTab({ references }: Props) {
           } catch {
             return null;
           }
-          const helpContentSlug = (ref as any).helpContentSlug as string | undefined;
-          const href = helpContentSlug ? `/help/${helpContentSlug}` : generate({ page: module, id: ref.id });
+          const howToType = (ref as any).howToType as string | undefined;
+          const slug = (ref as any).slug as string | undefined;
+          const href = howToType && slug ? `/help/${howToType}/${slug}` : generate({ page: module, id: ref.id });
           return (
             <TableRow key={`${ref.type}/${ref.id}`}>
               <TableCell>

package/src/features/help/components/HelpArticleBody.tsx

@@ -1,48 +1,56 @@
 "use client";
+
 import { ReactNode } from "react";
 import Link from "next/link";
 import { useFormatter, useTranslations } from "next-intl";
-import type { HelpArticle } from "../types/help-article.types";
 import { usePageUrlGenerator } from "../../../client";
-import { useHelp } from "../contexts/HelpContext";
-import { articleUrl } from "../utils/articleUrl";
-import { prevNextWithinMode } from "../utils/helpNavigation";
 
-export function HelpArticleBody({ article, children }: { article: HelpArticle; children: ReactNode }) {
+type Sibling = { howToType: string; slug: string; title: string };
+
+export function HelpArticleBody(props: {
+  howToType: string;
+  title: string;
+  summary?: string;
+  updatedAt?: string;
+  prev?: Sibling | null;
+  next?: Sibling | null;
+  children: ReactNode;
+}) {
   const t = useTranslations();
   const format = useFormatter();
   const generateUrl = usePageUrlGenerator();
-  const { manifest } = useHelp();
-  const { prev, next } = prevNextWithinMode(manifest, article);
+  const { howToType, title, summary, updatedAt, prev, next, children } = props;
 
   return (
     <article className="prose dark:prose-invert max-w-none">
       <nav className="text-muted-foreground mb-2 text-xs">
         <Link href={generateUrl({ page: "/help" })}>Help</Link>
         {" · "}
-        <Link href={generateUrl({ page: `/help/${article.mode}` })}>{t(`help.modes.${article.mode}`)}</Link>
+        <Link href={generateUrl({ page: `/help/${howToType}` })}>{t(`help.modes.${howToType}`)}</Link>
       </nav>
-      <h1>{article.title}</h1>
-      <p className="text-muted-foreground !mt-0 text-base">{article.summary}</p>
+      <h1>{title}</h1>
+      {summary ? <p className="text-muted-foreground !mt-0 text-base">{summary}</p> : null}
       {children}
       <hr className="my-6" />
-      <div className="text-muted-foreground text-xs">
-        <span>
-          {t("help.article.lastUpdated", {
-            date: format.dateTime(new Date(article.lastUpdated), { dateStyle: "short" }),
-          })}
-        </span>
-      </div>
+      {updatedAt ? (
+        <div className="text-muted-foreground text-xs">
+          <span>
+            {t("help.article.lastUpdated", {
+              date: format.dateTime(new Date(updatedAt), { dateStyle: "short" }),
+            })}
+          </span>
+        </div>
+      ) : null}
       <div className="mt-4 flex justify-between text-sm">
         {prev ? (
-          <Link href={articleUrl(generateUrl, prev)} className="hover:underline">
+          <Link href={generateUrl({ page: `/help/${prev.howToType}/${prev.slug}` })} className="hover:underline">
             ← {t("help.article.previous")}: {prev.title}
           </Link>
         ) : (
           <span />
         )}
         {next ? (
-          <Link href={articleUrl(generateUrl, next)} className="hover:underline">
+          <Link href={generateUrl({ page: `/help/${next.howToType}/${next.slug}` })} className="hover:underline">
             {t("help.article.next")}: {next.title} →
           </Link>
         ) : (

package/src/features/help/components/HelpHint.tsx

@@ -1,5 +1,5 @@
 "use client";
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { useTranslations } from "next-intl";
 import Link from "next/link";
 import { HelpCircleIcon } from "lucide-react";
@@ -13,20 +13,29 @@ import {
   SheetDescription,
 } from "../../../shadcnui";
 import { usePageUrlGenerator } from "../../../client";
-import { useHelp } from "../contexts/HelpContext";
-import { articleUrl } from "../utils/articleUrl";
-import type { HelpArticle } from "../types/help-article.types";
+import { HowToService } from "../../how-to/data/HowToService";
+import type { HowToInterface } from "../../how-to/data/HowToInterface";
 
 export function HelpHint({ contextKey }: { contextKey: string }) {
   const t = useTranslations();
   const generateUrl = usePageUrlGenerator();
-  const { manifest } = useHelp();
   const [open, setOpen] = useState(false);
-  const [picked, setPicked] = useState<HelpArticle | null>(null);
+  const [picked, setPicked] = useState<HowToInterface | null>(null);
+
+  const [articles, setArticles] = useState<HowToInterface[]>([]);
+  useEffect(() => {
+    let active = true;
+    HowToService.findPublished()
+      .then((list) => active && setArticles(list))
+      .catch(() => active && setArticles([]));
+    return () => {
+      active = false;
+    };
+  }, []);
 
   const matches = useMemo(
-    () => manifest.filter((a) => a.contextualKeys.includes(contextKey) && !a.draft),
-    [manifest, contextKey],
+    () => articles.filter((a) => a.contextualKeys.includes(contextKey) && !a.draft),
+    [articles, contextKey],
   );
 
   if (matches.length === 0) return null;
@@ -45,13 +54,13 @@ export function HelpHint({ contextKey }: { contextKey: string }) {
       </SheetTrigger>
       <SheetContent side="right" className="w-full max-w-md sm:max-w-lg">
         <SheetHeader>
-          <SheetTitle>{active ? active.title : t("help.hint.pickArticle")}</SheetTitle>
+          <SheetTitle>{active ? active.name : t("help.hint.pickArticle")}</SheetTitle>
           <SheetDescription>{active?.summary ?? ""}</SheetDescription>
         </SheetHeader>
         {active ? (
           <div className="mt-4 space-y-3">
             <p className="text-muted-foreground text-sm">{active.summary}</p>
-            <Link href={articleUrl(generateUrl, active)} className="text-sm">
+            <Link href={generateUrl({ page: `/help/${active.howToType}/${active.slug}` })} className="text-sm">
               {t("help.hint.viewArticle")}
             </Link>
           </div>
@@ -64,7 +73,7 @@ export function HelpHint({ contextKey }: { contextKey: string }) {
                   onClick={() => setPicked(a)}
                   className="hover:bg-muted block w-full rounded px-2 py-1 text-left text-sm"
                 >
-                  <div className="font-medium">{a.title}</div>
+                  <div className="font-medium">{a.name}</div>
                   <div className="text-muted-foreground text-xs">{a.summary}</div>
                 </button>
               </li>

package/src/features/help/components/HelpSearchResultRow.tsx

@@ -1,10 +1,12 @@
 "use client";
 import Link from "next/link";
 import { useTranslations } from "next-intl";
+import { useEffect, useState } from "react";
 import { LifeBuoyIcon, ArrowUpRightIcon } from "lucide-react";
 import { CommandItem } from "../../../shadcnui";
 import { usePageUrlGenerator } from "../../../client";
-import { useHelp } from "../contexts/HelpContext";
+import { HowToService } from "../../how-to/data/HowToService";
+import type { HowToInterface } from "../../how-to/data/HowToInterface";
 
 export interface HelpSearchResultRowProps {
   result: { id: string; name: string; entityType: string };
@@ -14,8 +16,16 @@ export interface HelpSearchResultRowProps {
 export function HelpSearchResultRow({ result, onSelect }: HelpSearchResultRowProps) {
   const t = useTranslations();
   const generateUrl = usePageUrlGenerator();
-  const { manifest } = useHelp();
-  const article = manifest.find((a) => a.id === result.id);
+  const [article, setArticle] = useState<HowToInterface | null>(null);
+  useEffect(() => {
+    let active = true;
+    HowToService.findOne({ id: result.id })
+      .then((a) => active && setArticle(a))
+      .catch(() => active && setArticle(null));
+    return () => {
+      active = false;
+    };
+  }, [result.id]);
 
   if (!article) {
     return (
@@ -32,16 +42,16 @@ export function HelpSearchResultRow({ result, onSelect }: HelpSearchResultRowPro
   return (
     <CommandItem value={result.id} onSelect={onSelect} className="cursor-pointer p-0">
       <Link
-        href={generateUrl({ page: `/help/${article.mode}/${article.slug}` })}
+        href={generateUrl({ page: `/help/${article.howToType}/${article.slug}` })}
         className="hover:bg-muted flex w-full items-center gap-3 rounded px-3 py-2"
       >
         <div className="bg-muted text-muted-foreground flex h-10 w-10 shrink-0 items-center justify-center rounded-full">
           <LifeBuoyIcon className="h-5 w-5" />
         </div>
         <div className="flex min-w-0 flex-1 flex-col">
-          <span className="text-foreground truncate text-sm font-semibold">{article.title}</span>
+          <span className="text-foreground truncate text-sm font-semibold">{article.name}</span>
           <span className="text-muted-foreground truncate text-xs">
-            {t(`help.modes.${article.mode}`)} · {article.summary}
+            {t(`help.modes.${article.howToType}`)} · {article.summary}
           </span>
         </div>
         <ArrowUpRightIcon className="text-muted-foreground h-5 w-5 shrink-0" />

package/src/features/help/components/HelpSideNav.tsx

@@ -1,24 +1,60 @@
 "use client";
+
+import { useEffect, useMemo, useState } from "react";
 import { useTranslations } from "next-intl";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
 import { HELP_MODES } from "../types/help-article.types";
 import { usePageUrlGenerator } from "../../../client";
-import { useHelp } from "../contexts/HelpContext";
 import { useHelpFilter } from "../hooks/useHelpFilter";
-import { buildHelpNav } from "../utils/helpNavigation";
-import { articleUrl, modeUrl } from "../utils/articleUrl";
+import { HowToService } from "../../how-to/data/HowToService";
+import type { HowToInterface } from "../../how-to/data/HowToInterface";
 
 export function HelpSideNav() {
   const t = useTranslations();
   const generateUrl = usePageUrlGenerator();
   const pathname = usePathname();
-  const { manifest } = useHelp();
-  const groups = buildHelpNav(manifest);
-  const allArticles = groups.flatMap((g) => g.articles);
-  const { query, setQuery, filtered } = useHelpFilter(allArticles);
+  const [articles, setArticles] = useState<HowToInterface[]>([]);
+
+  useEffect(() => {
+    let active = true;
+    HowToService.findPublished()
+      .then((list) => active && setArticles(list))
+      .catch(() => active && setArticles([]));
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  // useHelpFilter indexes by title/summary/tags — map HowTo getters into the shape it expects.
+  const indexable = useMemo(
+    () =>
+      articles.map((a) => ({
+        id: a.id,
+        title: a.name,
+        summary: a.summary ?? "",
+        tags: a.tags,
+        mode: a.howToType ?? "",
+        slug: a.slug ?? "",
+      })),
+    [articles],
+  );
+  const { query, setQuery, filtered } = useHelpFilter(indexable as any);
   const filtering = query.trim().length > 0;
 
+  const groups = useMemo(
+    () =>
+      HELP_MODES.map((mode) => ({
+        mode,
+        articles: articles
+          .filter((a) => a.howToType === mode && !a.draft)
+          .sort((x, y) => (x.order ?? 0) - (y.order ?? 0)),
+      })),
+    [articles],
+  );
+
+  const isActive = (mode: string, slug: string) => pathname.endsWith(`/help/${mode}/${slug}`);
+
   return (
     <nav aria-label="Help navigation" className="flex h-full flex-col gap-3 overflow-y-auto p-4">
       <input
@@ -29,17 +65,17 @@ export function HelpSideNav() {
         className="border-input bg-background w-full rounded-md border px-3 py-2 text-sm"
       />
       {filtering ? (
-        filtered.length === 0 ? (
+        (filtered as any[]).length === 0 ? (
           <p className="text-muted-foreground text-sm">{t("help.sideNav.noMatches")}</p>
         ) : (
           <ul className="space-y-1">
-            {filtered.map((a) => (
+            {(filtered as any[]).map((a) => (
               <li key={a.id}>
                 <Link
-                  href={articleUrl(generateUrl, a)}
+                  href={generateUrl({ page: `/help/${a.mode}/${a.slug}` })}
                   className={
                     "hover:bg-muted block rounded px-2 py-1 text-sm " +
-                    (pathname.endsWith(`/help/${a.mode}/${a.slug}`) ? "bg-muted font-medium" : "")
+                    (isActive(a.mode, a.slug) ? "bg-muted font-medium" : "")
                   }
                 >
                   {a.title}
@@ -49,28 +85,27 @@ export function HelpSideNav() {
           </ul>
         )
       ) : (
-        HELP_MODES.map((mode) => {
-          const group = groups.find((g) => g.mode === mode)!;
+        groups.map((group) => {
           if (group.articles.length === 0) return null;
           return (
-            <div key={mode}>
+            <div key={group.mode}>
               <Link
-                href={modeUrl(generateUrl, mode)}
+                href={generateUrl({ page: `/help/${group.mode}` })}
                 className="text-muted-foreground hover:text-foreground mb-1 block text-xs font-semibold tracking-wider uppercase"
               >
-                {t(`help.modes.${mode}`)}
+                {t(`help.modes.${group.mode}`)}
               </Link>
               <ul className="space-y-0.5">
                 {group.articles.map((a) => (
                   <li key={a.id}>
                     <Link
-                      href={articleUrl(generateUrl, a)}
+                      href={generateUrl({ page: `/help/${a.howToType}/${a.slug}` })}
                       className={
                         "hover:bg-muted block rounded px-2 py-1 text-sm " +
-                        (pathname.endsWith(`/help/${a.mode}/${a.slug}`) ? "bg-muted font-medium" : "")
+                        (isActive(a.howToType ?? "", a.slug ?? "") ? "bg-muted font-medium" : "")
                       }
                     >
-                      {a.title}
+                      {a.name}
                     </Link>
                   </li>
                 ))}

package/src/features/help/components/__tests__/HelpAskAi.spec.tsx

@@ -17,7 +17,7 @@ vi.mock("../HelpAssistantSheet", () => ({
 function setupConfig() {
   configureJsonApi({
     apiUrl: "http://localhost",
-    helpContent: { manifest: [], namespaceUuid: "00000000-0000-5000-8000-000000000000" },
+    helpContent: { brand: { label: "narr8" } },
   });
 }