feat: initial implementation of Nextcloud + Elasticsearch File Explorer (Next.js + WebDAV + ES + Tika + Sentry)

2025-09-13 06:15:14 -06:00 · 2025-09-13 06:15:14 -06:00 · 479e461430
commit 479e461430
parent 328b071c29
45 changed files with 8882 additions and 208 deletions
--- a/README.md
+++ b/README.md
@ -1,36 +1,263 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Nextcloud + Elasticsearch Discovery File Explorer

-## Getting Started
+A discovery-first file explorer built with Next.js (App Router, TypeScript, Tailwind, shadcn UI) that connects to Nextcloud via WebDAV and indexes metadata/content into Elasticsearch (BM25 baseline, optional semantic hybrid search). Includes upload/download, folder tree browsing, global search, and Sentry instrumentation.

-First, run the development server:
+## TL;DR (Quick Start)
+
+Prereqs:
+- Node 18+ and npm
+- Docker (for Elasticsearch/Kibana/Tika services)
+
+Setup:
+1) Configure environment
+   - Copy `.env.example` to `.env.local` and fill in your values (Nextcloud creds + Elasticsearch endpoint).
+   - A pre-populated `.env.local` is included for your provided Nextcloud host (update if needed).
+
+2) Provision Elasticsearch + Tika (Docker sample below)
+3) Create Elasticsearch index
+   - `npm run create:index`
+4) Ingest Nextcloud into ES (BM25 baseline)
+   - `npx tsx -r dotenv/config -r tsconfig-paths/register scripts/ingest-nextcloud.ts`
+5) Run the app
+   - `npm run dev` then open the reported URL (e.g., http://localhost:3000)
+
+## Why this exists
+
+Nextcloud is the system of record for files; this app provides a discovery UX (fast search, filters, previews later) by indexing normalized documents into Elasticsearch. Apache Tika can extract plain text for rich BM25 search, and optional OpenAI-compatible embeddings enable semantic hybrid search.
+
+## Architecture
+
+- UI: Next.js App Router (TypeScript), Tailwind CSS, shadcn UI
+- Data
+  - Nextcloud WebDAV for browse/upload/download
+  - Elasticsearch for indexing and search (BM25 baseline)
+  - Apache Tika server for content extraction (optional but recommended)
+  - OpenAI-compatible embeddings (optional) for dense vectors/hybrid queries
+- Observability: Sentry (client/server/edge) with logs and spans
+
+## Features
+
+- Browse Nextcloud directories via a lazy-loading sidebar tree
+- View files with size/type and actions in a table
+- Upload files into the current folder
+- Download/proxy via Next.js route
+- Global search box (BM25 baseline) with optional “Semantic” toggle for hybrid search (when embeddings are configured)
+- Sentry logging/tracing sprinkled around WebDAV and Elasticsearch calls
+
+## Project Layout (highlights)
+
+- src/lib
+  - env.ts: zod-validated env loader with flags
+  - paths.ts: normalization/helpers for DAV paths
+  - elasticsearch.ts: ES client, ensureIndex, bm25Search, knnSearch, hybridSearch
+  - webdav.ts: Nextcloud WebDAV wrapper (list/create/upload/download/stat) with spans
+  - embeddings.ts: OpenAI-compatible embeddings client
+- src/app/api
+  - folders/list, folders/create
+  - files/list, files/upload, files/download
+  - search/query
+- scripts
+  - create-index.ts: creates ES index + alias
+  - ingest-nextcloud.ts: crawl Nextcloud → optional Tika → index into ES
+- docs/elasticsearch/mappings.json: canonical baseline mapping
+- Sentry init
+  - instrumentation-client.ts, sentry.server.config.ts, sentry.edge.config.ts
+
+## Environment Variables
+
+Populate `.env.local` (not committed). See `.env.example` for full list.
+
+Required:
+- NEXTCLOUD_BASE_URL: e.g. https://your-nextcloud.example.com
+- NEXTCLOUD_USERNAME: WebDAV user
+- NEXTCLOUD_APP_PASSWORD: App password generated in Nextcloud (not login password)
+- NEXTCLOUD_ROOT_PATH: e.g. `/remote.php/dav/files/admin`
+
+- ELASTICSEARCH_URL: e.g. http://localhost:9200
+- ELASTICSEARCH_INDEX: default `files`
+- ELASTICSEARCH_ALIAS: default `files_current`
+
+Optional:
+- TIKA_BASE_URL: e.g. http://localhost:9998 (if using Apache Tika for extraction)
+- SENTRY_DSN: if provided, Sentry is enabled
+- OPENAI_API_BASE, OPENAI_API_KEY, OPENAI_EMBEDDING_MODEL, EMBEDDING_DIM: Enable embeddings + semantic hybrid
+
+## Dependencies and Local Services (Docker)
+
+Below is a sample docker-compose for local development. Adjust versions for your environment. For TrueNAS Scale, translate this into an appropriate app configuration.
+
+```yaml
+version: "3.9"
+services:
+  elasticsearch:
+    image: docker.elastic.co/elasticsearch/elasticsearch:8.12.2
+    container_name: es
+    environment:
+      - discovery.type=single-node
+      - xpack.security.enabled=false
+      - ES_JAVA_OPTS=-Xms1g -Xmx1g
+    ports:
+      - "9200:9200"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9200/_cluster/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  kibana:
+    image: docker.elastic.co/kibana/kibana:8.12.2
+    container_name: kibana
+    environment:
+      - ELASTICSEARCH_HOSTS=http://elasticsearch:9200
+    ports:
+      - "5601:5601"
+    depends_on:
+      elasticsearch:
+        condition: service_healthy
+
+  tika:
+    image: apache/tika:latest-full
+    container_name: tika
+    ports:
+      - "9998:9998"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9998"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+```
+
+Notes:
+- Security is relaxed in this dev config (xpack security disabled). Harden for production.
+- Set `TIKA_BASE_URL=http://localhost:9998` to enable content extraction.
+
+## Install & Run
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Run development server:

 ```bash
 npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+# Next.js will print the URL, for example http://localhost:3000
 ```

-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+Build and start:

-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+```bash
+npm run build
+npm start
+```

-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+## Initialize Elasticsearch

-## Learn More
+Create the index and alias (files/files_current):

-To learn more about Next.js, take a look at the following resources:
+```bash
+npm run create:index
+# internally: tsx -r dotenv/config -r tsconfig-paths/register scripts/create-index.ts
+```

- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+To recreate:
+```bash
+npm run create:index -- --recreate
+```

-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+## Ingest Nextcloud → Elasticsearch

-## Deploy on Vercel
+Crawl Nextcloud via WebDAV, optionally extract content with Tika, index into ES:

-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+```bash
+npx tsx -r dotenv/config -r tsconfig-paths/register scripts/ingest-nextcloud.ts
+```

-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+Restrict to a subtree:
+```bash
+npx tsx -r dotenv/config -r tsconfig-paths/register scripts/ingest-nextcloud.ts -- --root=/remote.php/dav/files/admin/SomeFolder
+```
+
+After ingestion, try searching in the UI (BM25).
+
+## Optional: Semantic Hybrid Search
+
+To enable, configure embeddings:
+- OPENAI_API_BASE (e.g., https://api.openai.com/v1 or your compatible endpoint)
+- OPENAI_API_KEY
+- OPENAI_EMBEDDING_MODEL (e.g., text-embedding-3-large)
+- EMBEDDING_DIM (e.g., 1536)
+
+Current code path supports:
+- Hybrid search in API when `semantic: true` in requests; UI has a “Semantic” toggle.
+- A future backfill script can be added to compute vectors for existing docs (planned).
+
+## Sentry
+
+- Files:
+  - instrumentation-client.ts (client init)
+  - sentry.server.config.ts (node runtime)
+  - sentry.edge.config.ts (edge runtime)
+- Enable by setting SENTRY_DSN in `.env.local`.
+- Logging enabled (`consoleLoggingIntegration`), capturing console.log/warn/error.
+- Spans instrument WebDAV and ES operations with meaningful op/name and attributes.
+
+## API Endpoints
+
+- GET `/api/folders/list?path=/abs/path` → { folders[], files[] }
+- POST `/api/folders/create` body: `{ path: "/abs/path" }` → `{ ok: true }`
+- GET `/api/files/list?path=/abs/path&page=1&perPage=50` → `{ total, page, perPage, items[] }`
+- POST `/api/files/upload` (multipart) form-data: `file`, `destPath`
+- GET `/api/files/download?path=/abs/path` → stream download
+- POST `/api/search/query` → body: `{ q, filters?, sort?, page?, perPage?, semantic? }`
+
+## UI Usage
+
+- Navigate folders via the left sidebar. Root defaults to `NEXTCLOUD_ROOT_PATH`.
+- Breadcrumbs show the current path; click to navigate.
+- Global search queries ES (BM25). Toggle “Semantic” to blend vector similarity (when enabled).
+- Use “Upload” to send a file to the current folder.
+- Click a file name or download action to retrieve it.
+
+## Known Caveats / TODO
+
+- When starting from `NEXTCLOUD_ROOT_PATH`, breadcrumb segments may include technical path prefixes (e.g., `/remote.php`, `/dav`) that aren’t browsable independently. This can be adjusted to start breadcrumbs from the user root only.
+- Embeddings backfill script & “Find similar” API/UI are planned.
+- Tests (unit/integration/E2E) and TrueNAS-specific compose notes can be added next.
+
+## Development Notes
+
+- Code style: TypeScript, ESLint (Next config), Tailwind v4.
+- shadcn components added (Slate), most primitives included.
+- ES Types via `@elastic/elasticsearch` estypes.
+- Stream interop handled for Node → Web streams in downloads and uploads.
+- Zod-based env loader normalizes URLs and validates required vars.
+
+## Troubleshooting
+
+- Search 500s:
+  - Ensure Elasticsearch is running and reachable at `ELASTICSEARCH_URL`.
+  - Run `npm run create:index` to create the index and alias.
+  - If using Tika for content, ensure `TIKA_BASE_URL` is set and service is healthy (optional).
+- WebDAV failures:
+  - Verify `NEXTCLOUD_BASE_URL`, `NEXTCLOUD_USERNAME`, `NEXTCLOUD_APP_PASSWORD`, and `NEXTCLOUD_ROOT_PATH`.
+  - Confirm the user has permission for the target path.
+- Sentry issues:
+  - Ensure `SENTRY_DSN` is set; check networking/outbound restrictions.
+
+## Scripts
+
+- `npm run create:index`: Create/recreate Elasticsearch index and alias
+- `scripts/ingest-nextcloud.ts`: Crawl Nextcloud → Tika (optional) → Elasticsearch
+
+## Security
+
+- Keep `.env.local` out of source control (already in .gitignore).
+- Use Nextcloud App Passwords, not login passwords.
+- Harden Elasticsearch/Kibana/Tika for production (auth, TLS, resource limits).
+
+---
+
+Built per implementation_plan.md with a deterministic order of rollout and Sentry instrumentation aligned to organizational rules.
--- a/components.json
+++ b/components.json
@ -0,0 +1,22 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/globals.css",
+    "baseColor": "slate",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "registries": {}
+}
--- a/docs/elasticsearch/mappings.json
+++ b/docs/elasticsearch/mappings.json
@ -0,0 +1,63 @@
+{
+  "settings": {
+    "analysis": {
+      "normalizer": {
+        "lowercase_normalizer": {
+          "type": "custom",
+          "filter": ["lowercase"]
+        }
+      }
+    }
+  },
+  "mappings": {
+    "dynamic": "strict",
+    "properties": {
+      "id": { "type": "keyword" },
+      "name": {
+        "type": "text",
+        "fields": {
+          "keyword": { "type": "keyword", "ignore_above": 256 }
+        }
+      },
+      "nickname": {
+        "type": "text",
+        "fields": {
+          "keyword": { "type": "keyword", "ignore_above": 256 }
+        }
+      },
+      "title": {
+        "type": "text",
+        "fields": {
+          "keyword": { "type": "keyword", "ignore_above": 256 }
+        }
+      },
+      "content": { "type": "text" },
+      "path": {
+        "type": "keyword",
+        "normalizer": "lowercase_normalizer",
+        "fields": {
+          "text": { "type": "text" }
+        }
+      },
+      "parentPath": {
+        "type": "keyword",
+        "normalizer": "lowercase_normalizer"
+      },
+      "sizeBytes": { "type": "long" },
+      "mimeType": { "type": "keyword" },
+      "owner": { "type": "keyword" },
+      "uploadedBy": { "type": "keyword" },
+      "uploadedAt": { "type": "date" },
+      "modifiedAt": { "type": "date" },
+      "tags": { "type": "keyword" },
+      "etag": { "type": "keyword" },
+      "previewAvailable": { "type": "boolean" },
+      "acl": {
+        "properties": {
+          "principals": { "type": "keyword" },
+          "public": { "type": "boolean" }
+        }
+      }
+    }
+  }
+}
--- a/instrumentation-client.ts
+++ b/instrumentation-client.ts
@ -0,0 +1,14 @@
+import * as Sentry from "@sentry/nextjs";
+
+// Client runtime initialization
+Sentry.init({
+  dsn: process.env.SENTRY_DSN || undefined,
+  tracesSampleRate: 0.2,
+  _experiments: {
+    enableLogs: true,
+  },
+  integrations: [
+    // send console.log, console.warn, and console.error calls as logs to Sentry
+    Sentry.consoleLoggingIntegration({ levels: ["log", "warn", "error"] }),
+  ],
+});
--- a/package-lock.json
+++ b/package-lock.json
--- a/package.json
+++ b/package.json
@ -6,22 +6,46 @@
    "dev": "next dev --turbopack",
    "build": "next build --turbopack",
    "start": "next start",
-    "lint": "eslint"
+    "lint": "eslint",
+    "create:index": "tsx -r dotenv/config -r tsconfig-paths/register scripts/create-index.ts"
  },
  "dependencies": {
+    "@elastic/elasticsearch": "^9.1.1",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-progress": "^1.1.7",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-slot": "^1.2.3",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@sentry/nextjs": "^10.11.0",
+    "@tanstack/react-query": "^5.87.4",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "date-fns": "^4.1.0",
+    "lucide-react": "^0.544.0",
+    "next": "15.5.3",
+    "next-themes": "^0.4.6",
+    "openai": "^5.20.2",
    "react": "19.1.0",
    "react-dom": "19.1.0",
-    "next": "15.5.3"
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.3.1",
+    "webdav": "^5.8.0",
+    "zod": "^3.25.76"
  },
  "devDependencies": {
-    "typescript": "^5",
+    "@eslint/eslintrc": "^3",
+    "@tailwindcss/postcss": "^4",
    "@types/node": "^20",
    "@types/react": "^19",
    "@types/react-dom": "^19",
-    "@tailwindcss/postcss": "^4",
-    "tailwindcss": "^4",
+    "dotenv": "^17.2.2",
    "eslint": "^9",
    "eslint-config-next": "15.5.3",
-    "@eslint/eslintrc": "^3"
+    "tailwindcss": "^4",
+    "tsconfig-paths": "^4.2.0",
+    "tsx": "^4.20.5",
+    "tw-animate-css": "^1.3.8",
+    "typescript": "^5"
  }
 }
--- a/scripts/create-index.ts
+++ b/scripts/create-index.ts
@ -0,0 +1,38 @@
+#!/usr/bin/env tsx
+/**
+ * Create or recreate the Elasticsearch index used by the app.
+ *
+ * Usage:
+ *   npm run create:index
+ *   npm run create:index -- --recreate
+ *
+ * Notes:
+ * - Loads environment from .env/.env.local via `-r dotenv/config` in the npm script.
+ * - Resolves TS path aliases via `-r tsconfig-paths/register`.
+ */
+import { ensureIndex } from "@/lib/elasticsearch";
+
+function parseRecreateArg(argv: string[]): boolean {
+  let recreate = false;
+  for (const arg of argv) {
+    if (arg === "--recreate" || arg === "-r") {
+      recreate = true;
+    } else if (arg.startsWith("--recreate=")) {
+      const v = arg.split("=")[1]?.trim().toLowerCase();
+      recreate = v === "1" || v === "true" || v === "yes";
+    }
+  }
+  return recreate;
+}
+
+async function main() {
+  const recreate = parseRecreateArg(process.argv.slice(2));
+  console.log(`[create-index] Starting. recreate=${recreate}`);
+  await ensureIndex({ recreate });
+  console.log("[create-index] Done.");
+}
+
+main().catch((err) => {
+  console.error("[create-index] Failed:", err);
+  process.exit(1);
+});
--- a/scripts/ingest-nextcloud.ts
+++ b/scripts/ingest-nextcloud.ts
@ -0,0 +1,159 @@
+#!/usr/bin/env tsx
+/**
+ * Ingest Nextcloud files into Elasticsearch (BM25 baseline).
+ *
+ * Flow:
+ * - Crawl Nextcloud via WebDAV starting from NEXTCLOUD_ROOT_PATH
+ * - For each file, build an IndexDocument
+ * - Optionally extract text with Apache Tika if TIKA_BASE_URL is set
+ * - Index into Elasticsearch using env.ELASTICSEARCH_INDEX/ALIAS
+ *
+ * Usage:
+ *   npm run ingest:nextcloud
+ *   npm run ingest:nextcloud -- --root=/remote.php/dav/files/admin/SomeFolder
+ *
+ * Notes:
+ * - Requires .env.local with Nextcloud + Elasticsearch creds
+ * - Tika is optional; if not configured or fails, content is omitted
+ */
+
+import * as Sentry from "@sentry/nextjs";
+import { env } from "@/lib/env";
+import { nextcloud, NextcloudClient } from "@/lib/webdav";
+import { basename, joinPath, normalizePath, pathToId, parentPath as getParent } from "@/lib/paths";
+import type { WebDavEntry } from "@/types/files";
+import type { IndexDocument } from "@/types/ingest";
+import { indexDocument, ensureIndex } from "@/lib/elasticsearch";
+
+// Simple fetch helper for Node (global fetch supported in Next runtime)
+async function tikaExtractText(stream: NodeJS.ReadableStream, contentType?: string): Promise<{ text?: string; meta?: Record<string, unknown> }> {
+  if (!env.TIKA_BASE_URL) return {};
+  try {
+    // Tika Server v2: POST /tika/text for plain text
+    const url = `${env.TIKA_BASE_URL.replace(/\/$/, "")}/tika/text`;
+    const res = await fetch(url, {
+      method: "PUT", // Some deployments use PUT; POST is also supported depending on image
+      headers: {
+        Accept: "text/plain",
+        ...(contentType ? { "Content-Type": contentType } : {}),
+      },
+      body: stream as unknown as BodyInit,
+    } as RequestInit);
+
+    if (!res.ok) {
+      throw new Error(`Tika extraction failed: ${res.status} ${res.statusText}`);
+    }
+    const text = await res.text();
+    return { text };
+  } catch (err) {
+    Sentry.captureException(err);
+    return {};
+  }
+}
+
+type CrawlOpts = {
+  client: NextcloudClient;
+  root: string;
+};
+
+async function* crawl({ client, root }: CrawlOpts): AsyncGenerator<WebDavEntry> {
+  const stack: string[] = [root];
+  while (stack.length) {
+    const current = stack.pop()!;
+    const entries = await client.listDirectory(current);
+    for (const e of entries) {
+      // Skip the container itself when PROPFIND returns the directory entry
+      if (normalizePath(e.href) === normalizePath(current) && e.isDirectory) continue;
+      if (e.isDirectory) {
+        stack.push(e.href);
+      } else {
+        yield e;
+      }
+    }
+  }
+}
+
+function toIndexDoc(e: WebDavEntry): IndexDocument {
+  const p = normalizePath(e.href);
+  const doc: IndexDocument = {
+    id: pathToId(p),
+    name: e.name || basename(p),
+    path: p,
+    parentPath: getParent(p)!,
+    sizeBytes: typeof e.size === "number" ? e.size : 0,
+    mimeType: e.contentType || "application/octet-stream",
+    owner: env.NEXTCLOUD_USERNAME,
+    modifiedAt: e.lastmod,
+    etag: e.etag,
+    previewAvailable: false,
+    tags: [],
+  };
+  return doc;
+}
+
+function parseArgs(argv: string[]) {
+  const out: Record<string, string | boolean> = {};
+  for (const arg of argv) {
+    if (arg.startsWith("--")) {
+      const [k, v] = arg.slice(2).split("=");
+      out[k] = v ?? true;
+    }
+  }
+  return out;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const root = normalizePath(
+    typeof args.root === "string" && args.root.length > 1 ? args.root : env.NEXTCLOUD_ROOT_PATH,
+  );
+  console.log(`[ingest] Start crawl from: ${root}`);
+
+  // Ensure index exists (creates mappings and alias if missing)
+  await ensureIndex();
+
+  // Create a client rooted at NEXTCLOUD_ROOT_PATH (resolve uses absolute)
+  const client = new NextcloudClient(env.NEXTCLOUD_ROOT_PATH);
+
+  let count = 0;
+  for await (const e of crawl({ client, root })) {
+    try {
+      // Build document from DAV metadata
+      const baseDoc = toIndexDoc(e);
+
+      // Try Tika extraction (optional)
+      let contentText: string | undefined;
+      try {
+        const stream = await client.downloadStream(e.href);
+        const { text } = await tikaExtractText(stream, e.contentType);
+        if (text && text.trim().length > 0) contentText = text;
+      } catch (err) {
+        // Non-fatal; proceed without content
+        Sentry.captureException(err);
+      }
+
+      const doc: IndexDocument = {
+        ...baseDoc,
+        content: contentText,
+        title: baseDoc.name,
+      };
+
+      // Index into ES
+      await indexDocument(doc);
+      count++;
+      if (count % 50 === 0) {
+        console.log(`[ingest] Indexed ${count} documents`);
+      }
+    } catch (err) {
+      console.error(`[ingest] Failed for ${e.href}:`, err);
+      Sentry.captureException(err);
+    }
+  }
+
+  console.log(`[ingest] Done. Indexed ${count} documents.`);
+}
+
+main().catch((err) => {
+  console.error("[ingest] Fatal error:", err);
+  process.exit(1);
+});
--- a/sentry.edge.config.ts
+++ b/sentry.edge.config.ts
@ -0,0 +1,14 @@
+import * as Sentry from "@sentry/nextjs";
+
+// Edge runtime initialization (route handlers / middleware in edge)
+Sentry.init({
+  dsn: process.env.SENTRY_DSN || undefined,
+  tracesSampleRate: 0.2,
+  _experiments: {
+    enableLogs: true,
+  },
+  integrations: [
+    // send console.log, console.warn, and console.error calls as logs to Sentry
+    Sentry.consoleLoggingIntegration({ levels: ["log", "warn", "error"] }),
+  ],
+});
--- a/sentry.server.config.ts
+++ b/sentry.server.config.ts
@ -0,0 +1,14 @@
+import * as Sentry from "@sentry/nextjs";
+
+// Server runtime initialization
+Sentry.init({
+  dsn: process.env.SENTRY_DSN || undefined,
+  tracesSampleRate: 0.2,
+  _experiments: {
+    enableLogs: true,
+  },
+  integrations: [
+    // Capture console logs as structured logs in Sentry (info/warn/error)
+    Sentry.consoleLoggingIntegration({ levels: ["log", "warn", "error"] }),
+  ],
+});
--- a/src/app/api/files/download/route.ts
+++ b/src/app/api/files/download/route.ts
@ -0,0 +1,66 @@
+import * as Sentry from "@sentry/nextjs";
+import { NextResponse } from "next/server";
+import { nextcloud } from "@/lib/webdav";
+import { normalizePath } from "@/lib/paths";
+import { Readable } from "node:stream";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+function badRequest(message: string) {
+  return NextResponse.json({ error: message }, { status: 400 });
+}
+
+export async function GET(req: Request) {
+  try {
+    const { searchParams } = new URL(req.url);
+    const rawPath = searchParams.get("path");
+    if (!rawPath) return badRequest("Missing path");
+    const path = normalizePath(rawPath);
+
+    const result = await Sentry.startSpan(
+      { op: "function", name: "api.files.download" },
+      async (span) => {
+        span.setAttribute("path", path);
+
+        // Optionally stat to get metadata (mime/name). Non-fatal if it fails.
+        const stat = await nextcloud.stat(path).catch(() => null);
+
+        const nodeStream = await nextcloud.downloadStream(path);
+        // Convert Node.js readable to Web ReadableStream
+        const asReadable = Readable as unknown as {
+          toWeb?: (s: NodeJS.ReadableStream) => ReadableStream;
+        };
+        const webStream =
+          typeof asReadable.toWeb === "function"
+            ? asReadable.toWeb(nodeStream)
+            : (nodeStream as unknown as ReadableStream);
+
+        const filename = stat?.name ?? path.split("/").pop() ?? "download";
+        const contentType = stat?.contentType ?? "application/octet-stream";
+
+        const headers = new Headers();
+        headers.set("Content-Type", contentType);
+        // Default to attachment; UI may change to inline for previews later
+        headers.set(
+          "Content-Disposition",
+          `attachment; filename*=UTF-8''${encodeURIComponent(filename)}`,
+        );
+        if (stat?.etag) headers.set("ETag", stat.etag);
+
+        return new Response(webStream, { headers });
+      },
+    );
+
+    return result;
+  } catch (error) {
+    Sentry.captureException(error);
+    return NextResponse.json(
+      {
+        error: "Failed to download file",
+        message: error instanceof Error ? error.message : String(error),
+      },
+      { status: 500 },
+    );
+  }
+}
--- a/src/app/api/files/list/route.ts
+++ b/src/app/api/files/list/route.ts
@ -0,0 +1,60 @@
+import * as Sentry from "@sentry/nextjs";
+import { NextResponse } from "next/server";
+import { nextcloud } from "@/lib/webdav";
+import { normalizePath, parentPath } from "@/lib/paths";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+function json<T>(data: T, init?: { status?: number } & ResponseInit) {
+  return NextResponse.json(data, init);
+}
+
+export async function GET(req: Request) {
+  try {
+    const { searchParams } = new URL(req.url);
+    const rawPath = searchParams.get("path") || undefined;
+    const path = rawPath ? normalizePath(rawPath) : undefined;
+
+    const page = Math.max(1, Number(searchParams.get("page") || "1") || 1);
+    const perPage = Math.min(100, Math.max(1, Number(searchParams.get("perPage") || "25") || 25));
+    const from = (page - 1) * perPage;
+
+    const result = await Sentry.startSpan(
+      { op: "function", name: "api.files.list" },
+      async (span) => {
+        if (path) span.setAttribute("path", path);
+
+        const entries = await nextcloud.listDirectory(path);
+        const files = entries
+          .filter((e) => !e.isDirectory)
+          .map((e) => ({
+            id: e.href,
+            name: e.name,
+            path: e.href,
+            parentPath: parentPath(e.href),
+            kind: "File" as const,
+            sizeBytes: e.size ?? 0,
+            mimeType: e.contentType ?? "application/octet-stream",
+            etag: e.etag,
+          }))
+          .sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" }));
+
+        const total = files.length;
+        const pageItems = files.slice(from, from + perPage);
+        return { total, page, perPage, items: pageItems };
+      },
+    );
+
+    return json(result);
+  } catch (error) {
+    Sentry.captureException(error);
+    return json(
+      {
+        error: "Failed to list files",
+        message: error instanceof Error ? error.message : String(error),
+      },
+      { status: 500 },
+    );
+  }
+}
--- a/src/app/api/files/upload/route.ts
+++ b/src/app/api/files/upload/route.ts
@ -0,0 +1,71 @@
+import * as Sentry from "@sentry/nextjs";
+import { NextResponse } from "next/server";
+import { nextcloud } from "@/lib/webdav";
+import { normalizePath, parentPath } from "@/lib/paths";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+function json<T>(data: T, init?: { status?: number } & ResponseInit) {
+  return NextResponse.json(data, init);
+}
+
+export async function POST(req: Request) {
+  try {
+    const ct = req.headers.get("content-type") || "";
+    if (!ct.includes("multipart/form-data")) {
+      return json({ error: "Expected multipart/form-data" }, { status: 400 });
+    }
+
+    const form = await req.formData();
+    const file = form.get("file");
+    const rawDest = form.get("destPath");
+
+    if (!(file instanceof File)) {
+      return json({ error: "Missing file" }, { status: 400 });
+    }
+    if (typeof rawDest !== "string" || !rawDest) {
+      return json({ error: "Missing destPath" }, { status: 400 });
+    }
+    const destPath = normalizePath(rawDest);
+
+    const result = await Sentry.startSpan(
+      { op: "function", name: "api.files.upload" },
+      async (span) => {
+        span.setAttribute("path", destPath);
+        span.setAttribute("size", file.size);
+        span.setAttribute("filename", file.name);
+        if (file.type) span.setAttribute("mimeType", file.type);
+
+        const upload = await nextcloud.uploadFile(destPath, file, file.type || undefined);
+
+        return {
+          ok: upload.ok,
+          etag: upload.etag,
+          size: upload.size ?? file.size,
+          item: {
+            id: destPath,
+            name: file.name,
+            path: destPath,
+            parentPath: parentPath(destPath),
+            kind: "File" as const,
+            sizeBytes: upload.size ?? file.size,
+            mimeType: file.type || "application/octet-stream",
+            etag: upload.etag,
+          },
+        };
+      },
+    );
+
+    return json(result, { status: result.ok ? 200 : 500 });
+  } catch (error) {
+    Sentry.captureException(error);
+    return json(
+      {
+        error: "Failed to upload file",
+        message: error instanceof Error ? error.message : String(error),
+      },
+      { status: 500 },
+    );
+  }
+}
--- a/src/app/api/folders/create/route.ts
+++ b/src/app/api/folders/create/route.ts
@ -0,0 +1,42 @@
+import * as Sentry from "@sentry/nextjs";
+import { NextResponse } from "next/server";
+import { nextcloud } from "@/lib/webdav";
+import { normalizePath } from "@/lib/paths";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+function json<T>(data: T, init?: { status?: number } & ResponseInit) {
+  return NextResponse.json(data, init);
+}
+
+export async function POST(req: Request) {
+  try {
+    const body = await req.json().catch(() => ({} as Record<string, unknown>));
+    const rawPath = typeof body?.path === "string" ? body.path : "";
+    if (!rawPath) {
+      return json({ error: "Path is required" }, { status: 400 });
+    }
+    const path = normalizePath(rawPath);
+
+    const result = await Sentry.startSpan(
+      { op: "function", name: "api.folders.create" },
+      async (span) => {
+        span.setAttribute("path", path);
+        const res = await nextcloud.createFolder(path);
+        return res;
+      },
+    );
+
+    return json(result);
+  } catch (error) {
+    Sentry.captureException(error);
+    return json(
+      {
+        error: "Failed to create folder",
+        message: error instanceof Error ? error.message : String(error),
+      },
+      { status: 500 },
+    );
+  }
+}
--- a/src/app/api/folders/list/route.ts
+++ b/src/app/api/folders/list/route.ts
@ -0,0 +1,68 @@
+import * as Sentry from "@sentry/nextjs";
+import { NextResponse } from "next/server";
+import { nextcloud } from "@/lib/webdav";
+import { normalizePath, parentPath } from "@/lib/paths";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+function json<T>(data: T, init?: { status?: number } & ResponseInit) {
+  return NextResponse.json(data, init);
+}
+
+export async function GET(req: Request) {
+  try {
+    const { searchParams } = new URL(req.url);
+    const rawPath = searchParams.get("path") || undefined;
+    const path = rawPath ? normalizePath(rawPath) : undefined;
+
+    const span = Sentry.startSpan(
+      { op: "function", name: "api.folders.list" },
+      async (span) => {
+        if (path) {
+          span.setAttribute("path", path);
+        }
+        const entries = await nextcloud.listDirectory(path);
+        // Provide folder meta and a basic partition for folders vs files
+        const folders = entries
+          .filter((e) => e.isDirectory)
+          .map((e) => ({
+            id: e.href,
+            name: e.name,
+            path: e.href,
+            parentPath: parentPath(e.href),
+            kind: "Folder" as const,
+            etag: e.etag,
+            childrenLoaded: false,
+          }));
+
+        const files = entries
+          .filter((e) => !e.isDirectory)
+          .map((e) => ({
+            id: e.href,
+            name: e.name,
+            path: e.href,
+            parentPath: parentPath(e.href),
+            kind: "File" as const,
+            sizeBytes: e.size ?? 0,
+            mimeType: e.contentType ?? "application/octet-stream",
+            etag: e.etag,
+          }));
+
+        return { folders, files };
+      },
+    );
+
+    const result = await span;
+    return json(result);
+  } catch (error) {
+    Sentry.captureException(error);
+    return json(
+      {
+        error: "Failed to list directory",
+        message: error instanceof Error ? error.message : String(error),
+      },
+      { status: 500 },
+    );
+  }
+}
--- a/src/app/api/search/query/route.ts
+++ b/src/app/api/search/query/route.ts
@ -0,0 +1,59 @@
+import * as Sentry from "@sentry/nextjs";
+import { NextResponse } from "next/server";
+import type { SearchQuery } from "@/types/search";
+import { bm25Search, hybridSearch } from "@/lib/elasticsearch";
+import { embeddingsEnabled } from "@/lib/env";
+import { getEmbeddingForText } from "@/lib/embeddings";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+function json<T>(data: T, init?: { status?: number } & ResponseInit) {
+  return NextResponse.json(data, init);
+}
+
+export async function POST(req: Request) {
+  try {
+    const body = (await req.json().catch(() => ({}))) as Partial<SearchQuery>;
+
+    const q = typeof body.q === "string" ? body.q.trim() : "";
+    if (!q) return json({ error: "q is required" }, { status: 400 });
+
+    const filters = body.filters ?? {};
+    const sort = body.sort;
+    const page = body.page ?? 1;
+    const perPage = body.perPage ?? 25;
+    const semantic = !!body.semantic;
+
+    const result = await Sentry.startSpan(
+      { op: "function", name: "api.search.query" },
+      async (span) => {
+        span.setAttribute("q.length", q.length);
+        span.setAttribute("semantic", semantic);
+        span.setAttribute("page", page);
+        span.setAttribute("perPage", perPage);
+
+        if (semantic && embeddingsEnabled) {
+          // Compute query vector and run hybrid search
+          const vector = await getEmbeddingForText(q);
+          return hybridSearch(q, vector, filters, { page, perPage, sort, alpha: 0.6 });
+        }
+
+        // Fallback: pure BM25
+        return bm25Search(q, filters, { page, perPage, sort });
+      },
+    );
+
+    const data = await result;
+    return json(data);
+  } catch (error) {
+    Sentry.captureException(error);
+    return json(
+      {
+        error: "Search failed",
+        message: error instanceof Error ? error.message : String(error),
+      },
+      { status: 500 },
+    );
+  }
+}
--- a/src/app/globals.css
+++ b/src/app/globals.css
@ -1,26 +1,122 @@
@import "tailwindcss";
+@import "tw-animate-css";

-:root {
-  --background: #ffffff;
-  --foreground: #171717;
-}
+@custom-variant dark (&:is(.dark *));

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --font-sans: var(--font-geist-sans);
  --font-mono: var(--font-geist-mono);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-chart-5: var(--chart-5);
+  --color-chart-4: var(--chart-4);
+  --color-chart-3: var(--chart-3);
+  --color-chart-2: var(--chart-2);
+  --color-chart-1: var(--chart-1);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-border: var(--border);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-muted: var(--muted);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --color-card: var(--card);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
 }

-@media (prefers-color-scheme: dark) {
-  :root {
-    --background: #0a0a0a;
-    --foreground: #ededed;
+:root {
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.129 0.042 264.695);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.129 0.042 264.695);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.129 0.042 264.695);
+  --primary: oklch(0.208 0.042 265.755);
+  --primary-foreground: oklch(0.984 0.003 247.858);
+  --secondary: oklch(0.968 0.007 247.896);
+  --secondary-foreground: oklch(0.208 0.042 265.755);
+  --muted: oklch(0.968 0.007 247.896);
+  --muted-foreground: oklch(0.554 0.046 257.417);
+  --accent: oklch(0.968 0.007 247.896);
+  --accent-foreground: oklch(0.208 0.042 265.755);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.929 0.013 255.508);
+  --input: oklch(0.929 0.013 255.508);
+  --ring: oklch(0.704 0.04 256.788);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --sidebar: oklch(0.984 0.003 247.858);
+  --sidebar-foreground: oklch(0.129 0.042 264.695);
+  --sidebar-primary: oklch(0.208 0.042 265.755);
+  --sidebar-primary-foreground: oklch(0.984 0.003 247.858);
+  --sidebar-accent: oklch(0.968 0.007 247.896);
+  --sidebar-accent-foreground: oklch(0.208 0.042 265.755);
+  --sidebar-border: oklch(0.929 0.013 255.508);
+  --sidebar-ring: oklch(0.704 0.04 256.788);
+}
+
+.dark {
+  --background: oklch(0.129 0.042 264.695);
+  --foreground: oklch(0.984 0.003 247.858);
+  --card: oklch(0.208 0.042 265.755);
+  --card-foreground: oklch(0.984 0.003 247.858);
+  --popover: oklch(0.208 0.042 265.755);
+  --popover-foreground: oklch(0.984 0.003 247.858);
+  --primary: oklch(0.929 0.013 255.508);
+  --primary-foreground: oklch(0.208 0.042 265.755);
+  --secondary: oklch(0.279 0.041 260.031);
+  --secondary-foreground: oklch(0.984 0.003 247.858);
+  --muted: oklch(0.279 0.041 260.031);
+  --muted-foreground: oklch(0.704 0.04 256.788);
+  --accent: oklch(0.279 0.041 260.031);
+  --accent-foreground: oklch(0.984 0.003 247.858);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.551 0.027 264.364);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+  --sidebar: oklch(0.208 0.042 265.755);
+  --sidebar-foreground: oklch(0.984 0.003 247.858);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.984 0.003 247.858);
+  --sidebar-accent: oklch(0.279 0.041 260.031);
+  --sidebar-accent-foreground: oklch(0.984 0.003 247.858);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.551 0.027 264.364);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
  }
 }
-
-body {
-  background: var(--background);
-  color: var(--foreground);
-  font-family: Arial, Helvetica, sans-serif;
-}
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@ -1,6 +1,7 @@
 import type { Metadata } from "next";
 import { Geist, Geist_Mono } from "next/font/google";
 import "./globals.css";
+import { QueryProvider } from "@/components/providers/query-provider";

 const geistSans = Geist({
  variable: "--font-geist-sans",
@ -13,8 +14,8 @@ const geistMono = Geist_Mono({
 });

 export const metadata: Metadata = {
-  title: "Create Next App",
-  description: "Generated by create next app",
+  title: "Nextcloud Explorer",
+  description: "Discovery file explorer powered by Nextcloud + Elasticsearch",
 };

 export default function RootLayout({
@ -24,10 +25,8 @@ export default function RootLayout({
 }>) {
  return (
    <html lang="en">
-      <body
-        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
-      >
-        {children}
+      <body className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
+        <QueryProvider>{children}</QueryProvider>
      </body>
    </html>
  );
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@ -1,103 +1,189 @@
-import Image from "next/image";
+"use client";
+
+import * as React from "react";
+import { SidebarTree } from "@/components/sidebar/sidebar-tree";
+import { Breadcrumbs } from "@/components/navigation/breadcrumbs";
+import { FileTable, type FileRow } from "@/components/files/file-table";
+import { UploadDialog } from "@/components/files/upload-dialog";
+import { Input } from "@/components/ui/input";
+import { Button } from "@/components/ui/button";
+import { useQuery } from "@tanstack/react-query";
+import { Checkbox } from "@/components/ui/checkbox";
+
+type FilesListResponse = {
+  total: number;
+  page: number;
+  perPage: number;
+  items: Array<{
+    id: string;
+    name: string;
+    path: string;
+    parentPath?: string;
+    kind: "File";
+    sizeBytes: number;
+    mimeType: string;
+    etag?: string;
+  }>;
+};
+
+type SearchResult = {
+  total: number;
+  tookMs: number;
+  hits: Array<{
+    score: number;
+    bm25Score?: number;
+    vectorScore?: number;
+    doc: {
+      id: string;
+      name: string;
+      path: string;
+      parentPath?: string;
+      sizeBytes: number;
+      mimeType: string;
+      etag?: string;
+    };
+  }>;
+};
+
+async function fetchFiles(path?: string, page = 1, perPage = 50) {
+  const url = new URL("/api/files/list", window.location.origin);
+  if (path) url.searchParams.set("path", path);
+  url.searchParams.set("page", String(page));
+  url.searchParams.set("perPage", String(perPage));
+  const res = await fetch(url.toString(), { cache: "no-store" });
+  if (!res.ok) throw new Error(`Failed to load files: ${res.status}`);
+  const data = (await res.json()) as FilesListResponse;
+  return data;
+}
+
+async function executeSearch(q: string, semantic: boolean, page: number, perPage: number) {
+  const res = await fetch("/api/search/query", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ q, semantic, page, perPage }),
+  });
+  if (!res.ok) throw new Error(`Search failed: ${res.status}`);
+  const data = (await res.json()) as SearchResult;
+  return data;
+}

 export default function Home() {
-  return (
-    <div className="font-sans grid grid-rows-[20px_1fr_20px] items-center justify-items-center min-h-screen p-8 pb-20 gap-16 sm:p-20">
-      <main className="flex flex-col gap-[32px] row-start-2 items-center sm:items-start">
-        <Image
-          className="dark:invert"
-          src="/next.svg"
-          alt="Next.js logo"
-          width={180}
-          height={38}
-          priority
-        />
-        <ol className="font-mono list-inside list-decimal text-sm/6 text-center sm:text-left">
-          <li className="mb-2 tracking-[-.01em]">
-            Get started by editing{" "}
-            <code className="bg-black/[.05] dark:bg-white/[.06] font-mono font-semibold px-1 py-0.5 rounded">
-              src/app/page.tsx
-            </code>
-            .
-          </li>
-          <li className="tracking-[-.01em]">
-            Save and see your changes instantly.
-          </li>
-        </ol>
+  const [path, setPath] = React.useState<string | undefined>(undefined);
+  const [page, setPage] = React.useState(1);
+  const [perPage] = React.useState(50);

-        <div className="flex gap-4 items-center flex-col sm:flex-row">
-          <a
-            className="rounded-full border border-solid border-transparent transition-colors flex items-center justify-center bg-foreground text-background gap-2 hover:bg-[#383838] dark:hover:bg-[#ccc] font-medium text-sm sm:text-base h-10 sm:h-12 px-4 sm:px-5 sm:w-auto"
-            href="https://vercel.com/new?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
-            target="_blank"
-            rel="noopener noreferrer"
-          >
-            <Image
-              className="dark:invert"
-              src="/vercel.svg"
-              alt="Vercel logomark"
-              width={20}
-              height={20}
+  const [q, setQ] = React.useState("");
+  const [semantic, setSemantic] = React.useState(false);
+  const searching = q.trim().length > 0;
+
+  const filesQuery = useQuery({
+    queryKey: ["files", path, page, perPage],
+    queryFn: () => fetchFiles(path, page, perPage),
+    enabled: !searching,
+  });
+
+  const searchQuery = useQuery({
+    queryKey: ["search", q, semantic, page, perPage],
+    queryFn: () => executeSearch(q.trim(), semantic, page, perPage),
+    enabled: searching,
+  });
+
+  const files: FileRow[] = React.useMemo(() => {
+    if (searching) {
+      const hits = searchQuery.data?.hits ?? [];
+      return hits.map((h) => ({
+        id: h.doc.id,
+        name: h.doc.name,
+        path: h.doc.path,
+        parentPath: h.doc.parentPath,
+        sizeBytes: h.doc.sizeBytes,
+        mimeType: h.doc.mimeType,
+        etag: h.doc.etag,
+      }));
+    }
+    const items = filesQuery.data?.items ?? [];
+    return items.map((it) => ({
+      id: it.id,
+      name: it.name,
+      path: it.path,
+      parentPath: it.parentPath,
+      sizeBytes: it.sizeBytes,
+      mimeType: it.mimeType,
+      etag: it.etag,
+    }));
+  }, [filesQuery.data, searchQuery.data, searching]);
+
+  function handleDownload(item: FileRow) {
+    const url = new URL("/api/files/download", window.location.origin);
+    url.searchParams.set("path", item.path);
+    // open in a new tab to trigger save/open dialog
+    window.open(url.toString(), "_blank", "noopener,noreferrer");
+  }
+
+  function handleOpen(item: FileRow) {
+    // Placeholder for preview behavior; for now, download
+    handleDownload(item);
+  }
+
+  function handleUploaded() {
+    if (!searching) {
+      filesQuery.refetch();
+    }
+  }
+
+  return (
+    <div className="h-screen grid grid-cols-[280px_1fr]">
+      {/* Sidebar */}
+      <aside className="border-r h-full">
+        <SidebarTree path={path} onNavigate={(p) => { setPage(1); setPath(p); }} />
+      </aside>
+
+      {/* Main content */}
+      <main className="h-full flex flex-col">
+        <header className="border-b p-3 flex items-center gap-3">
+          <Breadcrumbs path={path} onNavigate={(p) => { setPage(1); setPath(p); }} />
+        </header>
+
+        <section className="p-3 flex items-center gap-2 border-b">
+          <div className="flex items-center gap-2 w-full">
+            <Input
+              placeholder="Search files..."
+              value={q}
+              onChange={(e) => { setPage(1); setQ(e.target.value); }}
            />
-            Deploy now
-          </a>
-          <a
-            className="rounded-full border border-solid border-black/[.08] dark:border-white/[.145] transition-colors flex items-center justify-center hover:bg-[#f2f2f2] dark:hover:bg-[#1a1a1a] hover:border-transparent font-medium text-sm sm:text-base h-10 sm:h-12 px-4 sm:px-5 w-full sm:w-auto md:w-[158px]"
-            href="https://nextjs.org/docs?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
-            target="_blank"
-            rel="noopener noreferrer"
-          >
-            Read our docs
-          </a>
-        </div>
+            <div className="flex items-center gap-2 px-2">
+              <Checkbox
+                id="semantic"
+                checked={semantic}
+                onCheckedChange={(v: boolean) => setSemantic(Boolean(v))}
+              />
+              <label htmlFor="semantic" className="text-sm">Semantic</label>
+            </div>
+            <Button
+              variant="secondary"
+              onClick={() => {
+                // Force refetch for the active mode
+                if (searching) searchQuery.refetch();
+                else filesQuery.refetch();
+              }}
+            >
+              Refresh
+            </Button>
+          </div>
+          <UploadDialog currentPath={path} onUploaded={handleUploaded} />
+        </section>
+
+        <section className="p-3 flex-1 overflow-auto">
+          {searching ? (
+            <div className="text-xs text-muted-foreground mb-2">
+              {searchQuery.isLoading
+                ? "Searching…"
+                : `Found ${searchQuery.data?.total ?? 0} in ${searchQuery.data?.tookMs ?? 0}ms`}
+            </div>
+          ) : null}
+          <FileTable items={files} onOpen={handleOpen} onDownload={handleDownload} />
+        </section>
      </main>
-      <footer className="row-start-3 flex gap-[24px] flex-wrap items-center justify-center">
-        <a
-          className="flex items-center gap-2 hover:underline hover:underline-offset-4"
-          href="https://nextjs.org/learn?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
-          target="_blank"
-          rel="noopener noreferrer"
-        >
-          <Image
-            aria-hidden
-            src="/file.svg"
-            alt="File icon"
-            width={16}
-            height={16}
-          />
-          Learn
-        </a>
-        <a
-          className="flex items-center gap-2 hover:underline hover:underline-offset-4"
-          href="https://vercel.com/templates?framework=next.js&utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
-          target="_blank"
-          rel="noopener noreferrer"
-        >
-          <Image
-            aria-hidden
-            src="/window.svg"
-            alt="Window icon"
-            width={16}
-            height={16}
-          />
-          Examples
-        </a>
-        <a
-          className="flex items-center gap-2 hover:underline hover:underline-offset-4"
-          href="https://nextjs.org?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
-          target="_blank"
-          rel="noopener noreferrer"
-        >
-          <Image
-            aria-hidden
-            src="/globe.svg"
-            alt="Globe icon"
-            width={16}
-            height={16}
-          />
-          Go to nextjs.org →
-        </a>
-      </footer>
    </div>
  );
 }
--- a/src/components/files/file-table.tsx
+++ b/src/components/files/file-table.tsx
@ -0,0 +1,84 @@
+"use client";
+
+import * as React from "react";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
+import { Button } from "@/components/ui/button";
+import { Download } from "lucide-react";
+
+export interface FileRow {
+  id: string;
+  name: string;
+  path: string;
+  parentPath?: string;
+  sizeBytes: number;
+  mimeType: string;
+  etag?: string;
+}
+
+function formatBytes(bytes?: number) {
+  const b = bytes ?? 0;
+  if (b === 0) return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(b) / Math.log(k));
+  return `${parseFloat((b / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
+}
+
+export function FileTable({
+  items,
+  onOpen,
+  onDownload,
+}: {
+  items: FileRow[];
+  onOpen?: (item: FileRow) => void;
+  onDownload?: (item: FileRow) => void;
+}) {
+  return (
+    <div className="rounded-md border">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead className="w-[40%]">Name</TableHead>
+            <TableHead className="hidden sm:table-cell">Type</TableHead>
+            <TableHead className="hidden sm:table-cell text-right">Size</TableHead>
+            <TableHead className="text-right">Actions</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {items.map((it) => (
+            <TableRow key={it.id}>
+              <TableCell className="font-medium">
+                <button
+                  className="text-left hover:underline"
+                  onClick={() => onOpen?.(it)}
+                  title={it.path}
+                >
+                  {it.name}
+                </button>
+              </TableCell>
+              <TableCell className="hidden sm:table-cell">{it.mimeType}</TableCell>
+              <TableCell className="hidden sm:table-cell text-right">{formatBytes(it.sizeBytes)}</TableCell>
+              <TableCell className="text-right">
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  onClick={() => onDownload?.(it)}
+                  title="Download"
+                >
+                  <Download className="h-4 w-4" />
+                </Button>
+              </TableCell>
+            </TableRow>
+          ))}
+          {items.length === 0 && (
+            <TableRow>
+              <TableCell colSpan={4} className="text-center text-muted-foreground">
+                No files
+              </TableCell>
+            </TableRow>
+          )}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}
--- a/src/components/files/upload-dialog.tsx
+++ b/src/components/files/upload-dialog.tsx
@ -0,0 +1,85 @@
+"use client";
+
+import * as React from "react";
+import { Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { toast } from "sonner";
+
+export function UploadDialog({
+  currentPath,
+  onUploaded,
+}: {
+  currentPath?: string;
+  onUploaded?: () => void;
+}) {
+  const [open, setOpen] = React.useState(false);
+  const [file, setFile] = React.useState<File | null>(null);
+  const [submitting, setSubmitting] = React.useState(false);
+
+  async function handleUpload() {
+    if (!file) {
+      toast.error("Choose a file first");
+      return;
+    }
+    try {
+      setSubmitting(true);
+      const fd = new FormData();
+      fd.set("file", file);
+      // Upload to the current folder; include filename in dest path
+      const dest = `${currentPath ?? ""}/${file.name}`.replace(/\/+/g, "/");
+      fd.set("destPath", dest);
+
+      const res = await fetch("/api/files/upload", {
+        method: "POST",
+        body: fd,
+      });
+
+      if (!res.ok) {
+        const payload = await res.json().catch(() => ({}));
+        throw new Error(payload?.message || `Upload failed (${res.status})`);
+      }
+
+      toast.success(`Uploaded ${file.name}`);
+      setOpen(false);
+      setFile(null);
+      onUploaded?.();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      toast.error(message);
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={(v) => !submitting && setOpen(v)}>
+      <DialogTrigger asChild>
+        <Button variant="default" size="sm">Upload</Button>
+      </DialogTrigger>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>Upload file</DialogTitle>
+        </DialogHeader>
+        <div className="py-2">
+          <Input
+            type="file"
+            onChange={(e) => setFile(e.target.files?.[0] ?? null)}
+            disabled={submitting}
+          />
+          <div className="text-xs text-muted-foreground mt-2">
+            Destination: <code>{currentPath || "/"}</code>
+          </div>
+        </div>
+        <DialogFooter>
+          <Button variant="outline" onClick={() => setOpen(false)} disabled={submitting}>
+            Cancel
+          </Button>
+          <Button onClick={handleUpload} disabled={submitting || !file}>
+            {submitting ? "Uploading..." : "Upload"}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
--- a/src/components/navigation/breadcrumbs.tsx
+++ b/src/components/navigation/breadcrumbs.tsx
@ -0,0 +1,60 @@
+"use client";
+
+import React from "react";
+import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbSeparator } from "@/components/ui/breadcrumb";
+
+function segmentsFromPath(path?: string): { label: string; path: string }[] {
+  if (!path) return [];
+  const parts = path.split("/").filter(Boolean);
+  const segs: { label: string; path: string }[] = [];
+  let acc = "";
+  for (const p of parts) {
+    acc += `/${p}`;
+    segs.push({ label: p, path: acc });
+  }
+  return segs;
+}
+
+export function Breadcrumbs({
+  path,
+  onNavigate,
+}: {
+  path?: string;
+  onNavigate: (p?: string) => void;
+}) {
+  const segs = segmentsFromPath(path);
+
+  return (
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink
+            href="#"
+            onClick={(e) => {
+              e.preventDefault();
+              onNavigate(undefined);
+            }}
+          >
+            Root
+          </BreadcrumbLink>
+        </BreadcrumbItem>
+        {segs.map((s, idx) => (
+          <React.Fragment key={s.path}>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem>
+              <BreadcrumbLink
+                href="#"
+                onClick={(e) => {
+                  e.preventDefault();
+                  onNavigate(s.path);
+                }}
+              >
+                {s.label}
+              </BreadcrumbLink>
+            </BreadcrumbItem>
+          </React.Fragment>
+        ))}
+      </BreadcrumbList>
+    </Breadcrumb>
+  );
+}
--- a/src/components/providers/query-provider.tsx
+++ b/src/components/providers/query-provider.tsx
@ -0,0 +1,31 @@
+"use client";
+
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { Toaster } from "@/components/ui/sonner";
+
+let client: QueryClient | null = null;
+
+function getClient() {
+  if (!client) {
+    client = new QueryClient({
+      defaultOptions: {
+        queries: {
+          refetchOnWindowFocus: false,
+          retry: 2,
+        },
+      },
+    });
+  }
+  return client;
+}
+
+export function QueryProvider({ children }: { children: React.ReactNode }) {
+  const qc = React.useMemo(() => getClient(), []);
+  return (
+    <QueryClientProvider client={qc}>
+      {children}
+      <Toaster richColors />
+    </QueryClientProvider>
+  );
+}
--- a/src/components/sidebar/sidebar-tree.tsx
+++ b/src/components/sidebar/sidebar-tree.tsx
@ -0,0 +1,89 @@
+"use client";
+
+import * as React from "react";
+import { useQuery } from "@tanstack/react-query";
+import { ScrollArea } from "@/components/ui/scroll-area";
+import { Button } from "@/components/ui/button";
+import { ChevronRight, Folder } from "lucide-react";
+
+type FolderItem = {
+  id: string;
+  name: string;
+  path: string;
+  parentPath?: string;
+  kind: "Folder";
+  etag?: string;
+  childrenLoaded: boolean;
+};
+
+async function fetchFolders(path?: string) {
+  const url = new URL("/api/folders/list", window.location.origin);
+  if (path) url.searchParams.set("path", path);
+  const res = await fetch(url.toString(), { cache: "no-store" });
+  if (!res.ok) throw new Error(`Failed to load folders: ${res.status}`);
+  const data = (await res.json()) as { folders: FolderItem[]; files: unknown[] };
+  return data.folders;
+}
+
+export function SidebarTree({
+  path,
+  onNavigate,
+}: {
+  path?: string;
+  onNavigate: (p?: string) => void;
+}) {
+  const { data, isLoading, error, refetch } = useQuery({
+    queryKey: ["folders", path ?? "__root__"],
+    queryFn: () => fetchFolders(path),
+  });
+
+  const items = data ?? [];
+
+  return (
+    <div className="h-full flex flex-col">
+      <div className="p-2">
+        <div className="text-sm font-semibold">Folders</div>
+      </div>
+      <ScrollArea className="flex-1">
+        <div className="px-2 py-1 space-y-1">
+          <Button
+            variant={path ? "ghost" : "secondary"}
+            size="sm"
+            className="w-full justify-start"
+            onClick={() => onNavigate(undefined)}
+          >
+            <Folder className="h-4 w-4 mr-2" />
+            Root
+          </Button>
+          {isLoading && (
+            <div className="text-xs text-muted-foreground px-2 py-1">Loading…</div>
+          )}
+          {error && (
+            <div className="text-xs text-destructive px-2 py-1">
+              {(error as Error).message}
+            </div>
+          )}
+          {items.map((f) => (
+            <Button
+              key={f.id}
+              variant={path === f.path ? "secondary" : "ghost"}
+              size="sm"
+              className="w-full justify-between"
+              onClick={() => onNavigate(f.path)}
+              title={f.path}
+            >
+              <span className="truncate flex items-center">
+                <Folder className="h-4 w-4 mr-2" />
+                {f.name}
+              </span>
+              <ChevronRight className="h-4 w-4 opacity-60" />
+            </Button>
+          ))}
+          {items.length === 0 && !isLoading && !error && (
+            <div className="text-xs text-muted-foreground px-2 py-1">No folders</div>
+          )}
+        </div>
+      </ScrollArea>
+    </div>
+  );
+}
--- a/src/components/ui/badge.tsx
+++ b/src/components/ui/badge.tsx
@ -0,0 +1,46 @@
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const badgeVariants = cva(
+  "inline-flex items-center justify-center rounded-md border px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden",
+  {
+    variants: {
+      variant: {
+        default:
+          "border-transparent bg-primary text-primary-foreground [a&]:hover:bg-primary/90",
+        secondary:
+          "border-transparent bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90",
+        destructive:
+          "border-transparent bg-destructive text-white [a&]:hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
+        outline:
+          "text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+function Badge({
+  className,
+  variant,
+  asChild = false,
+  ...props
+}: React.ComponentProps<"span"> &
+  VariantProps<typeof badgeVariants> & { asChild?: boolean }) {
+  const Comp = asChild ? Slot : "span"
+
+  return (
+    <Comp
+      data-slot="badge"
+      className={cn(badgeVariants({ variant }), className)}
+      {...props}
+    />
+  )
+}
+
+export { Badge, badgeVariants }
--- a/src/components/ui/breadcrumb.tsx
+++ b/src/components/ui/breadcrumb.tsx
@ -0,0 +1,109 @@
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { ChevronRight, MoreHorizontal } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+
+function Breadcrumb({ ...props }: React.ComponentProps<"nav">) {
+  return <nav aria-label="breadcrumb" data-slot="breadcrumb" {...props} />
+}
+
+function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">) {
+  return (
+    <ol
+      data-slot="breadcrumb-list"
+      className={cn(
+        "text-muted-foreground flex flex-wrap items-center gap-1.5 text-sm break-words sm:gap-2.5",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function BreadcrumbItem({ className, ...props }: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="breadcrumb-item"
+      className={cn("inline-flex items-center gap-1.5", className)}
+      {...props}
+    />
+  )
+}
+
+function BreadcrumbLink({
+  asChild,
+  className,
+  ...props
+}: React.ComponentProps<"a"> & {
+  asChild?: boolean
+}) {
+  const Comp = asChild ? Slot : "a"
+
+  return (
+    <Comp
+      data-slot="breadcrumb-link"
+      className={cn("hover:text-foreground transition-colors", className)}
+      {...props}
+    />
+  )
+}
+
+function BreadcrumbPage({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="breadcrumb-page"
+      role="link"
+      aria-disabled="true"
+      aria-current="page"
+      className={cn("text-foreground font-normal", className)}
+      {...props}
+    />
+  )
+}
+
+function BreadcrumbSeparator({
+  children,
+  className,
+  ...props
+}: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="breadcrumb-separator"
+      role="presentation"
+      aria-hidden="true"
+      className={cn("[&>svg]:size-3.5", className)}
+      {...props}
+    >
+      {children ?? <ChevronRight />}
+    </li>
+  )
+}
+
+function BreadcrumbEllipsis({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="breadcrumb-ellipsis"
+      role="presentation"
+      aria-hidden="true"
+      className={cn("flex size-9 items-center justify-center", className)}
+      {...props}
+    >
+      <MoreHorizontal className="size-4" />
+      <span className="sr-only">More</span>
+    </span>
+  )
+}
+
+export {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+}
--- a/src/components/ui/button.tsx
+++ b/src/components/ui/button.tsx
@ -0,0 +1,59 @@
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+  {
+    variants: {
+      variant: {
+        default:
+          "bg-primary text-primary-foreground shadow-xs hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-white shadow-xs hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
+        outline:
+          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",
+        secondary:
+          "bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80",
+        ghost:
+          "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-9 px-4 py-2 has-[>svg]:px-3",
+        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",
+        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",
+        icon: "size-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+function Button({
+  className,
+  variant,
+  size,
+  asChild = false,
+  ...props
+}: React.ComponentProps<"button"> &
+  VariantProps<typeof buttonVariants> & {
+    asChild?: boolean
+  }) {
+  const Comp = asChild ? Slot : "button"
+
+  return (
+    <Comp
+      data-slot="button"
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  )
+}
+
+export { Button, buttonVariants }
--- a/src/components/ui/checkbox.tsx
+++ b/src/components/ui/checkbox.tsx
@ -0,0 +1,37 @@
+"use client";
+
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+type CheckboxProps = {
+  id?: string;
+  checked?: boolean;
+  defaultChecked?: boolean;
+  disabled?: boolean;
+  className?: string;
+  onCheckedChange?: (checked: boolean) => void;
+};
+
+export function Checkbox({
+  id,
+  checked,
+  defaultChecked,
+  disabled,
+  className,
+  onCheckedChange,
+}: CheckboxProps) {
+  return (
+    <input
+      id={id}
+      type="checkbox"
+      className={cn(
+        "h-4 w-4 rounded border border-input text-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+        className,
+      )}
+      checked={checked}
+      defaultChecked={defaultChecked}
+      disabled={disabled}
+      onChange={(e) => onCheckedChange?.(e.currentTarget.checked)}
+    />
+  );
+}
--- a/src/components/ui/dialog.tsx
+++ b/src/components/ui/dialog.tsx
@ -0,0 +1,143 @@
+"use client"
+
+import * as React from "react"
+import * as DialogPrimitive from "@radix-ui/react-dialog"
+import { XIcon } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+
+function Dialog({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Root>) {
+  return <DialogPrimitive.Root data-slot="dialog" {...props} />
+}
+
+function DialogTrigger({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Trigger>) {
+  return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />
+}
+
+function DialogPortal({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Portal>) {
+  return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />
+}
+
+function DialogClose({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Close>) {
+  return <DialogPrimitive.Close data-slot="dialog-close" {...props} />
+}
+
+function DialogOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Overlay>) {
+  return (
+    <DialogPrimitive.Overlay
+      data-slot="dialog-overlay"
+      className={cn(
+        "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DialogContent({
+  className,
+  children,
+  showCloseButton = true,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Content> & {
+  showCloseButton?: boolean
+}) {
+  return (
+    <DialogPortal data-slot="dialog-portal">
+      <DialogOverlay />
+      <DialogPrimitive.Content
+        data-slot="dialog-content"
+        className={cn(
+          "bg-background data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border p-6 shadow-lg duration-200 sm:max-w-lg",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        {showCloseButton && (
+          <DialogPrimitive.Close
+            data-slot="dialog-close"
+            className="ring-offset-background focus:ring-ring data-[state=open]:bg-accent data-[state=open]:text-muted-foreground absolute top-4 right-4 rounded-xs opacity-70 transition-opacity hover:opacity-100 focus:ring-2 focus:ring-offset-2 focus:outline-hidden disabled:pointer-events-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4"
+          >
+            <XIcon />
+            <span className="sr-only">Close</span>
+          </DialogPrimitive.Close>
+        )}
+      </DialogPrimitive.Content>
+    </DialogPortal>
+  )
+}
+
+function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="dialog-header"
+      className={cn("flex flex-col gap-2 text-center sm:text-left", className)}
+      {...props}
+    />
+  )
+}
+
+function DialogFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="dialog-footer"
+      className={cn(
+        "flex flex-col-reverse gap-2 sm:flex-row sm:justify-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DialogTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Title>) {
+  return (
+    <DialogPrimitive.Title
+      data-slot="dialog-title"
+      className={cn("text-lg leading-none font-semibold", className)}
+      {...props}
+    />
+  )
+}
+
+function DialogDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Description>) {
+  return (
+    <DialogPrimitive.Description
+      data-slot="dialog-description"
+      className={cn("text-muted-foreground text-sm", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+}
--- a/src/components/ui/dropdown-menu.tsx
+++ b/src/components/ui/dropdown-menu.tsx
@ -0,0 +1,257 @@
+"use client"
+
+import * as React from "react"
+import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu"
+import { CheckIcon, ChevronRightIcon, CircleIcon } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+
+function DropdownMenu({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Root>) {
+  return <DropdownMenuPrimitive.Root data-slot="dropdown-menu" {...props} />
+}
+
+function DropdownMenuPortal({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>) {
+  return (
+    <DropdownMenuPrimitive.Portal data-slot="dropdown-menu-portal" {...props} />
+  )
+}
+
+function DropdownMenuTrigger({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>) {
+  return (
+    <DropdownMenuPrimitive.Trigger
+      data-slot="dropdown-menu-trigger"
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuContent({
+  className,
+  sideOffset = 4,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
+  return (
+    <DropdownMenuPrimitive.Portal>
+      <DropdownMenuPrimitive.Content
+        data-slot="dropdown-menu-content"
+        sideOffset={sideOffset}
+        className={cn(
+          "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 max-h-(--radix-dropdown-menu-content-available-height) min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border p-1 shadow-md",
+          className
+        )}
+        {...props}
+      />
+    </DropdownMenuPrimitive.Portal>
+  )
+}
+
+function DropdownMenuGroup({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Group>) {
+  return (
+    <DropdownMenuPrimitive.Group data-slot="dropdown-menu-group" {...props} />
+  )
+}
+
+function DropdownMenuItem({
+  className,
+  inset,
+  variant = "default",
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
+  inset?: boolean
+  variant?: "default" | "destructive"
+}) {
+  return (
+    <DropdownMenuPrimitive.Item
+      data-slot="dropdown-menu-item"
+      data-inset={inset}
+      data-variant={variant}
+      className={cn(
+        "focus:bg-accent focus:text-accent-foreground data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 dark:data-[variant=destructive]:focus:bg-destructive/20 data-[variant=destructive]:focus:text-destructive data-[variant=destructive]:*:[svg]:!text-destructive [&_svg:not([class*='text-'])]:text-muted-foreground relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuCheckboxItem({
+  className,
+  children,
+  checked,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem>) {
+  return (
+    <DropdownMenuPrimitive.CheckboxItem
+      data-slot="dropdown-menu-checkbox-item"
+      className={cn(
+        "focus:bg-accent focus:text-accent-foreground relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      checked={checked}
+      {...props}
+    >
+      <span className="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center">
+        <DropdownMenuPrimitive.ItemIndicator>
+          <CheckIcon className="size-4" />
+        </DropdownMenuPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </DropdownMenuPrimitive.CheckboxItem>
+  )
+}
+
+function DropdownMenuRadioGroup({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>) {
+  return (
+    <DropdownMenuPrimitive.RadioGroup
+      data-slot="dropdown-menu-radio-group"
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuRadioItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem>) {
+  return (
+    <DropdownMenuPrimitive.RadioItem
+      data-slot="dropdown-menu-radio-item"
+      className={cn(
+        "focus:bg-accent focus:text-accent-foreground relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <span className="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center">
+        <DropdownMenuPrimitive.ItemIndicator>
+          <CircleIcon className="size-2 fill-current" />
+        </DropdownMenuPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </DropdownMenuPrimitive.RadioItem>
+  )
+}
+
+function DropdownMenuLabel({
+  className,
+  inset,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
+  inset?: boolean
+}) {
+  return (
+    <DropdownMenuPrimitive.Label
+      data-slot="dropdown-menu-label"
+      data-inset={inset}
+      className={cn(
+        "px-2 py-1.5 text-sm font-medium data-[inset]:pl-8",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>) {
+  return (
+    <DropdownMenuPrimitive.Separator
+      data-slot="dropdown-menu-separator"
+      className={cn("bg-border -mx-1 my-1 h-px", className)}
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuShortcut({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="dropdown-menu-shortcut"
+      className={cn(
+        "text-muted-foreground ml-auto text-xs tracking-widest",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuSub({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>) {
+  return <DropdownMenuPrimitive.Sub data-slot="dropdown-menu-sub" {...props} />
+}
+
+function DropdownMenuSubTrigger({
+  className,
+  inset,
+  children,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
+  inset?: boolean
+}) {
+  return (
+    <DropdownMenuPrimitive.SubTrigger
+      data-slot="dropdown-menu-sub-trigger"
+      data-inset={inset}
+      className={cn(
+        "focus:bg-accent focus:text-accent-foreground data-[state=open]:bg-accent data-[state=open]:text-accent-foreground flex cursor-default items-center rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[inset]:pl-8",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <ChevronRightIcon className="ml-auto size-4" />
+    </DropdownMenuPrimitive.SubTrigger>
+  )
+}
+
+function DropdownMenuSubContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>) {
+  return (
+    <DropdownMenuPrimitive.SubContent
+      data-slot="dropdown-menu-sub-content"
+      className={cn(
+        "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-md border p-1 shadow-lg",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  DropdownMenu,
+  DropdownMenuPortal,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuLabel,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+}
--- a/src/components/ui/input.tsx
+++ b/src/components/ui/input.tsx
@ -0,0 +1,21 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return (
+    <input
+      type={type}
+      data-slot="input"
+      className={cn(
+        "file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground dark:bg-input/30 border-input flex h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]",
+        "aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Input }
--- a/src/components/ui/progress.tsx
+++ b/src/components/ui/progress.tsx
@ -0,0 +1,31 @@
+"use client"
+
+import * as React from "react"
+import * as ProgressPrimitive from "@radix-ui/react-progress"
+
+import { cn } from "@/lib/utils"
+
+function Progress({
+  className,
+  value,
+  ...props
+}: React.ComponentProps<typeof ProgressPrimitive.Root>) {
+  return (
+    <ProgressPrimitive.Root
+      data-slot="progress"
+      className={cn(
+        "bg-primary/20 relative h-2 w-full overflow-hidden rounded-full",
+        className
+      )}
+      {...props}
+    >
+      <ProgressPrimitive.Indicator
+        data-slot="progress-indicator"
+        className="bg-primary h-full w-full flex-1 transition-all"
+        style={{ transform: `translateX(-${100 - (value || 0)}%)` }}
+      />
+    </ProgressPrimitive.Root>
+  )
+}
+
+export { Progress }
--- a/src/components/ui/scroll-area.tsx
+++ b/src/components/ui/scroll-area.tsx
@ -0,0 +1,58 @@
+"use client"
+
+import * as React from "react"
+import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area"
+
+import { cn } from "@/lib/utils"
+
+function ScrollArea({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof ScrollAreaPrimitive.Root>) {
+  return (
+    <ScrollAreaPrimitive.Root
+      data-slot="scroll-area"
+      className={cn("relative", className)}
+      {...props}
+    >
+      <ScrollAreaPrimitive.Viewport
+        data-slot="scroll-area-viewport"
+        className="focus-visible:ring-ring/50 size-full rounded-[inherit] transition-[color,box-shadow] outline-none focus-visible:ring-[3px] focus-visible:outline-1"
+      >
+        {children}
+      </ScrollAreaPrimitive.Viewport>
+      <ScrollBar />
+      <ScrollAreaPrimitive.Corner />
+    </ScrollAreaPrimitive.Root>
+  )
+}
+
+function ScrollBar({
+  className,
+  orientation = "vertical",
+  ...props
+}: React.ComponentProps<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>) {
+  return (
+    <ScrollAreaPrimitive.ScrollAreaScrollbar
+      data-slot="scroll-area-scrollbar"
+      orientation={orientation}
+      className={cn(
+        "flex touch-none p-px transition-colors select-none",
+        orientation === "vertical" &&
+          "h-full w-2.5 border-l border-l-transparent",
+        orientation === "horizontal" &&
+          "h-2.5 flex-col border-t border-t-transparent",
+        className
+      )}
+      {...props}
+    >
+      <ScrollAreaPrimitive.ScrollAreaThumb
+        data-slot="scroll-area-thumb"
+        className="bg-border relative flex-1 rounded-full"
+      />
+    </ScrollAreaPrimitive.ScrollAreaScrollbar>
+  )
+}
+
+export { ScrollArea, ScrollBar }
--- a/src/components/ui/sonner.tsx
+++ b/src/components/ui/sonner.tsx
@ -0,0 +1,25 @@
+"use client"
+
+import { useTheme } from "next-themes"
+import { Toaster as Sonner, ToasterProps } from "sonner"
+
+const Toaster = ({ ...props }: ToasterProps) => {
+  const { theme = "system" } = useTheme()
+
+  return (
+    <Sonner
+      theme={theme as ToasterProps["theme"]}
+      className="toaster group"
+      style={
+        {
+          "--normal-bg": "var(--popover)",
+          "--normal-text": "var(--popover-foreground)",
+          "--normal-border": "var(--border)",
+        } as React.CSSProperties
+      }
+      {...props}
+    />
+  )
+}
+
+export { Toaster }
--- a/src/components/ui/table.tsx
+++ b/src/components/ui/table.tsx
@ -0,0 +1,116 @@
+"use client"
+
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Table({ className, ...props }: React.ComponentProps<"table">) {
+  return (
+    <div
+      data-slot="table-container"
+      className="relative w-full overflow-x-auto"
+    >
+      <table
+        data-slot="table"
+        className={cn("w-full caption-bottom text-sm", className)}
+        {...props}
+      />
+    </div>
+  )
+}
+
+function TableHeader({ className, ...props }: React.ComponentProps<"thead">) {
+  return (
+    <thead
+      data-slot="table-header"
+      className={cn("[&_tr]:border-b", className)}
+      {...props}
+    />
+  )
+}
+
+function TableBody({ className, ...props }: React.ComponentProps<"tbody">) {
+  return (
+    <tbody
+      data-slot="table-body"
+      className={cn("[&_tr:last-child]:border-0", className)}
+      {...props}
+    />
+  )
+}
+
+function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">) {
+  return (
+    <tfoot
+      data-slot="table-footer"
+      className={cn(
+        "bg-muted/50 border-t font-medium [&>tr]:last:border-b-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableRow({ className, ...props }: React.ComponentProps<"tr">) {
+  return (
+    <tr
+      data-slot="table-row"
+      className={cn(
+        "hover:bg-muted/50 data-[state=selected]:bg-muted border-b transition-colors",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableHead({ className, ...props }: React.ComponentProps<"th">) {
+  return (
+    <th
+      data-slot="table-head"
+      className={cn(
+        "text-foreground h-10 px-2 text-left align-middle font-medium whitespace-nowrap [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[2px]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableCell({ className, ...props }: React.ComponentProps<"td">) {
+  return (
+    <td
+      data-slot="table-cell"
+      className={cn(
+        "p-2 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[2px]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableCaption({
+  className,
+  ...props
+}: React.ComponentProps<"caption">) {
+  return (
+    <caption
+      data-slot="table-caption"
+      className={cn("text-muted-foreground mt-4 text-sm", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableHead,
+  TableRow,
+  TableCell,
+  TableCaption,
+}
--- a/src/components/ui/tooltip.tsx
+++ b/src/components/ui/tooltip.tsx
@ -0,0 +1,61 @@
+"use client"
+
+import * as React from "react"
+import * as TooltipPrimitive from "@radix-ui/react-tooltip"
+
+import { cn } from "@/lib/utils"
+
+function TooltipProvider({
+  delayDuration = 0,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delayDuration={delayDuration}
+      {...props}
+    />
+  )
+}
+
+function Tooltip({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+  return (
+    <TooltipProvider>
+      <TooltipPrimitive.Root data-slot="tooltip" {...props} />
+    </TooltipProvider>
+  )
+}
+
+function TooltipTrigger({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
+}
+
+function TooltipContent({
+  className,
+  sideOffset = 0,
+  children,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        data-slot="tooltip-content"
+        sideOffset={sideOffset}
+        className={cn(
+          "bg-primary text-primary-foreground animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-fit origin-(--radix-tooltip-content-transform-origin) rounded-md px-3 py-1.5 text-xs text-balance",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <TooltipPrimitive.Arrow className="bg-primary fill-primary z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px]" />
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  )
+}
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }
--- a/src/lib/elasticsearch.ts
+++ b/src/lib/elasticsearch.ts
@ -0,0 +1,498 @@
+import * as Sentry from "@sentry/nextjs";
+import { Client } from "@elastic/elasticsearch";
+import type { estypes } from "@elastic/elasticsearch";
+import { env, getEsAuth, embeddingsEnabled } from "@/lib/env";
+import type { FacetFilters, SearchResult, SortMode } from "@/types/search";
+import type { IndexDocument } from "@/types/ingest";
+
+let _client: Client | null = null;
+
+type DocType = SearchResult["hits"][number]["doc"];
+
+export function getEsClient(): Client {
+  if (_client) return _client;
+  _client = new Client({
+    node: env.ELASTICSEARCH_URL,
+    auth: getEsAuth(),
+  });
+  return _client;
+}
+
+function filtersToBool(
+  filters?: FacetFilters,
+): {
+  must: estypes.QueryDslQueryContainer[];
+  filter: estypes.QueryDslQueryContainer[];
+  must_not: estypes.QueryDslQueryContainer[];
+  should: estypes.QueryDslQueryContainer[];
+} {
+  const must: estypes.QueryDslQueryContainer[] = [];
+  const filter: estypes.QueryDslQueryContainer[] = [];
+  const mustNot: estypes.QueryDslQueryContainer[] = [];
+  const should: estypes.QueryDslQueryContainer[] = [];
+
+  if (!filters) return { must, filter, must_not: mustNot, should };
+
+  if (filters.types && filters.types.length > 0) {
+    // Match mimeType prefix(es) like "image/" or full like "application/pdf"
+    const clauses: estypes.QueryDslQueryContainer[] = filters.types.map((t) =>
+      t.endsWith("/")
+        ? ({ prefix: { mimeType: t } } as estypes.QueryDslQueryContainer)
+        : ({ term: { mimeType: t } } as estypes.QueryDslQueryContainer),
+    );
+    filter.push(
+      {
+        bool: { should: clauses, minimum_should_match: 1 },
+      } as estypes.QueryDslQueryContainer,
+    );
+  }
+
+  if (filters.owner && filters.owner.length) {
+    filter.push({ terms: { owner: filters.owner } } as estypes.QueryDslQueryContainer);
+  }
+
+  if (filters.tags && filters.tags.length) {
+    filter.push({ terms: { tags: filters.tags } } as estypes.QueryDslQueryContainer);
+  }
+
+  if (filters.pathPrefix) {
+    // Use keyword field for exact prefix matching on path string
+    filter.push(
+      { prefix: { "path.keyword": filters.pathPrefix } } as estypes.QueryDslQueryContainer,
+    );
+  }
+
+  if (filters.sizeMinBytes != null || filters.sizeMaxBytes != null) {
+    const sizeRange: Record<string, number> = {};
+    if (filters.sizeMinBytes != null) sizeRange.gte = filters.sizeMinBytes;
+    if (filters.sizeMaxBytes != null) sizeRange.lte = filters.sizeMaxBytes;
+    filter.push(
+      { range: { sizeBytes: sizeRange } } as estypes.QueryDslQueryContainer,
+    );
+  }
+
+  if (filters.dateFrom || filters.dateTo) {
+    const dateRange: Record<string, string> = {};
+    if (filters.dateFrom) dateRange.gte = filters.dateFrom;
+    if (filters.dateTo) dateRange.lte = filters.dateTo;
+    // Prefer modifiedAt, fallback to uploadedAt if missing in docs at query time using should
+    should.push(
+      { range: { modifiedAt: dateRange } } as estypes.QueryDslQueryContainer,
+      { range: { uploadedAt: dateRange } } as estypes.QueryDslQueryContainer,
+    );
+  }
+
+  return { must, filter, must_not: mustNot, should };
+}
+
+function sortFromMode(sort: SortMode | undefined) {
+  if (!sort || sort === "relevance") return undefined;
+  if (sort === "modified") {
+    return [{ modifiedAt: { order: "desc" as const, unmapped_type: "date" as const } }];
+  }
+  if (sort === "size") {
+    return [{ sizeBytes: { order: "desc" as const, unmapped_type: "long" as const } }];
+  }
+  return undefined;
+}
+
+export async function ensureIndex(options?: { recreate?: boolean }) {
+  const span = Sentry.startSpan(
+    { op: "db.query", name: "ES ensureIndex" },
+    async () => {
+      const client = getEsClient();
+      const index = env.ELASTICSEARCH_INDEX;
+      const alias = env.ELASTICSEARCH_ALIAS;
+
+      const exists = await client.indices.exists({ index });
+
+      if (exists && options?.recreate) {
+        await client.indices.delete({ index });
+      }
+
+      if (!exists || options?.recreate) {
+        const dims = embeddingsEnabled ? env.EMBEDDING_DIM ?? 1536 : undefined;
+
+        const body: Record<string, unknown> = {
+          settings: {
+            index: {
+              knn: embeddingsEnabled ? true : undefined,
+            },
+            analysis: {
+              normalizer: {
+                lowercase_normalizer: {
+                  type: "custom",
+                  filter: ["lowercase"],
+                },
+              },
+            },
+          },
+          mappings: {
+            dynamic: "strict",
+            properties: {
+              id: { type: "keyword" },
+              name: {
+                type: "text",
+                fields: {
+                  keyword: { type: "keyword", ignore_above: 256 },
+                },
+              },
+              nickname: {
+                type: "text",
+                fields: {
+                  keyword: { type: "keyword", ignore_above: 256 },
+                },
+              },
+              title: {
+                type: "text",
+                fields: {
+                  keyword: { type: "keyword", ignore_above: 256 },
+                },
+              },
+              content: { type: "text" },
+              path: {
+                type: "keyword",
+                normalizer: "lowercase_normalizer",
+                fields: {
+                  text: { type: "text" },
+                },
+              },
+              parentPath: {
+                type: "keyword",
+                normalizer: "lowercase_normalizer",
+              },
+              sizeBytes: { type: "long" },
+              mimeType: { type: "keyword" },
+              owner: { type: "keyword" },
+              uploadedBy: { type: "keyword" },
+              uploadedAt: { type: "date" },
+              modifiedAt: { type: "date" },
+              tags: { type: "keyword" },
+              etag: { type: "keyword" },
+              previewAvailable: { type: "boolean" },
+              acl: {
+                properties: {
+                  principals: { type: "keyword" },
+                  public: { type: "boolean" },
+                },
+              },
+            },
+          },
+        };
+
+        if (embeddingsEnabled && dims) {
+          const mappings = (body as { mappings: { properties: Record<string, unknown> } }).mappings;
+          (mappings.properties as Record<string, unknown>).content_vector = {
+            type: "dense_vector",
+            dims,
+            index: true,
+            similarity: "cosine",
+          };
+          (mappings.properties as Record<string, unknown>).title_vector = {
+            type: "dense_vector",
+            dims,
+            index: true,
+            similarity: "cosine",
+          };
+        }
+
+        await client.indices.create({ index, body });
+
+        // Maintain alias pointing to current index
+        const aliasExists = await client.indices.existsAlias({ name: alias }).catch(() => false);
+        if (!aliasExists) {
+          await client.indices.putAlias({ index, name: alias });
+        } else {
+          // Point alias to this index (basic re-alias; no rollover strategy here)
+          const current = await client.indices
+            .getAlias({ name: alias })
+            .catch(() => ({} as estypes.IndicesGetAliasResponse));
+          const actions: NonNullable<estypes.IndicesUpdateAliasesRequest["actions"]> = [
+            { add: { index, alias } },
+          ];
+          for (const idx of Object.keys(current)) {
+            if (idx !== index) actions.push({ remove: { index: idx, alias } });
+          }
+          await client.indices.updateAliases({ actions });
+        }
+      }
+    },
+  );
+  await span;
+}
+
+export async function indexDocument(doc: IndexDocument): Promise<void> {
+  return Sentry.startSpan(
+    { op: "db.query", name: "ES indexDocument" },
+    async (span) => {
+      span.setAttribute("doc.id", doc.id);
+      span.setAttribute("index", env.ELASTICSEARCH_INDEX);
+      const client = getEsClient();
+      await client.index<Record<string, unknown>>({
+        index: env.ELASTICSEARCH_INDEX,
+        id: doc.id,
+        document: doc as unknown as Record<string, unknown>,
+        refresh: "wait_for",
+      });
+    },
+  );
+}
+
+export async function bulkIndex(docs: IndexDocument[]): Promise<void> {
+  if (!docs.length) return;
+  return Sentry.startSpan(
+    { op: "db.query", name: "ES bulkIndex" },
+    async (span) => {
+      span.setAttribute("count", docs.length);
+      const client = getEsClient();
+      const operations: (estypes.BulkOperationContainer | Record<string, unknown>)[] = docs.flatMap(
+        (doc) => [
+          { index: { _index: env.ELASTICSEARCH_INDEX, _id: doc.id } } as estypes.BulkOperationContainer,
+          doc as unknown as Record<string, unknown>,
+        ],
+      );
+      const res = await client.bulk({ operations, refresh: "wait_for" });
+      if ((res as estypes.BulkResponse).errors) {
+        const err = new Error("Bulk index encountered errors");
+        Sentry.captureException(err);
+        throw err;
+      }
+    },
+  );
+}
+
+function normalizeHits(
+  hits: Array<{ _id: string; _source: unknown; _score?: number }>,
+): { id: string; _source: unknown; _score: number }[] {
+  return hits.map((h) => ({
+    id: h._id,
+    _source: h._source,
+    _score: h._score ?? 0,
+  }));
+}
+
+function toSearchResult(
+  hits: { id: string; _source: unknown; _score: number }[],
+  total: number,
+  took: number,
+): SearchResult {
+  return {
+    total,
+    tookMs: took,
+    hits: hits.map((h) => {
+      const src = h._source as Record<string, unknown> & {
+        bm25Score?: number;
+        vectorScore?: number;
+      };
+      return {
+        // We store docs in the same shape as IndexDocument; API layer adapts to UI type.
+        doc: src as unknown as DocType,
+        score: h._score,
+        bm25Score: src.bm25Score,
+        vectorScore: src.vectorScore,
+      };
+    }),
+  };
+}
+
+export async function bm25Search(
+  q: string,
+  filters: FacetFilters = {},
+  opts: { page?: number; perPage?: number; sort?: SortMode } = {},
+): Promise<SearchResult> {
+  return Sentry.startSpan(
+    { op: "db.query", name: "ES bm25Search" },
+    async (span) => {
+      const client = getEsClient();
+      const page = Math.max(1, opts.page ?? 1);
+      const perPage = Math.min(100, Math.max(1, opts.perPage ?? 25));
+      const from = (page - 1) * perPage;
+
+      const bool = filtersToBool(filters);
+      const sort = sortFromMode(opts.sort);
+
+      const body: Record<string, unknown> = {
+        from,
+        size: perPage,
+        query: {
+          bool: {
+            ...bool,
+            must: [
+              ...(bool.must || []),
+              q
+                ? {
+                    multi_match: {
+                      query: q,
+                      type: "best_fields",
+                      fields: [
+                        "name^4",
+                        "nickname^3",
+                        "title^3",
+                        "tags^2",
+                        "content^1",
+                        "path.text^0.5",
+                      ],
+                      operator: "and",
+                      fuzziness: "AUTO",
+                    },
+                  }
+                : { match_all: {} },
+            ],
+          },
+        },
+        highlight: q
+          ? {
+              fields: {
+                name: {},
+                title: {},
+                content: {},
+              },
+            }
+          : undefined,
+        sort,
+      };
+
+      const res = await client.search({
+        index: env.ELASTICSEARCH_ALIAS || env.ELASTICSEARCH_INDEX,
+        body,
+      });
+
+      const total =
+        typeof res.hits.total === "number"
+          ? res.hits.total
+          : res.hits.total?.value ?? 0;
+      const hits = normalizeHits(
+        res.hits.hits as Array<{ _id: string; _source: unknown; _score?: number }>,
+      );
+      return toSearchResult(hits, total, res.took ?? 0);
+    },
+  );
+}
+
+export async function knnSearchEmbedding(
+  vector: number[],
+  opts: {
+    filters?: FacetFilters;
+    k?: number;
+    numCandidates?: number;
+  } = {},
+): Promise<SearchResult> {
+  if (!embeddingsEnabled) {
+    throw new Error("Embeddings are not enabled; cannot perform kNN search");
+  }
+
+  return Sentry.startSpan(
+    { op: "db.query", name: "ES knnSearchEmbedding" },
+    async (span) => {
+      const client = getEsClient();
+      const k = Math.min(200, Math.max(1, opts.k ?? 50));
+      const num_candidates = Math.max(k, Math.min(10000, opts.numCandidates ?? 1000));
+      const bool = filtersToBool(opts.filters);
+
+      const body: Record<string, unknown> = {
+        knn: {
+          field: "content_vector",
+          query_vector: vector,
+          k,
+          num_candidates,
+          filter: {
+            bool: {
+              filter: bool.filter,
+              must: bool.must,
+              must_not: bool.must_not,
+              should: bool.should,
+            },
+          },
+        },
+      };
+
+      const res = await client.search({
+        index: env.ELASTICSEARCH_ALIAS || env.ELASTICSEARCH_INDEX,
+        body,
+      });
+
+      const total =
+        typeof res.hits.total === "number"
+          ? res.hits.total
+          : res.hits.total?.value ?? 0;
+      const hits = normalizeHits(
+        res.hits.hits as Array<{ _id: string; _source: unknown; _score?: number }>,
+      ).map((h) => ({
+        ...h,
+        _source: { ...(h._source as Record<string, unknown>), vectorScore: h._score },
+      }));
+      return toSearchResult(hits, total, res.took ?? 0);
+    },
+  );
+}
+
+export async function hybridSearch(
+  q: string,
+  vector: number[] | undefined,
+  filters: FacetFilters = {},
+  opts: { page?: number; perPage?: number; sort?: SortMode; alpha?: number } = {},
+): Promise<SearchResult> {
+  const alpha = Math.max(0, Math.min(1, opts.alpha ?? 0.5));
+  const page = Math.max(1, opts.page ?? 1);
+  const perPage = Math.min(100, Math.max(1, opts.perPage ?? 25));
+
+  return Sentry.startSpan(
+    { op: "db.query", name: "ES hybridSearch" },
+    async (span) => {
+      const [bm25, knn] = await Promise.all([
+        bm25Search(q, filters, { page: 1, perPage: perPage * 4, sort: "relevance" }),
+        vector ? knnSearchEmbedding(vector, { filters, k: perPage * 4 }) : Promise.resolve(null),
+      ]);
+
+      // Normalize and blend
+      const scores = new Map<
+        string,
+        { src: DocType; bm25?: number; vec?: number }
+      >();
+
+      let maxBm25 = 0;
+      for (const h of bm25.hits) {
+        maxBm25 = Math.max(maxBm25, h.score || 0);
+      }
+      let maxVec = 0;
+      if (knn) {
+        for (const h of knn.hits) {
+          maxVec = Math.max(maxVec, h.score || 0);
+        }
+      }
+
+      for (const h of bm25.hits) {
+        scores.set(h.doc.id, { src: h.doc, bm25: maxBm25 ? h.score / maxBm25 : 0 });
+      }
+      if (knn) {
+        for (const h of knn.hits) {
+          const prev = scores.get(h.doc.id);
+          const norm = maxVec ? h.score / maxVec : 0;
+          if (prev) {
+            prev.vec = norm;
+          } else {
+            scores.set(h.doc.id, { src: h.doc, vec: norm });
+          }
+        }
+      }
+
+      const blended = Array.from(scores.entries()).map(([id, v]) => {
+        const b = v.bm25 ?? 0;
+        const w = v.vec ?? 0;
+        const score = alpha * b + (1 - alpha) * w;
+        const srcObj = v.src as unknown as Record<string, unknown>;
+        return {
+          id,
+          _source: { ...srcObj, bm25Score: b, vectorScore: w },
+          _score: score,
+        };
+      });
+
+      blended.sort((a, b) => b._score - a._score);
+      const pageStart = (page - 1) * perPage;
+      const pageItems = blended.slice(pageStart, pageStart + perPage);
+
+      return toSearchResult(pageItems, blended.length, 0);
+    },
+  );
+}
--- a/src/lib/embeddings.ts
+++ b/src/lib/embeddings.ts
@ -0,0 +1,56 @@
+import OpenAI from "openai";
+import * as Sentry from "@sentry/nextjs";
+import { env, embeddingsEnabled } from "@/lib/env";
+
+/**
+ * OpenAI-compatible embeddings helper.
+ * Supports custom base URL and model via environment variables.
+ */
+
+let _client: OpenAI | null = null;
+
+function getClient(): OpenAI {
+  if (!embeddingsEnabled) {
+    throw new Error("Embeddings are not enabled. Set OPENAI_API_BASE, OPENAI_API_KEY, and OPENAI_EMBEDDING_MODEL.");
+  }
+  if (_client) return _client;
+  _client = new OpenAI({
+    apiKey: env.OPENAI_API_KEY,
+    baseURL: env.OPENAI_API_BASE,
+  });
+  return _client;
+}
+
+/**
+ * Returns the embedding dimension configured (or default).
+ */
+export function getEmbeddingDim(): number {
+  return env.EMBEDDING_DIM ?? 1536;
+}
+
+/**
+ * Create an embedding vector for the given text.
+ */
+export async function getEmbeddingForText(text: string, model?: string): Promise<number[]> {
+  if (!embeddingsEnabled) {
+    throw new Error("Embeddings are not enabled.");
+  }
+  return Sentry.startSpan(
+    { op: "ai.embeddings", name: "Create embedding" },
+    async (span) => {
+      span.setAttribute("model", model ?? env.OPENAI_EMBEDDING_MODEL ?? "unknown");
+      const client = getClient();
+      const res = await client.embeddings.create({
+        model: model ?? (env.OPENAI_EMBEDDING_MODEL as string),
+        input: text,
+      });
+      const vec = res.data?.[0]?.embedding as unknown as number[] | undefined;
+      if (!vec) {
+        const err = new Error("No embedding returned from provider");
+        Sentry.captureException(err);
+        throw err;
+      }
+      return vec;
+    },
+  );
+}
--- a/src/lib/env.ts
+++ b/src/lib/env.ts
@ -0,0 +1,128 @@
+import { z } from "zod";
+
+/**
+ * Environment schema and safe runtime parsing.
+ * - Validates URLs and required secrets.
+ * - Normalizes base URLs by stripping trailing slashes.
+ * - Leaves optional values undefined when blank.
+ *
+ * Usage:
+ *   import { env, embeddingsEnabled, sentryEnabled } from "@/lib/env";
+ */
+
+const normalizeUrl = (val: string) => val.replace(/\/$/, "");
+
+const urlSchema = z
+  .string()
+  .url("Expected a valid URL")
+  .transform((s) => normalizeUrl(s));
+
+const optionalUrl = z
+  .string()
+  .optional()
+  .or(z.literal(""))
+  .transform((s) => (s ? normalizeUrl(s) : undefined));
+
+const optionalString = z
+  .string()
+  .optional()
+  .or(z.literal(""))
+  .transform((s) => (s ? s : undefined));
+
+const numberFromEnv = z.preprocess(
+  (val) => {
+    if (val === undefined || val === "") return undefined;
+    if (typeof val === "number") return val;
+    const parsed = Number(val);
+    return Number.isFinite(parsed) ? parsed : val;
+  },
+  z.number().int().positive().optional(),
+);
+
+const EnvSchema = z.object({
+  // Nextcloud (WebDAV)
+  NEXTCLOUD_BASE_URL: urlSchema,
+  NEXTCLOUD_USERNAME: z.string().min(1, "NEXTCLOUD_USERNAME is required"),
+  NEXTCLOUD_APP_PASSWORD: z.string().min(1, "NEXTCLOUD_APP_PASSWORD is required"),
+  NEXTCLOUD_ROOT_PATH: z
+    .string()
+    .min(1, "NEXTCLOUD_ROOT_PATH is required")
+    .refine((s) => s.startsWith("/"), {
+      message: "NEXTCLOUD_ROOT_PATH must start with /",
+    }),
+
+  // Elasticsearch
+  ELASTICSEARCH_URL: urlSchema,
+  ELASTICSEARCH_USERNAME: optionalString,
+  ELASTICSEARCH_PASSWORD: optionalString,
+  ELASTICSEARCH_INDEX: z.string().min(1).default("files"),
+  ELASTICSEARCH_ALIAS: z.string().min(1).default("files_current"),
+
+  // Apache Tika (optional until ingestion)
+  TIKA_BASE_URL: optionalUrl,
+
+  // OpenAI-compatible embeddings (optional)
+  OPENAI_API_BASE: optionalUrl,
+  OPENAI_API_KEY: optionalString,
+  OPENAI_EMBEDDING_MODEL: optionalString,
+  EMBEDDING_DIM: numberFromEnv, // e.g., 1536
+
+  // Sentry (optional)
+  SENTRY_DSN: optionalUrl,
+});
+
+type Env = z.infer<typeof EnvSchema>;
+
+let _env: Env | null = null;
+
+function parseEnv(): Env {
+  const result = EnvSchema.safeParse(process.env);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((i) => `- ${i.path.join(".")}: ${i.message}`)
+      .join("\n");
+    throw new Error(
+      `Invalid environment variables:\n${issues}\n\n` +
+        `Ensure you have a valid .env.local based on .env.example.`,
+    );
+  }
+  const parsed = result.data;
+
+  // Normalize/derive defaults where helpful
+  if (!parsed.ELASTICSEARCH_INDEX) parsed.ELASTICSEARCH_INDEX = "files";
+  if (!parsed.ELASTICSEARCH_ALIAS) parsed.ELASTICSEARCH_ALIAS = "files_current";
+
+  return parsed;
+}
+
+/**
+ * Parsed and validated environment configuration.
+ * Throws at import time if required vars are missing/invalid,
+ * which is desirable for server-only libs and API routes.
+ */
+export const env: Env = (() => {
+  if (_env) return _env;
+  _env = parseEnv();
+  return _env;
+})();
+
+/**
+ * Helpers/flags
+ */
+export const embeddingsEnabled =
+  !!env.OPENAI_API_BASE && !!env.OPENAI_API_KEY && !!env.OPENAI_EMBEDDING_MODEL;
+
+export const sentryEnabled = !!env.SENTRY_DSN;
+
+/**
+ * Optional helper to build Elasticsearch client auth config
+ */
+export function getEsAuth() {
+  if (env.ELASTICSEARCH_USERNAME && env.ELASTICSEARCH_PASSWORD) {
+    return {
+      username: env.ELASTICSEARCH_USERNAME,
+      password: env.ELASTICSEARCH_PASSWORD,
+    };
+  }
+  return undefined;
+}
--- a/src/lib/paths.ts
+++ b/src/lib/paths.ts
@ -0,0 +1,87 @@
+import crypto from "crypto";
+
+/**
+ * Path utilities for WebDAV/Nextcloud paths.
+ * All paths are normalized absolute strings starting with "/"
+ * without a trailing slash (except root which is exactly "/").
+ *
+ * These helpers are safe for server-side use. Do not import in client components.
+ */
+
+export type PathId = string;
+
+/**
+ * Normalize a path:
+ * - Converts backslashes to forward slashes
+ * - Ensures it starts with "/"
+ * - Collapses duplicate slashes
+ * - Removes trailing slash except for root
+ */
+export function normalizePath(input: string): PathId {
+  if (input == null) throw new Error("normalizePath: input is required");
+  let s = String(input).trim();
+
+  // Convert Windows-style slashes
+  s = s.replace(/\\/g, "/");
+
+  // Prepend leading slash if missing
+  if (!s.startsWith("/")) s = `/${s}`;
+
+  // Collapse duplicate slashes
+  s = s.replace(/\/+/g, "/");
+
+  // Remove trailing slash except for root
+  if (s.length > 1 && s.endsWith("/")) s = s.slice(0, -1);
+
+  return s as PathId;
+}
+
+/**
+ * Join path segments and normalize to an absolute path.
+ * Any leading/trailing slashes in segments are tolerated.
+ */
+export function joinPath(...segments: string[]): PathId {
+  const cleaned = segments
+    .filter((seg) => seg != null && seg !== "")
+    .map((seg) => String(seg));
+
+  let combined = cleaned.join("/");
+  // Ensure absolute
+  if (!combined.startsWith("/")) combined = `/${combined}`;
+
+  return normalizePath(combined);
+}
+
+/**
+ * Get the final segment of a normalized path.
+ */
+export function basename(path: string): string {
+  const p = normalizePath(path);
+  if (p === "/") return "/";
+  const idx = p.lastIndexOf("/");
+  return idx >= 0 ? p.slice(idx + 1) : p;
+}
+
+/**
+ * Get the parent path of a normalized path.
+ * - For "/" (root), returns "/" by default, or undefined if options.undefinedForRoot is true.
+ */
+export function parentPath(
+  path: string,
+  options?: { undefinedForRoot?: boolean },
+): PathId | undefined {
+  const p = normalizePath(path);
+  if (p === "/") return options?.undefinedForRoot ? undefined : ("/" as PathId);
+  const idx = p.lastIndexOf("/");
+  if (idx <= 0) return "/" as PathId;
+  return p.slice(0, idx) as PathId;
+}
+
+/**
+ * Stable ID for a path using SHA-256 hex.
+ * Collisions are extremely unlikely; this is deterministic for a given path.
+ */
+export function pathToId(path: string): string {
+  const p = normalizePath(path);
+  return crypto.createHash("sha256").update(p).digest("hex");
+}
--- a/src/lib/utils.ts
+++ b/src/lib/utils.ts
@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
--- a/src/lib/webdav.ts
+++ b/src/lib/webdav.ts
@ -0,0 +1,183 @@
+import * as Sentry from "@sentry/nextjs";
+import { createClient, type WebDAVClient, type FileStat } from "webdav";
+import { Readable as NodeReadable } from "node:stream";
+import { env } from "@/lib/env";
+import { normalizePath } from "@/lib/paths";
+import type { WebDavEntry } from "@/types/files";
+
+/**
+ * Nextcloud WebDAV wrapper with Sentry spans.
+ * Uses credentials from env and talks directly to the Nextcloud WebDAV endpoint.
+ */
+let _client: WebDAVClient | null = null;
+
+function getClient(): WebDAVClient {
+  if (_client) return _client;
+  _client = createClient(env.NEXTCLOUD_BASE_URL, {
+    username: env.NEXTCLOUD_USERNAME,
+    password: env.NEXTCLOUD_APP_PASSWORD,
+  });
+  return _client;
+}
+
+/**
+ * Type guards and converters for upload data to match webdav client types.
+ */
+function isNodeReadable(val: unknown): val is NodeReadable {
+  return typeof val === "object" && val !== null && "pipe" in val && typeof (val as NodeReadable).pipe === "function";
+}
+
+async function toWebdavData(
+  file: unknown,
+): Promise<Buffer | NodeReadable | string> {
+  if (typeof file === "string") return file;
+  if (typeof Buffer !== "undefined" && Buffer.isBuffer(file)) {
+    return file as Buffer;
+  }
+  if (file instanceof Uint8Array) {
+    return Buffer.from(file as Uint8Array);
+  }
+  if (file instanceof ArrayBuffer) {
+    return Buffer.from(new Uint8Array(file as ArrayBuffer));
+  }
+  // Blob (from web File API)
+  if (typeof Blob !== "undefined" && file instanceof Blob) {
+    const ab = await (file as Blob).arrayBuffer();
+    return Buffer.from(new Uint8Array(ab));
+  }
+  // Node stream
+  if (isNodeReadable(file)) {
+    return file as NodeReadable;
+  }
+  // Web ReadableStream (convert to Buffer)
+  if (typeof ReadableStream !== "undefined" && file instanceof ReadableStream) {
+    const reader = (file as ReadableStream<Uint8Array>).getReader();
+    const chunks: Uint8Array[] = [];
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) chunks.push(value);
+    }
+    const total = chunks.reduce((sum, c) => sum + c.byteLength, 0);
+    const buf = Buffer.alloc(total);
+    let offset = 0;
+    for (const c of chunks) {
+      buf.set(c, offset);
+      offset += c.byteLength;
+    }
+    return buf;
+  }
+  throw new Error("Unsupported upload data type for WebDAV");
+}
+
+function mapStatToEntry(stat: FileStat): WebDavEntry {
+  const mime = (stat as unknown as { mime?: unknown }).mime;
+  return {
+    href: normalizePath(stat.filename),
+    name: stat.basename,
+    isDirectory: stat.type === "directory",
+    lastmod: typeof stat.lastmod === "string" ? stat.lastmod : undefined,
+    size: typeof stat.size === "number" ? stat.size : undefined,
+    etag: typeof stat.etag === "string" ? stat.etag : undefined,
+    contentType: typeof mime === "string" ? mime : undefined,
+    props: undefined,
+  };
+}
+
+export class NextcloudClient {
+  private rootPath: string;
+
+  constructor(rootPath: string = env.NEXTCLOUD_ROOT_PATH) {
+    this.rootPath = normalizePath(rootPath);
+  }
+
+  /**
+   * Resolve incoming path to an absolute normalized DAV path.
+   * If given path is absolute, use it as-is; otherwise join with NEXTCLOUD_ROOT_PATH.
+   */
+  private resolve(path: string | undefined): string {
+    if (!path) return this.rootPath;
+    const p = normalizePath(path);
+    return p;
+  }
+
+  async listDirectory(path?: string): Promise<WebDavEntry[]> {
+    return Sentry.startSpan(
+      { op: "http.client", name: "WebDAV PROPFIND list" },
+      async (span) => {
+        const target = this.resolve(path);
+        span.setAttribute("path", target);
+        const client = getClient();
+        const stats = (await client.getDirectoryContents(target)) as FileStat[];
+        return stats.map(mapStatToEntry);
+      },
+    );
+  }
+
+  async createFolder(path: string): Promise<{ ok: boolean; etag?: string }> {
+    return Sentry.startSpan(
+      { op: "http.client", name: "WebDAV MKCOL createFolder" },
+      async (span) => {
+        const target = this.resolve(path);
+        span.setAttribute("path", target);
+        const client = getClient();
+        await client.createDirectory(target);
+        // ETag not typically returned by createDirectory in webdav client
+        return { ok: true };
+      },
+    );
+  }
+
+  async uploadFile(
+    destPath: string,
+    file: unknown,
+    contentType?: string,
+  ): Promise<{ ok: boolean; etag?: string; size?: number }> {
+    return Sentry.startSpan(
+      { op: "http.client", name: "WebDAV PUT uploadFile" },
+      async (span) => {
+        const target = this.resolve(destPath);
+        span.setAttribute("path", target);
+        if (contentType) span.setAttribute("contentType", contentType);
+        const client = getClient();
+        const data = await toWebdavData(file);
+        await client.putFileContents(target, data, { overwrite: true });
+        return { ok: true };
+      },
+    );
+  }
+
+  downloadStream(path: string): Promise<NodeJS.ReadableStream> {
+    return Sentry.startSpan(
+      { op: "http.client", name: "WebDAV GET downloadStream" },
+      async (span) => {
+        const target = this.resolve(path);
+        span.setAttribute("path", target);
+        const client = getClient();
+        const stream = client.createReadStream(target) as unknown as NodeJS.ReadableStream;
+        return stream;
+      },
+    );
+  }
+
+  async stat(path: string): Promise<WebDavEntry | null> {
+    return Sentry.startSpan(
+      { op: "http.client", name: "WebDAV PROPFIND stat" },
+      async (span) => {
+        const target = this.resolve(path);
+        span.setAttribute("path", target);
+        const client = getClient();
+        try {
+          const s = (await client.stat(target)) as FileStat;
+          return mapStatToEntry(s);
+        } catch (err) {
+          // 404 -> not found
+          Sentry.captureException(err);
+          return null;
+        }
+      },
+    );
+  }
+}
+
+export const nextcloud = new NextcloudClient();
--- a/src/types/files.ts
+++ b/src/types/files.ts
@ -0,0 +1,49 @@
+import type { PathId } from "@/lib/paths";
+
+export enum FileKind {
+  File = "File",
+  Folder = "Folder",
+}
+
+export interface FolderNode {
+  id: string; // stable hash of path
+  name: string; // basename
+  path: PathId; // absolute path
+  parentPath?: PathId;
+  childrenLoaded: boolean; // lazy tree loading flag
+  fileCount?: number;
+  sizeBytes?: number;
+  etag?: string;
+  permissions?: string[]; // placeholder for future ACLs
+}
+
+export interface FileItem {
+  id: string; // stable hash of path
+  name: string;
+  nickname?: string;
+  kind: FileKind.File;
+  path: PathId;
+  parentPath: PathId;
+  sizeBytes: number;
+  mimeType: string;
+  owner: string; // Nextcloud owner
+  uploadedBy?: string; // uploader principal if different
+  uploadedAt?: string; // ISO date
+  modifiedAt?: string; // ISO date
+  tags?: string[];
+  previewAvailable?: boolean;
+  webDavHref: string; // server-side-resolved href
+  etag?: string;
+  permissions?: string[];
+}
+
+export interface WebDavEntry {
+  href: string;
+  name: string;
+  isDirectory: boolean;
+  lastmod?: string;
+  size?: number;
+  etag?: string;
+  contentType?: string;
+  props?: Record<string, unknown>;
+}
--- a/src/types/ingest.ts
+++ b/src/types/ingest.ts
@ -0,0 +1,30 @@
+import type { PathId } from "@/lib/paths";
+
+export interface IndexDocument {
+  id: string;
+  name: string;
+  nickname?: string;
+  path: PathId;
+  parentPath: PathId;
+  sizeBytes: number;
+  mimeType: string;
+  owner: string;
+  uploadedBy?: string;
+  uploadedAt?: string; // ISO
+  modifiedAt?: string; // ISO
+  tags?: string[];
+  etag?: string;
+  previewAvailable?: boolean;
+
+  // Full-text and vectors
+  content?: string; // extracted by Tika
+  title?: string;
+  content_vector?: number[]; // optional embeddings
+  title_vector?: number[]; // optional embeddings
+
+  // Permissions placeholder
+  acl?: {
+    principals?: string[]; // user/group ids
+    public?: boolean;
+  };
+}
--- a/src/types/search.ts
+++ b/src/types/search.ts
@ -0,0 +1,37 @@
+import type { FileItem } from "@/types/files";
+import type { PathId } from "@/lib/paths";
+
+export interface FacetFilters {
+  types?: string[]; // mime supertype(s) e.g. ["application/pdf","image/"]
+  owner?: string[];
+  tags?: string[];
+  dateFrom?: string; // ISO
+  dateTo?: string; // ISO
+  pathPrefix?: PathId; // filter by project path
+  sizeMinBytes?: number;
+  sizeMaxBytes?: number;
+}
+
+export type SortMode = "relevance" | "modified" | "size";
+
+export interface SearchQuery {
+  q: string;
+  filters?: FacetFilters;
+  sort?: SortMode;
+  page?: number; // default 1
+  perPage?: number; // default 25
+  semantic?: boolean; // if true and embeddings configured, blend kNN
+}
+
+export interface SearchHit {
+  doc: FileItem;
+  score: number;
+  bm25Score?: number;
+  vectorScore?: number;
+}
+
+export interface SearchResult {
+  total: number;
+  hits: SearchHit[];
+  tookMs: number;
+}