@promptbook/cli 0.112.0-99 → 0.113.0-0

package/apps/agents-server/src/components/Header/buildHeaderSystemMenuItems.ts

@@ -5,11 +5,15 @@ import {
     KeyRound,
     RefreshCw,
     Settings2,
+    ShieldCheck,
+    TriangleAlert,
     UserRound,
     Wrench,
     type LucideIcon,
 } from 'lucide-react';
+import { createElement } from 'react';
 import type { ServerTranslationKey } from '../../languages/ServerTranslationKeys';
+import type { ShibbolethAuthenticationMenuStatus } from '../../constants/shibbolethAuth';
 import type { ChatFeedbackMode } from '../../utils/chatFeedbackMode';
 import type { UserInfo } from '../../utils/getCurrentUser';
 import type { SubMenuItem } from './SubMenuItem';
@@ -31,6 +35,7 @@ type SystemCategoryLabel =
     | 'Utilities'
     | 'Super Admin'
     | 'Administration'
+    | 'Login Methods'
     | 'Monitoring & Usage'
     | 'Integrations & Keys'
     | 'Developer / Debug'
@@ -48,6 +53,7 @@ type BuildHeaderSystemMenuItemsOptions = {
     readonly isGlobalAdmin: boolean;
     readonly isExperimental: boolean;
     readonly feedbackMode: ChatFeedbackMode;
+    readonly shibbolethAuthenticationStatus?: ShibbolethAuthenticationMenuStatus;
 };
 
 /**
@@ -58,6 +64,7 @@ const SYSTEM_CATEGORY_ICON_MAP: Record<SystemCategoryLabel, LucideIcon> = {
     Utilities: Wrench,
     'Super Admin': Settings2,
     Administration: Settings2,
+    'Login Methods': KeyRound,
     'Monitoring & Usage': BarChart3,
     'Integrations & Keys': KeyRound,
     'Developer / Debug': Code2,
@@ -72,6 +79,7 @@ const SYSTEM_CATEGORY_TRANSLATION_KEY_MAP: Record<SystemCategoryLabel, ServerTra
     Utilities: 'header.utilities',
     'Super Admin': 'header.superAdmin',
     Administration: 'header.administration',
+    'Login Methods': 'header.loginMethods',
     'Monitoring & Usage': 'header.monitoringAndUsage',
     'Integrations & Keys': 'header.integrationsAndKeys',
     'Developer / Debug': 'header.developerDebug',
@@ -95,6 +103,21 @@ function applyFallbackSubMenuIcon(
     });
 }
 
+/**
+ * Decorates a menu label with the warning indicator used for misconfigured login methods.
+ */
+function createWarningMenuLabel(label: string) {
+    return createElement(
+        'span',
+        { className: 'inline-flex items-center gap-2' },
+        label,
+        createElement(TriangleAlert, {
+            className: 'h-4 w-4 text-amber-500',
+            'aria-label': 'Warning',
+        }),
+    );
+}
+
 /**
  * Creates one category entry inside the System dropdown when there are items to show.
  */
@@ -102,6 +125,7 @@ function createSystemCategory(
     label: SystemCategoryLabel,
     items: ReadonlyArray<SubMenuItem>,
     translate: HeaderTranslate,
+    isWarningShown = false,
 ): SubMenuItem[] {
     if (items.length === 0) {
         return [];
@@ -110,7 +134,9 @@ function createSystemCategory(
     const categoryIcon = SYSTEM_CATEGORY_ICON_MAP[label];
     return [
         {
-            label: translate(SYSTEM_CATEGORY_TRANSLATION_KEY_MAP[label]),
+            label: isWarningShown
+                ? createWarningMenuLabel(translate(SYSTEM_CATEGORY_TRANSLATION_KEY_MAP[label]))
+                : translate(SYSTEM_CATEGORY_TRANSLATION_KEY_MAP[label]),
             icon: categoryIcon,
             items: applyFallbackSubMenuIcon(items, categoryIcon),
         },
@@ -129,6 +155,7 @@ export function buildHeaderSystemMenuItems({
     isGlobalAdmin,
     isExperimental,
     feedbackMode,
+    shibbolethAuthenticationStatus,
 }: BuildHeaderSystemMenuItemsOptions): SubMenuItem[] {
     const userAccountSystemItems: SubMenuItem[] = [
         {
@@ -274,6 +301,23 @@ export function buildHeaderSystemMenuItems({
         },
     ];
 
+    const isShibbolethConfigurationWarningShown = Boolean(
+        shibbolethAuthenticationStatus?.isActive && !shibbolethAuthenticationStatus.isConfigured,
+    );
+    const loginMethodsSystemItems: SubMenuItem[] = shibbolethAuthenticationStatus?.isActive
+        ? [
+              {
+                  label: isShibbolethConfigurationWarningShown
+                      ? createWarningMenuLabel(translate('header.shibboleth'))
+                      : translate('header.shibboleth'),
+                  href: isShibbolethConfigurationWarningShown
+                      ? '/admin/login-methods/shibboleth#setup-instructions'
+                      : '/admin/login-methods/shibboleth',
+                  icon: ShieldCheck,
+              },
+          ]
+        : [];
+
     const monitoringAndUsageSystemItems: SubMenuItem[] = [
         {
             label: translate('header.usageAnalytics'),
@@ -345,6 +389,12 @@ export function buildHeaderSystemMenuItems({
         ...createSystemCategory('Utilities', utilitiesSystemItems, translate),
         ...createSystemCategory('Super Admin', superAdminSystemItems, translate),
         ...createSystemCategory('Administration', administrationSystemItems, translate),
+        ...createSystemCategory(
+            'Login Methods',
+            loginMethodsSystemItems,
+            translate,
+            isShibbolethConfigurationWarningShown,
+        ),
         ...createSystemCategory('Monitoring & Usage', monitoringAndUsageSystemItems, translate),
         ...createSystemCategory('Integrations & Keys', integrationsAndKeysSystemItems, translate),
         ...createSystemCategory('Developer / Debug', developerDebugSystemItems, translate),

package/apps/agents-server/src/components/Header/useHeaderActiveAgent.ts

@@ -5,6 +5,7 @@ import { buildAgentFolderContext, type AgentFolderContext } from '../../utils/ag
 import type { AgentOrganizationAgent } from '../../utils/agentOrganization/types';
 import { buildAgentProfileHref, buildFreshAgentChatHref } from '../../utils/agentRouting/agentRouteHrefs';
 import type { ServerTranslationKey } from '../../languages/ServerTranslationKeys';
+import { useActiveAgentBreadcrumbInfo, type ActiveAgentBreadcrumbInfo } from './ActiveAgentBreadcrumbContext';
 import type { HeaderAgentMenuFolder } from './AgentMenuStructure';
 import { buildAgentMenuStructure } from './buildAgentMenuStructure';
 import { createAgentViewLabel } from './createAgentViewLabel';
@@ -137,11 +138,17 @@ function createActiveAgentHref(activeAgentNavigationId: string | null): string {
 /**
  * Resolves the breadcrumb label shown for the active agent.
  *
+ * The agent's identifier (its `agentName` or `permanentId`) must never leak into the breadcrumb
+ * because the URL form is opaque to the user. When the agent cannot be resolved from the loaded
+ * organization list (typical for anonymous users browsing a public agent), the Header falls back
+ * to the breadcrumb info registered by the agent page; if that is also missing, a generic label
+ * is shown instead of the raw identifier.
+ *
  * @private function of Header
  */
 function createActiveAgentLabel(
     activeAgent: AgentOrganizationAgent | null,
-    activeAgentIdentifier: string | null,
+    activeAgentBreadcrumbInfo: ActiveAgentBreadcrumbInfo | null,
     agentFolderById: Map<number, HeaderAgentMenuFolder>,
     namingPlural: string,
     translate: HeaderTranslate,
@@ -150,7 +157,11 @@ function createActiveAgentLabel(
         return createAgentHierarchyLabel(activeAgent, agentFolderById);
     }
 
-    return activeAgentIdentifier || translate('header.agentsLabelFallback', { agentsPlural: namingPlural });
+    if (activeAgentBreadcrumbInfo) {
+        return activeAgentBreadcrumbInfo.meta?.fullname || activeAgentBreadcrumbInfo.agentName;
+    }
+
+    return translate('header.agentsLabelFallback', { agentsPlural: namingPlural });
 }
 
 /**
@@ -218,11 +229,12 @@ export function useHeaderActiveAgent({
         () => resolveActiveAgent(activeAgentNavigation, agentByIdentifier),
         [activeAgentNavigation, agentByIdentifier],
     );
+    const activeAgentBreadcrumbInfo = useActiveAgentBreadcrumbInfo();
     const activeAgentNavigationId = resolveActiveAgentNavigationId(activeAgent, activeAgentNavigation.agentIdentifier);
     const activeAgentHref = createActiveAgentHref(activeAgentNavigationId);
     const activeAgentLabel = createActiveAgentLabel(
         activeAgent,
-        activeAgentNavigation.agentIdentifier,
+        activeAgentBreadcrumbInfo,
         agentFolderById,
         namingPlural,
         translate,
@@ -239,10 +251,17 @@ export function useHeaderActiveAgent({
         [activeAgentMenuAgent.folderId, activeAgentMenuAgent.visibility, agentFolderById],
     );
     const { origin, hostname } = readWindowLocationState();
-    const activeAgentAvatarUrl = useMemo(
-        () => (activeAgent ? resolveAgentAvatarImageUrl({ agent: activeAgent }) : null),
-        [activeAgent],
-    );
+    const activeAgentAvatarUrl = useMemo(() => {
+        if (activeAgent) {
+            return resolveAgentAvatarImageUrl({ agent: activeAgent });
+        }
+
+        if (activeAgentBreadcrumbInfo) {
+            return resolveAgentAvatarImageUrl({ agent: activeAgentBreadcrumbInfo });
+        }
+
+        return null;
+    }, [activeAgent, activeAgentBreadcrumbInfo]);
 
     return {
         activeAgent,

package/apps/agents-server/src/components/Header/useHeaderAgentMenus.tsx

@@ -44,7 +44,6 @@ type UseHeaderAgentMenusOptions = {
     readonly isAdmin: boolean;
     readonly isAuthenticated: boolean;
     readonly isInstalled: boolean;
-    readonly navigateToHref: (href: string) => void;
     readonly namingPlural: string;
     readonly namingSingular: string;
     readonly onAgentRenamed: (payload: AgentContextMenuRenamePayload) => void;
@@ -160,7 +159,6 @@ export function useHeaderAgentMenus({
     isAdmin,
     isAuthenticated,
     isInstalled,
-    navigateToHref,
     namingPlural,
     namingSingular,
     onAgentRenamed,
@@ -214,9 +212,6 @@ export function useHeaderAgentMenus({
         openNewAgentDialog,
         dialog: newAgentDialog,
     } = useNewAgentDialog({
-        onCreated: ({ targetPath }) => {
-            navigateToHref(targetPath);
-        },
         onCreateFailed: async (error) => {
             await showNewAgentFailure('Failed to create agent:', error, namingSingular, translate);
         },

package/apps/agents-server/src/components/Homepage/AgentCard.tsx

@@ -5,7 +5,11 @@ import { CheckCircle2Icon, EyeIcon, EyeOffIcon, LockIcon, RotateCcwIcon } from '
 import Link from 'next/link';
 import { AgentBasicInformation } from '../../../../../src/book-2.0/agent-source/AgentBasicInformation';
 import type { AgentVisibility } from '../../utils/agentVisibility';
-import { AgentCapabilityChips, HOMEPAGE_CAPABILITY_CHIPS_LIMIT } from '../AgentProfile/AgentCapabilityChips';
+import {
+    AGENT_CARD_HIDDEN_CAPABILITY_TYPES,
+    AgentCapabilityChips,
+    HOMEPAGE_CAPABILITY_CHIPS_LIMIT,
+} from '../AgentProfile/AgentCapabilityChips';
 import { useAgentBackground } from '../AgentProfile/useAgentBackground';
 import { useAgentNaming } from '../AgentNaming/AgentNamingContext';
 import { AgentAvatar } from '../AgentAvatar/AgentAvatar';
@@ -153,6 +157,7 @@ export function AgentCard({
                             <AgentCapabilityChips
                                 agent={agent}
                                 className="mt-2"
+                                hiddenCapabilityTypes={AGENT_CARD_HIDDEN_CAPABILITY_TYPES}
                                 maxChips={HOMEPAGE_CAPABILITY_CHIPS_LIMIT}
                                 size="compact"
                             />
@@ -202,6 +207,7 @@ export function AgentCard({
                             <AgentCapabilityChips
                                 agent={agent}
                                 className="mt-2"
+                                hiddenCapabilityTypes={AGENT_CARD_HIDDEN_CAPABILITY_TYPES}
                                 maxChips={HOMEPAGE_CAPABILITY_CHIPS_LIMIT}
                                 size="compact"
                             />

package/apps/agents-server/src/components/Homepage/AgentsList.tsx

@@ -72,15 +72,35 @@ export function AgentsList(props: AgentsListProps) {
         isAdmin && contextMenuFolder ? () => state.handleRequestFolderVisibilityUpdate(contextMenuFolder.id) : undefined;
 
     return (
-        <section className="mt-16 first:mt-4 mb-4">
+        <section
+            className={`relative mt-16 first:mt-4 mb-4 ${
+                state.isAgentsImportDragActive ? 'rounded-xl ring-2 ring-blue-400 ring-offset-4' : ''
+            }`}
+            onDragEnter={isAdmin ? state.handleAgentsFileDragEnter : undefined}
+            onDragLeave={isAdmin ? state.handleAgentsFileDragLeave : undefined}
+            onDragOver={isAdmin ? state.handleAgentsFileDragOver : undefined}
+            onDrop={isAdmin ? state.handleAgentsFileDrop : undefined}
+        >
+            {isAdmin && state.isAgentsImportDragActive && (
+                <div className="pointer-events-none absolute inset-0 z-20 flex items-center justify-center rounded-xl border-2 border-dashed border-blue-400 bg-blue-50/85 text-sm font-medium text-blue-800 shadow-sm">
+                    Drop books or ZIP archives to import agents
+                </div>
+            )}
             <AgentsListHeader
                 agentCount={state.agentCount}
                 allAgentsLabel={state.allAgentsLabel}
                 breadcrumbFolders={state.breadcrumbFolders}
                 canOrganize={canOrganize}
+                hasHiddenFolders={state.hasHiddenFolders}
                 headingTitle={state.headingTitle}
+                isAdmin={isAdmin}
+                isAgentsExporting={state.isAgentsExporting}
+                isAgentsImporting={state.isAgentsImporting}
+                isHiddenFoldersVisible={state.isHiddenFoldersVisible}
                 onCreateFolder={state.handleCreateFolder}
+                onExportAgents={() => void state.handleAgentsExport()}
                 onNavigateToFolder={state.navigateToFolder}
+                onSetHiddenFoldersVisible={state.setHiddenFoldersVisible}
                 onSetViewMode={state.setViewMode}
                 viewMode={state.viewMode}
             />
@@ -108,6 +128,7 @@ export function AgentsList(props: AgentsListProps) {
                 handleDragEnd={state.handleDragEnd}
                 handleDragOver={state.handleDragOver}
                 handleDragStart={state.handleDragStart}
+                handleAgentsFileDropIntoFolder={state.handleAgentsFileDropIntoFolder}
                 handleFolderContextMenu={state.handleFolderContextMenu}
                 handleRenameFolder={state.handleRenameFolder}
                 handleRequestAgentVisibilityChange={state.handleRequestAgentVisibilityChange}

package/apps/agents-server/src/components/Homepage/AgentsListHeader.tsx

@@ -1,6 +1,17 @@
 'use client';
 
-import { Building2, FolderPlusIcon, Gamepad2, Grid, Map, Network, type LucideIcon } from 'lucide-react';
+import {
+    Building2,
+    DownloadIcon,
+    Eye,
+    EyeOff,
+    FolderPlusIcon,
+    Gamepad2,
+    Grid,
+    Map,
+    Network,
+    type LucideIcon,
+} from 'lucide-react';
 import type { AgentOrganizationFolder } from '../../utils/agentOrganization/types';
 import type { HomeViewMode } from './homeViewMode';
 import { BreadcrumbDropTarget } from './BreadcrumbDropTarget';
@@ -51,10 +62,26 @@ type AgentsListHeaderProps = {
      * Whether folder-management controls are available.
      */
     readonly canOrganize: boolean;
+    /**
+     * Whether the unfiltered organization snapshot contains at least one hidden folder.
+     */
+    readonly hasHiddenFolders: boolean;
     /**
      * Current heading title.
      */
     readonly headingTitle: string;
+    /**
+     * Whether agents import/export controls are available.
+     */
+    readonly isAdmin: boolean;
+    /**
+     * Whether hidden folders are currently rendered in the agents list.
+     */
+    readonly isHiddenFoldersVisible: boolean;
+    /**
+     * Downloads an agents archive.
+     */
+    readonly onExportAgents: () => void;
     /**
      * Opens the create-folder dialog.
      */
@@ -63,6 +90,10 @@ type AgentsListHeaderProps = {
      * Navigates to the selected folder scope.
      */
     readonly onNavigateToFolder: (folderId: number | null) => void;
+    /**
+     * Toggles whether hidden folders are visible in the agents list.
+     */
+    readonly onSetHiddenFoldersVisible: (isVisible: boolean) => void;
     /**
      * Switches the homepage view mode.
      */
@@ -71,6 +102,14 @@ type AgentsListHeaderProps = {
      * Currently active homepage view mode.
      */
     readonly viewMode: HomeViewMode;
+    /**
+     * Whether agents export is currently running.
+     */
+    readonly isAgentsExporting: boolean;
+    /**
+     * Whether agents import is currently running.
+     */
+    readonly isAgentsImporting: boolean;
 };
 
 /**
@@ -99,9 +138,16 @@ export function AgentsListHeader({
     allAgentsLabel,
     breadcrumbFolders,
     canOrganize,
+    hasHiddenFolders,
     headingTitle,
+    isAdmin,
+    isAgentsExporting,
+    isAgentsImporting,
+    isHiddenFoldersVisible,
     onCreateFolder,
+    onExportAgents,
     onNavigateToFolder,
+    onSetHiddenFoldersVisible,
     onSetViewMode,
     viewMode,
 }: AgentsListHeaderProps) {
@@ -138,6 +184,20 @@ export function AgentsListHeader({
                     )}
                 </div>
                 <div className="flex items-center gap-2">
+                    {isListView && isAdmin && (
+                        <>
+                            <button
+                                type="button"
+                                onClick={onExportAgents}
+                                disabled={isAgentsExporting || isAgentsImporting}
+                                className="flex items-center gap-2 px-3 py-2 rounded-lg border border-gray-200 bg-white text-gray-700 hover:bg-gray-50 transition-colors text-sm disabled:cursor-not-allowed disabled:opacity-60"
+                                title="Download agents"
+                            >
+                                <DownloadIcon className="w-4 h-4" />
+                                {isAgentsExporting ? 'Downloading...' : 'Download'}
+                            </button>
+                        </>
+                    )}
                     {isListView && canOrganize && (
                         <button
                             type="button"
@@ -149,6 +209,30 @@ export function AgentsListHeader({
                             New Folder
                         </button>
                     )}
+                    {hasHiddenFolders && (
+                        <button
+                            type="button"
+                            onClick={() => onSetHiddenFoldersVisible(!isHiddenFoldersVisible)}
+                            className={`flex items-center gap-2 px-3 py-2 rounded-lg border text-sm transition-colors ${
+                                isHiddenFoldersVisible
+                                    ? 'border-blue-200 bg-blue-50 text-blue-700 hover:bg-blue-100'
+                                    : 'border-gray-200 bg-white text-gray-700 hover:bg-gray-50'
+                            }`}
+                            title={
+                                isHiddenFoldersVisible
+                                    ? 'Hide folders whose name starts with "."'
+                                    : 'Show folders whose name starts with "."'
+                            }
+                            aria-pressed={isHiddenFoldersVisible}
+                        >
+                            {isHiddenFoldersVisible ? (
+                                <EyeOff className="w-4 h-4" />
+                            ) : (
+                                <Eye className="w-4 h-4" />
+                            )}
+                            {isHiddenFoldersVisible ? 'Hide hidden' : 'Show hidden'}
+                        </button>
+                    )}
                     <div className="flex items-center gap-2 bg-gray-100 p-1 rounded-lg ml-4">
                         {VIEW_MODE_BUTTONS.map(({ mode, label, title, icon: Icon }) => (
                             <button

package/apps/agents-server/src/components/Homepage/AgentsListListView.tsx

@@ -101,6 +101,10 @@ type AgentsListListViewProps = {
      * dnd-kit drag-start handler.
      */
     readonly handleDragStart: ComponentProps<typeof DndContext>['onDragStart'];
+    /**
+     * Imports dropped book files or ZIP archives directly into one folder.
+     */
+    readonly handleAgentsFileDropIntoFolder: SortableFolderCardProps['onFileDrop'];
     /**
      * Handles folder context-menu requests.
      */
@@ -193,6 +197,7 @@ export function AgentsListListView({
     handleDragEnd,
     handleDragOver,
     handleDragStart,
+    handleAgentsFileDropIntoFolder,
     handleFolderContextMenu,
     handleRenameFolder,
     handleRequestAgentVisibilityChange,
@@ -239,6 +244,7 @@ export function AgentsListListView({
                             onRename={canOrganize ? () => handleRenameFolder(folder.id) : undefined}
                             onDelete={canOrganize ? () => handleDeleteFolder(folder.id) : undefined}
                             onContextMenu={handleFolderContextMenu}
+                            onFileDrop={isAdmin ? handleAgentsFileDropIntoFolder : undefined}
                             dragHandleLabel={dragFolderLabel}
                             allowFullCardDrag={allowFullCardDrag}
                         />

package/apps/agents-server/src/components/Homepage/AgentsListViewContent.tsx

@@ -111,6 +111,10 @@ type AgentsListViewContentProps = {
      * dnd-kit drag-start handler.
      */
     readonly handleDragStart: ComponentProps<typeof DndContext>['onDragStart'];
+    /**
+     * Imports dropped book files or ZIP archives directly into one folder.
+     */
+    readonly handleAgentsFileDropIntoFolder: ComponentProps<typeof AgentsListListView>['handleAgentsFileDropIntoFolder'];
     /**
      * Handles folder context-menu requests.
      */
@@ -269,6 +273,7 @@ export function AgentsListViewContent({
     handleDragEnd,
     handleDragOver,
     handleDragStart,
+    handleAgentsFileDropIntoFolder,
     handleFolderContextMenu,
     handleRenameFolder,
     handleRequestAgentVisibilityChange,
@@ -308,6 +313,7 @@ export function AgentsListViewContent({
                 handleDragEnd={handleDragEnd}
                 handleDragOver={handleDragOver}
                 handleDragStart={handleDragStart}
+                handleAgentsFileDropIntoFolder={handleAgentsFileDropIntoFolder}
                 handleFolderContextMenu={handleFolderContextMenu}
                 handleRenameFolder={handleRenameFolder}
                 handleRequestAgentVisibilityChange={handleRequestAgentVisibilityChange}

package/apps/agents-server/src/components/Homepage/Card.tsx

@@ -15,7 +15,7 @@ type CardProps = {
 export function Card({ children, className = '', style }: CardProps) {
     return (
         <div
-            className={`block h-full p-6 bg-white rounded-lg shadow-md hover:shadow-xl transition-shadow duration-300 border border-gray-200 hover:border-blue-400 ${className}`}
+            className={`block h-full p-6 bg-white rounded-lg shadow-md hover:shadow-xl transition-shadow duration-300 border border-gray-200 hover:border-blue-400 dark:border-slate-700 dark:bg-slate-900/90 dark:text-slate-100 dark:shadow-slate-950/30 dark:hover:border-blue-400/70 ${className}`}
             style={style}
         >
             {children}

package/apps/agents-server/src/components/Homepage/Section.tsx

@@ -51,7 +51,9 @@ export function Section({
 }: SectionProps) {
     return (
         <section className={`mt-16 first:mt-4 mb-4 ${sectionClassName || ''}`.trim()}>
-            <h2 className={`text-3xl text-gray-900 mb-6 font-light ${titleClassName || ''}`.trim()}>{title}</h2>
+            <h2 className={`text-3xl text-gray-900 mb-6 font-light dark:text-slate-100 ${titleClassName || ''}`.trim()}>
+                {title}
+            </h2>
             <div className={gridClassName}>{children}</div>
         </section>
     );

package/apps/agents-server/src/components/Homepage/SortableFolderCard.tsx

@@ -4,7 +4,7 @@ import { CSS } from '@dnd-kit/utilities';
 import { useSortable } from '@dnd-kit/sortable';
 import type { string_url } from '@promptbook-local/types';
 import type { AgentBasicInformation } from '../../../../../src/book-2.0/agent-source/AgentBasicInformation';
-import type { CSSProperties, MouseEvent } from 'react';
+import type { CSSProperties, DragEvent, MouseEvent } from 'react';
 import type { AgentOrganizationFolder } from '../../utils/agentOrganization/types';
 import { FolderCard } from './FolderCard';
 import { buildCardDragProps, DragHandle } from './DragHandle';
@@ -61,6 +61,10 @@ export type SortableFolderCardProps = {
      * Context menu handler for the folder.
      */
     readonly onContextMenu?: (event: MouseEvent<HTMLDivElement>, folder: AgentOrganizationFolder) => void;
+    /**
+     * File-drop handler for importing agents directly into this folder.
+     */
+    readonly onFileDrop?: (event: DragEvent<HTMLDivElement>, folderId: number) => void;
     /**
      * Accessible label displayed for the drag handle.
      */
@@ -88,6 +92,7 @@ export function SortableFolderCard({
     onRename,
     onDelete,
     onContextMenu,
+    onFileDrop,
     dragHandleLabel,
     allowFullCardDrag,
 }: SortableFolderCardProps) {
@@ -125,6 +130,7 @@ export function SortableFolderCard({
             className={`relative ${canOrganize ? 'select-none' : ''} ${isDragging ? 'opacity-0' : ''} ${dropClasses}`}
             {...dragProps}
             onContextMenu={(event) => onContextMenu?.(event, folder)}
+            onDrop={(event) => onFileDrop?.(event, folder.id)}
         >
             <FolderCard
                 folderName={folder.name}

package/apps/agents-server/src/components/Homepage/hiddenFolders.ts

@@ -0,0 +1,104 @@
+import type { AgentOrganizationAgent, AgentOrganizationFolder } from '../../utils/agentOrganization/types';
+import { buildFolderMaps, collectDescendantFolderIds } from './agentOrganizationUtils';
+
+/**
+ * Prefix that marks a folder as hidden from default homepage listings.
+ *
+ * Folders whose name starts with this prefix (for example `.core`) are excluded
+ * from the agents list, graph, and office views unless the user explicitly toggles
+ * hidden-folder visibility on.
+ *
+ * @private function of AgentsList
+ */
+export const HIDDEN_FOLDER_NAME_PREFIX = '.';
+
+/**
+ * Determines whether one folder name represents a hidden folder.
+ *
+ * @param folderName - Folder name persisted in the database.
+ * @returns True when the folder should be hidden by default.
+ *
+ * @private function of AgentsList
+ */
+export function isHiddenFolderName(folderName: string): boolean {
+    return folderName.startsWith(HIDDEN_FOLDER_NAME_PREFIX);
+}
+
+/**
+ * Collects identifiers of all hidden folders together with their descendant folders.
+ *
+ * A folder is hidden when its own name starts with the hidden-folder prefix, or when
+ * it lives under another hidden folder. Descendants are included so that nested
+ * content is hidden together with the marker folder.
+ *
+ * @param folders - All folders in the organization.
+ * @returns Set of folder identifiers that should be excluded from default views.
+ *
+ * @private function of AgentsList
+ */
+export function collectHiddenFolderIds(folders: ReadonlyArray<AgentOrganizationFolder>): Set<number> {
+    const folderMaps = buildFolderMaps(folders);
+    const hiddenFolderIds = new Set<number>();
+
+    for (const folder of folders) {
+        if (!isHiddenFolderName(folder.name)) {
+            continue;
+        }
+
+        for (const descendantId of collectDescendantFolderIds(folder.id, folderMaps.childrenByParentId)) {
+            hiddenFolderIds.add(descendantId);
+        }
+    }
+
+    return hiddenFolderIds;
+}
+
+/**
+ * Result of removing hidden folders and their agents from one organization snapshot.
+ *
+ * @private function of AgentsList
+ */
+type FilterHiddenFolderTreeResult = {
+    readonly folders: AgentOrganizationFolder[];
+    readonly agents: AgentOrganizationAgent[];
+    readonly hasHiddenFolders: boolean;
+};
+
+/**
+ * Removes hidden folders and their agents from one organization snapshot.
+ *
+ * When `isHiddenFoldersVisible` is true the snapshot passes through unchanged so the
+ * caller can render every folder. When false, all hidden folders (including their
+ * descendants and the agents inside them) are removed in one pass — keeping the
+ * single filtering rule in one place across list, graph, and office views.
+ *
+ * @param folders - All folders in the organization.
+ * @param agents - All agents in the organization.
+ * @param isHiddenFoldersVisible - Whether the user has opted to display hidden folders.
+ * @returns Filtered organization snapshot together with the unfiltered detection flag.
+ *
+ * @private function of AgentsList
+ */
+export function filterHiddenFolderTree(
+    folders: ReadonlyArray<AgentOrganizationFolder>,
+    agents: ReadonlyArray<AgentOrganizationAgent>,
+    isHiddenFoldersVisible: boolean,
+): FilterHiddenFolderTreeResult {
+    const hasHiddenFolders = folders.some((folder) => isHiddenFolderName(folder.name));
+
+    if (isHiddenFoldersVisible || !hasHiddenFolders) {
+        return {
+            folders: Array.from(folders),
+            agents: Array.from(agents),
+            hasHiddenFolders,
+        };
+    }
+
+    const hiddenFolderIds = collectHiddenFolderIds(folders);
+
+    return {
+        folders: folders.filter((folder) => !hiddenFolderIds.has(folder.id)),
+        agents: agents.filter((agent) => agent.folderId === null || !hiddenFolderIds.has(agent.folderId)),
+        hasHiddenFolders,
+    };
+}