feat: enhance obsidian connector doc and add notes for migration from legacy obsidian connector

Author: AnishSarkar22

surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/obsidian-config.tsx

@@ -1,11 +1,13 @@
 "use client";
 
-import { Info } from "lucide-react";
+import { AlertTriangle, Info } from "lucide-react";
 import { type FC, useEffect, useMemo, useState } from "react";
 import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
 import { connectorsApiService, type ObsidianStats } from "@/lib/apis/connectors-api.service";
 import type { ConnectorConfigProps } from "../index";
 
+const OBSIDIAN_SETUP_DOCS_URL = "/docs/connectors/obsidian";
+
 function formatTimestamp(value: unknown): string {
 	if (typeof value !== "string" || !value) return "—";
 	const d = new Date(value);
@@ -22,17 +24,61 @@ function formatTimestamp(value: unknown): string {
  * web UI doesn't expose a Name input or a Save button for Obsidian (the
  * latter is suppressed in `connector-edit-view.tsx`).
  *
- * Renders plugin stats when connector metadata comes from the plugin.
- * If metadata is missing or malformed, we show a recovery hint.
+ * Renders one of three modes depending on the connector's `config`:
+ *
+ * 1. **Plugin connector** (`config.source === "plugin"`) — read-only stats
+ *    panel showing what the plugin most recently reported.
+ * 2. **Legacy server-path connector** (`config.legacy === true`, set by the
+ *    migration) — migration warning + docs link + explicit disconnect data-loss
+ *    warning so users move to the plugin flow safely.
+ * 3. **Unknown** — fallback for rows that escaped migration; suggests a
+ *    clean re-install.
  */
 export const ObsidianConfig: FC<ConnectorConfigProps> = ({ connector }) => {
 	const config = (connector.config ?? {}) as Record<string, unknown>;
+	const isLegacy = config.legacy === true;
 	const isPlugin = config.source === "plugin";
 
+	if (isLegacy) return <LegacyBanner />;
 	if (isPlugin) return <PluginStats config={config} />;
 	return <UnknownConnectorState />;
 };
 
+const LegacyBanner: FC = () => {
+	return (
+		<div className="space-y-6">
+			<Alert className="border-amber-500/40 bg-amber-500/10">
+				<AlertTriangle className="size-4 shrink-0 text-amber-500" />
+				<AlertTitle className="text-xs sm:text-sm">
+					Sync stopped, install the plugin to migrate
+				</AlertTitle>
+				<AlertDescription className="text-[11px] sm:text-xs leading-relaxed">
+					This Obsidian connector used the legacy server-path scanner, which has been removed. The
+					notes already indexed remain searchable, but they no longer reflect changes made in your
+					vault.
+				</AlertDescription>
+			</Alert>
+
+			<div className="rounded-xl border border-border bg-slate-400/5 p-3 sm:p-6 dark:bg-white/5">
+				<h3 className="mb-3 text-sm font-medium sm:text-base">Migration required</h3>
+				<p className="mb-3 text-[11px] leading-relaxed text-muted-foreground sm:text-xs">
+					Follow the{" "}
+					<a
+						href={OBSIDIAN_SETUP_DOCS_URL}
+						className="font-medium text-primary underline underline-offset-4 hover:text-primary/80"
+					>
+						Obsidian setup guide
+					</a>{" "}
+					to reconnect this vault through the plugin.
+				</p>
+				<p className="text-[11px] leading-relaxed text-amber-600 dark:text-amber-400 sm:text-xs">
+					Heads up: Disconnect also deletes every document this connector previously indexed.
+				</p>
+			</div>
+		</div>
+	);
+};
+
 const PluginStats: FC<{ config: Record<string, unknown> }> = ({ config }) => {
 	const vaultId = typeof config.vault_id === "string" ? config.vault_id : null;
 	const [stats, setStats] = useState<ObsidianStats | null>(null);
@@ -114,8 +160,8 @@ const UnknownConnectorState: FC = () => (
 		<Info className="size-4 shrink-0" />
 		<AlertTitle className="text-xs sm:text-sm">Unrecognized config</AlertTitle>
 		<AlertDescription className="text-[11px] sm:text-xs">
-			This connector is missing plugin metadata. Delete it, then reconnect your vault from the
-			SurfSense Obsidian plugin so sync can resume.
+			This connector has neither plugin metadata nor a legacy marker. It may predate migration —
+			you can safely delete it and re-install the SurfSense Obsidian plugin to resume syncing.
 		</AlertDescription>
 	</Alert>
 );

surfsense_web/content/docs/connectors/index.mdx

@@ -105,7 +105,7 @@ Connect SurfSense to your favorite tools and services. Browse the available inte
   />
   <Card
     title="Obsidian"
-    description="Connect your Obsidian vault to SurfSense"
+    description="Sync your Obsidian vault using the SurfSense plugin"
     href="/docs/connectors/obsidian"
   />
   <Card

surfsense_web/content/docs/connectors/obsidian.mdx

@@ -6,7 +6,6 @@ description: Sync your Obsidian vault with the SurfSense plugin
 # Obsidian Plugin Setup Guide
 
 SurfSense integrates with Obsidian through the SurfSense Obsidian plugin.
-The old server-side vault path scanner is no longer supported.
 
 ## How it works
 
@@ -28,20 +27,22 @@ This works for cloud and self-hosted deployments, including desktop and mobile c
 1. Open **Connectors** in SurfSense and choose **Obsidian**.
 2. Click **Open plugin releases** and install the latest SurfSense Obsidian plugin.
 3. In Obsidian, open **Settings → SurfSense**.
-4. Paste your SurfSense API token from the connector setup panel.
-5. Paste your SurfSense backend URL in the plugin's **Server URL** setting.
-6. Choose the Search Space in the plugin, then run the first sync.
-7. Confirm the connector appears as **Obsidian — <vault>** in SurfSense.
+4. Paste your SurfSense API token from the user settings section.
+5. Paste your Server URL in the plugin setting: either your SurfSense main domain (if `/api/v1` rewrites are enabled) or your direct backend URL.
+6. Choose the Search Space in the plugin, then the first sync should run automatically.
+7. Confirm the connector appears as **Obsidian — &lt;vault&gt;** in SurfSense.
 
-<Callout type="info">
-    You do not create or configure a vault path in the web UI. The connector row is created automatically when the plugin calls `/api/v1/obsidian/connect`.
-</Callout>
+## Migrating from the legacy connector
 
-## Self-hosted notes
+If you previously used the legacy Obsidian connector architecture, migrate to the plugin flow:
 
-- Use your public or LAN backend URL that your Obsidian device can reach.
-- No Docker bind mount for the vault is required.
-- If your instance is behind TLS, ensure the URL/certificate is valid for the device running Obsidian.
+1. Delete the old legacy Obsidian connector from SurfSense.
+2. Install and configure the SurfSense Obsidian plugin using the quick start above.
+3. Run the first plugin sync and verify the new **Obsidian — &lt;vault&gt;** connector is active.
+
+<Callout type="warn">
+    Deleting the legacy connector also deletes all documents that were indexed by that connector. Always finish and verify plugin sync before deleting the old connector.
+</Callout>
 
 ## Troubleshooting
 
@@ -50,6 +51,10 @@ This works for cloud and self-hosted deployments, including desktop and mobile c
 - Trigger a manual sync from the plugin settings.
 - Confirm your API token is valid and not expired.
 
+**Self-hosted URL issues**
+- Use a public or LAN backend URL that your Obsidian device can reach.
+- If your instance is behind TLS, ensure the URL/certificate is valid for the device running Obsidian.
+
 **Unauthorized / 401 errors**
 - Regenerate and paste a fresh API token from SurfSense.
 - Ensure the token belongs to the same account and workspace you are syncing into.