Merge remote-tracking branch 'upstream/dev' into refactor/indexing-pipelines

.gitignore

@@ -5,4 +5,5 @@ node_modules/
 .ruff_cache/
 .venv
 .pnpm-store
-.DS_Store
+.DS_Store
+deepagents/

CONTRIBUTING.md

@@ -39,6 +39,22 @@ Found a bug? Create an issue with:
 
 Want to fix it? Go for it! Just link the issue in your PR.
 
+## 🌿 Branching Workflow
+
+We follow a **branch protection model** to keep `main` stable:
+
+| Branch | Purpose | Who can merge |
+|--------|---------|---------------|
+| `main` | Stable/release branch | Maintainers only (from `dev`) |
+| `dev` | Active development & integration | Via approved PRs from contributors |
+| `feature/*`, `fix/*`, etc. | Individual work branches | Contributors create PRs to `dev` |
+
+### Important Rules
+
+- **All contributor PRs must target the `dev` branch.** PRs targeting `main` will not be accepted.
+- `main` is updated exclusively by maintainers merging from `dev` when a release is ready.
+- Always create your feature/fix branches from the latest `dev`.
+
 ## 🛠️ Development Setup
 
 ### Prerequisites
@@ -49,17 +65,24 @@ Want to fix it? Go for it! Just link the issue in your PR.
 - **API Keys** for external services you're testing
 
 ### Quick Start
-1. **Clone the repository**
+1. **Fork and clone the repository**
    ```bash
-   git clone https://github.com/MODSetter/SurfSense.git
+   git clone https://github.com/<your-username>/SurfSense.git
    cd SurfSense
    ```
 
-2. **Choose your setup method**:
+2. **Create your branch from `dev`**
+   ```bash
+   git checkout dev
+   git pull origin dev
+   git checkout -b feature/your-feature-name
+   ```
+
+3. **Choose your setup method**:
    - **Docker Setup**: Follow the [Docker Setup Guide](./DOCKER_SETUP.md)
    - **Manual Setup**: Follow the [Installation Guide](https://www.surfsense.com/docs/)
 
-3. **Configure services**:
+4. **Configure services**:
    - Set up PGVector & PostgreSQL
    - Configure a file ETL service: `Unstructured.io` or `LlamaIndex`
    - Add API keys for external services
@@ -103,7 +126,7 @@ refactor: improve error handling in connectors
 - Include integration tests for API endpoints
 
 ### Branch Naming
-Use descriptive branch names:
+Create branches from `dev` with descriptive names:
 - `feature/add-document-search`
 - `fix/pagination-issue`
 - `docs/update-contributing-guide`
@@ -112,12 +135,16 @@ Use descriptive branch names:
 
 ### Before Submitting
 1. **Create an issue** first (unless it's a minor fix)
-2. **Fork the repository** and create a feature branch
+2. **Fork the repository** and create a branch from `dev`
 3. **Make your changes** following the coding guidelines
 4. **Test your changes** thoroughly
 5. **Update documentation** if needed
+6. **Open a PR targeting the `dev` branch**
+
+> **Note:** PRs targeting `main` will **not** be reviewed or merged. If you accidentally open a PR to `main`, please retarget it to `dev`.
 
 ### PR Requirements
+- **Target the `dev` branch** — this is mandatory
 - **One feature or fix per PR** - keep changes focused
 - **Link related issues** in the PR description
 - **Include screenshots or demos** for UI changes

deepagents

@@ -0,0 +1 @@
+Subproject commit a32ce7ff6b2112cf48170d2279a1953eded61987

surfsense_backend/alembic/versions/107_add_video_presentations_table.py

@@ -37,7 +37,9 @@ def upgrade() -> None:
 
     conn = op.get_bind()
     result = conn.execute(
-        sa.text("SELECT 1 FROM information_schema.tables WHERE table_name = 'video_presentations'")
+        sa.text(
+            "SELECT 1 FROM information_schema.tables WHERE table_name = 'video_presentations'"
+        )
     )
     if not result.fetchone():
         op.create_table(

surfsense_backend/alembic/versions/109_add_folders_table.py

@@ -0,0 +1,90 @@
+"""Add folders table and folder_id to documents
+
+Revision ID: 109
+Revises: 108
+
+Creates the folders table for nested folder organization (max 8 levels),
+adds folder_id FK to documents, and creates an expression-based unique
+index to correctly handle NULL parent_id at root level.
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = "109"
+down_revision: str | None = "108"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "folders",
+        sa.Column("id", sa.Integer(), primary_key=True, index=True),
+        sa.Column("name", sa.String(255), nullable=False, index=True),
+        sa.Column("position", sa.String(50), nullable=False, index=True),
+        sa.Column(
+            "parent_id",
+            sa.Integer(),
+            sa.ForeignKey("folders.id", ondelete="CASCADE"),
+            nullable=True,
+            index=True,
+        ),
+        sa.Column(
+            "search_space_id",
+            sa.Integer(),
+            sa.ForeignKey("searchspaces.id", ondelete="CASCADE"),
+            nullable=False,
+            index=True,
+        ),
+        sa.Column(
+            "created_by_id",
+            sa.Uuid(),
+            sa.ForeignKey("user.id", ondelete="SET NULL"),
+            nullable=True,
+            index=True,
+        ),
+        sa.Column(
+            "created_at",
+            sa.TIMESTAMP(timezone=True),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.TIMESTAMP(timezone=True),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+    )
+
+    # Expression-based unique index: COALESCE(parent_id, 0) handles NULL correctly.
+    # PostgreSQL treats NULL != NULL in regular unique constraints, so a standard
+    # UniqueConstraint(search_space_id, parent_id, name) would allow duplicate
+    # folder names at the root level.
+    op.execute(
+        """
+        CREATE UNIQUE INDEX uq_folder_space_parent_name
+        ON folders (search_space_id, COALESCE(parent_id, 0), name);
+        """
+    )
+
+    op.add_column(
+        "documents",
+        sa.Column(
+            "folder_id",
+            sa.Integer(),
+            sa.ForeignKey("folders.id", ondelete="SET NULL"),
+            nullable=True,
+            index=True,
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("documents", "folder_id")
+    op.execute("DROP INDEX IF EXISTS uq_folder_space_parent_name;")
+    op.drop_table("folders")

surfsense_backend/app/db.py

@@ -914,6 +914,43 @@ class SharedMemory(BaseModel, TimestampMixin):
     created_by = relationship("User")
 
 
+class Folder(BaseModel, TimestampMixin):
+    __tablename__ = "folders"
+
+    name = Column(String(255), nullable=False, index=True)
+    position = Column(String(50), nullable=False, index=True)
+    parent_id = Column(
+        Integer,
+        ForeignKey("folders.id", ondelete="CASCADE"),
+        nullable=True,
+        index=True,
+    )
+    search_space_id = Column(
+        Integer,
+        ForeignKey("searchspaces.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    created_by_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("user.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )
+    updated_at = Column(
+        TIMESTAMP(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(UTC),
+        onupdate=lambda: datetime.now(UTC),
+        index=True,
+    )
+
+    parent = relationship("Folder", remote_side="Folder.id", backref="children")
+    search_space = relationship("SearchSpace", back_populates="folders")
+    created_by = relationship("User", back_populates="folders")
+    documents = relationship("Document", back_populates="folder", passive_deletes=True)
+
+
 class Document(BaseModel, TimestampMixin):
     __tablename__ = "documents"
 
@@ -947,6 +984,13 @@ class Document(BaseModel, TimestampMixin):
         Integer, ForeignKey("searchspaces.id", ondelete="CASCADE"), nullable=False
     )
 
+    folder_id = Column(
+        Integer,
+        ForeignKey("folders.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )
+
     # Track who created/uploaded this document
     created_by_id = Column(
         UUID(as_uuid=True),
@@ -976,6 +1020,7 @@ class Document(BaseModel, TimestampMixin):
 
     # Relationships
     search_space = relationship("SearchSpace", back_populates="documents")
+    folder = relationship("Folder", back_populates="documents")
     created_by = relationship("User", back_populates="documents")
     connector = relationship("SearchSourceConnector", back_populates="documents")
     chunks = relationship(
@@ -1279,6 +1324,12 @@ class SearchSpace(BaseModel, TimestampMixin):
     )
     user = relationship("User", back_populates="search_spaces")
 
+    folders = relationship(
+        "Folder",
+        back_populates="search_space",
+        order_by="Folder.position",
+        cascade="all, delete-orphan",
+    )
     documents = relationship(
         "Document",
         back_populates="search_space",
@@ -1765,6 +1816,13 @@ if config.AUTH_TYPE == "GOOGLE":
             passive_deletes=True,
         )
 
+        # Folders created by this user
+        folders = relationship(
+            "Folder",
+            back_populates="created_by",
+            passive_deletes=True,
+        )
+
         # Image generations created by this user
         image_generations = relationship(
             "ImageGeneration",
@@ -1867,6 +1925,13 @@ else:
             passive_deletes=True,
         )
 
+        # Folders created by this user
+        folders = relationship(
+            "Folder",
+            back_populates="created_by",
+            passive_deletes=True,
+        )
+
         # Image generations created by this user
         image_generations = relationship(
             "ImageGeneration",

surfsense_backend/app/routes/__init__.py

@@ -11,6 +11,7 @@ from .confluence_add_connector_route import router as confluence_add_connector_r
 from .discord_add_connector_route import router as discord_add_connector_router
 from .documents_routes import router as documents_router
 from .editor_routes import router as editor_router
+from .folders_routes import router as folders_router
 from .google_calendar_add_connector_route import (
     router as google_calendar_add_connector_router,
 )
@@ -51,6 +52,7 @@ router.include_router(search_spaces_router)
 router.include_router(rbac_router)  # RBAC routes for roles, members, invites
 router.include_router(editor_router)
 router.include_router(documents_router)
+router.include_router(folders_router)
 router.include_router(notes_router)
 router.include_router(new_chat_router)  # Chat with assistant-ui persistence
 router.include_router(sandbox_router)  # Sandbox file downloads (Daytona)

surfsense_backend/app/routes/documents_routes.py

@@ -320,6 +320,7 @@ async def read_documents(
     page_size: int = 50,
     search_space_id: int | None = None,
     document_types: str | None = None,
+    folder_id: int | str | None = None,
     sort_by: str = "created_at",
     sort_order: str = "desc",
     session: AsyncSession = Depends(get_async_session),
@@ -391,6 +392,17 @@ async def read_documents(
                 query = query.filter(Document.document_type.in_(type_list))
                 count_query = count_query.filter(Document.document_type.in_(type_list))
 
+        # Filter by folder_id: "root" or "null" => root level (folder_id IS NULL),
+        # integer => specific folder, omitted => all documents
+        if folder_id is not None:
+            if str(folder_id).lower() in ("root", "null"):
+                query = query.filter(Document.folder_id.is_(None))
+                count_query = count_query.filter(Document.folder_id.is_(None))
+            else:
+                fid = int(folder_id)
+                query = query.filter(Document.folder_id == fid)
+                count_query = count_query.filter(Document.folder_id == fid)
+
         total_result = await session.execute(count_query)
         total = total_result.scalar() or 0
 
@@ -451,6 +463,7 @@ async def read_documents(
                     created_at=doc.created_at,
                     updated_at=doc.updated_at,
                     search_space_id=doc.search_space_id,
+                    folder_id=doc.folder_id,
                     created_by_id=doc.created_by_id,
                     created_by_name=created_by_name,
                     created_by_email=created_by_email,
@@ -608,6 +621,7 @@ async def search_documents(
                     created_at=doc.created_at,
                     updated_at=doc.updated_at,
                     search_space_id=doc.search_space_id,
+                    folder_id=doc.folder_id,
                     created_by_id=doc.created_by_id,
                     created_by_name=created_by_name,
                     created_by_email=created_by_email,
@@ -978,6 +992,7 @@ async def read_document(
             created_at=document.created_at,
             updated_at=document.updated_at,
             search_space_id=document.search_space_id,
+            folder_id=document.folder_id,
         )
     except HTTPException:
         raise
@@ -1036,6 +1051,7 @@ async def update_document(
             created_at=db_document.created_at,
             updated_at=db_document.updated_at,
             search_space_id=db_document.search_space_id,
+            folder_id=db_document.folder_id,
         )
     except HTTPException:
         raise

surfsense_backend/app/routes/folders_routes.py

@@ -0,0 +1,516 @@
+"""API routes for folder CRUD, move, reorder, and document move operations."""
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.future import select
+
+from app.db import Document, Folder, Permission, User, get_async_session
+from app.schemas import (
+    BulkDocumentMove,
+    DocumentMove,
+    FolderBreadcrumb,
+    FolderCreate,
+    FolderMove,
+    FolderRead,
+    FolderReorder,
+    FolderUpdate,
+)
+from app.services.folder_service import (
+    check_no_circular_reference,
+    generate_folder_position,
+    get_folder_subtree_ids,
+    get_subtree_max_depth,
+    validate_folder_depth,
+)
+from app.users import current_active_user
+from app.utils.rbac import check_permission
+
+router = APIRouter()
+
+
+@router.post("/folders", response_model=FolderRead)
+async def create_folder(
+    request: FolderCreate,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Create a new folder. Requires DOCUMENTS_CREATE permission."""
+    try:
+        await check_permission(
+            session,
+            user,
+            request.search_space_id,
+            Permission.DOCUMENTS_CREATE.value,
+            "You don't have permission to create folders in this search space",
+        )
+
+        if request.parent_id is not None:
+            parent = await session.get(Folder, request.parent_id)
+            if not parent:
+                raise HTTPException(status_code=404, detail="Parent folder not found")
+            if parent.search_space_id != request.search_space_id:
+                raise HTTPException(
+                    status_code=400,
+                    detail="Parent folder belongs to a different search space",
+                )
+
+        await validate_folder_depth(session, request.parent_id)
+
+        position = await generate_folder_position(
+            session, request.search_space_id, request.parent_id
+        )
+
+        folder = Folder(
+            name=request.name,
+            position=position,
+            parent_id=request.parent_id,
+            search_space_id=request.search_space_id,
+            created_by_id=user.id,
+        )
+        session.add(folder)
+        await session.commit()
+        await session.refresh(folder)
+        return folder
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        await session.rollback()
+        if "uq_folder_space_parent_name" in str(e):
+            raise HTTPException(
+                status_code=409,
+                detail="A folder with this name already exists at this location",
+            ) from e
+        raise HTTPException(
+            status_code=500, detail=f"Failed to create folder: {e!s}"
+        ) from e
+
+
+@router.get("/folders", response_model=list[FolderRead])
+async def list_folders(
+    search_space_id: int,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """List all folders in a search space (flat). Requires DOCUMENTS_READ permission."""
+    try:
+        await check_permission(
+            session,
+            user,
+            search_space_id,
+            Permission.DOCUMENTS_READ.value,
+            "You don't have permission to read folders in this search space",
+        )
+
+        result = await session.execute(
+            select(Folder)
+            .where(Folder.search_space_id == search_space_id)
+            .order_by(Folder.position)
+        )
+        return result.scalars().all()
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(
+            status_code=500, detail=f"Failed to list folders: {e!s}"
+        ) from e
+
+
+@router.get("/folders/{folder_id}", response_model=FolderRead)
+async def get_folder(
+    folder_id: int,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Get a single folder. Requires DOCUMENTS_READ permission."""
+    try:
+        folder = await session.get(Folder, folder_id)
+        if not folder:
+            raise HTTPException(status_code=404, detail="Folder not found")
+
+        await check_permission(
+            session,
+            user,
+            folder.search_space_id,
+            Permission.DOCUMENTS_READ.value,
+            "You don't have permission to read folders in this search space",
+        )
+
+        return folder
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get folder: {e!s}"
+        ) from e
+
+
+@router.get("/folders/{folder_id}/breadcrumb", response_model=list[FolderBreadcrumb])
+async def get_folder_breadcrumb(
+    folder_id: int,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Get ancestor chain for breadcrumb display. Requires DOCUMENTS_READ permission."""
+    try:
+        folder = await session.get(Folder, folder_id)
+        if not folder:
+            raise HTTPException(status_code=404, detail="Folder not found")
+
+        await check_permission(
+            session,
+            user,
+            folder.search_space_id,
+            Permission.DOCUMENTS_READ.value,
+            "You don't have permission to read folders in this search space",
+        )
+
+        result = await session.execute(
+            text("""
+                WITH RECURSIVE ancestors AS (
+                    SELECT id, name, parent_id, 0 AS depth
+                    FROM folders WHERE id = :folder_id
+                    UNION ALL
+                    SELECT f.id, f.name, f.parent_id, a.depth + 1
+                    FROM folders f JOIN ancestors a ON f.id = a.parent_id
+                )
+                SELECT id, name FROM ancestors ORDER BY depth DESC;
+            """),
+            {"folder_id": folder_id},
+        )
+        rows = result.fetchall()
+        return [FolderBreadcrumb(id=row.id, name=row.name) for row in rows]
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get breadcrumb: {e!s}"
+        ) from e
+
+
+@router.put("/folders/{folder_id}", response_model=FolderRead)
+async def update_folder(
+    folder_id: int,
+    request: FolderUpdate,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Rename a folder. Requires DOCUMENTS_UPDATE permission."""
+    try:
+        folder = await session.get(Folder, folder_id)
+        if not folder:
+            raise HTTPException(status_code=404, detail="Folder not found")
+
+        await check_permission(
+            session,
+            user,
+            folder.search_space_id,
+            Permission.DOCUMENTS_UPDATE.value,
+            "You don't have permission to update folders in this search space",
+        )
+
+        folder.name = request.name
+        await session.commit()
+        await session.refresh(folder)
+        return folder
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        await session.rollback()
+        if "uq_folder_space_parent_name" in str(e):
+            raise HTTPException(
+                status_code=409,
+                detail="A folder with this name already exists at this location",
+            ) from e
+        raise HTTPException(
+            status_code=500, detail=f"Failed to update folder: {e!s}"
+        ) from e
+
+
+@router.put("/folders/{folder_id}/move", response_model=FolderRead)
+async def move_folder(
+    folder_id: int,
+    request: FolderMove,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Move a folder to a new parent. Requires DOCUMENTS_UPDATE permission."""
+    try:
+        folder = await session.get(Folder, folder_id)
+        if not folder:
+            raise HTTPException(status_code=404, detail="Folder not found")
+
+        await check_permission(
+            session,
+            user,
+            folder.search_space_id,
+            Permission.DOCUMENTS_UPDATE.value,
+            "You don't have permission to move folders in this search space",
+        )
+
+        if request.new_parent_id is not None:
+            new_parent = await session.get(Folder, request.new_parent_id)
+            if not new_parent:
+                raise HTTPException(
+                    status_code=404, detail="Target parent folder not found"
+                )
+            if new_parent.search_space_id != folder.search_space_id:
+                raise HTTPException(
+                    status_code=400,
+                    detail="Cannot move folder to a different search space",
+                )
+
+        await check_no_circular_reference(session, folder_id, request.new_parent_id)
+        subtree_depth = await get_subtree_max_depth(session, folder_id)
+        await validate_folder_depth(session, request.new_parent_id, subtree_depth)
+
+        position = await generate_folder_position(
+            session, folder.search_space_id, request.new_parent_id
+        )
+        folder.parent_id = request.new_parent_id
+        folder.position = position
+        await session.commit()
+        await session.refresh(folder)
+        return folder
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        await session.rollback()
+        if "uq_folder_space_parent_name" in str(e):
+            raise HTTPException(
+                status_code=409,
+                detail="A folder with this name already exists at the target location",
+            ) from e
+        raise HTTPException(
+            status_code=500, detail=f"Failed to move folder: {e!s}"
+        ) from e
+
+
+@router.put("/folders/{folder_id}/reorder", response_model=FolderRead)
+async def reorder_folder(
+    folder_id: int,
+    request: FolderReorder,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Reorder a folder among its siblings via fractional indexing. Requires DOCUMENTS_UPDATE."""
+    try:
+        folder = await session.get(Folder, folder_id)
+        if not folder:
+            raise HTTPException(status_code=404, detail="Folder not found")
+
+        await check_permission(
+            session,
+            user,
+            folder.search_space_id,
+            Permission.DOCUMENTS_UPDATE.value,
+            "You don't have permission to reorder folders in this search space",
+        )
+
+        position = await generate_folder_position(
+            session,
+            folder.search_space_id,
+            folder.parent_id,
+            before_position=request.before_position,
+            after_position=request.after_position,
+        )
+        folder.position = position
+        await session.commit()
+        await session.refresh(folder)
+        return folder
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        await session.rollback()
+        raise HTTPException(
+            status_code=500, detail=f"Failed to reorder folder: {e!s}"
+        ) from e
+
+
+@router.delete("/folders/{folder_id}")
+async def delete_folder(
+    folder_id: int,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Delete a folder and cascade-delete subfolders. Documents are async-deleted via Celery."""
+    try:
+        folder = await session.get(Folder, folder_id)
+        if not folder:
+            raise HTTPException(status_code=404, detail="Folder not found")
+
+        await check_permission(
+            session,
+            user,
+            folder.search_space_id,
+            Permission.DOCUMENTS_DELETE.value,
+            "You don't have permission to delete folders in this search space",
+        )
+
+        subtree_ids = await get_folder_subtree_ids(session, folder_id)
+
+        doc_result = await session.execute(
+            select(Document.id).where(
+                Document.folder_id.in_(subtree_ids),
+                Document.status["state"].as_string() != "deleting",
+            )
+        )
+        document_ids = list(doc_result.scalars().all())
+
+        if document_ids:
+            await session.execute(
+                Document.__table__.update()
+                .where(Document.id.in_(document_ids))
+                .values(status={"state": "deleting"})
+            )
+            await session.commit()
+
+        await session.execute(Folder.__table__.delete().where(Folder.id == folder_id))
+        await session.commit()
+
+        if document_ids:
+            try:
+                from app.tasks.celery_tasks.document_tasks import (
+                    delete_folder_documents_task,
+                )
+
+                delete_folder_documents_task.delay(document_ids)
+            except Exception as err:
+                await session.execute(
+                    Document.__table__.update()
+                    .where(Document.id.in_(document_ids))
+                    .values(status={"state": "ready"})
+                )
+                await session.commit()
+                raise HTTPException(
+                    status_code=503,
+                    detail="Folder deleted but document cleanup could not be queued. Documents have been restored.",
+                ) from err
+
+        return {
+            "message": "Folder deleted successfully",
+            "documents_queued_for_deletion": len(document_ids),
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        await session.rollback()
+        raise HTTPException(
+            status_code=500, detail=f"Failed to delete folder: {e!s}"
+        ) from e
+
+
+@router.put("/documents/{document_id}/move")
+async def move_document(
+    document_id: int,
+    request: DocumentMove,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Move a document to a folder (or root). Requires DOCUMENTS_UPDATE permission."""
+    try:
+        result = await session.execute(
+            select(Document).filter(Document.id == document_id)
+        )
+        document = result.scalars().first()
+        if not document:
+            raise HTTPException(status_code=404, detail="Document not found")
+
+        await check_permission(
+            session,
+            user,
+            document.search_space_id,
+            Permission.DOCUMENTS_UPDATE.value,
+            "You don't have permission to move documents in this search space",
+        )
+
+        if request.folder_id is not None:
+            target = await session.get(Folder, request.folder_id)
+            if not target:
+                raise HTTPException(status_code=404, detail="Target folder not found")
+            if target.search_space_id != document.search_space_id:
+                raise HTTPException(
+                    status_code=400,
+                    detail="Cannot move document to a folder in a different search space",
+                )
+
+        document.folder_id = request.folder_id
+        await session.commit()
+        return {"message": "Document moved successfully"}
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        await session.rollback()
+        raise HTTPException(
+            status_code=500, detail=f"Failed to move document: {e!s}"
+        ) from e
+
+
+@router.put("/documents/bulk-move")
+async def bulk_move_documents(
+    request: BulkDocumentMove,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Move multiple documents to a folder (or root). Requires DOCUMENTS_UPDATE permission."""
+    try:
+        if not request.document_ids:
+            raise HTTPException(status_code=400, detail="No document IDs provided")
+
+        result = await session.execute(
+            select(Document).filter(Document.id.in_(request.document_ids))
+        )
+        documents = result.scalars().all()
+
+        if not documents:
+            raise HTTPException(status_code=404, detail="No documents found")
+
+        search_space_ids = {doc.search_space_id for doc in documents}
+        for ss_id in search_space_ids:
+            await check_permission(
+                session,
+                user,
+                ss_id,
+                Permission.DOCUMENTS_UPDATE.value,
+                "You don't have permission to move documents in this search space",
+            )
+
+        if request.folder_id is not None:
+            target = await session.get(Folder, request.folder_id)
+            if not target:
+                raise HTTPException(status_code=404, detail="Target folder not found")
+            mismatched = [
+                doc.id
+                for doc in documents
+                if doc.search_space_id != target.search_space_id
+            ]
+            if mismatched:
+                raise HTTPException(
+                    status_code=400,
+                    detail="Cannot move documents to a folder in a different search space",
+                )
+
+        await session.execute(
+            Document.__table__.update()
+            .where(Document.id.in_(request.document_ids))
+            .values(folder_id=request.folder_id)
+        )
+        await session.commit()
+        return {"message": f"{len(request.document_ids)} documents moved successfully"}
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        await session.rollback()
+        raise HTTPException(
+            status_code=500, detail=f"Failed to move documents: {e!s}"
+        ) from e

surfsense_backend/app/schemas/__init__.py

@@ -22,6 +22,16 @@ from .documents import (
     ExtensionDocumentMetadata,
     PaginatedResponse,
 )
+from .folders import (
+    BulkDocumentMove,
+    DocumentMove,
+    FolderBreadcrumb,
+    FolderCreate,
+    FolderMove,
+    FolderRead,
+    FolderReorder,
+    FolderUpdate,
+)
 from .google_drive import DriveItem, GoogleDriveIndexingOptions, GoogleDriveIndexRequest
 from .image_generation import (
     GlobalImageGenConfigRead,
@@ -109,6 +119,8 @@ from .video_presentations import (
 )
 
 __all__ = [
+    # Folder schemas
+    "BulkDocumentMove",
     # Chat schemas (assistant-ui integration)
     "ChatMessage",
     # Chunk schemas
@@ -119,6 +131,7 @@ __all__ = [
     "DefaultSystemInstructionsResponse",
     # Document schemas
     "DocumentBase",
+    "DocumentMove",
     "DocumentRead",
     "DocumentStatusBatchResponse",
     "DocumentStatusItemRead",
@@ -132,6 +145,12 @@ __all__ = [
     "DriveItem",
     "ExtensionDocumentContent",
     "ExtensionDocumentMetadata",
+    "FolderBreadcrumb",
+    "FolderCreate",
+    "FolderMove",
+    "FolderRead",
+    "FolderReorder",
+    "FolderUpdate",
     "GlobalImageGenConfigRead",
     "GlobalNewLLMConfigRead",
     "GoogleDriveIndexRequest",

surfsense_backend/app/schemas/documents.py

@@ -59,6 +59,7 @@ class DocumentRead(BaseModel):
     created_at: datetime
     updated_at: datetime | None
     search_space_id: int
+    folder_id: int | None = None
     created_by_id: UUID | None = None  # User who created/uploaded this document
     created_by_name: str | None = None
     created_by_email: str | None = None
@@ -89,6 +90,7 @@ class DocumentTitleRead(BaseModel):
     id: int
     title: str
     document_type: DocumentType
+    folder_id: int | None = None
 
     model_config = ConfigDict(from_attributes=True)
 

surfsense_backend/app/schemas/folders.py

@@ -0,0 +1,52 @@
+"""Pydantic schemas for folder CRUD, move, and reorder operations."""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FolderCreate(BaseModel):
+    name: str = Field(max_length=255, min_length=1)
+    parent_id: int | None = None
+    search_space_id: int
+
+
+class FolderUpdate(BaseModel):
+    name: str = Field(max_length=255, min_length=1)
+
+
+class FolderMove(BaseModel):
+    new_parent_id: int | None = None
+
+
+class FolderReorder(BaseModel):
+    before_position: str | None = None
+    after_position: str | None = None
+
+
+class FolderRead(BaseModel):
+    id: int
+    name: str
+    position: str
+    parent_id: int | None
+    search_space_id: int
+    created_by_id: UUID | None
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class FolderBreadcrumb(BaseModel):
+    id: int
+    name: str
+
+
+class DocumentMove(BaseModel):
+    folder_id: int | None = None
+
+
+class BulkDocumentMove(BaseModel):
+    document_ids: list[int]
+    folder_id: int | None = None

surfsense_backend/app/services/folder_service.py

@@ -0,0 +1,158 @@
+"""Folder service: depth validation, circular reference checks, and position generation."""
+
+from fastapi import HTTPException
+from fractional_indexing import generate_key_between
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.future import select
+
+from app.db import Folder
+
+MAX_FOLDER_DEPTH = 8
+
+
+async def get_folder_depth(session: AsyncSession, folder_id: int) -> int:
+    """Return the depth of a folder (root-level = 1) using a recursive CTE."""
+    result = await session.execute(
+        text("""
+            WITH RECURSIVE ancestors AS (
+                SELECT id, parent_id, 1 AS depth
+                FROM folders
+                WHERE id = :folder_id
+                UNION ALL
+                SELECT f.id, f.parent_id, a.depth + 1
+                FROM folders f
+                JOIN ancestors a ON f.id = a.parent_id
+            )
+            SELECT MAX(depth) FROM ancestors;
+        """),
+        {"folder_id": folder_id},
+    )
+    return result.scalar() or 0
+
+
+async def get_subtree_max_depth(session: AsyncSession, folder_id: int) -> int:
+    """Return the maximum depth of any descendant below folder_id (0 if leaf)."""
+    result = await session.execute(
+        text("""
+            WITH RECURSIVE descendants AS (
+                SELECT id, 0 AS depth
+                FROM folders
+                WHERE parent_id = :folder_id
+                UNION ALL
+                SELECT f.id, d.depth + 1
+                FROM folders f
+                JOIN descendants d ON f.parent_id = d.id
+            )
+            SELECT COALESCE(MAX(depth), -1) FROM descendants;
+        """),
+        {"folder_id": folder_id},
+    )
+    val = result.scalar()
+    return (val + 1) if val is not None and val >= 0 else 0
+
+
+async def validate_folder_depth(
+    session: AsyncSession,
+    parent_id: int | None,
+    subtree_depth: int = 0,
+) -> None:
+    """Raise 400 if placing a folder (with subtree) under parent_id would exceed MAX_FOLDER_DEPTH."""
+    if parent_id is None:
+        parent_depth = 0
+    else:
+        parent_depth = await get_folder_depth(session, parent_id)
+
+    total = parent_depth + 1 + subtree_depth
+    if total > MAX_FOLDER_DEPTH:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Maximum folder nesting depth is {MAX_FOLDER_DEPTH}. "
+            f"This operation would result in depth {total}.",
+        )
+
+
+async def check_no_circular_reference(
+    session: AsyncSession,
+    folder_id: int,
+    new_parent_id: int | None,
+) -> None:
+    """Raise 400 if new_parent_id is folder_id itself or a descendant of folder_id."""
+    if new_parent_id is None:
+        return
+
+    if new_parent_id == folder_id:
+        raise HTTPException(
+            status_code=400,
+            detail="A folder cannot be moved into itself.",
+        )
+
+    result = await session.execute(
+        text("""
+            WITH RECURSIVE ancestors AS (
+                SELECT id, parent_id
+                FROM folders
+                WHERE id = :new_parent_id
+                UNION ALL
+                SELECT f.id, f.parent_id
+                FROM folders f
+                JOIN ancestors a ON f.id = a.parent_id
+            )
+            SELECT 1 FROM ancestors WHERE id = :folder_id LIMIT 1;
+        """),
+        {"new_parent_id": new_parent_id, "folder_id": folder_id},
+    )
+    if result.scalar() is not None:
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot move a folder into one of its own descendants.",
+        )
+
+
+async def generate_folder_position(
+    session: AsyncSession,
+    search_space_id: int,
+    parent_id: int | None,
+    before_position: str | None = None,
+    after_position: str | None = None,
+) -> str:
+    """Generate a fractional index key for ordering a folder among its siblings.
+
+    - Default (no before/after): append after last sibling
+    - Prepend: before_position=None, after_position=first sibling position
+    - Insert between: both positions provided
+    """
+    if before_position is not None or after_position is not None:
+        return generate_key_between(before_position, after_position)
+
+    # Append after last sibling
+    query = (
+        select(Folder.position)
+        .where(
+            Folder.search_space_id == search_space_id,
+            Folder.parent_id == parent_id
+            if parent_id is not None
+            else Folder.parent_id.is_(None),
+        )
+        .order_by(Folder.position.desc())
+        .limit(1)
+    )
+    result = await session.execute(query)
+    last_position = result.scalar()
+    return generate_key_between(last_position, None)
+
+
+async def get_folder_subtree_ids(session: AsyncSession, folder_id: int) -> list[int]:
+    """Return all folder IDs in the subtree rooted at folder_id (inclusive)."""
+    result = await session.execute(
+        text("""
+            WITH RECURSIVE subtree AS (
+                SELECT id FROM folders WHERE id = :folder_id
+                UNION ALL
+                SELECT f.id FROM folders f JOIN subtree s ON f.parent_id = s.id
+            )
+            SELECT id FROM subtree;
+        """),
+        {"folder_id": folder_id},
+    )
+    return list(result.scalars().all())

surfsense_backend/app/tasks/celery_tasks/document_tasks.py

@@ -133,6 +133,51 @@ async def _delete_document_background(document_id: int) -> None:
             await session.commit()
 
 
+@celery_app.task(
+    name="delete_folder_documents_background",
+    bind=True,
+    autoretry_for=(Exception,),
+    retry_backoff=True,
+    retry_backoff_max=300,
+    max_retries=5,
+)
+def delete_folder_documents_task(self, document_ids: list[int]):
+    """Celery task to batch-delete documents orphaned by folder deletion."""
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    try:
+        loop.run_until_complete(_delete_folder_documents(document_ids))
+    finally:
+        loop.close()
+
+
+async def _delete_folder_documents(document_ids: list[int]) -> None:
+    """Delete chunks in batches, then document rows for each orphaned document."""
+    from sqlalchemy import delete as sa_delete, select
+
+    from app.db import Chunk, Document
+
+    async with get_celery_session_maker()() as session:
+        batch_size = 500
+        for doc_id in document_ids:
+            while True:
+                chunk_ids_result = await session.execute(
+                    select(Chunk.id)
+                    .where(Chunk.document_id == doc_id)
+                    .limit(batch_size)
+                )
+                chunk_ids = chunk_ids_result.scalars().all()
+                if not chunk_ids:
+                    break
+                await session.execute(sa_delete(Chunk).where(Chunk.id.in_(chunk_ids)))
+                await session.commit()
+
+            doc = await session.get(Document, doc_id)
+            if doc:
+                await session.delete(doc)
+                await session.commit()
+
+
 @celery_app.task(
     name="delete_search_space_background",
     bind=True,

surfsense_backend/pyproject.toml

@@ -73,6 +73,7 @@ dependencies = [
     "langchain-daytona>=0.0.2",
     "pypandoc>=1.16.2",
     "notion-markdown>=0.7.0",
+    "fractional-indexing>=0.1.3",
 ]
 
 [dependency-groups]

surfsense_desktop/src/ipc/channels.ts

@@ -0,0 +1,6 @@
+export const IPC_CHANNELS = {
+  OPEN_EXTERNAL: 'open-external',
+  GET_APP_VERSION: 'get-app-version',
+  DEEP_LINK: 'deep-link',
+  QUICK_ASK_TEXT: 'quick-ask-text',
+} as const;

surfsense_desktop/src/ipc/handlers.ts

@@ -0,0 +1,19 @@
+import { app, ipcMain, shell } from 'electron';
+import { IPC_CHANNELS } from './channels';
+
+export function registerIpcHandlers(): void {
+  ipcMain.on(IPC_CHANNELS.OPEN_EXTERNAL, (_event, url: string) => {
+    try {
+      const parsed = new URL(url);
+      if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
+        shell.openExternal(url);
+      }
+    } catch {
+      // invalid URL — ignore
+    }
+  });
+
+  ipcMain.handle(IPC_CHANNELS.GET_APP_VERSION, () => {
+    return app.getVersion();
+  });
+}

surfsense_desktop/src/main.ts

@@ -1,258 +1,20 @@
-import { app, BrowserWindow, shell, ipcMain, session, dialog, clipboard, Menu } from 'electron';
-import path from 'path';
-import { getPort } from 'get-port-please';
-import { autoUpdater } from 'electron-updater';
+import { app, BrowserWindow } from 'electron';
+import { registerGlobalErrorHandlers, showErrorDialog } from './modules/errors';
+import { startNextServer } from './modules/server';
+import { createMainWindow } from './modules/window';
+import { setupDeepLinks, handlePendingDeepLink } from './modules/deep-links';
+import { setupAutoUpdater } from './modules/auto-updater';
+import { setupMenu } from './modules/menu';
+import { registerQuickAsk, unregisterQuickAsk } from './modules/quick-ask';
+import { registerIpcHandlers } from './ipc/handlers';
 
-function showErrorDialog(title: string, error: unknown): void {
-  const err = error instanceof Error ? error : new Error(String(error));
-  console.error(`${title}:`, err);
+registerGlobalErrorHandlers();
 
-  if (app.isReady()) {
-    const detail = err.stack || err.message;
-    const buttonIndex = dialog.showMessageBoxSync({
-      type: 'error',
-      buttons: ['OK', process.platform === 'darwin' ? 'Copy Error' : 'Copy error'],
-      defaultId: 0,
-      noLink: true,
-      message: title,
-      detail,
-    });
-    if (buttonIndex === 1) {
-      clipboard.writeText(`${title}\n${detail}`);
-    }
-  } else {
-    dialog.showErrorBox(title, err.stack || err.message);
-  }
-}
-
-process.on('uncaughtException', (error) => {
-  showErrorDialog('Unhandled Error', error);
-});
-
-process.on('unhandledRejection', (reason) => {
-  showErrorDialog('Unhandled Promise Rejection', reason);
-});
-
-const isDev = !app.isPackaged;
-let mainWindow: BrowserWindow | null = null;
-let deepLinkUrl: string | null = null;
-let serverPort: number = 3000; // overwritten at startup with a free port
-
-const PROTOCOL = 'surfsense';
-// Injected at compile time from .env via esbuild define
-const HOSTED_FRONTEND_URL = process.env.HOSTED_FRONTEND_URL as string;
-
-function getStandalonePath(): string {
-  if (isDev) {
-    return path.join(__dirname, '..', '..', 'surfsense_web', '.next', 'standalone', 'surfsense_web');
-  }
-  return path.join(process.resourcesPath, 'standalone');
-}
-
-async function waitForServer(url: string, maxRetries = 60): Promise<boolean> {
-  for (let i = 0; i < maxRetries; i++) {
-    try {
-      const res = await fetch(url);
-      if (res.ok || res.status === 404 || res.status === 500) return true;
-    } catch {
-      // not ready yet
-    }
-    await new Promise((r) => setTimeout(r, 500));
-  }
-  return false;
-}
-
-async function startNextServer(): Promise<void> {
-  if (isDev) return;
-
-  serverPort = await getPort({ port: 3000, portRange: [30_011, 50_000] });
-  console.log(`Selected port ${serverPort}`);
-
-  const standalonePath = getStandalonePath();
-  const serverScript = path.join(standalonePath, 'server.js');
-
-  // The standalone server.js reads PORT / HOSTNAME from process.env and
-  // uses process.chdir(__dirname). Running it via require() in the same
-  // process is the proven approach (avoids spawning a second Electron
-  // instance whose ASAR-patched fs breaks Next.js static file serving).
-  process.env.PORT = String(serverPort);
-  process.env.HOSTNAME = 'localhost';
-  process.env.NODE_ENV = 'production';
-  process.chdir(standalonePath);
-
-  require(serverScript);
-
-  const ready = await waitForServer(`http://localhost:${serverPort}`);
-  if (!ready) {
-    throw new Error('Next.js server failed to start within 30 s');
-  }
-  console.log(`Next.js server ready on port ${serverPort}`);
-}
-
-function createWindow() {
-  mainWindow = new BrowserWindow({
-    width: 1280,
-    height: 800,
-    minWidth: 800,
-    minHeight: 600,
-    webPreferences: {
-      preload: path.join(__dirname, 'preload.js'),
-      contextIsolation: true,
-      nodeIntegration: false,
-      sandbox: true,
-      webviewTag: false,
-    },
-    show: false,
-    titleBarStyle: 'hiddenInset',
-  });
-
-  mainWindow.once('ready-to-show', () => {
-    mainWindow?.show();
-  });
-
-  mainWindow.loadURL(`http://localhost:${serverPort}/login`);
-
-  // External links open in system browser, not in the Electron window
-  mainWindow.webContents.setWindowOpenHandler(({ url }) => {
-    if (url.startsWith('http://localhost')) {
-      return { action: 'allow' };
-    }
-    shell.openExternal(url);
-    return { action: 'deny' };
-  });
-
-  // Intercept backend OAuth redirects targeting the hosted web frontend
-  // and rewrite them to localhost so the user stays in the desktop app.
-  const filter = { urls: [`${HOSTED_FRONTEND_URL}/*`] };
-  session.defaultSession.webRequest.onBeforeRequest(filter, (details, callback) => {
-    const rewritten = details.url.replace(HOSTED_FRONTEND_URL, `http://localhost:${serverPort}`);
-    callback({ redirectURL: rewritten });
-  });
-
-  mainWindow.webContents.on('did-fail-load', (_event, errorCode, errorDescription, validatedURL) => {
-    console.error(`Failed to load ${validatedURL}: ${errorDescription} (${errorCode})`);
-    if (errorCode === -3) return; // ERR_ABORTED — normal during redirects
-    showErrorDialog('Page failed to load', new Error(`${errorDescription} (${errorCode})\n${validatedURL}`));
-  });
-
-  if (isDev) {
-    mainWindow.webContents.openDevTools();
-  }
-
-  mainWindow.on('closed', () => {
-    mainWindow = null;
-  });
-}
-
-// IPC handlers
-ipcMain.on('open-external', (_event, url: string) => {
-  try {
-    const parsed = new URL(url);
-    if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
-      shell.openExternal(url);
-    }
-  } catch {
-    // invalid URL — ignore
-  }
-});
-
-ipcMain.handle('get-app-version', () => {
-  return app.getVersion();
-});
-
-// Deep link handling
-function handleDeepLink(url: string) {
-  if (!url.startsWith(`${PROTOCOL}://`)) return;
-
-  deepLinkUrl = url;
-
-  if (!mainWindow) return;
-
-  // Rewrite surfsense:// deep link to localhost so TokenHandler.tsx processes it
-  const parsed = new URL(url);
-  if (parsed.hostname === 'auth' && parsed.pathname === '/callback') {
-    const params = parsed.searchParams.toString();
-    mainWindow.loadURL(`http://localhost:${serverPort}/auth/callback?${params}`);
-  }
-
-  mainWindow.show();
-  mainWindow.focus();
-}
-
-// Single instance lock — second instance passes deep link to first
-const gotTheLock = app.requestSingleInstanceLock();
-if (!gotTheLock) {
+if (!setupDeepLinks()) {
   app.quit();
-} else {
-  app.on('second-instance', (_event, argv) => {
-    // Windows/Linux: deep link URL is in argv
-    const url = argv.find((arg) => arg.startsWith(`${PROTOCOL}://`));
-    if (url) handleDeepLink(url);
-
-    if (mainWindow) {
-      if (mainWindow.isMinimized()) mainWindow.restore();
-      mainWindow.focus();
-    }
-  });
 }
 
-// macOS: deep link arrives via open-url event
-app.on('open-url', (event, url) => {
-  event.preventDefault();
-  handleDeepLink(url);
-});
-
-// Register surfsense:// protocol
-if (process.defaultApp) {
-  if (process.argv.length >= 2) {
-    app.setAsDefaultProtocolClient(PROTOCOL, process.execPath, [path.resolve(process.argv[1])]);
-  }
-} else {
-  app.setAsDefaultProtocolClient(PROTOCOL);
-}
-
-function setupAutoUpdater() {
-  if (isDev) return;
-
-  autoUpdater.autoDownload = true;
-
-  autoUpdater.on('update-available', (info) => {
-    console.log(`Update available: ${info.version}`);
-  });
-
-  autoUpdater.on('update-downloaded', (info) => {
-    console.log(`Update downloaded: ${info.version}`);
-    dialog.showMessageBox({
-      type: 'info',
-      buttons: ['Restart', 'Later'],
-      defaultId: 0,
-      title: 'Update Ready',
-      message: `Version ${info.version} has been downloaded. Restart to apply the update.`,
-    }).then(({ response }) => {
-      if (response === 0) {
-        autoUpdater.quitAndInstall();
-      }
-    });
-  });
-
-  autoUpdater.on('error', (err) => {
-    console.error('Auto-updater error:', err);
-  });
-
-  autoUpdater.checkForUpdates();
-}
-
-function setupMenu() {
-  const isMac = process.platform === 'darwin';
-  const template: Electron.MenuItemConstructorOptions[] = [
-    ...(isMac ? [{ role: 'appMenu' as const }] : []),
-    { role: 'fileMenu' as const },
-    { role: 'editMenu' as const },
-    { role: 'viewMenu' as const },
-    { role: 'windowMenu' as const },
-  ];
-  Menu.setApplicationMenu(Menu.buildFromTemplate(template));
-}
+registerIpcHandlers();
 
 // App lifecycle
 app.whenReady().then(async () => {
@@ -264,18 +26,15 @@ app.whenReady().then(async () => {
     setTimeout(() => app.quit(), 0);
     return;
   }
-  createWindow();
+  createMainWindow();
+  registerQuickAsk();
   setupAutoUpdater();
 
-  // If a deep link was received before the window was ready, handle it now
-  if (deepLinkUrl) {
-    handleDeepLink(deepLinkUrl);
-    deepLinkUrl = null;
-  }
+  handlePendingDeepLink();
 
   app.on('activate', () => {
     if (BrowserWindow.getAllWindows().length === 0) {
-      createWindow();
+      createMainWindow();
     }
   });
 });
@@ -287,5 +46,5 @@ app.on('window-all-closed', () => {
 });
 
 app.on('will-quit', () => {
-  // Server runs in-process — no child process to kill
+  unregisterQuickAsk();
 });

surfsense_desktop/src/modules/auto-updater.ts

@@ -0,0 +1,33 @@
+import { app, dialog } from 'electron';
+import { autoUpdater } from 'electron-updater';
+
+export function setupAutoUpdater(): void {
+  if (!app.isPackaged) return;
+
+  autoUpdater.autoDownload = true;
+
+  autoUpdater.on('update-available', (info) => {
+    console.log(`Update available: ${info.version}`);
+  });
+
+  autoUpdater.on('update-downloaded', (info) => {
+    console.log(`Update downloaded: ${info.version}`);
+    dialog.showMessageBox({
+      type: 'info',
+      buttons: ['Restart', 'Later'],
+      defaultId: 0,
+      title: 'Update Ready',
+      message: `Version ${info.version} has been downloaded. Restart to apply the update.`,
+    }).then(({ response }) => {
+      if (response === 0) {
+        autoUpdater.quitAndInstall();
+      }
+    });
+  });
+
+  autoUpdater.on('error', (err) => {
+    console.log('Auto-updater: update check skipped —', err.message?.split('\n')[0]);
+  });
+
+  autoUpdater.checkForUpdates().catch(() => {});
+}

surfsense_desktop/src/modules/deep-links.ts

@@ -0,0 +1,66 @@
+import { app } from 'electron';
+import path from 'path';
+import { getMainWindow } from './window';
+import { getServerPort } from './server';
+
+const PROTOCOL = 'surfsense';
+
+let deepLinkUrl: string | null = null;
+
+function handleDeepLink(url: string) {
+  if (!url.startsWith(`${PROTOCOL}://`)) return;
+
+  deepLinkUrl = url;
+
+  const win = getMainWindow();
+  if (!win) return;
+
+  const parsed = new URL(url);
+  if (parsed.hostname === 'auth' && parsed.pathname === '/callback') {
+    const params = parsed.searchParams.toString();
+    win.loadURL(`http://localhost:${getServerPort()}/auth/callback?${params}`);
+  }
+
+  win.show();
+  win.focus();
+}
+
+export function setupDeepLinks(): boolean {
+  const gotTheLock = app.requestSingleInstanceLock();
+  if (!gotTheLock) {
+    return false;
+  }
+
+  app.on('second-instance', (_event, argv) => {
+    const url = argv.find((arg) => arg.startsWith(`${PROTOCOL}://`));
+    if (url) handleDeepLink(url);
+
+    const win = getMainWindow();
+    if (win) {
+      if (win.isMinimized()) win.restore();
+      win.focus();
+    }
+  });
+
+  app.on('open-url', (event, url) => {
+    event.preventDefault();
+    handleDeepLink(url);
+  });
+
+  if (process.defaultApp) {
+    if (process.argv.length >= 2) {
+      app.setAsDefaultProtocolClient(PROTOCOL, process.execPath, [path.resolve(process.argv[1])]);
+    }
+  } else {
+    app.setAsDefaultProtocolClient(PROTOCOL);
+  }
+
+  return true;
+}
+
+export function handlePendingDeepLink(): void {
+  if (deepLinkUrl) {
+    handleDeepLink(deepLinkUrl);
+    deepLinkUrl = null;
+  }
+}

surfsense_desktop/src/modules/errors.ts

@@ -0,0 +1,33 @@
+import { app, clipboard, dialog } from 'electron';
+
+export function showErrorDialog(title: string, error: unknown): void {
+  const err = error instanceof Error ? error : new Error(String(error));
+  console.error(`${title}:`, err);
+
+  if (app.isReady()) {
+    const detail = err.stack || err.message;
+    const buttonIndex = dialog.showMessageBoxSync({
+      type: 'error',
+      buttons: ['OK', process.platform === 'darwin' ? 'Copy Error' : 'Copy error'],
+      defaultId: 0,
+      noLink: true,
+      message: title,
+      detail,
+    });
+    if (buttonIndex === 1) {
+      clipboard.writeText(`${title}\n${detail}`);
+    }
+  } else {
+    dialog.showErrorBox(title, err.stack || err.message);
+  }
+}
+
+export function registerGlobalErrorHandlers(): void {
+  process.on('uncaughtException', (error) => {
+    showErrorDialog('Unhandled Error', error);
+  });
+
+  process.on('unhandledRejection', (reason) => {
+    showErrorDialog('Unhandled Promise Rejection', reason);
+  });
+}

surfsense_desktop/src/modules/menu.ts

@@ -0,0 +1,13 @@
+import { Menu } from 'electron';
+
+export function setupMenu(): void {
+  const isMac = process.platform === 'darwin';
+  const template: Electron.MenuItemConstructorOptions[] = [
+    ...(isMac ? [{ role: 'appMenu' as const }] : []),
+    { role: 'fileMenu' as const },
+    { role: 'editMenu' as const },
+    { role: 'viewMenu' as const },
+    { role: 'windowMenu' as const },
+  ];
+  Menu.setApplicationMenu(Menu.buildFromTemplate(template));
+}

surfsense_desktop/src/modules/quick-ask.ts

@@ -0,0 +1,108 @@
+import { BrowserWindow, clipboard, globalShortcut, ipcMain, screen, shell } from 'electron';
+import path from 'path';
+import { IPC_CHANNELS } from '../ipc/channels';
+import { getServerPort } from './server';
+
+const SHORTCUT = 'CommandOrControl+Option+S';
+let quickAskWindow: BrowserWindow | null = null;
+let pendingText = '';
+
+function hideQuickAsk(): void {
+  if (quickAskWindow && !quickAskWindow.isDestroyed()) {
+    quickAskWindow.hide();
+  }
+}
+
+function clampToScreen(x: number, y: number, w: number, h: number): { x: number; y: number } {
+  const display = screen.getDisplayNearestPoint({ x, y });
+  const { x: dx, y: dy, width: dw, height: dh } = display.workArea;
+  return {
+    x: Math.max(dx, Math.min(x, dx + dw - w)),
+    y: Math.max(dy, Math.min(y, dy + dh - h)),
+  };
+}
+
+function createQuickAskWindow(x: number, y: number): BrowserWindow {
+  if (quickAskWindow && !quickAskWindow.isDestroyed()) {
+    quickAskWindow.setPosition(x, y);
+    quickAskWindow.show();
+    quickAskWindow.focus();
+    return quickAskWindow;
+  }
+
+  quickAskWindow = new BrowserWindow({
+    width: 450,
+    height: 550,
+    x,
+    y,
+    ...(process.platform === 'darwin'
+      ? { type: 'panel' as const }
+      : { type: 'toolbar' as const, alwaysOnTop: true }),
+    resizable: true,
+    fullscreenable: false,
+    maximizable: false,
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js'),
+      contextIsolation: true,
+      nodeIntegration: false,
+      sandbox: true,
+    },
+    show: false,
+    skipTaskbar: true,
+  });
+
+  quickAskWindow.loadURL(`http://localhost:${getServerPort()}/dashboard`);
+
+  quickAskWindow.once('ready-to-show', () => {
+    quickAskWindow?.show();
+  });
+
+  quickAskWindow.webContents.on('before-input-event', (_event, input) => {
+    if (input.key === 'Escape') hideQuickAsk();
+  });
+
+  quickAskWindow.webContents.setWindowOpenHandler(({ url }) => {
+    if (url.startsWith('http://localhost')) {
+      return { action: 'allow' };
+    }
+    shell.openExternal(url);
+    return { action: 'deny' };
+  });
+
+  quickAskWindow.on('closed', () => {
+    quickAskWindow = null;
+  });
+
+  return quickAskWindow;
+}
+
+export function registerQuickAsk(): void {
+  const ok = globalShortcut.register(SHORTCUT, () => {
+    if (quickAskWindow && !quickAskWindow.isDestroyed() && quickAskWindow.isVisible()) {
+      hideQuickAsk();
+      return;
+    }
+
+    const text = clipboard.readText().trim();
+    if (!text) return;
+
+    pendingText = text;
+    const cursor = screen.getCursorScreenPoint();
+    const pos = clampToScreen(cursor.x, cursor.y, 450, 550);
+    createQuickAskWindow(pos.x, pos.y);
+  });
+
+  if (!ok) {
+    console.log(`Quick-ask: failed to register ${SHORTCUT}`);
+  }
+
+  ipcMain.handle(IPC_CHANNELS.QUICK_ASK_TEXT, () => {
+    const text = pendingText;
+    pendingText = '';
+    return text;
+  });
+}
+
+export function unregisterQuickAsk(): void {
+  globalShortcut.unregister(SHORTCUT);
+}

surfsense_desktop/src/modules/server.ts

@@ -0,0 +1,53 @@
+import path from 'path';
+import { app } from 'electron';
+import { getPort } from 'get-port-please';
+
+const isDev = !app.isPackaged;
+let serverPort = 3000;
+
+export function getServerPort(): number {
+  return serverPort;
+}
+
+function getStandalonePath(): string {
+  if (isDev) {
+    return path.join(__dirname, '..', '..', 'surfsense_web', '.next', 'standalone', 'surfsense_web');
+  }
+  return path.join(process.resourcesPath, 'standalone');
+}
+
+async function waitForServer(url: string, maxRetries = 60): Promise<boolean> {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const res = await fetch(url);
+      if (res.ok || res.status === 404 || res.status === 500) return true;
+    } catch {
+      // not ready yet
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  return false;
+}
+
+export async function startNextServer(): Promise<void> {
+  if (isDev) return;
+
+  serverPort = await getPort({ port: 3000, portRange: [30_011, 50_000] });
+  console.log(`Selected port ${serverPort}`);
+
+  const standalonePath = getStandalonePath();
+  const serverScript = path.join(standalonePath, 'server.js');
+
+  process.env.PORT = String(serverPort);
+  process.env.HOSTNAME = '0.0.0.0';
+  process.env.NODE_ENV = 'production';
+  process.chdir(standalonePath);
+
+  require(serverScript);
+
+  const ready = await waitForServer(`http://localhost:${serverPort}`);
+  if (!ready) {
+    throw new Error('Next.js server failed to start within 30 s');
+  }
+  console.log(`Next.js server ready on port ${serverPort}`);
+}

surfsense_desktop/src/modules/window.ts

@@ -0,0 +1,67 @@
+import { app, BrowserWindow, shell, session } from 'electron';
+import path from 'path';
+import { showErrorDialog } from './errors';
+import { getServerPort } from './server';
+
+const isDev = !app.isPackaged;
+const HOSTED_FRONTEND_URL = process.env.HOSTED_FRONTEND_URL as string;
+
+let mainWindow: BrowserWindow | null = null;
+
+export function getMainWindow(): BrowserWindow | null {
+  return mainWindow;
+}
+
+export function createMainWindow(): BrowserWindow {
+  mainWindow = new BrowserWindow({
+    width: 1280,
+    height: 800,
+    minWidth: 800,
+    minHeight: 600,
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js'),
+      contextIsolation: true,
+      nodeIntegration: false,
+      sandbox: true,
+      webviewTag: false,
+    },
+    show: false,
+    titleBarStyle: 'hiddenInset',
+  });
+
+  mainWindow.once('ready-to-show', () => {
+    mainWindow?.show();
+  });
+
+  mainWindow.loadURL(`http://localhost:${getServerPort()}/dashboard`);
+
+  mainWindow.webContents.setWindowOpenHandler(({ url }) => {
+    if (url.startsWith('http://localhost')) {
+      return { action: 'allow' };
+    }
+    shell.openExternal(url);
+    return { action: 'deny' };
+  });
+
+  const filter = { urls: [`${HOSTED_FRONTEND_URL}/*`] };
+  session.defaultSession.webRequest.onBeforeRequest(filter, (details, callback) => {
+    const rewritten = details.url.replace(HOSTED_FRONTEND_URL, `http://localhost:${getServerPort()}`);
+    callback({ redirectURL: rewritten });
+  });
+
+  mainWindow.webContents.on('did-fail-load', (_event, errorCode, errorDescription, validatedURL) => {
+    console.error(`Failed to load ${validatedURL}: ${errorDescription} (${errorCode})`);
+    if (errorCode === -3) return;
+    showErrorDialog('Page failed to load', new Error(`${errorDescription} (${errorCode})\n${validatedURL}`));
+  });
+
+  if (isDev) {
+    mainWindow.webContents.openDevTools();
+  }
+
+  mainWindow.on('closed', () => {
+    mainWindow = null;
+  });
+
+  return mainWindow;
+}

surfsense_desktop/src/preload.ts

@@ -1,4 +1,5 @@
 const { contextBridge, ipcRenderer } = require('electron');
+const { IPC_CHANNELS } = require('./ipc/channels');
 
 contextBridge.exposeInMainWorld('electronAPI', {
   versions: {
@@ -7,13 +8,14 @@ contextBridge.exposeInMainWorld('electronAPI', {
     chrome: process.versions.chrome,
     platform: process.platform,
   },
-  openExternal: (url: string) => ipcRenderer.send('open-external', url),
-  getAppVersion: () => ipcRenderer.invoke('get-app-version'),
+  openExternal: (url: string) => ipcRenderer.send(IPC_CHANNELS.OPEN_EXTERNAL, url),
+  getAppVersion: () => ipcRenderer.invoke(IPC_CHANNELS.GET_APP_VERSION),
   onDeepLink: (callback: (url: string) => void) => {
     const listener = (_event: unknown, url: string) => callback(url);
-    ipcRenderer.on('deep-link', listener);
+    ipcRenderer.on(IPC_CHANNELS.DEEP_LINK, listener);
     return () => {
-      ipcRenderer.removeListener('deep-link', listener);
+      ipcRenderer.removeListener(IPC_CHANNELS.DEEP_LINK, listener);
     };
   },
+  getQuickAskText: () => ipcRenderer.invoke(IPC_CHANNELS.QUICK_ASK_TEXT),
 });

surfsense_web/app/(home)/login/LocalLoginForm.tsx

@@ -5,7 +5,7 @@ import { AnimatePresence, motion } from "motion/react";
 import Link from "next/link";
 import { useRouter } from "next/navigation";
 import { useTranslations } from "next-intl";
-import { useEffect, useState } from "react";
+import { useState } from "react";
 import { loginMutationAtom } from "@/atoms/auth/auth-mutation.atoms";
 import { Spinner } from "@/components/ui/spinner";
 import { getAuthErrorDetails, isNetworkError } from "@/lib/auth-errors";
@@ -25,15 +25,10 @@ export function LocalLoginForm() {
 		title: null,
 		message: null,
 	});
-	const [authType, setAuthType] = useState<string | null>(null);
+	const authType = AUTH_TYPE;
 	const router = useRouter();
 	const [{ mutateAsync: login, isPending: isLoggingIn }] = useAtom(loginMutationAtom);
 
-	useEffect(() => {
-		// Get the auth type from centralized config
-		setAuthType(AUTH_TYPE);
-	}, []);
-
 	const handleSubmit = async (e: React.FormEvent) => {
 		e.preventDefault();
 		setError({ title: null, message: null }); // Clear any previous errors
@@ -165,6 +160,7 @@ export function LocalLoginForm() {
 						id="email"
 						type="email"
 						required
+						placeholder="you@example.com"
 						value={username}
 						onChange={(e) => setUsername(e.target.value)}
 						className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-2 dark:bg-gray-800 dark:text-white transition-all ${
@@ -188,6 +184,7 @@ export function LocalLoginForm() {
 							id="password"
 							type={showPassword ? "text" : "password"}
 							required
+							placeholder="Enter your password"
 							value={password}
 							onChange={(e) => setPassword(e.target.value)}
 							className={`mt-1 block w-full rounded-md border pr-10 px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-2 dark:bg-gray-800 dark:text-white transition-all ${

surfsense_web/app/(home)/register/page.tsx

@@ -43,9 +43,12 @@ export default function RegisterPage() {
 		}
 	}, [router]);
 
-	const handleSubmit = async (e: React.FormEvent) => {
+	const handleSubmit = (e: React.FormEvent) => {
 		e.preventDefault();
+		submitForm();
+	};
 
+	const submitForm = async () => {
 		// Form validation
 		if (password !== confirmPassword) {
 			setError({ title: t("password_mismatch"), message: t("passwords_no_match_desc") });
@@ -140,7 +143,7 @@ export default function RegisterPage() {
 			if (shouldRetry(errorCode)) {
 				toastOptions.action = {
 					label: tCommon("retry"),
-					onClick: () => handleSubmit(e),
+					onClick: () => submitForm(),
 				};
 			}
 
@@ -231,6 +234,7 @@ export default function RegisterPage() {
 								id="email"
 								type="email"
 								required
+								placeholder="you@example.com"
 								value={email}
 								onChange={(e) => setEmail(e.target.value)}
 								className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-2 dark:bg-gray-800 dark:text-white transition-all ${
@@ -253,6 +257,7 @@ export default function RegisterPage() {
 								id="password"
 								type="password"
 								required
+								placeholder="Enter your password"
 								value={password}
 								onChange={(e) => setPassword(e.target.value)}
 								className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-2 dark:bg-gray-800 dark:text-white transition-all ${
@@ -275,6 +280,7 @@ export default function RegisterPage() {
 								id="confirmPassword"
 								type="password"
 								required
+								placeholder="Confirm your password"
 								value={confirmPassword}
 								onChange={(e) => setConfirmPassword(e.target.value)}
 								className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-2 dark:bg-gray-800 dark:text-white transition-all ${

surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentTypeIcon.tsx

@@ -63,7 +63,7 @@ export function DocumentTypeChip({ type, className }: { type: string; className?
 		checkTruncation();
 		window.addEventListener("resize", checkTruncation);
 		return () => window.removeEventListener("resize", checkTruncation);
-	}, []);
+	}, [type]);
 
 	const chip = (
 		<span

surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsFilters.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { ListFilter, Search, Upload, X } from "lucide-react";
+import { FolderPlus, ListFilter, Search, Upload, X } from "lucide-react";
 import { useTranslations } from "next-intl";
 import React, { useCallback, useMemo, useRef, useState } from "react";
 import { useDocumentUploadDialog } from "@/components/assistant-ui/document-upload-popup";
@@ -8,6 +8,7 @@ import { Button } from "@/components/ui/button";
 import { Checkbox } from "@/components/ui/checkbox";
 import { Input } from "@/components/ui/input";
 import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import type { DocumentTypeEnum } from "@/contracts/types/document.types";
 import { getDocumentTypeIcon, getDocumentTypeLabel } from "./DocumentTypeIcon";
 
@@ -17,12 +18,14 @@ export function DocumentsFilters({
 	searchValue,
 	onToggleType,
 	activeTypes,
+	onCreateFolder,
 }: {
 	typeCounts: Partial<Record<DocumentTypeEnum, number>>;
 	onSearch: (v: string) => void;
 	searchValue: string;
 	onToggleType: (type: DocumentTypeEnum, checked: boolean) => void;
 	activeTypes: DocumentTypeEnum[];
+	onCreateFolder?: () => void;
 }) {
 	const t = useTranslations("documents");
 	const id = React.useId();
@@ -194,6 +197,23 @@ export function DocumentsFilters({
 					)}
 				</div>
 
+				{/* New Folder Button */}
+				{onCreateFolder && (
+					<Tooltip>
+						<TooltipTrigger asChild>
+							<Button
+								variant="outline"
+								size="icon"
+								className="h-9 w-9 shrink-0 border-dashed border-sidebar-border text-sidebar-foreground/60 hover:text-sidebar-foreground hover:border-sidebar-border bg-sidebar"
+								onClick={onCreateFolder}
+							>
+								<FolderPlus size={14} />
+							</Button>
+						</TooltipTrigger>
+						<TooltipContent>New folder</TooltipContent>
+					</Tooltip>
+				)}
+
 				{/* Upload Button */}
 				<Button
 					data-joyride="upload-button"

surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/RowActions.tsx

@@ -24,8 +24,7 @@ import {
 } from "@/components/ui/dropdown-menu";
 import type { Document } from "./types";
 
-// Only FILE and NOTE document types can be edited
-const EDITABLE_DOCUMENT_TYPES = ["FILE", "NOTE"] as const;
+const EDITABLE_DOCUMENT_TYPES = ["NOTE"] as const;
 
 // SURFSENSE_DOCS are system-managed and cannot be deleted
 const NON_DELETABLE_DOCUMENT_TYPES = ["SURFSENSE_DOCS"] as const;
@@ -47,20 +46,14 @@ export function RowActions({
 		document.document_type as (typeof EDITABLE_DOCUMENT_TYPES)[number]
 	);
 
-	// Documents in "pending" or "processing" state should show disabled delete
 	const isBeingProcessed =
 		document.status?.state === "pending" || document.status?.state === "processing";
 
-	// FILE documents that failed processing cannot be edited
-	const isFileFailed = document.document_type === "FILE" && document.status?.state === "failed";
-
-	// SURFSENSE_DOCS are system-managed and should not show delete at all
 	const shouldShowDelete = !NON_DELETABLE_DOCUMENT_TYPES.includes(
 		document.document_type as (typeof NON_DELETABLE_DOCUMENT_TYPES)[number]
 	);
 
-	// Edit is disabled while processing OR for failed FILE documents
-	const isEditDisabled = isBeingProcessed || isFileFailed;
+	const isEditDisabled = isBeingProcessed;
 	const isDeleteDisabled = isBeingProcessed;
 
 	const handleDelete = async () => {

surfsense_web/app/dashboard/[search_space_id]/logs/loading.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+import { motion } from "motion/react";
+import { Skeleton } from "@/components/ui/skeleton";
+
+export default function Loading() {
+	return (
+		<motion.div
+			initial={{ opacity: 0, y: 20 }}
+			animate={{ opacity: 1, y: 0 }}
+			transition={{ duration: 0.3 }}
+			className="w-full px-6 py-4 space-y-6 min-h-[calc(100vh-64px)]"
+		>
+			{/* Summary Dashboard Skeleton */}
+			<motion.div
+				className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4"
+				initial={{ opacity: 0 }}
+				animate={{ opacity: 1 }}
+			>
+				{[...Array(4)].map((_, i) => (
+					<div key={i} className="rounded-lg border p-4">
+						<div className="flex flex-row items-center justify-between space-y-0 pb-2">
+							<Skeleton className="h-4 w-24" />
+							<Skeleton className="h-4 w-4 rounded-full" />
+						</div>
+						<div className="space-y-2">
+							<Skeleton className="h-8 w-16" />
+							<Skeleton className="h-3 w-32" />
+						</div>
+					</div>
+				))}
+			</motion.div>
+
+			{/* Header Section Skeleton */}
+			<motion.div
+				className="flex items-center justify-between"
+				initial={{ opacity: 0, y: 10 }}
+				animate={{ opacity: 1, y: 0 }}
+				transition={{ delay: 0.1 }}
+			>
+				<div className="space-y-2">
+					<Skeleton className="h-8 w-48" />
+					<Skeleton className="h-4 w-64" />
+				</div>
+				<Skeleton className="h-9 w-24" />
+			</motion.div>
+
+			{/* Filters Skeleton */}
+			<motion.div
+				className="flex flex-wrap items-center justify-start gap-3 w-full"
+				initial={{ opacity: 0, y: 10 }}
+				animate={{ opacity: 1, y: 0 }}
+				transition={{ delay: 0.2 }}
+			>
+				<div className="flex items-center gap-3 flex-wrap w-full sm:w-auto">
+					<Skeleton className="h-9 w-full sm:w-60" />
+					<Skeleton className="h-9 w-24" />
+					<Skeleton className="h-9 w-24" />
+					<Skeleton className="h-9 w-20" />
+				</div>
+			</motion.div>
+
+			{/* Table Skeleton */}
+			<motion.div
+				className="rounded-md border overflow-hidden"
+				initial={{ opacity: 0, y: 20 }}
+				animate={{ opacity: 1, y: 0 }}
+				transition={{ delay: 0.3 }}
+			>
+				{/* Table Header */}
+				<div className="border-b bg-muted/50 px-4 py-3 flex items-center gap-4">
+					<Skeleton className="h-4 w-4" />
+					<Skeleton className="h-4 w-16" />
+					<Skeleton className="h-4 w-20" />
+					<Skeleton className="h-4 w-24" />
+					<Skeleton className="h-4 flex-1" />
+					<Skeleton className="h-4 w-24" />
+					<Skeleton className="h-4 w-8" />
+				</div>
+
+				{/* Table Rows */}
+				{[...Array(6)].map((_, i) => (
+					<div key={i} className="border-b px-4 py-3 flex items-center gap-4 hover:bg-muted/50">
+						<Skeleton className="h-4 w-4" />
+						<Skeleton className="h-6 w-12 rounded-full" />
+						<Skeleton className="h-6 w-16 rounded-full" />
+						<div className="flex items-center gap-2">
+							<Skeleton className="h-4 w-4" />
+							<Skeleton className="h-4 w-20" />
+						</div>
+						<div className="flex-1 space-y-1">
+							<Skeleton className="h-4 w-32" />
+							<Skeleton className="h-3 w-48" />
+						</div>
+						<div className="space-y-1">
+							<Skeleton className="h-3 w-24" />
+							<Skeleton className="h-3 w-20" />
+						</div>
+						<Skeleton className="h-8 w-8" />
+					</div>
+				))}
+			</motion.div>
+
+			{/* Pagination Skeleton */}
+			<div className="flex items-center justify-between gap-8 mt-4">
+				<motion.div
+					className="flex items-center gap-3"
+					initial={{ opacity: 0, x: -20 }}
+					animate={{ opacity: 1, x: 0 }}
+				>
+					<Skeleton className="h-4 w-20 max-sm:sr-only" />
+					<Skeleton className="h-9 w-16" />
+				</motion.div>
+
+				<motion.div
+					className="flex grow justify-end"
+					initial={{ opacity: 0 }}
+					animate={{ opacity: 1 }}
+					transition={{ delay: 0.2 }}
+				>
+					<Skeleton className="h-4 w-40" />
+				</motion.div>
+
+				<div className="flex items-center gap-2">
+					<Skeleton className="h-9 w-9" />
+					<Skeleton className="h-9 w-9" />
+					<Skeleton className="h-9 w-9" />
+					<Skeleton className="h-9 w-9" />
+				</div>
+			</div>
+		</motion.div>
+	);
+}

surfsense_web/app/dashboard/[search_space_id]/more-pages/loading.tsx

@@ -0,0 +1,10 @@
+import { Skeleton } from "@/components/ui/skeleton";
+
+export default function Loading() {
+	return (
+		<div className="flex flex-1 flex-col items-center justify-center gap-4 p-4">
+			<Skeleton className="h-4 w-64" />
+			<Skeleton className="h-32 w-full max-w-2xl rounded-xl" />
+		</div>
+	);
+}

surfsense_web/app/dashboard/[search_space_id]/new-chat/[[...chat_id]]/page.tsx

@@ -32,6 +32,7 @@ import {
 import { closeReportPanelAtom } from "@/atoms/chat/report-panel.atom";
 import { closeEditorPanelAtom } from "@/atoms/editor/editor-panel.atom";
 import { membersAtom } from "@/atoms/members/members-query.atoms";
+import { updateChatTabTitleAtom } from "@/atoms/tabs/tabs.atom";
 import { currentUserAtom } from "@/atoms/user/user-query.atoms";
 import { ThinkingStepsDataUI } from "@/components/assistant-ui/thinking-steps";
 import { Thread } from "@/components/assistant-ui/thread";
@@ -74,6 +75,7 @@ import {
 	trackChatMessageSent,
 	trackChatResponseReceived,
 } from "@/lib/posthog/events";
+import Loading from "../loading";
 
 /**
  * After a tool produces output, mark any previously-decided interrupt tool
@@ -188,6 +190,7 @@ export default function NewChatPage() {
 	const clearTargetCommentId = useSetAtom(clearTargetCommentIdAtom);
 	const closeReportPanel = useSetAtom(closeReportPanelAtom);
 	const closeEditorPanel = useSetAtom(closeEditorPanelAtom);
+	const updateChatTabTitle = useSetAtom(updateChatTabTitleAtom);
 
 	// Get current user for author info in shared chats
 	const { data: currentUser } = useAtomValue(currentUserAtom);
@@ -726,12 +729,10 @@ export default function NewChatPage() {
 						}
 
 						case "data-thread-title-update": {
-							// Handle thread title update from LLM-generated title
 							const titleData = parsed.data as { threadId: number; title: string };
 							if (titleData?.title && titleData?.threadId === currentThreadId) {
-								// Update current thread state with new title
 								setCurrentThread((prev) => (prev ? { ...prev, title: titleData.title } : prev));
-								// Invalidate thread list to refresh sidebar
+								updateChatTabTitle({ chatId: currentThreadId, title: titleData.title });
 								queryClient.invalidateQueries({
 									queryKey: ["threads", String(searchSpaceId)],
 								});
@@ -1526,42 +1527,7 @@ export default function NewChatPage() {
 
 	// Show loading state only when loading an existing thread
 	if (isInitializing) {
-		return (
-			<div className="flex h-[calc(100dvh-64px)] flex-col bg-main-panel px-4">
-				<div className="mx-auto w-full max-w-[44rem] flex flex-1 flex-col gap-6 py-8">
-					{/* User message */}
-					<div className="flex justify-end">
-						<Skeleton className="h-12 w-56 rounded-2xl" />
-					</div>
-
-					{/* Assistant message */}
-					<div className="flex flex-col gap-2">
-						<Skeleton className="h-4 w-full" />
-						<Skeleton className="h-4 w-[85%]" />
-						<Skeleton className="h-4 w-[70%]" />
-					</div>
-
-					{/* User message */}
-					<div className="flex justify-end">
-						<Skeleton className="h-12 w-40 rounded-2xl" />
-					</div>
-
-					{/* Assistant message */}
-					<div className="flex flex-col gap-2">
-						<Skeleton className="h-4 w-full" />
-						<Skeleton className="h-4 w-[90%]" />
-						<Skeleton className="h-4 w-[60%]" />
-					</div>
-				</div>
-
-				{/* Input bar */}
-				<div className="sticky bottom-0 pb-6 bg-main-panel">
-					<div className="mx-auto w-full max-w-[44rem]">
-						<Skeleton className="h-24 w-full rounded-2xl" />
-					</div>
-				</div>
-			</div>
-		);
+		return <Loading />;
 	}
 
 	// Show error state only if we tried to load an existing thread but failed

surfsense_web/app/dashboard/[search_space_id]/new-chat/loading.tsx

@@ -0,0 +1,45 @@
+import { Skeleton } from "@/components/ui/skeleton";
+
+export default function Loading() {
+	return (
+		<div className="flex h-[calc(100dvh-64px)] flex-col bg-main-panel px-4">
+			<div className="mx-auto w-full max-w-[44rem] flex flex-1 flex-col gap-6 py-8">
+				{/* User message */}
+				<div className="flex justify-end">
+					<Skeleton className="h-12 w-56 rounded-2xl" />
+				</div>
+
+				{/* Assistant message */}
+				<div className="flex flex-col gap-2">
+					<Skeleton className="h-4 w-full" />
+					<Skeleton className="h-4 w-[85%]" />
+					<Skeleton className="h-18 w-[40%]" />
+				</div>
+
+				{/* User message */}
+				<div className="flex gap-2 justify-end">
+					<Skeleton className="h-12 w-72 rounded-2xl" />
+				</div>
+
+				{/* Assistant message */}
+				<div className="flex flex-col gap-2">
+					<Skeleton className="h-10 w-[30%]" />
+					<Skeleton className="h-4 w-[90%]" />
+					<Skeleton className="h-6 w-[60%]" />
+				</div>
+
+				{/* User message */}
+				<div className="flex gap-2 justify-end">
+					<Skeleton className="h-12 w-96 rounded-2xl" />
+				</div>
+			</div>
+
+			{/* Input bar */}
+			<div className="sticky bottom-0 pb-6 bg-main-panel">
+				<div className="mx-auto w-full max-w-[44rem]">
+					<Skeleton className="h-24 w-full rounded-2xl" />
+				</div>
+			</div>
+		</div>
+	);
+}

surfsense_web/app/dashboard/[search_space_id]/page.tsx

@@ -1,15 +1,10 @@
-"use client";
+import { redirect } from "next/navigation";
 
-import { useParams, useRouter } from "next/navigation";
-import { useEffect } from "react";
-
-export default function SearchSpaceDashboardPage() {
-	const router = useRouter();
-	const { search_space_id } = useParams();
-
-	useEffect(() => {
-		router.push(`/dashboard/${search_space_id}/new-chat`);
-	}, [router, search_space_id]);
-
-	return <></>;
+export default async function SearchSpaceDashboardPage({
+	params,
+}: {
+	params: Promise<{ search_space_id: string }>;
+}) {
+	const { search_space_id } = await params;
+	redirect(`/dashboard/${search_space_id}/new-chat`);
 }

surfsense_web/app/error.tsx

@@ -3,11 +3,11 @@
 import posthog from "posthog-js";
 import { useEffect } from "react";
 
-export default function Error({
+export default function ErrorPage({
 	error,
 	reset,
 }: {
-	error: Error & { digest?: string };
+	error: globalThis.Error & { digest?: string };
 	reset: () => void;
 }) {
 	useEffect(() => {

surfsense_web/app/global-error.tsx

@@ -1,8 +1,9 @@
 "use client";
 
-import NextError from "next/error";
+import "./globals.css";
 import posthog from "posthog-js";
 import { useEffect } from "react";
+import { Button } from "@/components/ui/button";
 
 export default function GlobalError({
 	error,
@@ -18,10 +19,11 @@ export default function GlobalError({
 	return (
 		<html lang="en">
 			<body>
-				<NextError statusCode={0} />
-				<button type="button" onClick={reset}>
-					Try again
-				</button>
+				<div className="flex min-h-screen flex-col items-center justify-center gap-4 p-4">
+					<h2 className="text-xl font-semibold">Something went wrong</h2>
+					<p className="text-sm text-muted-foreground">An unexpected error occurred.</p>
+					<Button onClick={reset}>Try again</Button>
+				</div>
 			</body>
 		</html>
 	);

surfsense_web/app/public/[token]/page.tsx

@@ -1,11 +1,7 @@
-"use client";
-
-import { useParams } from "next/navigation";
 import { PublicChatView } from "@/components/public-chat/public-chat-view";
 
-export default function PublicChatPage() {
-	const params = useParams();
-	const token = params.token as string;
+export default async function PublicChatPage({ params }: { params: Promise<{ token: string }> }) {
+	const { token } = await params;
 
 	return <PublicChatView shareToken={token} />;
 }

surfsense_web/atoms/documents/folder.atoms.ts

@@ -0,0 +1,19 @@
+"use client";
+
+import { atom } from "jotai";
+import { atomWithStorage } from "jotai/utils";
+
+/**
+ * Set of folder IDs that are currently expanded in the tree, keyed by search space ID.
+ * Persisted to localStorage so expand/collapse state survives page refreshes.
+ */
+export const expandedFolderIdsAtom = atomWithStorage<Record<number, number[]>>(
+	"surfsense:expandedFolderIds",
+	{}
+);
+
+/**
+ * Folder currently being renamed (inline edit mode).
+ * null means no folder is being renamed.
+ */
+export const renamingFolderIdAtom = atom<number | null>(null);

surfsense_web/atoms/tabs/tabs.atom.ts

@@ -0,0 +1,219 @@
+import { atom } from "jotai";
+import { atomWithStorage, createJSONStorage } from "jotai/utils";
+
+export type TabType = "chat" | "document";
+
+export interface Tab {
+	id: string;
+	type: TabType;
+	title: string;
+	/** For chat tabs */
+	chatId?: number | null;
+	chatUrl?: string;
+	/** For document tabs */
+	documentId?: number;
+	searchSpaceId?: number;
+}
+
+interface TabsState {
+	tabs: Tab[];
+	activeTabId: string | null;
+}
+
+const INITIAL_CHAT_TAB: Tab = {
+	id: "chat-new",
+	type: "chat",
+	title: "New Chat",
+	chatId: null,
+	chatUrl: undefined,
+};
+
+const initialState: TabsState = {
+	tabs: [INITIAL_CHAT_TAB],
+	activeTabId: "chat-new",
+};
+
+const sessionStorageAdapter = createJSONStorage<TabsState>(
+	() => (typeof window !== "undefined" ? sessionStorage : undefined) as Storage
+);
+
+export const tabsStateAtom = atomWithStorage<TabsState>(
+	"surfsense:tabs",
+	initialState,
+	sessionStorageAdapter,
+	{ getOnInit: true }
+);
+
+export const tabsAtom = atom((get) => get(tabsStateAtom).tabs);
+export const activeTabIdAtom = atom((get) => get(tabsStateAtom).activeTabId);
+export const activeTabAtom = atom((get) => {
+	const state = get(tabsStateAtom);
+	return state.tabs.find((t) => t.id === state.activeTabId) ?? null;
+});
+
+function makeChatTabId(chatId: number | null): string {
+	return chatId ? `chat-${chatId}` : "chat-new";
+}
+
+function makeDocumentTabId(documentId: number): string {
+	return `doc-${documentId}`;
+}
+
+/**
+ * Sync the current chat from Next.js routing into the tab bar.
+ * If a tab for this chat already exists, activate it.
+ * Otherwise, replace the "new chat" tab or create one.
+ */
+export const syncChatTabAtom = atom(
+	null,
+	(
+		get,
+		set,
+		{ chatId, title, chatUrl }: { chatId: number | null; title?: string; chatUrl?: string }
+	) => {
+		const state = get(tabsStateAtom);
+		const tabId = makeChatTabId(chatId);
+		const existing = state.tabs.find((t) => t.id === tabId);
+
+		if (existing) {
+			set(tabsStateAtom, {
+				...state,
+				activeTabId: tabId,
+				tabs: state.tabs.map((t) =>
+					t.id === tabId ? { ...t, title: title || t.title, chatUrl: chatUrl || t.chatUrl } : t
+				),
+			});
+			return;
+		}
+
+		// If navigating to a new chat (no chatId), ensure there's a "new chat" tab
+		if (!chatId) {
+			const hasNewChatTab = state.tabs.some((t) => t.id === "chat-new");
+			if (hasNewChatTab) {
+				set(tabsStateAtom, { ...state, activeTabId: "chat-new" });
+			} else {
+				set(tabsStateAtom, {
+					tabs: [...state.tabs, INITIAL_CHAT_TAB],
+					activeTabId: "chat-new",
+				});
+			}
+			return;
+		}
+
+		// Replace the "new chat" tab if it exists and is empty, otherwise add new tab
+		const newChatTabIdx = state.tabs.findIndex((t) => t.id === "chat-new");
+		const newTab: Tab = {
+			id: tabId,
+			type: "chat",
+			title: title || `Chat ${chatId}`,
+			chatId,
+			chatUrl,
+		};
+
+		let updatedTabs: Tab[];
+		if (newChatTabIdx !== -1) {
+			updatedTabs = [...state.tabs];
+			updatedTabs[newChatTabIdx] = newTab;
+		} else {
+			updatedTabs = [...state.tabs, newTab];
+		}
+
+		set(tabsStateAtom, { tabs: updatedTabs, activeTabId: tabId });
+	}
+);
+
+/** Update the title of the current chat tab (e.g., when a chat gets its first response). */
+export const updateChatTabTitleAtom = atom(
+	null,
+	(get, set, { chatId, title }: { chatId: number; title: string }) => {
+		const state = get(tabsStateAtom);
+		const tabId = makeChatTabId(chatId);
+		set(tabsStateAtom, {
+			...state,
+			tabs: state.tabs.map((t) => (t.id === tabId ? { ...t, title } : t)),
+		});
+	}
+);
+
+/** Open a document tab. If already open, just switch to it. */
+export const openDocumentTabAtom = atom(
+	null,
+	(
+		get,
+		set,
+		{
+			documentId,
+			searchSpaceId,
+			title,
+		}: { documentId: number; searchSpaceId: number; title?: string }
+	) => {
+		const state = get(tabsStateAtom);
+		const tabId = makeDocumentTabId(documentId);
+		const existing = state.tabs.find((t) => t.id === tabId);
+
+		if (existing) {
+			set(tabsStateAtom, {
+				...state,
+				activeTabId: tabId,
+				tabs: state.tabs.map((t) => (t.id === tabId ? { ...t, title: title || t.title } : t)),
+			});
+			return;
+		}
+
+		const newTab: Tab = {
+			id: tabId,
+			type: "document",
+			title: title || `Document ${documentId}`,
+			documentId,
+			searchSpaceId,
+		};
+
+		set(tabsStateAtom, {
+			tabs: [...state.tabs, newTab],
+			activeTabId: tabId,
+		});
+	}
+);
+
+/** Switch to a tab by ID. Returns the tab so the caller can navigate if needed. */
+export const switchTabAtom = atom(null, (get, set, tabId: string) => {
+	const state = get(tabsStateAtom);
+	const tab = state.tabs.find((t) => t.id === tabId);
+	if (tab) {
+		set(tabsStateAtom, { ...state, activeTabId: tabId });
+	}
+	return tab ?? null;
+});
+
+/** Close a tab. If it was active, activate the nearest sibling. */
+export const closeTabAtom = atom(null, (get, set, tabId: string) => {
+	const state = get(tabsStateAtom);
+	const idx = state.tabs.findIndex((t) => t.id === tabId);
+	if (idx === -1) return null;
+
+	const remaining = state.tabs.filter((t) => t.id !== tabId);
+
+	// Don't close the last tab — always keep at least one
+	if (remaining.length === 0) {
+		set(tabsStateAtom, {
+			tabs: [INITIAL_CHAT_TAB],
+			activeTabId: "chat-new",
+		});
+		return INITIAL_CHAT_TAB;
+	}
+
+	let newActiveId = state.activeTabId;
+	if (state.activeTabId === tabId) {
+		// Activate the tab to the left (or right if first)
+		const newIdx = Math.min(idx, remaining.length - 1);
+		newActiveId = remaining[newIdx].id;
+	}
+
+	set(tabsStateAtom, { tabs: remaining, activeTabId: newActiveId });
+	return remaining.find((t) => t.id === newActiveId) ?? null;
+});
+
+/** Reset tabs when switching search spaces. */
+export const resetTabsAtom = atom(null, (_get, set) => {
+	set(tabsStateAtom, { ...initialState });
+});

surfsense_web/components/Logo.tsx

@@ -1,5 +1,3 @@
-"use client";
-
 import Image from "next/image";
 import Link from "next/link";
 import { cn } from "@/lib/utils";

surfsense_web/components/UserDropdown.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { BadgeCheck, LogOut } from "lucide-react";
-import { useRouter } from "next/navigation";
+import Link from "next/link";
 import { useState } from "react";
 import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
 import { Button } from "@/components/ui/button";
@@ -27,7 +27,6 @@ export function UserDropdown({
 		avatar: string;
 	};
 }) {
-	const router = useRouter();
 	const [isLoggingOut, setIsLoggingOut] = useState(false);
 
 	const handleLogout = async () => {
@@ -75,12 +74,11 @@ export function UserDropdown({
 				</DropdownMenuLabel>
 				<DropdownMenuSeparator />
 				<DropdownMenuGroup>
-					<DropdownMenuItem
-						onClick={() => router.push(`/dashboard/api-key`)}
-						className="text-xs md:text-sm"
-					>
-						<BadgeCheck className="mr-2 h-3.5 w-3.5 md:h-4 md:w-4" />
-						API Key
+					<DropdownMenuItem asChild className="text-xs md:text-sm">
+						<Link href="/dashboard/api-key">
+							<BadgeCheck className="mr-2 h-3.5 w-3.5 md:h-4 md:w-4" />
+							API Key
+						</Link>
 					</DropdownMenuItem>
 				</DropdownMenuGroup>
 				<DropdownMenuSeparator />

surfsense_web/components/announcements/AnnouncementToastProvider.tsx

@@ -34,7 +34,7 @@ function showAnnouncementToast(announcement: Announcement) {
 					label: announcement.link.label,
 					onClick: () => {
 						if (announcement.link?.url.startsWith("http")) {
-							window.open(announcement.link.url, "_blank");
+							window.open(announcement.link.url, "_blank", "noopener,noreferrer");
 						} else if (announcement.link?.url) {
 							window.location.href = announcement.link.url;
 						}

surfsense_web/components/announcements/AnnouncementsEmptyState.tsx

@@ -1,5 +1,3 @@
-"use client";
-
 import { BellOff } from "lucide-react";
 
 export function AnnouncementsEmptyState() {

surfsense_web/components/assistant-ui/inline-citation.tsx

@@ -28,16 +28,14 @@ export const InlineCitation: FC<InlineCitationProps> = ({ chunkId, isDocsChunk =
 			url=""
 			isDocsChunk={isDocsChunk}
 		>
-			<span
+			<button
+				type="button"
 				onClick={() => setIsOpen(true)}
-				onKeyDown={(e) => e.key === "Enter" && setIsOpen(true)}
 				className="text-[10px] font-bold bg-primary/80 hover:bg-primary text-primary-foreground rounded-full min-w-4 h-4 px-1 inline-flex items-center justify-center align-super cursor-pointer transition-colors ml-0.5"
 				title={`View source chunk #${chunkId}`}
-				role="button"
-				tabIndex={0}
 			>
 				{chunkId}
-			</span>
+			</button>
 		</SourceDetailPanel>
 	);
 };

surfsense_web/components/assistant-ui/inline-mention-editor.tsx

@@ -47,6 +47,7 @@ interface InlineMentionEditorProps {
 	disabled?: boolean;
 	className?: string;
 	initialDocuments?: MentionedDocument[];
+	initialText?: string;
 }
 
 // Unique data attribute to identify chip elements
@@ -96,6 +97,7 @@ export const InlineMentionEditor = forwardRef<InlineMentionEditorRef, InlineMent
 			disabled = false,
 			className,
 			initialDocuments = [],
+			initialText,
 		},
 		ref
 	) => {
@@ -115,6 +117,29 @@ export const InlineMentionEditor = forwardRef<InlineMentionEditorRef, InlineMent
 			}
 		}, [initialDocuments]);
 
+		useEffect(() => {
+			if (!initialText || !editorRef.current) return;
+			// Insert the text and add trailing line breaks for typing space
+			editorRef.current.innerText = initialText;
+			editorRef.current.appendChild(document.createElement("br"));
+			editorRef.current.appendChild(document.createElement("br"));
+			setIsEmpty(false);
+			onChange?.(initialText, Array.from(mentionedDocs.values()));
+			// Place cursor at the end of the content
+			editorRef.current.focus();
+			const sel = window.getSelection();
+			const range = document.createRange();
+			range.selectNodeContents(editorRef.current);
+			range.collapse(false);
+			sel?.removeAllRanges();
+			sel?.addRange(range);
+			// Scroll to cursor via a temporary anchor element
+			const anchor = document.createElement("span");
+			range.insertNode(anchor);
+			anchor.scrollIntoView({ block: "end" });
+			anchor.remove();
+		}, [initialText]); // eslint-disable-line react-hooks/exhaustive-deps
+
 		// Focus at the end of the editor
 		const focusAtEnd = useCallback(() => {
 			if (!editorRef.current) return;

surfsense_web/components/assistant-ui/thread-list.tsx

@@ -225,17 +225,13 @@ function ThreadListItemComponent({
 	onDelete,
 }: ThreadListItemComponentProps) {
 	return (
-		<div
+		<button
+			type="button"
 			className={cn(
-				"group flex items-center gap-2 rounded-lg px-3 py-2 transition-colors cursor-pointer",
+				"group flex w-full items-center gap-2 rounded-lg px-3 py-2 transition-colors cursor-pointer text-left",
 				isActive ? "bg-accent text-accent-foreground" : "hover:bg-muted/50"
 			)}
 			onClick={onClick}
-			onKeyDown={(e) => {
-				if (e.key === "Enter" || e.key === " ") onClick();
-			}}
-			role="button"
-			tabIndex={0}
 		>
 			<MessageSquareIcon className="size-4 shrink-0 text-muted-foreground" />
 			<div className="flex-1 min-w-0">
@@ -274,7 +270,7 @@ function ThreadListItemComponent({
 					</DropdownMenuItem>
 				</DropdownMenuContent>
 			</DropdownMenu>
-		</div>
+		</button>
 	);
 }
 

surfsense_web/components/assistant-ui/thread.tsx

@@ -306,6 +306,13 @@ const Composer: FC = () => {
 	const aui = useAui();
 	const hasAutoFocusedRef = useRef(false);
 
+	const [quickAskText, setQuickAskText] = useState<string | undefined>();
+	useEffect(() => {
+		window.electronAPI?.getQuickAskText().then((text) => {
+			if (text) setQuickAskText(text);
+		});
+	}, []);
+
 	const isThreadEmpty = useAuiState(({ thread }) => thread.isEmpty);
 	const isThreadRunning = useAuiState(({ thread }) => thread.isRunning);
 
@@ -512,6 +519,7 @@ const Composer: FC = () => {
 						onDocumentRemove={handleDocumentRemove}
 						onSubmit={handleSubmit}
 						onKeyDown={handleKeyDown}
+						initialText={quickAskText}
 						className="min-h-[24px]"
 					/>
 				</div>

surfsense_web/components/assistant-ui/user-message.tsx

@@ -30,7 +30,7 @@ const UserAvatar: FC<AuthorMetadata> = ({ displayName, avatarUrl }) => {
 				alt={displayName || "User"}
 				width={32}
 				height={32}
-				className="size-8 rounded-full object-cover select-none"
+				className="size-8 rounded-full object-cover"
 				referrerPolicy="no-referrer"
 				onError={() => setHasError(true)}
 				unoptimized

surfsense_web/components/auth/sign-in-button.tsx

@@ -8,7 +8,14 @@ import { cn } from "@/lib/utils";
 
 // Official Google "G" logo with brand colors
 const GoogleLogo = ({ className }: { className?: string }) => (
-	<svg className={className} viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+	<svg
+		className={className}
+		viewBox="0 0 24 24"
+		xmlns="http://www.w3.org/2000/svg"
+		role="img"
+		aria-label="Google logo"
+	>
+		<title>Google logo</title>
 		<path
 			d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"
 			fill="#4285F4"

surfsense_web/components/contact/contact-form.tsx

@@ -185,7 +185,20 @@ export const Grid = ({ pattern, size }: { pattern?: [number, number][]; size?: n
 	);
 };
 
-export function GridPattern({ width, height, x, y, squares, ...props }: React.ComponentProps<"svg"> & { width: number; height: number; x: string | number; y: string | number; squares?: [number, number][] }) {
+export function GridPattern({
+	width,
+	height,
+	x,
+	y,
+	squares,
+	...props
+}: React.ComponentProps<"svg"> & {
+	width: number;
+	height: number;
+	x: string | number;
+	y: string | number;
+	squares?: [number, number][];
+}) {
 	const patternId = useId();
 
 	return (

surfsense_web/components/documents/CreateFolderDialog.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import { FolderPlus } from "lucide-react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Button } from "@/components/ui/button";
+import {
+	Dialog,
+	DialogContent,
+	DialogDescription,
+	DialogFooter,
+	DialogHeader,
+	DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+
+interface CreateFolderDialogProps {
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	parentFolderName?: string | null;
+	onConfirm: (name: string) => void;
+}
+
+export function CreateFolderDialog({
+	open,
+	onOpenChange,
+	parentFolderName,
+	onConfirm,
+}: CreateFolderDialogProps) {
+	const [name, setName] = useState("");
+	const inputRef = useRef<HTMLInputElement>(null);
+
+	useEffect(() => {
+		if (open) {
+			setName("");
+			setTimeout(() => inputRef.current?.focus(), 0);
+		}
+	}, [open]);
+
+	const handleSubmit = useCallback(
+		(e?: React.FormEvent) => {
+			e?.preventDefault();
+			const trimmed = name.trim();
+			if (!trimmed) return;
+			onConfirm(trimmed);
+			onOpenChange(false);
+		},
+		[name, onConfirm, onOpenChange]
+	);
+
+	const isSubfolder = !!parentFolderName;
+
+	return (
+		<Dialog open={open} onOpenChange={onOpenChange}>
+			<DialogContent className="max-w-sm">
+				<DialogHeader>
+					<DialogTitle className="flex items-center gap-2">
+						<FolderPlus className="size-5 text-muted-foreground" />
+						{isSubfolder ? "New subfolder" : "New folder"}
+					</DialogTitle>
+					<DialogDescription>
+						{isSubfolder
+							? `Create a new folder inside "${parentFolderName}".`
+							: "Create a new folder at the root level."}
+					</DialogDescription>
+				</DialogHeader>
+
+				<form onSubmit={handleSubmit} className="flex flex-col gap-4">
+					<div className="flex flex-col gap-2">
+						<Label htmlFor="folder-name">Folder name</Label>
+						<Input
+							ref={inputRef}
+							id="folder-name"
+							placeholder="e.g. Research, Notes, Archive…"
+							value={name}
+							onChange={(e) => setName(e.target.value)}
+							maxLength={255}
+							autoComplete="off"
+						/>
+					</div>
+
+					<DialogFooter>
+						<Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+							Cancel
+						</Button>
+						<Button type="submit" disabled={!name.trim()}>
+							Create
+						</Button>
+					</DialogFooter>
+				</form>
+			</DialogContent>
+		</Dialog>
+	);
+}

surfsense_web/components/documents/DocumentNode.tsx

@@ -0,0 +1,196 @@
+"use client";
+
+import { Eye, MoreHorizontal, Move, Pencil, Trash2 } from "lucide-react";
+import React, { useCallback } from "react";
+import { useDrag } from "react-dnd";
+import { getDocumentTypeIcon } from "@/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentTypeIcon";
+import { Button } from "@/components/ui/button";
+import { Checkbox } from "@/components/ui/checkbox";
+import {
+	ContextMenu,
+	ContextMenuContent,
+	ContextMenuItem,
+	ContextMenuSeparator,
+	ContextMenuTrigger,
+} from "@/components/ui/context-menu";
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuItem,
+	DropdownMenuSeparator,
+	DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import type { DocumentTypeEnum } from "@/contracts/types/document.types";
+import { cn } from "@/lib/utils";
+import { DND_TYPES } from "./FolderNode";
+
+export interface DocumentNodeDoc {
+	id: number;
+	title: string;
+	document_type: string;
+	folderId: number | null;
+	status?: { state: string; reason?: string | null };
+}
+
+interface DocumentNodeProps {
+	doc: DocumentNodeDoc;
+	depth: number;
+	isMentioned: boolean;
+	onToggleChatMention: (doc: DocumentNodeDoc, isMentioned: boolean) => void;
+	onPreview: (doc: DocumentNodeDoc) => void;
+	onEdit: (doc: DocumentNodeDoc) => void;
+	onDelete: (doc: DocumentNodeDoc) => void;
+	onMove: (doc: DocumentNodeDoc) => void;
+}
+
+export const DocumentNode = React.memo(function DocumentNode({
+	doc,
+	depth,
+	isMentioned,
+	onToggleChatMention,
+	onPreview,
+	onEdit,
+	onDelete,
+	onMove,
+}: DocumentNodeProps) {
+	const statusState = doc.status?.state ?? "ready";
+	const isSelectable = statusState !== "pending" && statusState !== "processing";
+	const isEditable =
+		doc.document_type === "NOTE" && statusState !== "pending" && statusState !== "processing";
+
+	const handleCheckChange = useCallback(() => {
+		if (isSelectable) {
+			onToggleChatMention(doc, isMentioned);
+		}
+	}, [doc, isMentioned, isSelectable, onToggleChatMention]);
+
+	const [{ isDragging }, drag] = useDrag(
+		() => ({
+			type: DND_TYPES.DOCUMENT,
+			item: { id: doc.id },
+			collect: (monitor) => ({ isDragging: monitor.isDragging() }),
+		}),
+		[doc.id]
+	);
+
+	const isProcessing = statusState === "pending" || statusState === "processing";
+
+	return (
+		<ContextMenu>
+			<ContextMenuTrigger asChild>
+				{/* biome-ignore lint/a11y/useSemanticElements: div required for drag ref */}
+				<div
+					ref={drag}
+					role="button"
+					tabIndex={0}
+					className={cn(
+						"group flex h-8 items-center gap-1.5 rounded-md px-1 text-sm hover:bg-accent/50 cursor-pointer select-none",
+						isMentioned && "bg-accent/30",
+						isDragging && "opacity-40"
+					)}
+					style={{ paddingLeft: `${depth * 16 + 4}px` }}
+					onClick={handleCheckChange}
+					onKeyDown={(e) => {
+						if (e.key === "Enter" || e.key === " ") {
+							e.preventDefault();
+							handleCheckChange();
+						}
+					}}
+				>
+					{isSelectable ? (
+						<Checkbox
+							checked={isMentioned}
+							onCheckedChange={handleCheckChange}
+							onClick={(e) => e.stopPropagation()}
+							className="h-3.5 w-3.5 shrink-0"
+						/>
+					) : (
+						<span className="flex h-3.5 w-3.5 shrink-0 items-center justify-center">
+							<span
+								className={cn(
+									"h-2 w-2 rounded-full",
+									statusState === "processing" && "animate-pulse bg-amber-500",
+									statusState === "pending" && "bg-muted-foreground/40",
+									statusState === "failed" && "bg-destructive"
+								)}
+							/>
+						</span>
+					)}
+
+					<span className="flex-1 min-w-0 truncate">{doc.title}</span>
+
+					<span className="shrink-0">
+						{getDocumentTypeIcon(
+							doc.document_type as DocumentTypeEnum,
+							"h-3.5 w-3.5 text-muted-foreground"
+						)}
+					</span>
+
+					<DropdownMenu>
+						<DropdownMenuTrigger asChild>
+							<Button
+								variant="ghost"
+								size="icon"
+								className="h-6 w-6 shrink-0 opacity-0 group-hover:opacity-100 transition-opacity"
+								onClick={(e) => e.stopPropagation()}
+							>
+								<MoreHorizontal className="h-3.5 w-3.5" />
+							</Button>
+						</DropdownMenuTrigger>
+						<DropdownMenuContent align="end" className="w-44">
+							<DropdownMenuItem onClick={() => onPreview(doc)}>
+								<Eye className="mr-2 h-4 w-4" />
+								Open
+							</DropdownMenuItem>
+							{isEditable && (
+								<DropdownMenuItem onClick={() => onEdit(doc)}>
+									<Pencil className="mr-2 h-4 w-4" />
+									Edit
+								</DropdownMenuItem>
+							)}
+							<DropdownMenuItem onClick={() => onMove(doc)}>
+								<Move className="mr-2 h-4 w-4" />
+								Move to...
+							</DropdownMenuItem>
+							<DropdownMenuSeparator />
+							<DropdownMenuItem
+								className="text-destructive focus:text-destructive"
+								disabled={isProcessing}
+								onClick={() => onDelete(doc)}
+							>
+								<Trash2 className="mr-2 h-4 w-4" />
+								Delete
+							</DropdownMenuItem>
+						</DropdownMenuContent>
+					</DropdownMenu>
+				</div>
+			</ContextMenuTrigger>
+
+			<ContextMenuContent className="w-44">
+				<ContextMenuItem onClick={() => onPreview(doc)}>
+					<Eye className="mr-2 h-4 w-4" />
+					Open
+				</ContextMenuItem>
+				{isEditable && (
+					<ContextMenuItem onClick={() => onEdit(doc)}>
+						<Pencil className="mr-2 h-4 w-4" />
+						Edit
+					</ContextMenuItem>
+				)}
+				<ContextMenuItem onClick={() => onMove(doc)}>
+					<Move className="mr-2 h-4 w-4" />
+					Move to...
+				</ContextMenuItem>
+				<ContextMenuSeparator />
+				<ContextMenuItem
+					className="text-destructive focus:text-destructive"
+					disabled={isProcessing}
+					onClick={() => onDelete(doc)}
+				>
+					<Trash2 className="mr-2 h-4 w-4" />
+					Delete
+				</ContextMenuItem>
+			</ContextMenuContent>
+		</ContextMenu>
+	);
+});

surfsense_web/components/documents/FolderNode.tsx

@@ -0,0 +1,359 @@
+"use client";
+
+import {
+	ChevronDown,
+	ChevronRight,
+	Folder,
+	FolderOpen,
+	FolderPlus,
+	MoreHorizontal,
+	Move,
+	Pencil,
+	Trash2,
+} from "lucide-react";
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { useDrag, useDrop } from "react-dnd";
+import { Button } from "@/components/ui/button";
+import {
+	ContextMenu,
+	ContextMenuContent,
+	ContextMenuItem,
+	ContextMenuSeparator,
+	ContextMenuTrigger,
+} from "@/components/ui/context-menu";
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuItem,
+	DropdownMenuSeparator,
+	DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { cn } from "@/lib/utils";
+
+export const DND_TYPES = {
+	FOLDER: "FOLDER",
+	DOCUMENT: "DOCUMENT",
+} as const;
+
+type DropZone = "top" | "middle" | "bottom";
+
+export interface FolderDisplay {
+	id: number;
+	name: string;
+	position: string;
+	parentId: number | null;
+	searchSpaceId: number;
+}
+
+interface FolderNodeProps {
+	folder: FolderDisplay;
+	depth: number;
+	isExpanded: boolean;
+	isRenaming: boolean;
+	childCount: number;
+	onToggleExpand: (folderId: number) => void;
+	onRename: (folder: FolderDisplay, newName: string) => void;
+	onStartRename: (folderId: number) => void;
+	onCancelRename: () => void;
+	onDelete: (folder: FolderDisplay) => void;
+	onMove: (folder: FolderDisplay) => void;
+	onCreateSubfolder: (parentId: number) => void;
+	onDropIntoFolder?: (
+		itemType: "folder" | "document",
+		itemId: number,
+		targetFolderId: number
+	) => void;
+	onReorderFolder?: (folderId: number, beforePos: string | null, afterPos: string | null) => void;
+	siblingPositions?: { before: string | null; after: string | null };
+	disabledDropIds?: Set<number>;
+}
+
+function getDropZone(
+	monitor: { getClientOffset: () => { y: number } | null },
+	element: HTMLElement
+): DropZone {
+	const offset = monitor.getClientOffset();
+	if (!offset) return "middle";
+	const rect = element.getBoundingClientRect();
+	const y = offset.y - rect.top;
+	const pct = y / rect.height;
+	if (pct < 0.25) return "top";
+	if (pct > 0.75) return "bottom";
+	return "middle";
+}
+
+export const FolderNode = React.memo(function FolderNode({
+	folder,
+	depth,
+	isExpanded,
+	isRenaming,
+	childCount,
+	onToggleExpand,
+	onRename,
+	onStartRename,
+	onCancelRename,
+	onDelete,
+	onMove,
+	onCreateSubfolder,
+	onDropIntoFolder,
+	onReorderFolder,
+	siblingPositions,
+	disabledDropIds,
+}: FolderNodeProps) {
+	const [renameValue, setRenameValue] = useState(folder.name);
+	const inputRef = useRef<HTMLInputElement>(null);
+	const rowRef = useRef<HTMLDivElement>(null);
+	const [dropZone, setDropZone] = useState<DropZone | null>(null);
+
+	const [{ isDragging }, drag] = useDrag(
+		() => ({
+			type: DND_TYPES.FOLDER,
+			item: { id: folder.id, position: folder.position, parentId: folder.parentId },
+			collect: (monitor) => ({ isDragging: monitor.isDragging() }),
+		}),
+		[folder.id, folder.position, folder.parentId]
+	);
+
+	const [{ isOver, canDrop }, drop] = useDrop(
+		() => ({
+			accept: [DND_TYPES.FOLDER, DND_TYPES.DOCUMENT],
+			canDrop: (item: { id: number }) => {
+				if (item.id === folder.id) return false;
+				if (disabledDropIds?.has(item.id)) return false;
+				return true;
+			},
+			hover: (_item, monitor) => {
+				if (!rowRef.current || !monitor.isOver({ shallow: true })) {
+					setDropZone(null);
+					return;
+				}
+				setDropZone(getDropZone(monitor, rowRef.current));
+			},
+			drop: (item: { id: number }, monitor) => {
+				if (!rowRef.current) return;
+				const zone = getDropZone(monitor, rowRef.current);
+				const type = monitor.getItemType();
+
+				if (zone === "middle") {
+					if (type === DND_TYPES.FOLDER) {
+						onDropIntoFolder?.("folder", item.id, folder.id);
+					} else {
+						onDropIntoFolder?.("document", item.id, folder.id);
+					}
+				} else if (type === DND_TYPES.FOLDER && onReorderFolder && siblingPositions) {
+					if (zone === "top") {
+						onReorderFolder(item.id, siblingPositions.before, folder.position);
+					} else {
+						onReorderFolder(item.id, folder.position, siblingPositions.after);
+					}
+				}
+				setDropZone(null);
+			},
+			collect: (monitor) => ({
+				isOver: monitor.isOver({ shallow: true }),
+				canDrop: monitor.canDrop(),
+			}),
+		}),
+		[
+			folder.id,
+			folder.position,
+			disabledDropIds,
+			onDropIntoFolder,
+			onReorderFolder,
+			siblingPositions,
+		]
+	);
+
+	useEffect(() => {
+		if (!isOver) setDropZone(null);
+	}, [isOver]);
+
+	const attachRef = useCallback(
+		(node: HTMLDivElement | null) => {
+			rowRef.current = node;
+			drag(drop(node));
+		},
+		[drag, drop]
+	);
+
+	useEffect(() => {
+		if (isRenaming && inputRef.current) {
+			inputRef.current.focus();
+			inputRef.current.select();
+		}
+	}, [isRenaming]);
+
+	const handleRenameSubmit = useCallback(() => {
+		const trimmed = renameValue.trim();
+		if (trimmed && trimmed !== folder.name) {
+			onRename(folder, trimmed);
+		}
+		onCancelRename();
+	}, [renameValue, folder, onRename, onCancelRename]);
+
+	const handleRenameKeyDown = useCallback(
+		(e: React.KeyboardEvent) => {
+			if (e.key === "Enter") {
+				e.preventDefault();
+				handleRenameSubmit();
+			} else if (e.key === "Escape") {
+				e.preventDefault();
+				setRenameValue(folder.name);
+				onCancelRename();
+			}
+		},
+		[handleRenameSubmit, folder.name, onCancelRename]
+	);
+
+	const startRename = useCallback(() => {
+		setRenameValue(folder.name);
+		onStartRename(folder.id);
+	}, [folder, onStartRename]);
+
+	const FolderIcon = isExpanded ? FolderOpen : Folder;
+
+	return (
+		<ContextMenu>
+			<ContextMenuTrigger asChild disabled={isRenaming}>
+				{/* biome-ignore lint/a11y/useSemanticElements: div required for drag/drop refs */}
+				<div
+					ref={attachRef}
+					role="button"
+					tabIndex={0}
+					className={cn(
+						"group relative flex h-8 items-center gap-1 rounded-md px-1 text-sm hover:bg-accent/50 cursor-pointer select-none",
+						isExpanded && "font-medium",
+						isDragging && "opacity-40",
+						isOver && canDrop && dropZone === "middle" && "bg-accent ring-1 ring-primary/40",
+						isOver && canDrop && dropZone === "top" && "border-t-2 border-primary",
+						isOver && canDrop && dropZone === "bottom" && "border-b-2 border-primary",
+						isOver && !canDrop && "cursor-not-allowed"
+					)}
+					style={{ paddingLeft: `${depth * 16 + 4}px` }}
+					onClick={() => onToggleExpand(folder.id)}
+					onKeyDown={(e) => {
+						if (e.key === "Enter" || e.key === " ") {
+							e.preventDefault();
+							onToggleExpand(folder.id);
+						}
+					}}
+					onDoubleClick={(e) => {
+						e.stopPropagation();
+						startRename();
+					}}
+				>
+					<span className="flex h-4 w-4 shrink-0 items-center justify-center">
+						{isExpanded ? (
+							<ChevronDown className="h-3.5 w-3.5 text-muted-foreground" />
+						) : (
+							<ChevronRight className="h-3.5 w-3.5 text-muted-foreground" />
+						)}
+					</span>
+
+					<FolderIcon className="h-4 w-4 shrink-0 text-muted-foreground" />
+
+					{isRenaming ? (
+						<input
+							ref={inputRef}
+							type="text"
+							value={renameValue}
+							onChange={(e) => setRenameValue(e.target.value)}
+							onBlur={handleRenameSubmit}
+							onKeyDown={handleRenameKeyDown}
+							onClick={(e) => e.stopPropagation()}
+							className="flex-1 min-w-0 rounded border border-primary bg-background px-1 py-0.5 text-sm outline-none"
+						/>
+					) : (
+						<span className="flex-1 min-w-0 truncate">{folder.name}</span>
+					)}
+
+					{!isRenaming && childCount > 0 && (
+						<span className="shrink-0 text-[10px] text-muted-foreground tabular-nums">
+							{childCount}
+						</span>
+					)}
+
+					{!isRenaming && (
+						<DropdownMenu>
+							<DropdownMenuTrigger asChild>
+								<Button
+									variant="ghost"
+									size="icon"
+									className="h-6 w-6 shrink-0 opacity-0 group-hover:opacity-100 transition-opacity"
+									onClick={(e) => e.stopPropagation()}
+								>
+									<MoreHorizontal className="h-3.5 w-3.5" />
+								</Button>
+							</DropdownMenuTrigger>
+							<DropdownMenuContent align="end" className="w-48">
+								<DropdownMenuItem
+									onClick={(e) => {
+										e.stopPropagation();
+										onCreateSubfolder(folder.id);
+									}}
+								>
+									<FolderPlus className="mr-2 h-4 w-4" />
+									New subfolder
+								</DropdownMenuItem>
+								<DropdownMenuItem
+									onClick={(e) => {
+										e.stopPropagation();
+										startRename();
+									}}
+								>
+									<Pencil className="mr-2 h-4 w-4" />
+									Rename
+								</DropdownMenuItem>
+								<DropdownMenuItem
+									onClick={(e) => {
+										e.stopPropagation();
+										onMove(folder);
+									}}
+								>
+									<Move className="mr-2 h-4 w-4" />
+									Move to...
+								</DropdownMenuItem>
+								<DropdownMenuSeparator />
+								<DropdownMenuItem
+									className="text-destructive focus:text-destructive"
+									onClick={(e) => {
+										e.stopPropagation();
+										onDelete(folder);
+									}}
+								>
+									<Trash2 className="mr-2 h-4 w-4" />
+									Delete
+								</DropdownMenuItem>
+							</DropdownMenuContent>
+						</DropdownMenu>
+					)}
+				</div>
+			</ContextMenuTrigger>
+
+			{!isRenaming && (
+				<ContextMenuContent className="w-48">
+					<ContextMenuItem onClick={() => onCreateSubfolder(folder.id)}>
+						<FolderPlus className="mr-2 h-4 w-4" />
+						New subfolder
+					</ContextMenuItem>
+					<ContextMenuItem onClick={() => startRename()}>
+						<Pencil className="mr-2 h-4 w-4" />
+						Rename
+					</ContextMenuItem>
+					<ContextMenuItem onClick={() => onMove(folder)}>
+						<Move className="mr-2 h-4 w-4" />
+						Move to...
+					</ContextMenuItem>
+					<ContextMenuSeparator />
+					<ContextMenuItem
+						className="text-destructive focus:text-destructive"
+						onClick={() => onDelete(folder)}
+					>
+						<Trash2 className="mr-2 h-4 w-4" />
+						Delete
+					</ContextMenuItem>
+				</ContextMenuContent>
+			)}
+		</ContextMenu>
+	);
+});

surfsense_web/components/documents/FolderPickerDialog.tsx

@@ -0,0 +1,159 @@
+"use client";
+
+import { ChevronDown, ChevronRight, Folder, FolderOpen, Home } from "lucide-react";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Button } from "@/components/ui/button";
+import {
+	Dialog,
+	DialogContent,
+	DialogDescription,
+	DialogFooter,
+	DialogHeader,
+	DialogTitle,
+} from "@/components/ui/dialog";
+import { cn } from "@/lib/utils";
+import type { FolderDisplay } from "./FolderNode";
+
+interface FolderPickerDialogProps {
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	folders: FolderDisplay[];
+	title: string;
+	description?: string;
+	disabledFolderIds?: Set<number>;
+	onSelect: (folderId: number | null) => void;
+}
+
+export function FolderPickerDialog({
+	open,
+	onOpenChange,
+	folders,
+	title,
+	description,
+	disabledFolderIds,
+	onSelect,
+}: FolderPickerDialogProps) {
+	const [selectedId, setSelectedId] = useState<number | null>(null);
+	const [expandedIds, setExpandedIds] = useState<Set<number>>(new Set());
+
+	useEffect(() => {
+		if (open) {
+			setSelectedId(null);
+			setExpandedIds(new Set());
+		}
+	}, [open]);
+
+	const foldersByParent = useMemo(() => {
+		const map: Record<string, FolderDisplay[]> = {};
+		for (const f of folders) {
+			const key = f.parentId ?? "root";
+			if (!map[key]) map[key] = [];
+			map[key].push(f);
+		}
+		return map;
+	}, [folders]);
+
+	const toggleExpand = useCallback((id: number) => {
+		setExpandedIds((prev) => {
+			const next = new Set(prev);
+			if (next.has(id)) next.delete(id);
+			else next.add(id);
+			return next;
+		});
+	}, []);
+
+	const handleConfirm = useCallback(() => {
+		onSelect(selectedId);
+		onOpenChange(false);
+	}, [selectedId, onSelect, onOpenChange]);
+
+	function renderPickerLevel(parentId: number | null, depth: number): React.ReactNode[] {
+		const key = parentId ?? "root";
+		const children = (foldersByParent[key] ?? [])
+			.slice()
+			.sort((a, b) => a.position.localeCompare(b.position));
+
+		return children.flatMap((f) => {
+			const isDisabled = disabledFolderIds?.has(f.id) ?? false;
+			const isExpanded = expandedIds.has(f.id);
+			const hasChildren = (foldersByParent[f.id] ?? []).length > 0;
+			const isSelected = selectedId === f.id;
+			const FolderIcon = isExpanded ? FolderOpen : Folder;
+
+			return [
+				<button
+					key={f.id}
+					type="button"
+					disabled={isDisabled}
+					className={cn(
+						"flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-sm transition-colors",
+						isSelected && "bg-accent text-accent-foreground",
+						!isSelected && !isDisabled && "hover:bg-accent/50",
+						isDisabled && "cursor-not-allowed opacity-40"
+					)}
+					style={{ paddingLeft: `${depth * 16 + 8}px` }}
+					onClick={() => {
+						if (!isDisabled) setSelectedId(f.id);
+					}}
+				>
+					{hasChildren ? (
+						<button
+							type="button"
+							className="flex h-4 w-4 shrink-0 items-center justify-center"
+							onClick={(e) => {
+								e.stopPropagation();
+								toggleExpand(f.id);
+							}}
+						>
+							{isExpanded ? (
+								<ChevronDown className="h-3.5 w-3.5" />
+							) : (
+								<ChevronRight className="h-3.5 w-3.5" />
+							)}
+						</button>
+					) : (
+						<span className="h-4 w-4 shrink-0" />
+					)}
+					<FolderIcon className="h-4 w-4 shrink-0 text-muted-foreground" />
+					<span className="truncate">{f.name}</span>
+				</button>,
+				...(isExpanded ? renderPickerLevel(f.id, depth + 1) : []),
+			];
+		});
+	}
+
+	return (
+		<Dialog open={open} onOpenChange={onOpenChange}>
+			<DialogContent className="max-w-sm">
+				<DialogHeader>
+					<DialogTitle>{title}</DialogTitle>
+					{description && <DialogDescription>{description}</DialogDescription>}
+				</DialogHeader>
+
+				<div className="max-h-[300px] overflow-y-auto rounded-md border p-1">
+					<button
+						type="button"
+						className={cn(
+							"flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-sm transition-colors",
+							selectedId === null && "bg-accent text-accent-foreground",
+							selectedId !== null && "hover:bg-accent/50"
+						)}
+						onClick={() => setSelectedId(null)}
+					>
+						<span className="h-4 w-4 shrink-0" />
+						<Home className="h-4 w-4 shrink-0 text-muted-foreground" />
+						<span>Root</span>
+					</button>
+					{renderPickerLevel(null, 1)}
+				</div>
+
+				<DialogFooter>
+					<Button variant="outline" onClick={() => onOpenChange(false)}>
+						Cancel
+					</Button>
+					<Button onClick={handleConfirm}>Move here</Button>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+}

surfsense_web/components/documents/FolderTreeView.tsx

@@ -0,0 +1,212 @@
+"use client";
+
+import { useAtom } from "jotai";
+import { TreePine } from "lucide-react";
+import { useCallback, useMemo } from "react";
+import { DndProvider } from "react-dnd";
+import { HTML5Backend } from "react-dnd-html5-backend";
+import { renamingFolderIdAtom } from "@/atoms/documents/folder.atoms";
+import type { DocumentTypeEnum } from "@/contracts/types/document.types";
+import { DocumentNode, type DocumentNodeDoc } from "./DocumentNode";
+import { type FolderDisplay, FolderNode } from "./FolderNode";
+
+interface FolderTreeViewProps {
+	folders: FolderDisplay[];
+	documents: DocumentNodeDoc[];
+	expandedIds: Set<number>;
+	onToggleExpand: (folderId: number) => void;
+	mentionedDocIds: Set<number>;
+	onToggleChatMention: (
+		doc: { id: number; title: string; document_type: string },
+		isMentioned: boolean
+	) => void;
+	onRenameFolder: (folder: FolderDisplay, newName: string) => void;
+	onDeleteFolder: (folder: FolderDisplay) => void;
+	onMoveFolder: (folder: FolderDisplay) => void;
+	onCreateFolder: (parentId: number | null) => void;
+	onPreviewDocument: (doc: DocumentNodeDoc) => void;
+	onEditDocument: (doc: DocumentNodeDoc) => void;
+	onDeleteDocument: (doc: DocumentNodeDoc) => void;
+	onMoveDocument: (doc: DocumentNodeDoc) => void;
+	activeTypes: DocumentTypeEnum[];
+	onDropIntoFolder?: (
+		itemType: "folder" | "document",
+		itemId: number,
+		targetFolderId: number | null
+	) => void;
+	onReorderFolder?: (folderId: number, beforePos: string | null, afterPos: string | null) => void;
+}
+
+function groupBy<T>(items: T[], keyFn: (item: T) => string | number): Record<string | number, T[]> {
+	const result: Record<string | number, T[]> = {};
+	for (const item of items) {
+		const key = keyFn(item);
+		if (!result[key]) result[key] = [];
+		result[key].push(item);
+	}
+	return result;
+}
+
+export function FolderTreeView({
+	folders,
+	documents,
+	expandedIds,
+	onToggleExpand,
+	mentionedDocIds,
+	onToggleChatMention,
+	onRenameFolder,
+	onDeleteFolder,
+	onMoveFolder,
+	onCreateFolder,
+	onPreviewDocument,
+	onEditDocument,
+	onDeleteDocument,
+	onMoveDocument,
+	activeTypes,
+	onDropIntoFolder,
+	onReorderFolder,
+}: FolderTreeViewProps) {
+	const foldersByParent = useMemo(() => groupBy(folders, (f) => f.parentId ?? "root"), [folders]);
+
+	const docsByFolder = useMemo(() => groupBy(documents, (d) => d.folderId ?? "root"), [documents]);
+
+	const folderChildCounts = useMemo(() => {
+		const counts: Record<number, number> = {};
+		for (const f of folders) {
+			const children = foldersByParent[f.id] ?? [];
+			const docs = docsByFolder[f.id] ?? [];
+			counts[f.id] = children.length + docs.length;
+		}
+		return counts;
+	}, [folders, foldersByParent, docsByFolder]);
+
+	// Single subscription for rename state — derived boolean passed to each FolderNode
+	const [renamingFolderId, setRenamingFolderId] = useAtom(renamingFolderIdAtom);
+	const handleStartRename = useCallback(
+		(folderId: number) => setRenamingFolderId(folderId),
+		[setRenamingFolderId]
+	);
+	const handleCancelRename = useCallback(() => setRenamingFolderId(null), [setRenamingFolderId]);
+
+	const hasDescendantMatch = useMemo(() => {
+		if (activeTypes.length === 0) return null;
+		const match: Record<number, boolean> = {};
+
+		function check(folderId: number): boolean {
+			if (match[folderId] !== undefined) return match[folderId];
+			const childDocs = (docsByFolder[folderId] ?? []).some((d) =>
+				activeTypes.includes(d.document_type as DocumentTypeEnum)
+			);
+			if (childDocs) {
+				match[folderId] = true;
+				return true;
+			}
+			const childFolders = foldersByParent[folderId] ?? [];
+			for (const cf of childFolders) {
+				if (check(cf.id)) {
+					match[folderId] = true;
+					return true;
+				}
+			}
+			match[folderId] = false;
+			return false;
+		}
+
+		for (const f of folders) {
+			check(f.id);
+		}
+		return match;
+	}, [folders, docsByFolder, foldersByParent, activeTypes]);
+
+	function renderLevel(parentId: number | null, depth: number): React.ReactNode[] {
+		const key = parentId ?? "root";
+		const childFolders = (foldersByParent[key] ?? [])
+			.slice()
+			.sort((a, b) => a.position.localeCompare(b.position));
+		const visibleFolders = hasDescendantMatch
+			? childFolders.filter((f) => hasDescendantMatch[f.id])
+			: childFolders;
+		const childDocs = (docsByFolder[key] ?? []).filter(
+			(d) => activeTypes.length === 0 || activeTypes.includes(d.document_type as DocumentTypeEnum)
+		);
+
+		const nodes: React.ReactNode[] = [];
+
+		for (let i = 0; i < visibleFolders.length; i++) {
+			const f = visibleFolders[i];
+			const siblingPositions = {
+				before: i > 0 ? visibleFolders[i - 1].position : null,
+				after: i < visibleFolders.length - 1 ? visibleFolders[i + 1].position : null,
+			};
+
+			nodes.push(
+				<FolderNode
+					key={`folder-${f.id}`}
+					folder={f}
+					depth={depth}
+					isExpanded={expandedIds.has(f.id)}
+					isRenaming={renamingFolderId === f.id}
+					childCount={folderChildCounts[f.id] ?? 0}
+					onToggleExpand={onToggleExpand}
+					onRename={onRenameFolder}
+					onStartRename={handleStartRename}
+					onCancelRename={handleCancelRename}
+					onDelete={onDeleteFolder}
+					onMove={onMoveFolder}
+					onCreateSubfolder={onCreateFolder}
+					onDropIntoFolder={onDropIntoFolder}
+					onReorderFolder={onReorderFolder}
+					siblingPositions={siblingPositions}
+				/>
+			);
+
+			if (expandedIds.has(f.id)) {
+				nodes.push(...renderLevel(f.id, depth + 1));
+			}
+		}
+
+		for (const d of childDocs) {
+			nodes.push(
+				<DocumentNode
+					key={`doc-${d.id}`}
+					doc={d}
+					depth={depth}
+					isMentioned={mentionedDocIds.has(d.id)}
+					onToggleChatMention={onToggleChatMention}
+					onPreview={onPreviewDocument}
+					onEdit={onEditDocument}
+					onDelete={onDeleteDocument}
+					onMove={onMoveDocument}
+				/>
+			);
+		}
+
+		return nodes;
+	}
+
+	const treeNodes = renderLevel(null, 0);
+
+	if (treeNodes.length === 0 && folders.length === 0 && documents.length === 0) {
+		return (
+			<div className="flex flex-1 flex-col items-center justify-center gap-3 px-4 py-12 text-muted-foreground">
+				<TreePine className="h-10 w-10" />
+				<p className="text-sm">No documents yet</p>
+			</div>
+		);
+	}
+
+	if (treeNodes.length === 0 && activeTypes.length > 0) {
+		return (
+			<div className="flex flex-1 flex-col items-center justify-center gap-3 px-4 py-12 text-muted-foreground">
+				<TreePine className="h-10 w-10" />
+				<p className="text-sm">No matching documents</p>
+			</div>
+		);
+	}
+
+	return (
+		<DndProvider backend={HTML5Backend}>
+			<div className="flex-1 min-h-0 overflow-y-auto px-2 py-1">{treeNodes}</div>
+		</DndProvider>
+	);
+}

surfsense_web/components/homepage/github-stars-badge.tsx

@@ -3,6 +3,7 @@
 import { IconBrandGithub } from "@tabler/icons-react";
 import { motion, useMotionValue, useSpring } from "motion/react";
 import * as React from "react";
+import { Skeleton } from "@/components/ui/skeleton";
 import { cn } from "@/lib/utils";
 
 // ---------------------------------------------------------------------------
@@ -277,12 +278,16 @@ function NavbarGitHubStars({
 			)}
 		>
 			<IconBrandGithub className="h-5 w-5 text-neutral-700 dark:text-neutral-300 shrink-0" />
-			<AnimatedStarCount
-				value={isLoading ? 10000 : stars}
-				itemSize={ITEM_SIZE}
-				isRolling={isLoading}
-				className="text-sm font-semibold tabular-nums text-neutral-700 dark:text-neutral-300 group-hover:text-neutral-900 dark:group-hover:text-neutral-100 transition-colors"
-			/>
+			{isLoading ? (
+				<Skeleton className="h-4 w-10" />
+			) : (
+				<AnimatedStarCount
+					value={stars}
+					itemSize={ITEM_SIZE}
+					isRolling={false}
+					className="text-sm font-semibold tabular-nums text-neutral-700 dark:text-neutral-300 group-hover:text-neutral-900 dark:group-hover:text-neutral-100 transition-colors"
+				/>
+			)}
 		</a>
 	);
 }

surfsense_web/components/homepage/hero-section.tsx

@@ -35,7 +35,14 @@ const HeroCarousel = dynamic(
 
 // Official Google "G" logo with brand colors
 const GoogleLogo = ({ className }: { className?: string }) => (
-	<svg className={className} viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+	<svg
+		className={className}
+		viewBox="0 0 24 24"
+		xmlns="http://www.w3.org/2000/svg"
+		role="img"
+		aria-label="Google logo"
+	>
+		<title>Google logo</title>
 		<path
 			d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"
 			fill="#4285F4"
@@ -277,21 +284,24 @@ const CollisionMechanism = ({
 	}, [cycleCollisionDetected, parentRef]);
 
 	useEffect(() => {
-		if (collision.detected && collision.coordinates) {
-			setTimeout(() => {
-				setCollision({ detected: false, coordinates: null });
-				setCycleCollisionDetected(false);
-				// Set beam opacity to 0
-				if (beamRef.current) {
-					beamRef.current.style.opacity = "1";
-				}
-			}, 2000);
+		if (!collision.detected || !collision.coordinates) return;
 
-			// Reset the beam animation after a delay
-			setTimeout(() => {
-				setBeamKey((prevKey) => prevKey + 1);
-			}, 2000);
-		}
+		const timer1 = setTimeout(() => {
+			setCollision({ detected: false, coordinates: null });
+			setCycleCollisionDetected(false);
+			if (beamRef.current) {
+				beamRef.current.style.opacity = "1";
+			}
+		}, 2000);
+
+		const timer2 = setTimeout(() => {
+			setBeamKey((prevKey) => prevKey + 1);
+		}, 2000);
+
+		return () => {
+			clearTimeout(timer1);
+			clearTimeout(timer2);
+		};
 	}, [collision]);
 
 	return (

surfsense_web/components/homepage/use-cases-grid.tsx

@@ -63,9 +63,18 @@ function UseCaseCard({
 				transition={{ duration: 0.5, ease: "easeOut" }}
 				className={`group overflow-hidden rounded-2xl border border-neutral-200/60 bg-white shadow-sm transition-shadow duration-300 hover:shadow-xl dark:border-neutral-700/60 dark:bg-neutral-900 ${className ?? ""}`}
 			>
+				{/* biome-ignore lint/a11y/useSemanticElements: div wraps img, button would break layout */}
 				<div
+					role="button"
+					tabIndex={0}
 					className="cursor-pointer overflow-hidden bg-neutral-50 p-2 dark:bg-neutral-950"
 					onClick={open}
+					onKeyDown={(e) => {
+						if (e.key === "Enter" || e.key === " ") {
+							e.preventDefault();
+							open();
+						}
+					}}
 				>
 					<img
 						src={src}

surfsense_web/components/layout/providers/LayoutDataProvider.tsx

@@ -20,6 +20,7 @@ import {
 	teamDialogAtom,
 	userSettingsDialogAtom,
 } from "@/atoms/settings/settings-dialog.atoms";
+import { resetTabsAtom, syncChatTabAtom, type Tab } from "@/atoms/tabs/tabs.atom";
 import { currentUserAtom } from "@/atoms/user/user-query.atoms";
 import { MorePagesDialog } from "@/components/settings/more-pages-dialog";
 import { SearchSpaceSettingsDialog } from "@/components/settings/search-space-settings-dialog";
@@ -100,6 +101,8 @@ export function LayoutDataProvider({ searchSpaceId, children }: LayoutDataProvid
 	const { mutateAsync: deleteSearchSpace } = useAtomValue(deleteSearchSpaceMutationAtom);
 	const currentThreadState = useAtomValue(currentThreadAtom);
 	const resetCurrentThread = useSetAtom(resetCurrentThreadAtom);
+	const syncChatTab = useSetAtom(syncChatTabAtom);
+	const resetTabs = useSetAtom(resetTabsAtom);
 
 	// State for handling new chat navigation when router is out of sync
 	const [pendingNewChat, setPendingNewChat] = useState(false);
@@ -264,10 +267,16 @@ export function LayoutDataProvider({ searchSpaceId, children }: LayoutDataProvid
 		}
 	}, [pendingNewChat, params?.chat_id, router, searchSpaceId, resetCurrentThread]);
 
-	// Reset transient slide-out panels when switching search spaces.
+	// Reset transient slide-out panels and tabs when switching search spaces.
+	// Use a ref to skip the initial mount — only reset when the space actually changes.
+	const prevSearchSpaceIdRef = useRef(searchSpaceId);
 	useEffect(() => {
-		setActiveSlideoutPanel(null);
-	}, [searchSpaceId]);
+		if (prevSearchSpaceIdRef.current !== searchSpaceId) {
+			prevSearchSpaceIdRef.current = searchSpaceId;
+			setActiveSlideoutPanel(null);
+			resetTabs();
+		}
+	}, [searchSpaceId, resetTabs]);
 
 	const searchSpaces: SearchSpace[] = useMemo(() => {
 		if (!searchSpacesData || !Array.isArray(searchSpacesData)) return [];
@@ -307,6 +316,20 @@ export function LayoutDataProvider({ searchSpaceId, children }: LayoutDataProvid
 		router,
 	]);
 
+	// Sync current chat route with tab state
+	useEffect(() => {
+		const chatId = currentChatId ?? null;
+		const chatUrl = chatId
+			? `/dashboard/${searchSpaceId}/new-chat/${chatId}`
+			: `/dashboard/${searchSpaceId}/new-chat`;
+		const thread = threadsData?.threads?.find((t) => t.id === chatId);
+		syncChatTab({
+			chatId,
+			title: thread?.title || (chatId ? `Chat ${chatId}` : "New Chat"),
+			chatUrl,
+		});
+	}, [currentChatId, searchSpaceId, threadsData?.threads, syncChatTab]);
+
 	// Transform and split chats into private and shared based on visibility
 	const { myChats, sharedChats } = useMemo(() => {
 		if (!threadsData?.threads) return { myChats: [], sharedChats: [] };
@@ -473,6 +496,17 @@ export function LayoutDataProvider({ searchSpaceId, children }: LayoutDataProvid
 		}
 	}, [searchSpaceToLeave, refetchSearchSpaces, searchSpaceId, router, t]);
 
+	const handleTabSwitch = useCallback(
+		(tab: Tab) => {
+			if (tab.type === "chat") {
+				const url = tab.chatUrl || `/dashboard/${searchSpaceId}/new-chat`;
+				router.push(url);
+			}
+			// Document tabs are handled in-place by LayoutShell — no navigation needed
+		},
+		[router, searchSpaceId]
+	);
+
 	const handleNavItemClick = useCallback(
 		(item: NavItem) => {
 			if (item.url === "#inbox") {
@@ -738,6 +772,7 @@ export function LayoutDataProvider({ searchSpaceId, children }: LayoutDataProvid
 					isDocked: isDocumentsDocked,
 					onDockedChange: setIsDocumentsDocked,
 				}}
+				onTabSwitch={handleTabSwitch}
 			>
 				<Fragment key={chatResetKey}>{children}</Fragment>
 			</LayoutShell>

surfsense_web/components/layout/ui/header/Header.tsx

@@ -8,6 +8,7 @@ import { reportPanelAtom } from "@/atoms/chat/report-panel.atom";
 import { documentsSidebarOpenAtom } from "@/atoms/documents/ui.atoms";
 import { rightPanelCollapsedAtom } from "@/atoms/layout/right-panel.atom";
 import { activeSearchSpaceIdAtom } from "@/atoms/search-spaces/search-space-query.atoms";
+import { activeTabAtom } from "@/atoms/tabs/tabs.atom";
 import { ChatHeader } from "@/components/new-chat/chat-header";
 import { ChatShareButton } from "@/components/new-chat/chat-share-button";
 import { Button } from "@/components/ui/button";
@@ -23,12 +24,14 @@ export function Header({ mobileMenuTrigger }: HeaderProps) {
 	const pathname = usePathname();
 	const searchSpaceId = useAtomValue(activeSearchSpaceIdAtom);
 	const isMobile = useIsMobile();
+	const activeTab = useAtomValue(activeTabAtom);
 
 	const isChatPage = pathname?.includes("/new-chat") ?? false;
+	const isDocumentTab = activeTab?.type === "document";
 
 	const currentThreadState = useAtomValue(currentThreadAtom);
 
-	const hasThread = isChatPage && currentThreadState.id !== null;
+	const hasThread = isChatPage && !isDocumentTab && currentThreadState.id !== null;
 
 	const threadForButton: ThreadRecord | null =
 		hasThread && currentThreadState.id !== null
@@ -58,7 +61,7 @@ export function Header({ mobileMenuTrigger }: HeaderProps) {
 			{/* Left side - Mobile menu trigger + Model selector */}
 			<div className="flex flex-1 items-center gap-2 min-w-0">
 				{mobileMenuTrigger}
-				{isChatPage && searchSpaceId && (
+				{isChatPage && !isDocumentTab && searchSpaceId && (
 					<ChatHeader searchSpaceId={Number(searchSpaceId)} className="md:h-9 md:px-4 md:text-sm" />
 				)}
 			</div>

surfsense_web/components/layout/ui/shell/LayoutShell.tsx

@@ -1,7 +1,9 @@
 "use client";
 
+import { useAtomValue } from "jotai";
 import { AnimatePresence, motion } from "motion/react";
 import { useCallback, useMemo, useState } from "react";
+import { activeTabAtom, type Tab } from "@/atoms/tabs/tabs.atom";
 import { TooltipProvider } from "@/components/ui/tooltip";
 import type { InboxItem } from "@/hooks/use-inbox";
 import { useIsMobile } from "@/hooks/use-mobile";
@@ -23,6 +25,8 @@ import {
 	Sidebar,
 } from "../sidebar";
 import { SidebarSlideOutPanel } from "../sidebar/SidebarSlideOutPanel";
+import { DocumentTabContent } from "../tabs/DocumentTabContent";
+import { TabBar } from "../tabs/TabBar";
 
 // Per-tab data source
 interface TabDataSource {
@@ -97,6 +101,44 @@ interface LayoutShellProps {
 		isDocked?: boolean;
 		onDockedChange?: (docked: boolean) => void;
 	};
+	onTabSwitch?: (tab: Tab) => void;
+}
+
+function MainContentPanel({
+	isChatPage,
+	onTabSwitch,
+	onNewChat,
+	children,
+}: {
+	isChatPage: boolean;
+	onTabSwitch?: (tab: Tab) => void;
+	onNewChat?: () => void;
+	children: React.ReactNode;
+}) {
+	const activeTab = useAtomValue(activeTabAtom);
+	const isDocumentTab = activeTab?.type === "document";
+
+	return (
+		<div className="relative flex flex-1 flex-col rounded-xl border bg-main-panel overflow-hidden min-w-0">
+			<TabBar onTabSwitch={onTabSwitch} onNewChat={onNewChat} />
+			<Header />
+
+			{isDocumentTab && activeTab.documentId && activeTab.searchSpaceId ? (
+				<div className="flex-1 overflow-hidden">
+					<DocumentTabContent
+						key={activeTab.documentId}
+						documentId={activeTab.documentId}
+						searchSpaceId={activeTab.searchSpaceId}
+						title={activeTab.title}
+					/>
+				</div>
+			) : (
+				<div className={cn("flex-1", isChatPage ? "overflow-hidden" : "overflow-auto")}>
+					{children}
+				</div>
+			)}
+		</div>
+	);
 }
 
 export function LayoutShell({
@@ -138,6 +180,7 @@ export function LayoutShell({
 	allSharedChatsPanel,
 	allPrivateChatsPanel,
 	documentsPanel,
+	onTabSwitch,
 }: LayoutShellProps) {
 	const isMobile = useIsMobile();
 	const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
@@ -455,13 +498,9 @@ export function LayoutShell({
 					)}
 
 					{/* Main content panel */}
-					<div className="relative flex flex-1 flex-col rounded-xl border bg-main-panel overflow-hidden min-w-0">
-						<Header />
-
-						<div className={cn("flex-1", isChatPage ? "overflow-hidden" : "overflow-auto")}>
-							{children}
-						</div>
-					</div>
+					<MainContentPanel isChatPage={isChatPage} onTabSwitch={onTabSwitch} onNewChat={onNewChat}>
+						{children}
+					</MainContentPanel>
 
 					{/* Right panel — tabbed Sources/Report (desktop only) */}
 					{documentsPanel && (

surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useQuery } from "@rocicorp/zero/react";
 import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import { ChevronLeft, ChevronRight, Unplug } from "lucide-react";
 import { useParams } from "next/navigation";
@@ -15,6 +16,13 @@ import { sidebarSelectedDocumentsAtom } from "@/atoms/chat/mentioned-documents.a
 import { connectorDialogOpenAtom } from "@/atoms/connector-dialog/connector-dialog.atoms";
 import { connectorsAtom } from "@/atoms/connectors/connector-query.atoms";
 import { deleteDocumentMutationAtom } from "@/atoms/documents/document-mutation.atoms";
+import { expandedFolderIdsAtom } from "@/atoms/documents/folder.atoms";
+import { openDocumentTabAtom } from "@/atoms/tabs/tabs.atom";
+import { CreateFolderDialog } from "@/components/documents/CreateFolderDialog";
+import type { DocumentNodeDoc } from "@/components/documents/DocumentNode";
+import type { FolderDisplay } from "@/components/documents/FolderNode";
+import { FolderPickerDialog } from "@/components/documents/FolderPickerDialog";
+import { FolderTreeView } from "@/components/documents/FolderTreeView";
 import { Avatar, AvatarFallback, AvatarGroup } from "@/components/ui/avatar";
 import { Button } from "@/components/ui/button";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
@@ -24,6 +32,8 @@ import { useDebouncedValue } from "@/hooks/use-debounced-value";
 import { useDocumentSearch } from "@/hooks/use-document-search";
 import { useDocuments } from "@/hooks/use-documents";
 import { useMediaQuery } from "@/hooks/use-media-query";
+import { foldersApiService } from "@/lib/apis/folders-api.service";
+import { queries } from "@/zero/queries/index";
 import { SidebarSlideOutPanel } from "./SidebarSlideOutPanel";
 
 const SHOWCASE_CONNECTORS = [
@@ -63,6 +73,7 @@ export function DocumentsSidebar({
 	const isMobile = !useMediaQuery("(min-width: 640px)");
 	const searchSpaceId = Number(params.search_space_id);
 	const setConnectorDialogOpen = useSetAtom(connectorDialogOpenAtom);
+	const openDocumentTab = useSetAtom(openDocumentTabAtom);
 	const { data: connectors } = useAtomValue(connectorsAtom);
 	const connectorCount = connectors?.length ?? 0;
 
@@ -76,6 +87,211 @@ export function DocumentsSidebar({
 	const [sidebarDocs, setSidebarDocs] = useAtom(sidebarSelectedDocumentsAtom);
 	const mentionedDocIds = useMemo(() => new Set(sidebarDocs.map((d) => d.id)), [sidebarDocs]);
 
+	// Folder state
+	const [expandedFolderMap, setExpandedFolderMap] = useAtom(expandedFolderIdsAtom);
+	const expandedIds = useMemo(
+		() => new Set(expandedFolderMap[searchSpaceId] ?? []),
+		[expandedFolderMap, searchSpaceId]
+	);
+	const toggleFolderExpand = useCallback(
+		(folderId: number) => {
+			setExpandedFolderMap((prev) => {
+				const current = new Set(prev[searchSpaceId] ?? []);
+				if (current.has(folderId)) current.delete(folderId);
+				else current.add(folderId);
+				return { ...prev, [searchSpaceId]: [...current] };
+			});
+		},
+		[searchSpaceId, setExpandedFolderMap]
+	);
+
+	// Zero queries for tree data
+	const [zeroFolders] = useQuery(queries.folders.bySpace({ searchSpaceId }));
+	const [zeroAllDocs] = useQuery(queries.documents.bySpace({ searchSpaceId }));
+
+	const treeFolders: FolderDisplay[] = useMemo(
+		() =>
+			(zeroFolders ?? []).map((f) => ({
+				id: f.id,
+				name: f.name,
+				position: f.position,
+				parentId: f.parentId ?? null,
+				searchSpaceId: f.searchSpaceId,
+			})),
+		[zeroFolders]
+	);
+
+	const treeDocuments: DocumentNodeDoc[] = useMemo(
+		() =>
+			(zeroAllDocs ?? [])
+				.filter((d) => d.title && d.title.trim() !== "")
+				.map((d) => ({
+					id: d.id,
+					title: d.title,
+					document_type: d.documentType,
+					folderId: (d as { folderId?: number | null }).folderId ?? null,
+					status: d.status as { state: string; reason?: string | null } | undefined,
+				})),
+		[zeroAllDocs]
+	);
+
+	const foldersByParent = useMemo(() => {
+		const map: Record<string, FolderDisplay[]> = {};
+		for (const f of treeFolders) {
+			const key = String(f.parentId ?? "root");
+			if (!map[key]) map[key] = [];
+			map[key].push(f);
+		}
+		return map;
+	}, [treeFolders]);
+
+	// Folder actions
+	const [folderPickerOpen, setFolderPickerOpen] = useState(false);
+	const [folderPickerTarget, setFolderPickerTarget] = useState<{
+		type: "folder" | "document";
+		id: number;
+		disabledIds?: Set<number>;
+	} | null>(null);
+
+	// Create-folder dialog state
+	const [createFolderOpen, setCreateFolderOpen] = useState(false);
+	const [createFolderParentId, setCreateFolderParentId] = useState<number | null>(null);
+
+	const createFolderParentName = useMemo(() => {
+		if (createFolderParentId === null) return null;
+		return treeFolders.find((f) => f.id === createFolderParentId)?.name ?? null;
+	}, [createFolderParentId, treeFolders]);
+
+	const handleCreateFolder = useCallback((parentId: number | null) => {
+		setCreateFolderParentId(parentId);
+		setCreateFolderOpen(true);
+	}, []);
+
+	const handleCreateFolderConfirm = useCallback(
+		async (name: string) => {
+			try {
+				await foldersApiService.createFolder({
+					name,
+					parent_id: createFolderParentId,
+					search_space_id: searchSpaceId,
+				});
+				toast.success("Folder created");
+				if (createFolderParentId !== null) {
+					setExpandedFolderMap((prev) => {
+						const current = new Set(prev[searchSpaceId] ?? []);
+						current.add(createFolderParentId);
+						return { ...prev, [searchSpaceId]: [...current] };
+					});
+				}
+			} catch (e: unknown) {
+				toast.error((e as Error)?.message || "Failed to create folder");
+			}
+		},
+		[createFolderParentId, searchSpaceId, setExpandedFolderMap]
+	);
+
+	const handleRenameFolder = useCallback(async (folder: FolderDisplay, newName: string) => {
+		try {
+			await foldersApiService.updateFolder(folder.id, { name: newName });
+			toast.success("Folder renamed");
+		} catch (e: unknown) {
+			toast.error((e as Error)?.message || "Failed to rename folder");
+		}
+	}, []);
+
+	const handleDeleteFolder = useCallback(async (folder: FolderDisplay) => {
+		if (!confirm(`Delete folder "${folder.name}" and all its contents?`)) return;
+		try {
+			await foldersApiService.deleteFolder(folder.id);
+			toast.success("Folder deleted");
+		} catch (e: unknown) {
+			toast.error((e as Error)?.message || "Failed to delete folder");
+		}
+	}, []);
+
+	const handleMoveFolder = useCallback(
+		(folder: FolderDisplay) => {
+			const subtreeIds = new Set<number>();
+			function collectSubtree(id: number) {
+				subtreeIds.add(id);
+				for (const child of foldersByParent[String(id)] ?? []) {
+					collectSubtree(child.id);
+				}
+			}
+			collectSubtree(folder.id);
+			setFolderPickerTarget({
+				type: "folder",
+				id: folder.id,
+				disabledIds: subtreeIds,
+			});
+			setFolderPickerOpen(true);
+		},
+		[foldersByParent]
+	);
+
+	const handleMoveDocument = useCallback((doc: DocumentNodeDoc) => {
+		setFolderPickerTarget({ type: "document", id: doc.id });
+		setFolderPickerOpen(true);
+	}, []);
+
+	const handleFolderPickerSelect = useCallback(
+		async (targetFolderId: number | null) => {
+			if (!folderPickerTarget) return;
+			try {
+				if (folderPickerTarget.type === "folder") {
+					await foldersApiService.moveFolder(folderPickerTarget.id, {
+						new_parent_id: targetFolderId,
+					});
+					toast.success("Folder moved");
+				} else {
+					await foldersApiService.moveDocument(folderPickerTarget.id, {
+						folder_id: targetFolderId,
+					});
+					toast.success("Document moved");
+				}
+			} catch (e: unknown) {
+				toast.error((e as Error)?.message || "Failed to move item");
+			}
+			setFolderPickerTarget(null);
+		},
+		[folderPickerTarget]
+	);
+
+	const handleDropIntoFolder = useCallback(
+		async (itemType: "folder" | "document", itemId: number, targetFolderId: number | null) => {
+			try {
+				if (itemType === "folder") {
+					await foldersApiService.moveFolder(itemId, {
+						new_parent_id: targetFolderId,
+					});
+					toast.success("Folder moved");
+				} else {
+					await foldersApiService.moveDocument(itemId, {
+						folder_id: targetFolderId,
+					});
+					toast.success("Document moved");
+				}
+			} catch (e: unknown) {
+				toast.error((e as Error)?.message || "Failed to move item");
+			}
+		},
+		[]
+	);
+
+	const handleReorderFolder = useCallback(
+		async (folderId: number, beforePos: string | null, afterPos: string | null) => {
+			try {
+				await foldersApiService.reorderFolder(folderId, {
+					before_position: beforePos,
+					after_position: afterPos,
+				});
+			} catch (e: unknown) {
+				toast.error((e as Error)?.message || "Failed to reorder folder");
+			}
+		},
+		[]
+	);
+
 	const handleToggleChatMention = useCallback(
 		(doc: { id: number; title: string; document_type: string }, isMentioned: boolean) => {
 			if (isMentioned) {
@@ -123,14 +339,14 @@ export function DocumentsSidebar({
 	const loadingMore = isSearchMode ? searchLoadingMore : realtimeLoadingMore;
 	const onLoadMore = isSearchMode ? searchLoadMore : realtimeLoadMore;
 
-	const onToggleType = (type: DocumentTypeEnum, checked: boolean) => {
+	const onToggleType = useCallback((type: DocumentTypeEnum, checked: boolean) => {
 		setActiveTypes((prev) => {
 			if (checked) {
 				return prev.includes(type) ? prev : [...prev, type];
 			}
 			return prev.filter((t) => t !== type);
 		});
-	};
+	}, []);
 
 	const handleDeleteDocument = useCallback(
 		async (id: number): Promise<boolean> => {
@@ -340,27 +556,79 @@ export function DocumentsSidebar({
 						searchValue={search}
 						onToggleType={onToggleType}
 						activeTypes={activeTypes}
+						onCreateFolder={() => handleCreateFolder(null)}
 					/>
 				</div>
 
-				<DocumentsTableShell
-					documents={displayDocs}
-					loading={!!loading}
-					error={!!error}
-					sortKey={sortKey}
-					sortDesc={sortDesc}
-					onSortChange={handleSortChange}
-					deleteDocument={handleDeleteDocument}
-					bulkDeleteDocuments={handleBulkDeleteDocuments}
-					searchSpaceId={String(searchSpaceId)}
-					hasMore={hasMore}
-					loadingMore={loadingMore}
-					onLoadMore={onLoadMore}
-					mentionedDocIds={mentionedDocIds}
-					onToggleChatMention={handleToggleChatMention}
-					isSearchMode={isSearchMode || activeTypes.length > 0}
-				/>
+				{isSearchMode ? (
+					<DocumentsTableShell
+						documents={displayDocs}
+						loading={!!loading}
+						error={!!error}
+						sortKey={sortKey}
+						sortDesc={sortDesc}
+						onSortChange={handleSortChange}
+						deleteDocument={handleDeleteDocument}
+						bulkDeleteDocuments={handleBulkDeleteDocuments}
+						searchSpaceId={String(searchSpaceId)}
+						hasMore={hasMore}
+						loadingMore={loadingMore}
+						onLoadMore={onLoadMore}
+						mentionedDocIds={mentionedDocIds}
+						onToggleChatMention={handleToggleChatMention}
+						isSearchMode={isSearchMode || activeTypes.length > 0}
+					/>
+				) : (
+					<FolderTreeView
+						folders={treeFolders}
+						documents={treeDocuments}
+						expandedIds={expandedIds}
+						onToggleExpand={toggleFolderExpand}
+						mentionedDocIds={mentionedDocIds}
+						onToggleChatMention={handleToggleChatMention}
+						onRenameFolder={handleRenameFolder}
+						onDeleteFolder={handleDeleteFolder}
+						onMoveFolder={handleMoveFolder}
+						onCreateFolder={handleCreateFolder}
+						onPreviewDocument={(doc) => {
+							openDocumentTab({
+								documentId: doc.id,
+								searchSpaceId,
+								title: doc.title,
+							});
+						}}
+						onEditDocument={(doc) => {
+							openDocumentTab({
+								documentId: doc.id,
+								searchSpaceId,
+								title: doc.title,
+							});
+						}}
+						onDeleteDocument={(doc) => handleDeleteDocument(doc.id)}
+						onMoveDocument={handleMoveDocument}
+						activeTypes={activeTypes}
+						onDropIntoFolder={handleDropIntoFolder}
+						onReorderFolder={handleReorderFolder}
+					/>
+				)}
 			</div>
+
+			<FolderPickerDialog
+				open={folderPickerOpen}
+				onOpenChange={setFolderPickerOpen}
+				folders={treeFolders}
+				title={folderPickerTarget?.type === "folder" ? "Move folder to..." : "Move document to..."}
+				description="Select a destination folder, or choose Root to move to the top level."
+				disabledFolderIds={folderPickerTarget?.disabledIds}
+				onSelect={handleFolderPickerSelect}
+			/>
+
+			<CreateFolderDialog
+				open={createFolderOpen}
+				onOpenChange={setCreateFolderOpen}
+				parentFolderName={createFolderParentName}
+				onConfirm={handleCreateFolderConfirm}
+			/>
 		</>
 	);
 

surfsense_web/components/layout/ui/sidebar/SidebarHeader.tsx

@@ -1,7 +1,6 @@
 "use client";
 
 import { ChevronsUpDown, Settings, UserPen } from "lucide-react";
-import { useParams, useRouter } from "next/navigation";
 import { useTranslations } from "next-intl";
 import { Button } from "@/components/ui/button";
 import {
@@ -29,9 +28,6 @@ export function SidebarHeader({
 	className,
 }: SidebarHeaderProps) {
 	const t = useTranslations("sidebar");
-	const router = useRouter();
-	const params = useParams();
-	const searchSpaceId = params.search_space_id as string;
 
 	return (
 		<div className={cn("flex min-w-0 flex-1 items-center", className)}>

surfsense_web/components/layout/ui/tabs/DocumentTabContent.tsx

@@ -0,0 +1,240 @@
+"use client";
+
+import { AlertCircle, Pencil } from "lucide-react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { toast } from "sonner";
+import { PlateEditor } from "@/components/editor/plate-editor";
+import { MarkdownViewer } from "@/components/markdown-viewer";
+import { Button } from "@/components/ui/button";
+import { authenticatedFetch, getBearerToken, redirectToLogin } from "@/lib/auth-utils";
+
+interface DocumentContent {
+	document_id: number;
+	title: string;
+	document_type?: string;
+	source_markdown: string;
+}
+
+function DocumentSkeleton() {
+	return (
+		<div className="space-y-6 p-8 max-w-4xl mx-auto">
+			<div className="h-8 w-3/4 rounded-md bg-muted/60 animate-pulse" />
+			<div className="space-y-3">
+				<div className="h-4 w-full rounded-md bg-muted/60 animate-pulse" />
+				<div className="h-4 w-[95%] rounded-md bg-muted/60 animate-pulse [animation-delay:100ms]" />
+				<div className="h-4 w-[88%] rounded-md bg-muted/60 animate-pulse [animation-delay:200ms]" />
+				<div className="h-4 w-[60%] rounded-md bg-muted/60 animate-pulse [animation-delay:300ms]" />
+			</div>
+			<div className="h-6 w-2/5 rounded-md bg-muted/60 animate-pulse [animation-delay:400ms]" />
+			<div className="space-y-3">
+				<div className="h-4 w-full rounded-md bg-muted/60 animate-pulse [animation-delay:500ms]" />
+				<div className="h-4 w-[92%] rounded-md bg-muted/60 animate-pulse [animation-delay:600ms]" />
+				<div className="h-4 w-[75%] rounded-md bg-muted/60 animate-pulse [animation-delay:700ms]" />
+			</div>
+		</div>
+	);
+}
+
+interface DocumentTabContentProps {
+	documentId: number;
+	searchSpaceId: number;
+	title?: string;
+}
+
+export function DocumentTabContent({ documentId, searchSpaceId, title }: DocumentTabContentProps) {
+	const [doc, setDoc] = useState<DocumentContent | null>(null);
+	const [isLoading, setIsLoading] = useState(true);
+	const [error, setError] = useState<string | null>(null);
+	const [isEditing, setIsEditing] = useState(false);
+	const [saving, setSaving] = useState(false);
+	const [editedMarkdown, setEditedMarkdown] = useState<string | null>(null);
+	const markdownRef = useRef<string>("");
+	const initialLoadDone = useRef(false);
+	const changeCountRef = useRef(0);
+
+	useEffect(() => {
+		let cancelled = false;
+		setIsLoading(true);
+		setError(null);
+		setDoc(null);
+		setIsEditing(false);
+		setEditedMarkdown(null);
+		initialLoadDone.current = false;
+		changeCountRef.current = 0;
+
+		const fetchContent = async () => {
+			const token = getBearerToken();
+			if (!token) {
+				redirectToLogin();
+				return;
+			}
+
+			try {
+				const response = await authenticatedFetch(
+					`${process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL}/api/v1/search-spaces/${searchSpaceId}/documents/${documentId}/editor-content`,
+					{ method: "GET" }
+				);
+
+				if (cancelled) return;
+
+				if (!response.ok) {
+					const errorData = await response
+						.json()
+						.catch(() => ({ detail: "Failed to fetch document" }));
+					throw new Error(errorData.detail || "Failed to fetch document");
+				}
+
+				const data = await response.json();
+
+				if (data.source_markdown === undefined || data.source_markdown === null) {
+					setError("This document does not have viewable content.");
+					setIsLoading(false);
+					return;
+				}
+
+				markdownRef.current = data.source_markdown;
+				setDoc(data);
+				initialLoadDone.current = true;
+			} catch (err) {
+				if (cancelled) return;
+				console.error("Error fetching document:", err);
+				setError(err instanceof Error ? err.message : "Failed to fetch document");
+			} finally {
+				if (!cancelled) setIsLoading(false);
+			}
+		};
+
+		fetchContent();
+		return () => {
+			cancelled = true;
+		};
+	}, [documentId, searchSpaceId]);
+
+	const handleMarkdownChange = useCallback((md: string) => {
+		markdownRef.current = md;
+		if (!initialLoadDone.current) return;
+		changeCountRef.current += 1;
+		if (changeCountRef.current <= 1) return;
+		setEditedMarkdown(md);
+	}, []);
+
+	const handleSave = useCallback(async () => {
+		const token = getBearerToken();
+		if (!token) {
+			toast.error("Please login to save");
+			redirectToLogin();
+			return;
+		}
+
+		setSaving(true);
+		try {
+			const response = await authenticatedFetch(
+				`${process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL}/api/v1/search-spaces/${searchSpaceId}/documents/${documentId}/save`,
+				{
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify({ source_markdown: markdownRef.current }),
+				}
+			);
+
+			if (!response.ok) {
+				const errorData = await response
+					.json()
+					.catch(() => ({ detail: "Failed to save document" }));
+				throw new Error(errorData.detail || "Failed to save document");
+			}
+
+			setDoc((prev) => (prev ? { ...prev, source_markdown: markdownRef.current } : prev));
+			setEditedMarkdown(null);
+			toast.success("Document saved! Reindexing in background...");
+		} catch (err) {
+			console.error("Error saving document:", err);
+			toast.error(err instanceof Error ? err.message : "Failed to save document");
+		} finally {
+			setSaving(false);
+		}
+	}, [documentId, searchSpaceId]);
+
+	if (isLoading) return <DocumentSkeleton />;
+
+	if (error || !doc) {
+		return (
+			<div className="flex flex-1 flex-col items-center justify-center gap-3 p-6 text-center">
+				<AlertCircle className="size-10 text-destructive" />
+				<div>
+					<p className="font-medium text-foreground text-lg">Failed to load document</p>
+					<p className="text-sm text-muted-foreground mt-1">
+						{error || "An unknown error occurred"}
+					</p>
+				</div>
+			</div>
+		);
+	}
+
+	if (isEditing) {
+		return (
+			<div className="flex flex-col h-full overflow-hidden">
+				<div className="flex items-center justify-between px-6 py-3 border-b shrink-0">
+					<div className="flex-1 min-w-0">
+						<h1 className="text-base font-semibold truncate">{doc.title || title || "Untitled"}</h1>
+						{editedMarkdown !== null && (
+							<p className="text-xs text-muted-foreground">Unsaved changes</p>
+						)}
+					</div>
+					<Button
+						variant="outline"
+						size="sm"
+						onClick={() => {
+							setIsEditing(false);
+							setEditedMarkdown(null);
+							changeCountRef.current = 0;
+						}}
+					>
+						Done editing
+					</Button>
+				</div>
+				<div className="flex-1 overflow-hidden">
+					<PlateEditor
+						key={`edit-${documentId}`}
+						preset="full"
+						markdown={doc.source_markdown}
+						onMarkdownChange={handleMarkdownChange}
+						readOnly={false}
+						placeholder="Start writing..."
+						editorVariant="default"
+						onSave={handleSave}
+						hasUnsavedChanges={editedMarkdown !== null}
+						isSaving={saving}
+						defaultEditing={true}
+					/>
+				</div>
+			</div>
+		);
+	}
+
+	return (
+		<div className="flex flex-col h-full overflow-hidden">
+			<div className="flex items-center justify-between px-6 py-3 border-b shrink-0">
+				<h1 className="text-base font-semibold truncate flex-1 min-w-0">
+					{doc.title || title || "Untitled"}
+				</h1>
+				{doc.document_type === "NOTE" && (
+					<Button
+						variant="outline"
+						size="sm"
+						onClick={() => setIsEditing(true)}
+						className="gap-1.5"
+					>
+						<Pencil className="size-3.5" />
+						Edit
+					</Button>
+				)}
+			</div>
+			<div className="flex-1 overflow-auto">
+				<div className="max-w-4xl mx-auto px-6 py-6">
+					<MarkdownViewer content={doc.source_markdown} />
+				</div>
+			</div>
+		</div>
+	);
+}

surfsense_web/components/layout/ui/tabs/TabBar.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+import { useAtomValue, useSetAtom } from "jotai";
+import { FileText, MessageSquare, Plus, X } from "lucide-react";
+import { useCallback, useEffect, useRef } from "react";
+import {
+	activeTabIdAtom,
+	closeTabAtom,
+	switchTabAtom,
+	type Tab,
+	tabsAtom,
+} from "@/atoms/tabs/tabs.atom";
+import { cn } from "@/lib/utils";
+
+interface TabBarProps {
+	onTabSwitch?: (tab: Tab) => void;
+	onNewChat?: () => void;
+	className?: string;
+}
+
+export function TabBar({ onTabSwitch, onNewChat, className }: TabBarProps) {
+	const tabs = useAtomValue(tabsAtom);
+	const activeTabId = useAtomValue(activeTabIdAtom);
+	const switchTab = useSetAtom(switchTabAtom);
+	const closeTab = useSetAtom(closeTabAtom);
+	const scrollRef = useRef<HTMLDivElement>(null);
+
+	const handleTabClick = useCallback(
+		(tab: Tab) => {
+			if (tab.id === activeTabId) return;
+			switchTab(tab.id);
+			onTabSwitch?.(tab);
+		},
+		[activeTabId, switchTab, onTabSwitch]
+	);
+
+	const handleTabClose = useCallback(
+		(e: React.MouseEvent, tabId: string) => {
+			e.stopPropagation();
+			const fallback = closeTab(tabId);
+			if (fallback) {
+				onTabSwitch?.(fallback);
+			}
+		},
+		[closeTab, onTabSwitch]
+	);
+
+	// Scroll active tab into view
+	useEffect(() => {
+		if (!scrollRef.current || !activeTabId) return;
+		const activeEl = scrollRef.current.querySelector(`[data-tab-id="${activeTabId}"]`);
+		if (activeEl) {
+			activeEl.scrollIntoView({ behavior: "smooth", block: "nearest", inline: "nearest" });
+		}
+	}, [activeTabId]);
+
+	// Only show tab bar when there's more than one tab
+	if (tabs.length <= 1) return null;
+
+	return (
+		<div className={cn("flex items-center shrink-0 border-b bg-main-panel", className)}>
+			<div ref={scrollRef} className="flex items-center flex-1 overflow-x-auto scrollbar-none">
+				{tabs.map((tab) => {
+					const isActive = tab.id === activeTabId;
+					const Icon = tab.type === "document" ? FileText : MessageSquare;
+
+					return (
+						<button
+							key={tab.id}
+							type="button"
+							data-tab-id={tab.id}
+							onClick={() => handleTabClick(tab)}
+							className={cn(
+								"group relative flex items-center gap-1.5 px-3 h-9 min-w-0 max-w-[200px] text-xs font-medium border-r transition-colors shrink-0",
+								isActive
+									? "bg-main-panel text-foreground"
+									: "bg-muted/30 text-muted-foreground hover:bg-muted/60 hover:text-foreground"
+							)}
+						>
+							{isActive && <span className="absolute bottom-0 left-0 right-0 h-[2px] bg-primary" />}
+							<Icon className="size-3.5 shrink-0" />
+							<span className="truncate">{tab.title}</span>
+							{/* biome-ignore lint/a11y/useSemanticElements: cannot nest button inside button */}
+							<span
+								role="button"
+								tabIndex={0}
+								onClick={(e) => handleTabClose(e, tab.id)}
+								onKeyDown={(e) => {
+									if (e.key === "Enter" || e.key === " ") {
+										e.preventDefault();
+										handleTabClose(e as unknown as React.MouseEvent, tab.id);
+									}
+								}}
+								className={cn(
+									"ml-auto shrink-0 rounded-sm p-0.5 transition-colors",
+									isActive
+										? "opacity-60 hover:opacity-100 hover:bg-muted"
+										: "opacity-0 group-hover:opacity-60 hover:opacity-100! hover:bg-muted"
+								)}
+							>
+								<X className="size-3" />
+							</span>
+						</button>
+					);
+				})}
+			</div>
+
+			{onNewChat && (
+				<button
+					type="button"
+					onClick={onNewChat}
+					className="flex items-center justify-center size-9 shrink-0 text-muted-foreground hover:text-foreground hover:bg-muted/60 transition-colors"
+					title="New Chat"
+				>
+					<Plus className="size-3.5" />
+				</button>
+			)}
+		</div>
+	);
+}

surfsense_web/components/onboarding-tour.tsx

@@ -436,6 +436,7 @@ export function OnboardingTour() {
 	const { resolvedTheme } = useTheme();
 	const pathname = usePathname();
 	const retryCountRef = useRef(0);
+	const retryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 	const maxRetries = 10;
 	// Track previous user ID to detect user changes
 	const previousUserIdRef = useRef<string | null>(null);
@@ -477,7 +478,7 @@ export function OnboardingTour() {
 			retryCountRef.current = 0;
 		} else if (retryCountRef.current < maxRetries) {
 			retryCountRef.current++;
-			setTimeout(() => {
+			retryTimerRef.current = setTimeout(() => {
 				const retryEl = document.querySelector(currentStep.target);
 				if (retryEl) {
 					setTargetEl(retryEl);
@@ -487,6 +488,10 @@ export function OnboardingTour() {
 				}
 			}, 200);
 		}
+
+		return () => {
+			if (retryTimerRef.current) clearTimeout(retryTimerRef.current);
+		};
 	}, [currentStep]);
 
 	// Check if tour should run: localStorage + data validation with user ID tracking
@@ -556,7 +561,11 @@ export function OnboardingTour() {
 		}
 
 		// User is new and hasn't seen tour - wait for DOM elements and start tour
+		let cancelled = false;
+
 		const checkAndStartTour = () => {
+			if (cancelled) return;
+
 			// Check if all required elements exist
 			const connectorEl = document.querySelector(TOUR_STEPS[0].target);
 			const documentsEl = document.querySelector(TOUR_STEPS[1].target);
@@ -578,7 +587,10 @@ export function OnboardingTour() {
 
 		// Start checking after initial delay
 		const timer = setTimeout(checkAndStartTour, 500);
-		return () => clearTimeout(timer);
+		return () => {
+			cancelled = true;
+			clearTimeout(timer);
+		};
 	}, [mounted, user?.id, searchSpaceId, pathname, threadsData, documentTypeCounts, connectors]);
 
 	// Update position on resize/scroll

surfsense_web/components/pricing.tsx

@@ -103,7 +103,7 @@ export function Pricing({
 			>
 				{plans.map((plan, index) => (
 					<motion.div
-						key={index}
+						key={plan.name}
 						initial={{ y: 50, opacity: 1 }}
 						whileInView={
 							isDesktop
@@ -193,8 +193,8 @@ export function Pricing({
 							</p>
 
 							<ul className="mt-5 gap-2 flex flex-col">
-								{plan.features.map((feature, idx) => (
-									<li key={idx} className="flex items-start gap-2">
+								{plan.features.map((feature) => (
+									<li key={feature} className="flex items-start gap-2">
 										<Check className="h-4 w-4 text-primary mt-1 flex-shrink-0" />
 										<span className="text-left">{feature}</span>
 									</li>

surfsense_web/components/public-chat-snapshots/public-chat-snapshots-empty-state.tsx

@@ -1,5 +1,3 @@
-"use client";
-
 import { Link2Off } from "lucide-react";
 
 interface PublicChatSnapshotsEmptyStateProps {

surfsense_web/components/public-chat/public-thread.tsx

@@ -8,6 +8,7 @@ import {
 	useAuiState,
 } from "@assistant-ui/react";
 import { CheckIcon, CopyIcon } from "lucide-react";
+import Image from "next/image";
 import { type FC, type ReactNode, useState } from "react";
 import { MarkdownText } from "@/components/assistant-ui/markdown-text";
 import { ToolFallback } from "@/components/assistant-ui/tool-fallback";
@@ -79,10 +80,11 @@ const UserAvatar: FC<AuthorMetadata & { hasError: boolean; onError: () => void }
 
 	if (avatarUrl && !hasError) {
 		return (
-			// biome-ignore lint/performance/noImgElement: external OAuth/profile avatar URL
-			<img
+			<Image
 				src={avatarUrl}
 				alt={displayName || "User"}
+				width={32}
+				height={32}
 				className="size-8 rounded-full object-cover"
 				referrerPolicy="no-referrer"
 				onError={onError}

surfsense_web/components/settings/general-settings-manager.tsx

@@ -15,6 +15,7 @@ import { Label } from "@/components/ui/label";
 import { Skeleton } from "@/components/ui/skeleton";
 import { searchSpacesApiService } from "@/lib/apis/search-spaces-api.service";
 import { cacheKeys } from "@/lib/query-client/cache-keys";
+import { Spinner } from "../ui/spinner";
 
 interface GeneralSettingsManagerProps {
 	searchSpaceId: number;
@@ -81,6 +82,11 @@ export function GeneralSettingsManager({ searchSpaceId }: GeneralSettingsManager
 		}
 	};
 
+	const onSubmit = (e: React.FormEvent) => {
+		e.preventDefault();
+		handleSave();
+	};
+
 	if (loading) {
 		return (
 			<div className="space-y-4 md:space-y-6">
@@ -109,60 +115,66 @@ export function GeneralSettingsManager({ searchSpaceId }: GeneralSettingsManager
 			</Alert>
 
 			{/* Search Space Details Card */}
-			<Card>
-				<CardHeader className="px-3 md:px-6 pt-3 md:pt-6 pb-2 md:pb-3">
-					<CardTitle className="text-base md:text-lg">Search Space Details</CardTitle>
-					<CardDescription className="text-xs md:text-sm">
-						Manage the basic information for this search space.
-					</CardDescription>
-				</CardHeader>
-				<CardContent className="space-y-4 md:space-y-5 px-3 md:px-6 pb-3 md:pb-6">
-					<div className="space-y-1.5 md:space-y-2">
-						<Label htmlFor="search-space-name" className="text-sm md:text-base font-medium">
-							{t("general_name_label")}
-						</Label>
-						<Input
-							id="search-space-name"
-							placeholder={t("general_name_placeholder")}
-							value={name}
-							onChange={(e) => setName(e.target.value)}
-							className="text-sm md:text-base h-9 md:h-10"
-						/>
-						<p className="text-[10px] md:text-xs text-muted-foreground">
-							{t("general_name_description")}
-						</p>
-					</div>
+			<form onSubmit={onSubmit} className="space-y-4 md:space-y-6">
+				<Card>
+					<CardHeader className="px-3 md:px-6 pt-3 md:pt-6 pb-2 md:pb-3">
+						<CardTitle className="text-base md:text-lg">Search Space Details</CardTitle>
+						<CardDescription className="text-xs md:text-sm">
+							Manage the basic information for this search space.
+						</CardDescription>
+					</CardHeader>
+					<CardContent className="space-y-4 md:space-y-5 px-3 md:px-6 pb-3 md:pb-6">
+						<div className="space-y-1.5 md:space-y-2">
+							<Label htmlFor="search-space-name" className="text-sm md:text-base font-medium">
+								{t("general_name_label")}
+							</Label>
+							<Input
+								id="search-space-name"
+								placeholder={t("general_name_placeholder")}
+								value={name}
+								onChange={(e) => setName(e.target.value)}
+								className="text-sm md:text-base h-9 md:h-10"
+							/>
+							<p className="text-[10px] md:text-xs text-muted-foreground">
+								{t("general_name_description")}
+							</p>
+						</div>
 
-					<div className="space-y-1.5 md:space-y-2">
-						<Label htmlFor="search-space-description" className="text-sm md:text-base font-medium">
-							{t("general_description_label")}{" "}
-							<span className="text-muted-foreground font-normal">({tCommon("optional")})</span>
-						</Label>
-						<Input
-							id="search-space-description"
-							placeholder={t("general_description_placeholder")}
-							value={description}
-							onChange={(e) => setDescription(e.target.value)}
-							className="text-sm md:text-base h-9 md:h-10"
-						/>
-						<p className="text-[10px] md:text-xs text-muted-foreground">
-							{t("general_description_description")}
-						</p>
-					</div>
-				</CardContent>
-			</Card>
+						<div className="space-y-1.5 md:space-y-2">
+							<Label
+								htmlFor="search-space-description"
+								className="text-sm md:text-base font-medium"
+							>
+								{t("general_description_label")}{" "}
+								<span className="text-muted-foreground font-normal">({tCommon("optional")})</span>
+							</Label>
+							<Input
+								id="search-space-description"
+								placeholder={t("general_description_placeholder")}
+								value={description}
+								onChange={(e) => setDescription(e.target.value)}
+								className="text-sm md:text-base h-9 md:h-10"
+							/>
+							<p className="text-[10px] md:text-xs text-muted-foreground">
+								{t("general_description_description")}
+							</p>
+						</div>
+					</CardContent>
+				</Card>
 
-			{/* Action Buttons */}
-			<div className="flex justify-end pt-3 md:pt-4">
-				<Button
-					variant="outline"
-					onClick={handleSave}
-					disabled={!hasChanges || saving || !name.trim()}
-					className="gap-2 bg-white text-black hover:bg-neutral-100 dark:bg-white dark:text-black dark:hover:bg-neutral-200"
-				>
-					{saving ? t("general_saving") : t("general_save")}
-				</Button>
-			</div>
+				{/* Action Buttons */}
+				<div className="flex justify-end pt-3 md:pt-4">
+					<Button
+						type="submit"
+						variant="outline"
+						disabled={!hasChanges || saving || !name.trim()}
+						className="gap-2 bg-white text-black hover:bg-neutral-100 dark:bg-white dark:text-black dark:hover:bg-neutral-200"
+					>
+						{saving ? <Spinner size="sm" /> : null}
+						{saving ? t("general_saving") : t("general_save")}
+					</Button>
+				</div>
+			</form>
 		</div>
 	);
 }

surfsense_web/components/settings/prompt-config-manager.tsx

@@ -13,6 +13,7 @@ import { Textarea } from "@/components/ui/textarea";
 import { searchSpacesApiService } from "@/lib/apis/search-spaces-api.service";
 import { authenticatedFetch } from "@/lib/auth-utils";
 import { cacheKeys } from "@/lib/query-client/cache-keys";
+import { Spinner } from "../ui/spinner";
 
 interface PromptConfigManagerProps {
 	searchSpaceId: number;
@@ -83,6 +84,11 @@ export function PromptConfigManager({ searchSpaceId }: PromptConfigManagerProps)
 		}
 	};
 
+	const onSubmit = (e: React.FormEvent) => {
+		e.preventDefault();
+		handleSave();
+	};
+
 	if (loading) {
 		return (
 			<div className="space-y-4 md:space-y-6">
@@ -124,69 +130,73 @@ export function PromptConfigManager({ searchSpaceId }: PromptConfigManagerProps)
 			</Alert>
 
 			{/* System Instructions Card */}
-			<Card>
-				<CardHeader className="px-3 md:px-6 pt-3 md:pt-6 pb-2 md:pb-3">
-					<CardTitle className="text-base md:text-lg">Custom System Instructions</CardTitle>
-					<CardDescription className="text-xs md:text-sm">
-						Provide specific guidelines for how you want the AI to respond. These instructions will
-						be applied to all answers in this search space.
-					</CardDescription>
-				</CardHeader>
-				<CardContent className="space-y-3 md:space-y-4 px-3 md:px-6 pb-3 md:pb-6">
-					<div className="space-y-1.5 md:space-y-2">
-						<Label
-							htmlFor="custom-instructions-settings"
-							className="text-sm md:text-base font-medium"
-						>
-							Your Instructions
-						</Label>
-						<Textarea
-							id="custom-instructions-settings"
-							placeholder="E.g., Always provide practical examples, be concise, focus on technical details, use simple language, respond in a specific format..."
-							value={customInstructions}
-							onChange={(e) => setCustomInstructions(e.target.value)}
-							rows={10}
-							className="resize-none font-mono text-xs md:text-sm"
-						/>
-						<div className="flex items-center justify-between">
-							<p className="text-[10px] md:text-xs text-muted-foreground">
-								{customInstructions.length} characters
-							</p>
-							{customInstructions.length > 0 && (
-								<Button
-									variant="ghost"
-									size="sm"
-									onClick={() => setCustomInstructions("")}
-									className="h-auto py-0.5 md:py-1 px-1.5 md:px-2 text-[10px] md:text-xs"
-								>
-									Clear
-								</Button>
-							)}
+			<form onSubmit={onSubmit} className="space-y-4 md:space-y-6">
+				<Card>
+					<CardHeader className="px-3 md:px-6 pt-3 md:pt-6 pb-2 md:pb-3">
+						<CardTitle className="text-base md:text-lg">Custom System Instructions</CardTitle>
+						<CardDescription className="text-xs md:text-sm">
+							Provide specific guidelines for how you want the AI to respond. These instructions
+							will be applied to all answers in this search space.
+						</CardDescription>
+					</CardHeader>
+					<CardContent className="space-y-3 md:space-y-4 px-3 md:px-6 pb-3 md:pb-6">
+						<div className="space-y-1.5 md:space-y-2">
+							<Label
+								htmlFor="custom-instructions-settings"
+								className="text-sm md:text-base font-medium"
+							>
+								Your Instructions
+							</Label>
+							<Textarea
+								id="custom-instructions-settings"
+								placeholder="E.g., Always provide practical examples, be concise, focus on technical details, use simple language, respond in a specific format..."
+								value={customInstructions}
+								onChange={(e) => setCustomInstructions(e.target.value)}
+								rows={10}
+								className="resize-none font-mono text-xs md:text-sm"
+							/>
+							<div className="flex items-center justify-between">
+								<p className="text-[10px] md:text-xs text-muted-foreground">
+									{customInstructions.length} characters
+								</p>
+								{customInstructions.length > 0 && (
+									<Button
+										type="button"
+										variant="ghost"
+										size="sm"
+										onClick={() => setCustomInstructions("")}
+										className="h-auto py-0.5 md:py-1 px-1.5 md:px-2 text-[10px] md:text-xs"
+									>
+										Clear
+									</Button>
+								)}
+							</div>
 						</div>
-					</div>
 
-					{customInstructions.trim().length === 0 && (
-						<Alert className="py-2 md:py-3">
-							<Info className="h-3 w-3 md:h-4 md:w-4 shrink-0" />
-							<AlertDescription className="text-xs md:text-sm">
-								No system instructions are currently set. The AI will use default behavior.
-							</AlertDescription>
-						</Alert>
-					)}
-				</CardContent>
-			</Card>
+						{customInstructions.trim().length === 0 && (
+							<Alert className="py-2 md:py-3">
+								<Info className="h-3 w-3 md:h-4 md:w-4 shrink-0" />
+								<AlertDescription className="text-xs md:text-sm">
+									No system instructions are currently set. The AI will use default behavior.
+								</AlertDescription>
+							</Alert>
+						)}
+					</CardContent>
+				</Card>
 
-			{/* Action Buttons */}
-			<div className="flex justify-end pt-3 md:pt-4">
-				<Button
-					variant="outline"
-					onClick={handleSave}
-					disabled={!hasChanges || saving}
-					className="gap-2 bg-white text-black hover:bg-neutral-100 dark:bg-white dark:text-black dark:hover:bg-neutral-200"
-				>
-					{saving ? "Saving" : "Save Instructions"}
-				</Button>
-			</div>
+				{/* Action Buttons */}
+				<div className="flex justify-end pt-3 md:pt-4">
+					<Button
+						type="submit"
+						variant="outline"
+						disabled={!hasChanges || saving}
+						className="gap-2 bg-white text-black hover:bg-neutral-100 dark:bg-white dark:text-black dark:hover:bg-neutral-200"
+					>
+						{saving ? <Spinner size="sm" /> : null}
+						{saving ? "Saving" : "Save Instructions"}
+					</Button>
+				</div>
+			</form>
 		</div>
 	);
 }

surfsense_web/components/theme/theme-toggle.tsx

@@ -215,7 +215,7 @@ export const createAnimation = (
       `,
 		};
 	}
-	if (variant === "circle" && start == "center") {
+	if (variant === "circle" && start === "center") {
 		return {
 			name: `${variant}-${start}${blur ? "-blur" : ""}`,
 			css: `

surfsense_web/components/tool-ui/sandbox-execute.tsx

@@ -67,13 +67,14 @@ const SANDBOX_FILE_RE = /^SANDBOX_FILE:\s*(.+)$/gm;
 
 function extractSandboxFiles(text: string): SandboxFile[] {
 	const files: SandboxFile[] = [];
-	let match: RegExpExecArray | null;
-	while ((match = SANDBOX_FILE_RE.exec(text)) !== null) {
+	let match: RegExpExecArray | null = SANDBOX_FILE_RE.exec(text);
+	while (match !== null) {
 		const filePath = match[1].trim();
 		if (filePath) {
 			const name = filePath.includes("/") ? filePath.split("/").pop() || filePath : filePath;
 			files.push({ path: filePath, name });
 		}
+		match = SANDBOX_FILE_RE.exec(text);
 	}
 	SANDBOX_FILE_RE.lastIndex = 0;
 	return files;
@@ -148,7 +149,7 @@ function parseExecuteResult(result: ExecuteResult): ParsedOutput {
 
 function truncateCommand(command: string, maxLen = 80): string {
 	if (command.length <= maxLen) return command;
-	return command.slice(0, maxLen) + "…";
+	return `${command.slice(0, maxLen)}…`;
 }
 
 // ============================================================================

surfsense_web/components/ui/block-draggable.tsx

@@ -18,7 +18,7 @@ import {
 import * as React from "react";
 
 import { Button } from "@/components/ui/button";
-import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";
 import { cn } from "@/lib/utils";
 
 const UNDRAGGABLE_KEYS = [KEYS.column, KEYS.tr, KEYS.td];
@@ -94,23 +94,24 @@ function Draggable(props: PlateElementProps) {
 	};
 
 	// clear up virtual multiple preview when drag end
+	// biome-ignore lint/correctness/useExhaustiveDependencies: resetPreview is stable; intentionally only run on isDragging change
 	React.useEffect(() => {
 		if (!isDragging) {
 			resetPreview();
 		}
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [isDragging]);
 
+	// biome-ignore lint/correctness/useExhaustiveDependencies: previewRef is a stable ref; only run on isAboutToDrag change
 	React.useEffect(() => {
 		if (isAboutToDrag) {
 			previewRef.current?.classList.remove("opacity-0");
 		}
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [isAboutToDrag]);
 
 	const [dragButtonTop, setDragButtonTop] = React.useState(0);
 
 	return (
+		// biome-ignore lint/a11y/noStaticElementInteractions: plate editor block wrapper requires mouse events
 		<div
 			className={cn(
 				"relative",
@@ -158,6 +159,7 @@ function Draggable(props: PlateElementProps) {
 				contentEditable={false}
 			/>
 
+			{/* biome-ignore lint/a11y/noStaticElementInteractions: plate editor context menu handler */}
 			<div
 				ref={nodeRef}
 				className="slate-blockWrapper flow-root"
@@ -215,8 +217,10 @@ const DragHandle = React.memo(function DragHandle({
 	return (
 		<Tooltip>
 			<TooltipTrigger asChild>
+				{/* biome-ignore lint/a11y/useSemanticElements: drag handle requires div for plate editor integration */}
 				<div
 					className="flex size-full items-center justify-center"
+					tabIndex={0}
 					onClick={(e) => {
 						e.preventDefault();
 						editor.getApi(BlockSelectionPlugin).blockSelection.focus();
@@ -291,6 +295,12 @@ const DragHandle = React.memo(function DragHandle({
 					onMouseUp={() => {
 						resetPreview();
 					}}
+					onKeyDown={(e) => {
+						if (e.key === "Enter" || e.key === " ") {
+							e.preventDefault();
+							editor.getApi(BlockSelectionPlugin).blockSelection.focus();
+						}
+					}}
 					data-plate-prevent-deselect
 					role="button"
 				>

surfsense_web/components/ui/code-block-node.tsx

@@ -143,9 +143,11 @@ function CopyButton({
 	const [hasCopied, setHasCopied] = React.useState(false);
 
 	React.useEffect(() => {
-		setTimeout(() => {
+		if (!hasCopied) return;
+		const timer = setTimeout(() => {
 			setHasCopied(false);
 		}, 2000);
+		return () => clearTimeout(timer);
 	}, [hasCopied]);
 
 	return (

surfsense_web/components/ui/equation-node.tsx

@@ -43,10 +43,16 @@ export function EquationElement({ children, ...props }: PlateElementProps<TEquat
 				props.className
 			)}
 		>
+			{/* biome-ignore lint/a11y/useSemanticElements: contentEditable context requires div */}
 			<div
+				role="button"
+				tabIndex={0}
 				className="flex cursor-pointer items-center justify-center"
 				contentEditable={false}
 				onDoubleClick={() => setIsEditing(true)}
+				onKeyDown={(e) => {
+					if (e.key === "Enter") setIsEditing(true);
+				}}
 			>
 				{element.texExpression ? (
 					<div ref={katexRef} className="text-center" />
@@ -123,10 +129,16 @@ export function InlineEquationElement({ children, ...props }: PlateElementProps<
 			as="span"
 			className={cn("inline rounded-sm px-0.5", selected && "bg-brand/15", props.className)}
 		>
+			{/* biome-ignore lint/a11y/useSemanticElements: inline contentEditable context requires span */}
 			<span
+				role="button"
+				tabIndex={0}
 				className="cursor-pointer"
 				contentEditable={false}
 				onDoubleClick={() => setIsEditing(true)}
+				onKeyDown={(e) => {
+					if (e.key === "Enter") setIsEditing(true);
+				}}
 			>
 				{element.texExpression ? (
 					<span ref={katexRef} />

surfsense_web/components/ui/hero-carousel.tsx

@@ -97,7 +97,7 @@ function HeroCarouselCard({
 		observer.observe(video);
 
 		return () => observer.disconnect();
-	}, [src]);
+	}, []);
 
 	const handleCanPlay = useCallback(() => {
 		setHasLoaded(true);
@@ -114,7 +114,19 @@ function HeroCarouselCard({
 						<p className="text-sm text-neutral-500 dark:text-neutral-400">{description}</p>
 					</div>
 				</div>
-				<div className="cursor-pointer bg-neutral-50 p-2 sm:p-3 dark:bg-neutral-950" onClick={open}>
+				{/* biome-ignore lint/a11y/useSemanticElements: div wraps video element, button would break layout */}
+				<div
+					role="button"
+					tabIndex={0}
+					className="cursor-pointer bg-neutral-50 p-2 sm:p-3 dark:bg-neutral-950"
+					onClick={open}
+					onKeyDown={(e) => {
+						if (e.key === "Enter" || e.key === " ") {
+							e.preventDefault();
+							open();
+						}
+					}}
+				>
 					<div className="relative">
 						<video
 							ref={videoRef}
@@ -185,45 +197,45 @@ function HeroCarousel() {
 				</AnimatePresence>
 			</div>
 
-		<div className="relative z-5 mt-4 flex items-center justify-center gap-2">
-			<button
-				type="button"
-				onClick={() => !isGifExpanded && goToPrev()}
-				className="flex size-11 items-center justify-center rounded-full border border-neutral-200 bg-white text-neutral-700 shadow-sm transition-colors hover:bg-neutral-100 touch-manipulation dark:border-neutral-700 dark:bg-neutral-800 dark:text-neutral-200 dark:hover:bg-neutral-700"
-				aria-label="Previous slide"
-			>
-				<ChevronLeft className="size-5" />
-			</button>
+			<div className="relative z-5 mt-4 flex items-center justify-center gap-2">
+				<button
+					type="button"
+					onClick={() => !isGifExpanded && goToPrev()}
+					className="flex size-11 items-center justify-center rounded-full border border-neutral-200 bg-white text-neutral-700 shadow-sm transition-colors hover:bg-neutral-100 touch-manipulation dark:border-neutral-700 dark:bg-neutral-800 dark:text-neutral-200 dark:hover:bg-neutral-700"
+					aria-label="Previous slide"
+				>
+					<ChevronLeft className="size-5" />
+				</button>
 
-			<div className="flex items-center">
-				{carouselItems.map((_, i) => (
-					<button
-						key={`dot_${i}`}
-						type="button"
-						onClick={() => !isGifExpanded && goTo(i)}
-						className="flex h-11 min-w-[28px] items-center justify-center touch-manipulation"
-						aria-label={`Go to slide ${i + 1}`}
-					>
-						<span
-							className={`block h-2.5 rounded-full transition-all duration-300 ${
-								i === activeIndex
-									? "w-6 bg-neutral-900 dark:bg-white"
-									: "w-2.5 bg-neutral-300 hover:bg-neutral-400 dark:bg-neutral-600 dark:hover:bg-neutral-500"
-							}`}
-						/>
-					</button>
-				))}
+				<div className="flex items-center">
+					{carouselItems.map((_, i) => (
+						<button
+							key={`dot_${i}`}
+							type="button"
+							onClick={() => !isGifExpanded && goTo(i)}
+							className="flex h-11 min-w-[28px] items-center justify-center touch-manipulation"
+							aria-label={`Go to slide ${i + 1}`}
+						>
+							<span
+								className={`block h-2.5 rounded-full transition-all duration-300 ${
+									i === activeIndex
+										? "w-6 bg-neutral-900 dark:bg-white"
+										: "w-2.5 bg-neutral-300 hover:bg-neutral-400 dark:bg-neutral-600 dark:hover:bg-neutral-500"
+								}`}
+							/>
+						</button>
+					))}
+				</div>
+
+				<button
+					type="button"
+					onClick={() => !isGifExpanded && goToNext()}
+					className="flex size-11 items-center justify-center rounded-full border border-neutral-200 bg-white text-neutral-700 shadow-sm transition-colors hover:bg-neutral-100 touch-manipulation dark:border-neutral-700 dark:bg-neutral-800 dark:text-neutral-200 dark:hover:bg-neutral-700"
+					aria-label="Next slide"
+				>
+					<ChevronRight className="size-5" />
+				</button>
 			</div>
-
-			<button
-				type="button"
-				onClick={() => !isGifExpanded && goToNext()}
-				className="flex size-11 items-center justify-center rounded-full border border-neutral-200 bg-white text-neutral-700 shadow-sm transition-colors hover:bg-neutral-100 touch-manipulation dark:border-neutral-700 dark:bg-neutral-800 dark:text-neutral-200 dark:hover:bg-neutral-700"
-				aria-label="Next slide"
-			>
-				<ChevronRight className="size-5" />
-			</button>
-		</div>
 		</div>
 	);
 }

surfsense_web/components/ui/link-toolbar.tsx

@@ -160,22 +160,21 @@ function LinkOpenButton() {
 	const editor = useEditorRef();
 	const selection = useEditorSelection();
 
-	const attributes = React.useMemo(
-		() => {
-			const entry = editor.api.node<TLinkElement>({
-				match: { type: editor.getType(KEYS.link) },
-			});
-			if (!entry) {
-				return {};
-			}
-			const [element] = entry;
-			return getLinkAttributes(editor, element);
-		},
-		// eslint-disable-next-line react-hooks/exhaustive-deps
-		[editor, selection]
-	);
+	// biome-ignore lint/correctness/useExhaustiveDependencies: selection triggers recalculation of link attributes
+	const attributes = React.useMemo(() => {
+		const entry = editor.api.node<TLinkElement>({
+			match: { type: editor.getType(KEYS.link) },
+		});
+		if (!entry) {
+			return {};
+		}
+		const [element] = entry;
+		return getLinkAttributes(editor, element);
+	}, [editor, selection]);
 
 	return (
+		// biome-ignore lint/a11y/noStaticElementInteractions: <a> with spread attributes has dynamic href
+		// biome-ignore lint/a11y/useAriaPropsSupportedByRole: aria-label needed for icon-only link
 		<a
 			{...attributes}
 			className={buttonVariants({
@@ -185,8 +184,12 @@ function LinkOpenButton() {
 			onMouseOver={(e) => {
 				e.stopPropagation();
 			}}
+			onFocus={(e) => {
+				e.stopPropagation();
+			}}
 			aria-label="Open link in a new tab"
 			target="_blank"
+			rel="noopener noreferrer"
 		>
 			<ExternalLink width={18} />
 		</a>

surfsense_web/components/ui/spotlight.tsx

@@ -48,14 +48,17 @@ export function Spotlight({
 	useEffect(() => {
 		if (!parentElement) return;
 
+		const handleEnter = () => setIsHovered(true);
+		const handleLeave = () => setIsHovered(false);
+
 		parentElement.addEventListener("mousemove", handleMouseMove);
-		parentElement.addEventListener("mouseenter", () => setIsHovered(true));
-		parentElement.addEventListener("mouseleave", () => setIsHovered(false));
+		parentElement.addEventListener("mouseenter", handleEnter);
+		parentElement.addEventListener("mouseleave", handleLeave);
 
 		return () => {
 			parentElement.removeEventListener("mousemove", handleMouseMove);
-			parentElement.removeEventListener("mouseenter", () => setIsHovered(true));
-			parentElement.removeEventListener("mouseleave", () => setIsHovered(false));
+			parentElement.removeEventListener("mouseenter", handleEnter);
+			parentElement.removeEventListener("mouseleave", handleLeave);
 		};
 	}, [parentElement, handleMouseMove]);
 

surfsense_web/components/ui/toolbar.tsx

@@ -219,7 +219,8 @@ export function ToolbarSplitButtonSecondary({
 	...props
 }: React.ComponentPropsWithoutRef<"span"> & VariantProps<typeof dropdownArrowVariants>) {
 	return (
-		<span
+		<button
+			type="button"
 			className={cn(
 				dropdownArrowVariants({
 					size,
@@ -229,11 +230,10 @@ export function ToolbarSplitButtonSecondary({
 				className
 			)}
 			onClick={(e) => e.stopPropagation()}
-			role="button"
-			{...props}
+			{...(props as React.ComponentPropsWithoutRef<"button">)}
 		>
 			<ChevronDown className="size-3.5 text-muted-foreground" data-icon />
-		</span>
+		</button>
 	);
 }
 

surfsense_web/content/docs/how-to/zero-sync.mdx

@@ -74,6 +74,7 @@ Zero syncs the following tables for real-time features:
 |-------|---------|
 | `notifications` | Inbox (comments, document processing, connector status) |
 | `documents` | Document list, processing status indicators |
+| `folders` | Nested folder tree for organizing documents |
 | `search_source_connectors` | Connector status, indexing progress |
 | `new_chat_messages` | Live chat message sync for shared chats |
 | `chat_comments` | Real-time comment threads on AI responses |

surfsense_web/contracts/types/folder.types.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+
+export const folder = z.object({
+	id: z.number(),
+	name: z.string(),
+	position: z.string(),
+	parent_id: z.number().nullable(),
+	search_space_id: z.number(),
+	created_by_id: z.string().nullable().optional(),
+	created_at: z.string(),
+	updated_at: z.string(),
+});
+
+export const folderCreateRequest = z.object({
+	name: z.string().min(1).max(255),
+	parent_id: z.number().nullable().optional(),
+	search_space_id: z.number(),
+});
+
+export const folderUpdateRequest = z.object({
+	name: z.string().min(1).max(255),
+});
+
+export const folderMoveRequest = z.object({
+	new_parent_id: z.number().nullable().optional(),
+});
+
+export const folderReorderRequest = z.object({
+	before_position: z.string().nullable().optional(),
+	after_position: z.string().nullable().optional(),
+});
+
+export const folderBreadcrumb = z.object({
+	id: z.number(),
+	name: z.string(),
+});
+
+export const documentMoveRequest = z.object({
+	folder_id: z.number().nullable().optional(),
+});
+
+export const bulkDocumentMoveRequest = z.object({
+	document_ids: z.array(z.number()),
+	folder_id: z.number().nullable().optional(),
+});
+
+export const folderListResponse = z.array(folder);
+export const folderBreadcrumbResponse = z.array(folderBreadcrumb);
+
+export const folderDeleteResponse = z.object({
+	message: z.string(),
+	documents_queued_for_deletion: z.number(),
+});
+
+export type Folder = z.infer<typeof folder>;
+export type FolderCreateRequest = z.infer<typeof folderCreateRequest>;
+export type FolderUpdateRequest = z.infer<typeof folderUpdateRequest>;
+export type FolderMoveRequest = z.infer<typeof folderMoveRequest>;
+export type FolderReorderRequest = z.infer<typeof folderReorderRequest>;
+export type FolderBreadcrumb = z.infer<typeof folderBreadcrumb>;
+export type DocumentMoveRequest = z.infer<typeof documentMoveRequest>;
+export type BulkDocumentMoveRequest = z.infer<typeof bulkDocumentMoveRequest>;
+export type FolderListResponse = z.infer<typeof folderListResponse>;
+export type FolderBreadcrumbResponse = z.infer<typeof folderBreadcrumbResponse>;
+export type FolderDeleteResponse = z.infer<typeof folderDeleteResponse>;

surfsense_web/hooks/use-logs.ts

@@ -13,7 +13,7 @@ export interface Log {
 	status: LogStatus;
 	message: string;
 	source?: string;
-	log_metadata?: Record<string, any>;
+	log_metadata?: Record<string, unknown>;
 	created_at: string;
 	search_space_id: number;
 }
@@ -52,8 +52,9 @@ export interface LogSummary {
 }
 
 export function useLogs(searchSpaceId?: number, filters: LogFilters = {}) {
-	// Memoize filters to prevent infinite re-renders
-	const memoizedFilters = useMemo(() => filters, [JSON.stringify(filters)]);
+	const filtersKey = JSON.stringify(filters);
+	// biome-ignore lint/correctness/useExhaustiveDependencies: stable serialized key used intentionally
+	const memoizedFilters = useMemo(() => filters, [filtersKey]);
 
 	const buildQueryParams = useCallback(
 		(customFilters: LogFilters = {}) => {
@@ -62,22 +63,22 @@ export function useLogs(searchSpaceId?: number, filters: LogFilters = {}) {
 			const allFilters = { ...memoizedFilters, ...customFilters };
 
 			if (allFilters.search_space_id) {
-				params["search_space_id"] = allFilters.search_space_id.toString();
+				params.search_space_id = allFilters.search_space_id.toString();
 			}
 			if (allFilters.level) {
-				params["level"] = allFilters.level;
+				params.level = allFilters.level;
 			}
 			if (allFilters.status) {
-				params["status"] = allFilters.status;
+				params.status = allFilters.status;
 			}
 			if (allFilters.source) {
-				params["source"] = allFilters.source;
+				params.source = allFilters.source;
 			}
 			if (allFilters.start_date) {
-				params["start_date"] = allFilters.start_date;
+				params.start_date = allFilters.start_date;
 			}
 			if (allFilters.end_date) {
-				params["end_date"] = allFilters.end_date;
+				params.end_date = allFilters.end_date;
 			}
 
 			return params;

surfsense_web/hooks/use-search-source-connectors.ts

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useState } from "react";
-import { authenticatedFetch, getBearerToken, handleUnauthorized } from "@/lib/auth-utils";
+import { authenticatedFetch } from "@/lib/auth-utils";
 
 export interface SearchSourceConnector {
 	id: number;
@@ -7,7 +7,7 @@ export interface SearchSourceConnector {
 	connector_type: string;
 	is_indexable: boolean;
 	last_indexed_at: string | null;
-	config: Record<string, any>;
+	config: Record<string, unknown>;
 	search_space_id: number;
 	user_id?: string;
 	created_at?: string;
@@ -20,7 +20,7 @@ export interface ConnectorSourceItem {
 	id: number;
 	name: string;
 	type: string;
-	sources: any[];
+	sources: unknown[];
 }
 
 /**
@@ -60,6 +60,44 @@ export const useSearchSourceConnectors = (lazy: boolean = false, searchSpaceId?:
 		},
 	]);
 
+	const updateConnectorSourceItems = useCallback((currentConnectors: SearchSourceConnector[]) => {
+		const defaultConnectors: ConnectorSourceItem[] = [
+			{
+				id: 1,
+				name: "Crawled URL",
+				type: "CRAWLED_URL",
+				sources: [],
+			},
+			{
+				id: 2,
+				name: "File",
+				type: "FILE",
+				sources: [],
+			},
+			{
+				id: 3,
+				name: "Extension",
+				type: "EXTENSION",
+				sources: [],
+			},
+			{
+				id: 4,
+				name: "Youtube Video",
+				type: "YOUTUBE_VIDEO",
+				sources: [],
+			},
+		];
+
+		const apiConnectors: ConnectorSourceItem[] = currentConnectors.map((connector, index) => ({
+			id: 1000 + index,
+			name: connector.name,
+			type: connector.connector_type,
+			sources: [],
+		}));
+
+		setConnectorSourceItems([...defaultConnectors, ...apiConnectors]);
+	}, []);
+
 	const fetchConnectors = useCallback(
 		async (spaceId?: number) => {
 			if (isLoaded && lazy) return; // Avoid redundant calls in lazy mode
@@ -100,7 +138,7 @@ export const useSearchSourceConnectors = (lazy: boolean = false, searchSpaceId?:
 				setIsLoading(false);
 			}
 		},
-		[isLoaded, lazy]
+		[isLoaded, lazy, updateConnectorSourceItems]
 	);
 
 	useEffect(() => {
@@ -120,47 +158,6 @@ export const useSearchSourceConnectors = (lazy: boolean = false, searchSpaceId?:
 		[fetchConnectors, searchSpaceId]
 	);
 
-	// Update connector source items when connectors change
-	const updateConnectorSourceItems = (currentConnectors: SearchSourceConnector[]) => {
-		// Start with the default hardcoded connectors
-		const defaultConnectors: ConnectorSourceItem[] = [
-			{
-				id: 1,
-				name: "Crawled URL",
-				type: "CRAWLED_URL",
-				sources: [],
-			},
-			{
-				id: 2,
-				name: "File",
-				type: "FILE",
-				sources: [],
-			},
-			{
-				id: 3,
-				name: "Extension",
-				type: "EXTENSION",
-				sources: [],
-			},
-			{
-				id: 4,
-				name: "Youtube Video",
-				type: "YOUTUBE_VIDEO",
-				sources: [],
-			},
-		];
-
-		// Add the API connectors
-		const apiConnectors: ConnectorSourceItem[] = currentConnectors.map((connector, index) => ({
-			id: 1000 + index, // Use a high ID to avoid conflicts with hardcoded IDs
-			name: connector.name,
-			type: connector.connector_type,
-			sources: [],
-		}));
-
-		setConnectorSourceItems([...defaultConnectors, ...apiConnectors]);
-	};
-
 	/**
 	 * Create a new search source connector
 	 * @param connectorData - The connector data (excluding search_space_id)

surfsense_web/i18n/request.ts

@@ -10,7 +10,7 @@ export default getRequestConfig(async ({ requestLocale }) => {
 	let locale = await requestLocale;
 
 	// Ensure that the incoming `locale` is valid
-	if (!locale || !routing.locales.includes(locale as any)) {
+	if (!locale || !routing.locales.includes(locale as (typeof routing.locales)[number])) {
 		locale = routing.defaultLocale;
 	}
 

surfsense_web/lib/apis/base-api.service.ts

@@ -16,7 +16,7 @@ export type RequestOptions = {
 	headers?: Record<string, string>;
 	contentType?: "application/json" | "application/x-www-form-urlencoded";
 	signal?: AbortSignal;
-	body?: any;
+	body?: unknown;
 	responseType?: ResponseType;
 	_isRetry?: boolean; // Internal flag to prevent infinite retry loops
 	// Add more options as needed

surfsense_web/lib/apis/documents-api.service.ts

@@ -139,7 +139,7 @@ class DocumentsApiService {
 
 		for (const batch of batches) {
 			const formData = new FormData();
-			batch.forEach((file) => formData.append("files", file));
+			for (const file of batch) formData.append("files", file);
 			formData.append("search_space_id", String(search_space_id));
 			formData.append("should_summarize", String(should_summarize));
 

surfsense_web/lib/apis/folders-api.service.ts

@@ -0,0 +1,113 @@
+import {
+	type BulkDocumentMoveRequest,
+	bulkDocumentMoveRequest,
+	type DocumentMoveRequest,
+	documentMoveRequest,
+	type FolderCreateRequest,
+	type FolderMoveRequest,
+	type FolderReorderRequest,
+	type FolderUpdateRequest,
+	folder,
+	folderBreadcrumbResponse,
+	folderCreateRequest,
+	folderDeleteResponse,
+	folderListResponse,
+	folderMoveRequest,
+	folderReorderRequest,
+	folderUpdateRequest,
+} from "@/contracts/types/folder.types";
+import { ValidationError } from "../error";
+import { baseApiService } from "./base-api.service";
+
+class FoldersApiService {
+	createFolder = async (request: FolderCreateRequest) => {
+		const parsed = folderCreateRequest.safeParse(request);
+		if (!parsed.success) {
+			throw new ValidationError(
+				`Invalid request: ${parsed.error.issues.map((i) => i.message).join(", ")}`
+			);
+		}
+		return baseApiService.post("/api/v1/folders", folder, { body: parsed.data });
+	};
+
+	listFolders = async (searchSpaceId: number) => {
+		return baseApiService.get(
+			`/api/v1/folders?search_space_id=${searchSpaceId}`,
+			folderListResponse
+		);
+	};
+
+	getFolder = async (folderId: number) => {
+		return baseApiService.get(`/api/v1/folders/${folderId}`, folder);
+	};
+
+	getFolderBreadcrumb = async (folderId: number) => {
+		return baseApiService.get(`/api/v1/folders/${folderId}/breadcrumb`, folderBreadcrumbResponse);
+	};
+
+	updateFolder = async (folderId: number, request: FolderUpdateRequest) => {
+		const parsed = folderUpdateRequest.safeParse(request);
+		if (!parsed.success) {
+			throw new ValidationError(
+				`Invalid request: ${parsed.error.issues.map((i) => i.message).join(", ")}`
+			);
+		}
+		return baseApiService.put(`/api/v1/folders/${folderId}`, folder, {
+			body: parsed.data,
+		});
+	};
+
+	moveFolder = async (folderId: number, request: FolderMoveRequest) => {
+		const parsed = folderMoveRequest.safeParse(request);
+		if (!parsed.success) {
+			throw new ValidationError(
+				`Invalid request: ${parsed.error.issues.map((i) => i.message).join(", ")}`
+			);
+		}
+		return baseApiService.put(`/api/v1/folders/${folderId}/move`, folder, {
+			body: parsed.data,
+		});
+	};
+
+	reorderFolder = async (folderId: number, request: FolderReorderRequest) => {
+		const parsed = folderReorderRequest.safeParse(request);
+		if (!parsed.success) {
+			throw new ValidationError(
+				`Invalid request: ${parsed.error.issues.map((i) => i.message).join(", ")}`
+			);
+		}
+		return baseApiService.put(`/api/v1/folders/${folderId}/reorder`, folder, {
+			body: parsed.data,
+		});
+	};
+
+	deleteFolder = async (folderId: number) => {
+		return baseApiService.delete(`/api/v1/folders/${folderId}`, folderDeleteResponse);
+	};
+
+	moveDocument = async (documentId: number, request: DocumentMoveRequest) => {
+		const parsed = documentMoveRequest.safeParse(request);
+		if (!parsed.success) {
+			throw new ValidationError(
+				`Invalid request: ${parsed.error.issues.map((i) => i.message).join(", ")}`
+			);
+		}
+		return baseApiService.put(`/api/v1/documents/${documentId}/move`, undefined, {
+			body: parsed.data,
+		});
+	};
+
+	bulkMoveDocuments = async (request: BulkDocumentMoveRequest) => {
+		const parsed = bulkDocumentMoveRequest.safeParse(request);
+		if (!parsed.success) {
+			throw new ValidationError(
+				`Invalid request: ${parsed.error.issues.map((i) => i.message).join(", ")}`
+			);
+		}
+		return baseApiService.put("/api/v1/documents/bulk-move", undefined, {
+			body: parsed.data,
+		});
+	};
+}
+
+export const foldersApiService = new FoldersApiService();

surfsense_web/lib/apis/invites-api.service.ts

@@ -1,26 +1,20 @@
 import {
 	type AcceptInviteRequest,
-	type AcceptInviteResponse,
 	acceptInviteRequest,
 	acceptInviteResponse,
 	type CreateInviteRequest,
-	type CreateInviteResponse,
 	createInviteRequest,
 	createInviteResponse,
 	type DeleteInviteRequest,
-	type DeleteInviteResponse,
 	deleteInviteRequest,
 	deleteInviteResponse,
 	type GetInviteInfoRequest,
-	type GetInviteInfoResponse,
 	type GetInvitesRequest,
-	type GetInvitesResponse,
 	getInviteInfoRequest,
 	getInviteInfoResponse,
 	getInvitesRequest,
 	getInvitesResponse,
 	type UpdateInviteRequest,
-	type UpdateInviteResponse,
 	updateInviteRequest,
 	updateInviteResponse,
 } from "@/contracts/types/invites.types";

surfsense_web/lib/apis/logs-api.service.ts

@@ -14,8 +14,6 @@ import {
 	getLogSummaryResponse,
 	getLogsRequest,
 	getLogsResponse,
-	type Log,
-	log,
 	type UpdateLogRequest,
 	updateLogRequest,
 	updateLogResponse,

surfsense_web/lib/apis/members-api.service.ts

@@ -1,22 +1,17 @@
 import {
 	type DeleteMembershipRequest,
-	type DeleteMembershipResponse,
 	deleteMembershipRequest,
 	deleteMembershipResponse,
 	type GetMembersRequest,
-	type GetMembersResponse,
 	type GetMyAccessRequest,
-	type GetMyAccessResponse,
 	getMembersRequest,
 	getMembersResponse,
 	getMyAccessRequest,
 	getMyAccessResponse,
 	type LeaveSearchSpaceRequest,
-	type LeaveSearchSpaceResponse,
 	leaveSearchSpaceRequest,
 	leaveSearchSpaceResponse,
 	type UpdateMembershipRequest,
-	type UpdateMembershipResponse,
 	updateMembershipRequest,
 	updateMembershipResponse,
 } from "@/contracts/types/members.types";

surfsense_web/lib/chat/streaming-state.ts

@@ -136,7 +136,7 @@ export function buildContentForPersistence(
  * Async generator that reads an SSE stream and yields parsed JSON objects.
  * Handles buffering, event splitting, and skips malformed JSON / [DONE] lines.
  */
-export async function* readSSEStream(response: Response): AsyncGenerator<any> {
+export async function* readSSEStream(response: Response): AsyncGenerator<unknown> {
 	if (!response.body) {
 		throw new Error("No response body");
 	}

surfsense_web/next.config.ts

@@ -1,7 +1,7 @@
+import path from "node:path";
 import { createMDX } from "fumadocs-mdx/next";
 import type { NextConfig } from "next";
 import createNextIntlPlugin from "next-intl/plugin";
-import path from "path";
 
 // Create the next-intl plugin
 const withNextIntl = createNextIntlPlugin("./i18n/request.ts");
@@ -37,7 +37,9 @@ const nextConfig: NextConfig = {
 	// Configure webpack (SVGR)
 	webpack: (config) => {
 		// SVGR: import *.svg as React components
-		const fileLoaderRule = config.module.rules.find((rule: any) => rule.test?.test?.(".svg"));
+		const fileLoaderRule = config.module.rules.find(
+			(rule: { test?: { test?: (s: string) => boolean } }) => rule.test?.test?.(".svg")
+		);
 		config.module.rules.push(
 			// Re-apply the existing file loader for *.svg?url imports
 			{

surfsense_web/package.json

@@ -93,6 +93,7 @@
 		"dotenv": "^17.2.3",
 		"drizzle-orm": "^0.44.5",
 		"emblor": "^1.4.8",
+		"fractional-indexing": "^3.2.0",
 		"fumadocs-core": "^16.3.1",
 		"fumadocs-mdx": "^14.2.1",
 		"fumadocs-ui": "^16.3.1",

surfsense_web/pnpm-lock.yaml

@@ -224,6 +224,9 @@ importers:
       emblor:
         specifier: ^1.4.8
         version: 1.4.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      fractional-indexing:
+        specifier: ^3.2.0
+        version: 3.2.0
       fumadocs-core:
         specifier: ^16.3.1
         version: 16.6.5(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.4)(@types/mdast@4.0.4)(@types/react@19.2.14)(lucide-react@0.577.0(react@19.2.4))(next@16.1.6(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.3.6)
@@ -5781,6 +5784,10 @@ packages:
   forwarded-parse@2.1.2:
     resolution: {integrity: sha512-alTFZZQDKMporBH77856pXgzhEzaUVmLCDk+egLgIgHst3Tpndzz8MnKe+GzRJRfvVdn69HhpW7cmXzvtLvJAw==}
 
+  fractional-indexing@3.2.0:
+    resolution: {integrity: sha512-PcOxmqwYCW7O2ovKRU8OoQQj2yqTfEB/yeTYk4gPid6dN5ODRfU1hXd9tTVZzax/0NkO7AxpHykvZnT1aYp/BQ==}
+    engines: {node: ^14.13.1 || >=16.0.0}
+
   framer-motion@12.34.3:
     resolution: {integrity: sha512-v81ecyZKYO/DfpTwHivqkxSUBzvceOpoI+wLfgCgoUIKxlFKEXdg0oR9imxwXumT4SFy8vRk9xzJ5l3/Du/55Q==}
     peerDependencies:
@@ -14296,6 +14303,8 @@ snapshots:
 
   forwarded-parse@2.1.2: {}
 
+  fractional-indexing@3.2.0: {}
+
   framer-motion@12.34.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
     dependencies:
       motion-dom: 12.34.3

surfsense_web/types/window.d.ts

@@ -1,7 +1,21 @@
 import type { PostHog } from "posthog-js";
 
+interface ElectronAPI {
+	versions: {
+		electron: string;
+		node: string;
+		chrome: string;
+		platform: string;
+	};
+	openExternal: (url: string) => void;
+	getAppVersion: () => Promise<string>;
+	onDeepLink: (callback: (url: string) => void) => () => void;
+	getQuickAskText: () => Promise<string>;
+}
+
 declare global {
 	interface Window {
 		posthog?: PostHog;
+		electronAPI?: ElectronAPI;
 	}
 }

surfsense_web/zero/queries/folders.ts

@@ -0,0 +1,9 @@
+import { defineQuery } from "@rocicorp/zero";
+import { z } from "zod";
+import { zql } from "../schema/index";
+
+export const folderQueries = {
+	bySpace: defineQuery(z.object({ searchSpaceId: z.number() }), ({ args: { searchSpaceId } }) =>
+		zql.folders.where("searchSpaceId", searchSpaceId).orderBy("position", "asc")
+	),
+};