feat(platform): ship AI fallback stack and entity-scoped course planning

Unifies the new LangGraph-driven course-plan/media flow with robust provider fallbacks, admin AI provider settings, editable book-style materials, and strict entity isolation across LMS/course-plan APIs. Adds admin-only entity membership management in the Entities UI so users can switch linked entities directly from the platform.

Made-with: Cursor

frontend/src/components/AdminLmsLayout.tsx

@@ -1,4 +1,4 @@
-import { Outlet, Link, useNavigate, useLocation } from "react-router-dom";
+import { Outlet, Link, useNavigate, useLocation, useMatch } from "react-router-dom";
 import { Suspense } from "react";
 import { SidebarProvider, SidebarTrigger } from "@/components/ui/sidebar";
 import {
@@ -16,6 +16,7 @@ import AiAssistantDrawer from "@/components/ai/AiAssistantDrawer";
 import AiSearchBar from "@/components/ai/AiSearchBar";
 import { usePermissions } from "@/hooks/usePermissions";
 import { Button } from "@/components/ui/button";
+import { Badge } from "@/components/ui/badge";
 import {
   DropdownMenu, DropdownMenuContent, DropdownMenuItem,
   DropdownMenuSeparator, DropdownMenuTrigger,
@@ -238,9 +239,16 @@ function RouteContentFallback() {
 
 // ============= Main Layout =============
 export default function AdminLmsLayout() {
-  const { user, logout } = useAuth();
+  const { user, logout, selectedEntity, setSelectedEntityId } = useAuth();
   const navigate = useNavigate();
   const { t } = useTranslation();
+  // Hide the floating "Need help?" pill on multi-step wizard routes.
+  // It sits at `fixed bottom-6 end-6` z-50 and was intercepting clicks
+  // on the wizard's own Next/Finish footer (real bug repro: trying to
+  // click "Next" in the Course-plan wizard at the standard 1024×768
+  // viewport hits the pill instead). The AI Assistant orb also at the
+  // bottom-right is preserved — it's smaller and useful in-wizard.
+  const isWizardRoute = !!useMatch("/admin/smart-wizard/*");
 
   const initials = user?.name?.split(" ").map(w => w[0]).join("").slice(0, 2).toUpperCase() ?? "??";
 
@@ -261,6 +269,44 @@ export default function AdminLmsLayout() {
             </div>
             <AiSearchBar />
             <div className="flex items-center gap-2">
+              {user?.entities?.length ? (
+                <DropdownMenu>
+                  <DropdownMenuTrigger asChild>
+                    <Button variant="outline" size="sm" className="gap-1">
+                      <Building2 className="h-4 w-4" />
+                      <span className="max-w-40 truncate">
+                        {selectedEntity?.name ?? user.entities[0]?.name ?? t("nav.entities")}
+                      </span>
+                      <ChevronDown className="h-3.5 w-3.5 opacity-70" />
+                    </Button>
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent align="end" className="w-64">
+                    <div className="px-2 py-1.5 text-xs text-muted-foreground">
+                      {t("nav.entities")}
+                    </div>
+                    <DropdownMenuSeparator />
+                    {user.entities.map((entity) => (
+                      <DropdownMenuItem
+                        key={entity.id}
+                        onClick={() => {
+                          setSelectedEntityId(entity.id);
+                          // Force page data to refresh against the newly
+                          // selected entity scope.
+                          window.location.reload();
+                        }}
+                        className="flex items-center justify-between gap-2"
+                      >
+                        <span className="truncate">{entity.name}</span>
+                        {selectedEntity?.id === entity.id && (
+                          <Badge variant="secondary" className="text-[10px]">
+                            {t("common.active", "Active")}
+                          </Badge>
+                        )}
+                      </DropdownMenuItem>
+                    ))}
+                  </DropdownMenuContent>
+                </DropdownMenu>
+              ) : null}
               <LanguageToggle />
               <ThemeToggle />
               <NotificationDropdown />
@@ -303,13 +349,15 @@ export default function AdminLmsLayout() {
         </div>
       </div>
       <AiAssistantDrawer />
-      <Link
-        to="/admin/tickets"
-        className="fixed bottom-6 end-6 z-50 flex items-center gap-2 rounded-full bg-primary px-4 py-2.5 text-primary-foreground shadow-lg hover:opacity-90 transition-opacity"
-      >
-        <HelpCircle className="h-4 w-4" />
-        <span className="text-sm font-medium">{t("chrome.needHelp")}</span>
-      </Link>
+      {!isWizardRoute && (
+        <Link
+          to="/admin/tickets"
+          className="fixed bottom-6 end-6 z-40 flex items-center gap-2 rounded-full bg-primary px-4 py-2.5 text-primary-foreground shadow-lg hover:opacity-90 transition-opacity"
+        >
+          <HelpCircle className="h-4 w-4" />
+          <span className="text-sm font-medium">{t("chrome.needHelp")}</span>
+        </Link>
+      )}
     </SidebarProvider>
   );
 }

frontend/src/components/AppLayout.tsx

@@ -1,4 +1,4 @@
-import { Outlet, useLocation, Link, useNavigate } from "react-router-dom";
+import { Outlet, useLocation, Link, useNavigate, useMatch } from "react-router-dom";
 import { Suspense } from "react";
 import { SidebarProvider, SidebarTrigger } from "@/components/ui/sidebar";
 import { AppSidebar } from "@/components/AppSidebar";
@@ -7,14 +7,16 @@ import {
   BreadcrumbPage, BreadcrumbSeparator,
 } from "@/components/ui/breadcrumb";
 import { Button } from "@/components/ui/button";
+import { Badge } from "@/components/ui/badge";
 import {
   DropdownMenu, DropdownMenuContent, DropdownMenuItem,
   DropdownMenuSeparator, DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
-import { Ticket, Settings, User, LogOut, HelpCircle } from "lucide-react";
+import { Ticket, Settings, User, LogOut, HelpCircle, Building2, ChevronDown } from "lucide-react";
 import React from "react";
 import AiAssistantDrawer from "@/components/ai/AiAssistantDrawer";
 import AiSearchBar from "@/components/ai/AiSearchBar";
+import { useAuth } from "@/contexts/AuthContext";
 
 const routeLabels: Record<string, string> = {
   "dashboard": "Dashboard",
@@ -90,6 +92,14 @@ function RouteContentFallback() {
 
 export default function AppLayout() {
   const navigate = useNavigate();
+  const { user, selectedEntity, setSelectedEntityId } = useAuth();
+  // Hide the floating "Need help?" pill on multi-step wizard routes.
+  // The pill sits at `fixed bottom-6 right-6` with z-50 and was
+  // intercepting clicks on the wizard's own Next/Finish footer at most
+  // viewport heights, blocking users from finishing the flow. The AI
+  // Assistant orb (also bottom-right) stays — it's smaller and
+  // genuinely useful inside the wizard.
+  const isWizardRoute = !!useMatch("/admin/smart-wizard/*");
 
   return (
     <SidebarProvider>
@@ -103,6 +113,34 @@ export default function AppLayout() {
             </div>
             <AiSearchBar />
             <div className="flex items-center gap-2">
+              {user?.entities?.length ? (
+                <DropdownMenu>
+                  <DropdownMenuTrigger asChild>
+                    <Button variant="outline" size="sm" className="gap-1">
+                      <Building2 className="h-4 w-4" />
+                      <span className="max-w-40 truncate">
+                        {selectedEntity?.name ?? user.entities[0]?.name ?? "Entity"}
+                      </span>
+                      <ChevronDown className="h-3.5 w-3.5 opacity-70" />
+                    </Button>
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent align="end" className="w-64">
+                    {user.entities.map((entity) => {
+                      const active = selectedEntity?.id === entity.id;
+                      return (
+                        <DropdownMenuItem
+                          key={entity.id}
+                          onClick={() => setSelectedEntityId(entity.id)}
+                          className="flex items-center justify-between gap-3"
+                        >
+                          <span className="truncate">{entity.name}</span>
+                          {active ? <Badge variant="secondary">Current</Badge> : null}
+                        </DropdownMenuItem>
+                      );
+                    })}
+                  </DropdownMenuContent>
+                </DropdownMenu>
+              ) : null}
               <Button variant="ghost" size="icon" onClick={() => navigate("/tickets")} className="text-muted-foreground hover:text-foreground">
                 <Ticket className="h-4 w-4" />
               </Button>
@@ -145,14 +183,15 @@ export default function AppLayout() {
         </div>
       </div>
       <AiAssistantDrawer />
-      {/* Floating help button */}
-      <Link
-        to="/tickets"
-        className="fixed bottom-6 right-6 z-50 flex items-center gap-2 rounded-full bg-primary px-4 py-2.5 text-primary-foreground shadow-lg hover:opacity-90 transition-opacity"
-      >
-        <HelpCircle className="h-4 w-4" />
-        <span className="text-sm font-medium">Need help?</span>
-      </Link>
+      {!isWizardRoute && (
+        <Link
+          to="/tickets"
+          className="fixed bottom-6 right-6 z-40 flex items-center gap-2 rounded-full bg-primary px-4 py-2.5 text-primary-foreground shadow-lg hover:opacity-90 transition-opacity"
+        >
+          <HelpCircle className="h-4 w-4" />
+          <span className="text-sm font-medium">Need help?</span>
+        </Link>
+      )}
     </SidebarProvider>
   );
 }

frontend/src/components/coursePlan/LibraryPickerDialog.tsx

@@ -0,0 +1,214 @@
+import { useEffect, useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { useTranslation } from "react-i18next";
+import { Library, Loader2 } from "lucide-react";
+
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { Button } from "@/components/ui/button";
+import { Badge } from "@/components/ui/badge";
+import { Checkbox } from "@/components/ui/checkbox";
+import { Skeleton } from "@/components/ui/skeleton";
+
+import { resourcesService } from "@/services/resources.service";
+import type { Resource } from "@/types";
+
+/**
+ * Generic, reusable picker over `/api/resources`.
+ *
+ * Two callers wire this up today:
+ *
+ * 1. **AdminCoursePlanDetail** — for an *existing* plan, so it forwards
+ *    the picked resources to `coursePlanService.attachResources` in the
+ *    `onConfirm` handler and invalidates the sources query.
+ *
+ * 2. **CoursePlanWizard** — the plan does not exist yet at pick time,
+ *    so the wizard simply pushes the picks into its draft state and
+ *    attaches them in one batch after the plan is created.
+ *
+ * The dialog itself is purposefully agnostic: it only reports the
+ * selected `Resource` rows; the parent decides what to do.
+ */
+export function LibraryPickerDialog({
+  open,
+  onOpenChange,
+  alreadyLinkedIds,
+  onConfirm,
+  isPending,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** Resources whose ids are in this set render disabled + checked. */
+  alreadyLinkedIds?: Set<number>;
+  /** Called when the admin clicks "Attach selected". */
+  onConfirm: (resources: Resource[]) => void | Promise<void>;
+  /** Optional spinner state from the parent's mutation. */
+  isPending?: boolean;
+}) {
+  const { t } = useTranslation();
+  const [search, setSearch] = useState("");
+  const [typeFilter, setTypeFilter] = useState<string>("all");
+  const [selected, setSelected] = useState<Set<number>>(new Set());
+
+  // Reset every time the dialog re-opens so a previous session's
+  // selection doesn't bleed into the next attach.
+  useEffect(() => {
+    if (open) {
+      setSelected(new Set());
+      setSearch("");
+      setTypeFilter("all");
+    }
+  }, [open]);
+
+  const { data, isLoading } = useQuery({
+    queryKey: ["library-resources", { search, type: typeFilter }],
+    queryFn: () =>
+      resourcesService.list({
+        search: search || undefined,
+        resource_type: typeFilter === "all" ? undefined : typeFilter,
+        review_status: "approved",
+      }),
+    enabled: open,
+  });
+  const resources: Resource[] = data?.items ?? [];
+
+  const toggle = (id: number) => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+  };
+
+  const handleConfirm = async () => {
+    const picked = resources.filter((r) => selected.has(r.id));
+    if (!picked.length) return;
+    await onConfirm(picked);
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-[640px] max-h-[85vh] overflow-hidden flex flex-col">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Library className="h-5 w-5 text-primary" />
+            {t("coursePlan.sources.libraryTitle")}
+          </DialogTitle>
+          <DialogDescription>
+            {t("coursePlan.sources.libraryDescription")}
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="flex gap-2 pt-2">
+          <Input
+            placeholder={t("coursePlan.sources.librarySearchPlaceholder")}
+            value={search}
+            onChange={(e) => setSearch(e.target.value)}
+            className="flex-1"
+          />
+          <Select value={typeFilter} onValueChange={setTypeFilter}>
+            <SelectTrigger className="w-[140px]">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="all">
+                {t("coursePlan.sources.libraryTypeAll")}
+              </SelectItem>
+              <SelectItem value="pdf">PDF</SelectItem>
+              <SelectItem value="document">DOCX</SelectItem>
+              <SelectItem value="link">URL</SelectItem>
+              <SelectItem value="article">Article</SelectItem>
+            </SelectContent>
+          </Select>
+        </div>
+
+        <div className="flex-1 overflow-y-auto -mx-2 px-2 space-y-1">
+          {isLoading && <Skeleton className="h-32 w-full" />}
+          {!isLoading && resources.length === 0 && (
+            <p className="text-center text-sm text-muted-foreground py-8">
+              {t("coursePlan.sources.libraryEmpty")}
+            </p>
+          )}
+          {!isLoading &&
+            resources.map((r) => {
+              const isLinked = alreadyLinkedIds?.has(r.id) ?? false;
+              const isSelected = selected.has(r.id);
+              return (
+                <label
+                  key={r.id}
+                  className={`flex items-start gap-3 rounded-md border p-2 text-sm transition-colors ${
+                    isLinked
+                      ? "opacity-60 cursor-not-allowed bg-muted/40"
+                      : "cursor-pointer hover:bg-accent/50"
+                  }`}
+                >
+                  <Checkbox
+                    checked={isLinked || isSelected}
+                    disabled={isLinked}
+                    onCheckedChange={() => !isLinked && toggle(r.id)}
+                    className="mt-0.5"
+                  />
+                  <div className="flex-1 min-w-0 space-y-0.5">
+                    <div className="flex items-center gap-2 flex-wrap">
+                      <span className="font-medium truncate">{r.name}</span>
+                      <Badge
+                        variant="outline"
+                        className="text-[10px] capitalize"
+                      >
+                        {r.resource_type || r.type || "resource"}
+                      </Badge>
+                      {isLinked && (
+                        <Badge variant="secondary" className="text-[10px]">
+                          {t("coursePlan.sources.libraryAlreadyLinked")}
+                        </Badge>
+                      )}
+                    </div>
+                    {(r.subject_name || (r.topic_names ?? []).length > 0) && (
+                      <p className="text-xs text-muted-foreground truncate">
+                        {[r.subject_name, ...(r.topic_names?.slice(0, 2) ?? [])]
+                          .filter(Boolean)
+                          .join(" › ")}
+                      </p>
+                    )}
+                  </div>
+                </label>
+              );
+            })}
+        </div>
+
+        <DialogFooter className="border-t pt-3">
+          <span className="mr-auto text-xs text-muted-foreground self-center">
+            {t("coursePlan.sources.librarySelectedCount", {
+              count: selected.size,
+            })}
+          </span>
+          <Button variant="outline" onClick={() => onOpenChange(false)}>
+            {t("common.cancel", "Cancel")}
+          </Button>
+          <Button
+            onClick={handleConfirm}
+            disabled={!selected.size || isPending}
+          >
+            {isPending && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+            {t("coursePlan.sources.libraryAttach")}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

frontend/src/components/coursePlan/MaterialBookView.tsx

@@ -0,0 +1,78 @@
+import { Badge } from "@/components/ui/badge";
+import { cn } from "@/lib/utils";
+import type { CoursePlanMaterial } from "@/types";
+
+export const SKILL_STYLE: Record<string, string> = {
+  reading: "bg-blue-100 text-blue-800 border-blue-200",
+  writing: "bg-purple-100 text-purple-800 border-purple-200",
+  listening: "bg-emerald-100 text-emerald-800 border-emerald-200",
+  speaking: "bg-amber-100 text-amber-800 border-amber-200",
+  grammar: "bg-rose-100 text-rose-800 border-rose-200",
+  vocabulary: "bg-cyan-100 text-cyan-800 border-cyan-200",
+  integrated: "bg-slate-100 text-slate-800 border-slate-200",
+};
+
+export function SkillBadge({ skill }: { skill: string }) {
+  return (
+    <Badge
+      variant="outline"
+      className={cn("capitalize border", SKILL_STYLE[skill] ?? SKILL_STYLE.integrated)}
+    >
+      {skill || "integrated"}
+    </Badge>
+  );
+}
+
+function renderAny(value: unknown): React.ReactNode {
+  if (value == null) return null;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return <p className="leading-7">{String(value)}</p>;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return null;
+    return (
+      <ul className="list-disc ps-5 space-y-1">
+        {value.map((item, idx) => (
+          <li key={idx}>{renderAny(item)}</li>
+        ))}
+      </ul>
+    );
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>);
+    return (
+      <div className="space-y-3">
+        {entries.map(([k, v]) => (
+          <div key={k}>
+            <h5 className="font-medium capitalize text-sm text-muted-foreground mb-1">
+              {k.replace(/_/g, " ")}
+            </h5>
+            <div className="text-sm">{renderAny(v)}</div>
+          </div>
+        ))}
+      </div>
+    );
+  }
+  return null;
+}
+
+export default function MaterialBookView({
+  material,
+}: {
+  material: Pick<CoursePlanMaterial, "body" | "body_text" | "material_type">;
+}) {
+  const body = material.body ?? {};
+  const hasStructured = Object.keys(body).length > 0;
+
+  return (
+    <div className="rounded-lg border bg-background/70 p-4 space-y-4">
+      {hasStructured ? (
+        renderAny(body)
+      ) : (
+        <p className="text-sm whitespace-pre-wrap leading-7">
+          {material.body_text || "No content available yet."}
+        </p>
+      )}
+    </div>
+  );
+}