feat: native desktop notifications + rowboat:// deep links

Adds INotificationService with an Electron implementation, plus a deep-link
dispatcher (rowboat://) for routing notification clicks back into the app.

Notifications:
- New `notify-user` skill + builtin tool. Title, message, optional primary
    link, optional secondary actions. Supports https:// (opens in browser) and
    rowboat:// (opens in app) targets.
- ElectronNotificationService holds strong refs to active Notification
    instances so click handlers survive GC (otherwise macOS click silently
    no-ops).
- Calendar meeting notifier fires 1-min warnings with "take notes" /
    "join + take notes" actions backed by deep links.

Deep links (rowboat://):
- forge.config.cjs declares the protocol; main.ts wires single-instance
    lock, setAsDefaultProtocolClient, open-url (mac), second-instance (win/
    linux), and first-launch argv extraction.
- New deeplink.ts dispatcher with dispatchUrl(url): main-handled actions
    (rowboat://action?type=...) vs renderer navigation (rowboat://open?...)
    via app:openUrl IPC. Includes pending-URL buffering for first-launch
    delivery before the renderer is ready.
- Renderer parseDeepLink supports file / chat / graph / task /
    suggested-topics targets.
- New app:consumePendingDeepLink IPC for renderer one-time drain on mount.

Refactor: extractConferenceLink moved out of calendar-block.tsx into
shared lib/calendar-event.ts (used by both the block and the take-notes
deep-link handler)

apps/x/apps/main/forge.config.cjs

@@ -11,6 +11,9 @@ module.exports = {
         icon: './icons/icon',  // .icns extension added automatically
         appBundleId: 'com.rowboat.app',
         appCategoryType: 'public.app-category.productivity',
+        protocols: [
+            { name: 'Rowboat', schemes: ['rowboat'] },
+        ],
         extendInfo: {
             NSAudioCaptureUsageDescription: 'Rowboat needs access to system audio to transcribe meetings from other apps (Zoom, Meet, etc.)',
         },

apps/x/apps/main/src/deeplink.ts

@@ -0,0 +1,118 @@
+import { BrowserWindow } from "electron";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { WorkDir } from "@x/core/dist/config/config.js";
+
+export const DEEP_LINK_SCHEME = "rowboat";
+const URL_PREFIX = `${DEEP_LINK_SCHEME}://`;
+const ACTION_HOST = "action";
+
+let pendingUrl: string | null = null;
+let mainWindowRef: BrowserWindow | null = null;
+
+export function setMainWindowForDeepLinks(win: BrowserWindow | null): void {
+    mainWindowRef = win;
+}
+
+export function consumePendingDeepLink(): string | null {
+    const url = pendingUrl;
+    pendingUrl = null;
+    return url;
+}
+
+export function extractDeepLinkFromArgv(argv: readonly string[]): string | null {
+    for (const arg of argv) {
+        if (typeof arg === "string" && arg.startsWith(URL_PREFIX)) return arg;
+    }
+    return null;
+}
+
+/**
+ * Dispatch any rowboat:// URL — chooses navigation vs action automatically.
+ * Use this from notification click handlers and other URL entry points.
+ */
+export function dispatchUrl(url: string): void {
+    if (parseAction(url)) {
+        void dispatchAction(url);
+    } else {
+        dispatchDeepLink(url);
+    }
+}
+
+export function dispatchDeepLink(url: string): void {
+    if (!url.startsWith(URL_PREFIX)) return;
+
+    pendingUrl = url;
+
+    const win = mainWindowRef;
+    if (!win || win.isDestroyed()) return;
+    focusWindow(win);
+
+    if (win.webContents.isLoading()) return;
+
+    win.webContents.send("app:openUrl", { url });
+    pendingUrl = null;
+}
+
+interface MeetingNotesAction {
+    type: "take-meeting-notes" | "join-and-take-meeting-notes";
+    eventId: string;
+}
+
+type ParsedAction = MeetingNotesAction;
+
+function parseAction(url: string): ParsedAction | null {
+    if (!url.startsWith(URL_PREFIX)) return null;
+    const rest = url.slice(URL_PREFIX.length);
+    const queryIdx = rest.indexOf("?");
+    const host = (queryIdx >= 0 ? rest.slice(0, queryIdx) : rest).replace(/\/$/, "");
+    if (host !== ACTION_HOST) return null;
+    const params = new URLSearchParams(queryIdx >= 0 ? rest.slice(queryIdx + 1) : "");
+    const type = params.get("type");
+    if (type === "take-meeting-notes" || type === "join-and-take-meeting-notes") {
+        const eventId = params.get("eventId");
+        return eventId ? { type, eventId } : null;
+    }
+    return null;
+}
+
+async function dispatchAction(url: string): Promise<void> {
+    const parsed = parseAction(url);
+    if (!parsed) return;
+
+    const openMeeting = parsed.type === "join-and-take-meeting-notes";
+    await handleTakeMeetingNotes(parsed.eventId, openMeeting);
+}
+
+async function handleTakeMeetingNotes(eventId: string, openMeeting: boolean): Promise<void> {
+    const win = mainWindowRef;
+    if (!win || win.isDestroyed()) return;
+    focusWindow(win);
+
+    const filePath = path.join(WorkDir, "calendar_sync", `${eventId}.json`);
+    let event: unknown;
+    try {
+        const raw = await fs.readFile(filePath, "utf-8");
+        event = JSON.parse(raw);
+    } catch (err) {
+        console.error(`[deeplink] take-meeting-notes: failed to read ${filePath}`, err);
+        return;
+    }
+
+    const payload = { event, openMeeting };
+
+    if (win.webContents.isLoading()) {
+        win.webContents.once("did-finish-load", () => {
+            win.webContents.send("app:takeMeetingNotes", payload);
+        });
+        return;
+    }
+
+    win.webContents.send("app:takeMeetingNotes", payload);
+}
+
+function focusWindow(win: BrowserWindow): void {
+    if (win.isMinimized()) win.restore();
+    win.show();
+    win.focus();
+}

apps/x/apps/main/src/ipc.ts

@@ -34,6 +34,7 @@ import { triggerSync as triggerGranolaSync } from '@x/core/dist/knowledge/granol
 import { ISlackConfigRepo } from '@x/core/dist/slack/repo.js';
 import { isOnboardingComplete, markOnboardingComplete } from '@x/core/dist/config/note_creation_config.js';
 import * as composioHandler from './composio-handler.js';
+import { consumePendingDeepLink } from './deeplink.js';
 import { IAgentScheduleRepo } from '@x/core/dist/agent-schedule/repo.js';
 import { IAgentScheduleStateRepo } from '@x/core/dist/agent-schedule/state-repo.js';
 import { triggerRun as triggerAgentScheduleRun } from '@x/core/dist/agent-schedule/runner.js';
@@ -417,6 +418,9 @@ export function setupIpcHandlers() {
       // args is null for this channel (no request payload)
       return getVersions();
     },
+    'app:consumePendingDeepLink': async () => {
+      return { url: consumePendingDeepLink() };
+    },
     'analytics:bootstrap': async () => {
       return {
         installationId: getInstallationId(),

apps/x/apps/main/src/main.ts

@@ -23,6 +23,7 @@ import { init as initNoteTagging } from "@x/core/dist/knowledge/tag_notes.js";
 import { init as initInlineTasks } from "@x/core/dist/knowledge/inline_tasks.js";
 import { init as initAgentRunner } from "@x/core/dist/agent-schedule/runner.js";
 import { init as initAgentNotes } from "@x/core/dist/knowledge/agent_notes.js";
+import { init as initCalendarNotifications } from "@x/core/dist/knowledge/notify_calendar_meetings.js";
 import { init as initTrackScheduler } from "@x/core/dist/knowledge/track/scheduler.js";
 import { init as initTrackEventProcessor } from "@x/core/dist/knowledge/track/events.js";
 import { init as initLocalSites, shutdown as shutdownLocalSites } from "@x/core/dist/local-sites/server.js";
@@ -34,10 +35,17 @@ import started from "electron-squirrel-startup";
 import { execSync, exec, execFileSync } from "node:child_process";
 import { promisify } from "node:util";
 import { init as initChromeSync } from "@x/core/dist/knowledge/chrome-extension/server/server.js";
-import { registerBrowserControlService } from "@x/core/dist/di/container.js";
+import { registerBrowserControlService, registerNotificationService } from "@x/core/dist/di/container.js";
 import { browserViewManager, BROWSER_PARTITION } from "./browser/view.js";
 import { setupBrowserEventForwarding } from "./browser/ipc.js";
 import { ElectronBrowserControlService } from "./browser/control-service.js";
+import { ElectronNotificationService } from "./notification/electron-notification-service.js";
+import {
+  DEEP_LINK_SCHEME,
+  dispatchDeepLink,
+  extractDeepLinkFromArgv,
+  setMainWindowForDeepLinks,
+} from "./deeplink.js";
 
 const execAsync = promisify(exec);
 
@@ -47,6 +55,43 @@ const __dirname = dirname(__filename);
 // run this as early in the main process as possible
 if (started) app.quit();
 
+// Single-instance lock: route a second launch (e.g. clicking a rowboat:// link)
+// back into the existing process via the 'second-instance' event.
+if (!app.requestSingleInstanceLock()) {
+  app.quit();
+  process.exit(0);
+}
+
+// Register as the OS handler for rowboat:// URLs.
+// In dev, point at the right argv so the OS can re-invoke us correctly.
+if (process.defaultApp) {
+  if (process.argv.length >= 2) {
+    app.setAsDefaultProtocolClient(DEEP_LINK_SCHEME, process.execPath, [
+      path.resolve(process.argv[1]),
+    ]);
+  }
+} else {
+  app.setAsDefaultProtocolClient(DEEP_LINK_SCHEME);
+}
+
+// First-launch URL on Windows/Linux comes through argv.
+{
+  const initialUrl = extractDeepLinkFromArgv(process.argv);
+  if (initialUrl) dispatchDeepLink(initialUrl);
+}
+
+// macOS sends URLs via 'open-url' (both first launch and while running).
+app.on("open-url", (event, url) => {
+  event.preventDefault();
+  dispatchDeepLink(url);
+});
+
+// Subsequent launches on Windows/Linux land here via the single-instance lock.
+app.on("second-instance", (_event, argv) => {
+  const url = extractDeepLinkFromArgv(argv);
+  if (url) dispatchDeepLink(url);
+});
+
 // Fix PATH for packaged Electron apps on macOS/Linux.
 // Packaged apps inherit a minimal environment that doesn't include paths from
 // the user's shell profile (such as those provided by nvm, Homebrew, etc.).
@@ -165,6 +210,9 @@ function createWindow() {
   configureSessionPermissions(session.defaultSession);
   configureSessionPermissions(session.fromPartition(BROWSER_PARTITION));
 
+  setMainWindowForDeepLinks(win);
+  win.on("closed", () => setMainWindowForDeepLinks(null));
+
   // Show window when content is ready to prevent blank screen
   win.once("ready-to-show", () => {
     win.maximize();
@@ -240,6 +288,7 @@ app.whenReady().then(async () => {
   });
 
   registerBrowserControlService(new ElectronBrowserControlService());
+  registerNotificationService(new ElectronNotificationService());
 
   setupIpcHandlers();
   setupBrowserEventForwarding();
@@ -298,6 +347,9 @@ app.whenReady().then(async () => {
   // start agent notes learning service
   initAgentNotes();
 
+  // start calendar meeting notification service (fires 1-minute warnings)
+  initCalendarNotifications();
+
   // start chrome extension sync server
   initChromeSync();
 

apps/x/apps/main/src/notification/electron-notification-service.ts

@@ -0,0 +1,84 @@
+import { BrowserWindow, Notification, shell } from "electron";
+import type { INotificationService, NotifyInput } from "@x/core/dist/application/notification/service.js";
+import { dispatchUrl } from "../deeplink.js";
+
+const HTTP_URL = /^https?:\/\//i;
+const ROWBOAT_URL = /^rowboat:\/\//i;
+
+export class ElectronNotificationService implements INotificationService {
+    // Holds strong references to active Notification instances so the GC can't
+    // collect them while they're still visible — without this, the click handler
+    // gets dropped and macOS clicks just focus the app silently.
+    private active = new Set<Notification>();
+
+    isSupported(): boolean {
+        return Notification.isSupported();
+    }
+
+    notify({ title = "Rowboat", message, link, actionLabel, secondaryActions }: NotifyInput): void {
+        // Build the actions array AND a parallel index → link map.
+        // macOS shows actions[0] inline (Banner) or all of them (Alert);
+        // additional ones live behind the chevron menu.
+        const actionDefs: Electron.NotificationConstructorOptions["actions"] = [];
+        const actionLinks: string[] = [];
+
+        const primaryLabel = actionLabel?.trim();
+        if (link && primaryLabel) {
+            actionDefs!.push({ type: "button", text: primaryLabel });
+            actionLinks.push(link);
+        }
+        if (secondaryActions) {
+            for (const sa of secondaryActions) {
+                actionDefs!.push({ type: "button", text: sa.label });
+                actionLinks.push(sa.link);
+            }
+        }
+
+        const notification = new Notification({
+            title,
+            body: message,
+            actions: actionDefs,
+        });
+
+        this.active.add(notification);
+        const release = () => { this.active.delete(notification); };
+
+        const openLink = (target: string | undefined) => {
+            if (target && ROWBOAT_URL.test(target)) {
+                dispatchUrl(target);
+            } else if (target && HTTP_URL.test(target)) {
+                shell.openExternal(target).catch((err) => {
+                    console.error("[notification] failed to open link:", err);
+                });
+            } else {
+                this.focusMainWindow();
+            }
+            release();
+        };
+
+        // Body click: always opens the primary `link` (or focuses the app if none).
+        notification.on("click", () => openLink(link));
+
+        // Action button click: dispatch by index into the actions array.
+        notification.on("action", (_event, index) => {
+            if (index >= 0 && index < actionLinks.length) {
+                openLink(actionLinks[index]);
+            } else {
+                openLink(undefined);
+            }
+        });
+
+        notification.on("close", release);
+        notification.on("failed", release);
+
+        notification.show();
+    }
+
+    private focusMainWindow(): void {
+        const [win] = BrowserWindow.getAllWindows();
+        if (!win) return;
+        if (win.isMinimized()) win.restore();
+        win.show();
+        win.focus();
+    }
+}

apps/x/apps/renderer/src/App.tsx

@@ -54,6 +54,7 @@ import { Button } from "@/components/ui/button"
 import { Toaster } from "@/components/ui/sonner"
 import { stripKnowledgePrefix, toKnowledgePath, wikiLabel } from '@/lib/wiki-links'
 import { splitFrontmatter, joinFrontmatter } from '@/lib/frontmatter'
+import { extractConferenceLink } from '@/lib/calendar-event'
 import { OnboardingModal } from '@/components/onboarding'
 import { CommandPalette, type CommandPaletteContext, type CommandPaletteMention } from '@/components/search-dialog'
 import { TrackModal } from '@/components/track-modal'
@@ -515,6 +516,45 @@ function viewStatesEqual(a: ViewState, b: ViewState): boolean {
   return true // both graph
 }
 
+/**
+ * Parse a rowboat:// deep link into a ViewState. Returns null if the URL is
+ * malformed or names an unknown target.
+ *
+ * Shape: rowboat://open?type=<file|chat|graph|task|suggested-topics>&...
+ *   file:             ?type=file&path=knowledge/foo.md
+ *   chat:             ?type=chat&runId=abc123        (runId optional)
+ *   graph:            ?type=graph
+ *   task:             ?type=task&name=daily-brief
+ *   suggested-topics: ?type=suggested-topics
+ */
+function parseDeepLink(input: string): ViewState | null {
+  const SCHEME = 'rowboat://'
+  if (!input.startsWith(SCHEME)) return null
+  const rest = input.slice(SCHEME.length)
+  const queryIdx = rest.indexOf('?')
+  const host = (queryIdx >= 0 ? rest.slice(0, queryIdx) : rest).replace(/\/$/, '')
+  if (host !== 'open') return null
+  const params = new URLSearchParams(queryIdx >= 0 ? rest.slice(queryIdx + 1) : '')
+  switch (params.get('type')) {
+    case 'file': {
+      const path = params.get('path')
+      return path ? { type: 'file', path } : null
+    }
+    case 'chat':
+      return { type: 'chat', runId: params.get('runId') || null }
+    case 'graph':
+      return { type: 'graph' }
+    case 'task': {
+      const name = params.get('name')
+      return name ? { type: 'task', name } : null
+    }
+    case 'suggested-topics':
+      return { type: 'suggested-topics' }
+    default:
+      return null
+  }
+}
+
 /** Sidebar toggle (fixed position, top-left) */
 function FixedSidebarToggle({
   leftInsetPx,
@@ -3050,6 +3090,58 @@ function App() {
     void navigateToView({ type: 'file', path })
   }, [navigateToView])
 
+  // Deep-link handler kept in a ref so the useEffect below can register the
+  // IPC listener (and run the one-time pending-link drain) just once on mount,
+  // rather than re-running on every navigation when navigateToView's identity
+  // changes.
+  const navigateToViewRef = useRef(navigateToView)
+  useEffect(() => { navigateToViewRef.current = navigateToView }, [navigateToView])
+
+  useEffect(() => {
+    const handle = (url: string) => {
+      const view = parseDeepLink(url)
+      if (view) void navigateToViewRef.current(view)
+    }
+    void window.ipc.invoke('app:consumePendingDeepLink', null).then(({ url }) => {
+      if (url) handle(url)
+    })
+    return window.ipc.on('app:openUrl', ({ url }) => handle(url))
+  }, [])
+
+  // Triggered by main when the user clicks a calendar-meeting notification.
+  // Reuses the same flow as the in-app "Join meeting & take notes" button.
+  // When `openMeeting` is true, also opens the meeting URL in the system browser.
+  useEffect(() => {
+    return window.ipc.on('app:takeMeetingNotes', ({ event, openMeeting }) => {
+      const e = event as {
+        summary?: string
+        start?: { dateTime?: string; date?: string; timeZone?: string }
+        end?: { dateTime?: string; date?: string; timeZone?: string }
+        location?: string
+        htmlLink?: string
+        hangoutLink?: string
+        conferenceData?: { entryPoints?: Array<{ entryPointType?: string; uri?: string }> }
+      }
+      if (!e || typeof e !== 'object') return
+      const conferenceLink = extractConferenceLink(e as Record<string, unknown>)
+      if (openMeeting && conferenceLink) {
+        window.open(conferenceLink, '_blank')
+      } else if (openMeeting) {
+        console.warn('[take-meeting-notes] openMeeting requested but event has no conference link', e)
+      }
+      window.__pendingCalendarEvent = {
+        summary: e.summary,
+        start: e.start,
+        end: e.end,
+        location: e.location,
+        htmlLink: e.htmlLink,
+        conferenceLink,
+        source: 'calendar-sync',
+      }
+      window.dispatchEvent(new Event('calendar-block:join-meeting'))
+    })
+  }, [])
+
   const handleBaseConfigChange = useCallback((path: string, config: BaseConfig) => {
     setBaseConfigByPath((prev) => ({ ...prev, [path]: config }))
   }, [])

apps/x/apps/renderer/src/extensions/calendar-block.tsx

@@ -3,6 +3,7 @@ import { ReactNodeViewRenderer, NodeViewWrapper } from '@tiptap/react'
 import { X, Calendar, Video, ChevronDown, Mic } from 'lucide-react'
 import { blocks } from '@x/shared'
 import { useState, useEffect, useRef } from 'react'
+import { extractConferenceLink } from '../lib/calendar-event'
 
 function formatTime(dateStr: string): string {
   const d = new Date(dateStr)
@@ -40,25 +41,6 @@ function getTimeRange(event: blocks.CalendarEvent): string {
   return `${startTime} \u2013 ${endTime}`
 }
 
-/**
- * Extract a video conference link from raw Google Calendar event JSON.
- * Checks conferenceData.entryPoints (video type), hangoutLink, then falls back
- * to conferenceLink if already set.
- */
-function extractConferenceLink(raw: Record<string, unknown>): string | undefined {
-  // Check conferenceData.entryPoints for video entry
-  const confData = raw.conferenceData as { entryPoints?: { entryPointType?: string; uri?: string }[] } | undefined
-  if (confData?.entryPoints) {
-    const video = confData.entryPoints.find(ep => ep.entryPointType === 'video')
-    if (video?.uri) return video.uri
-  }
-  // Check hangoutLink (Google Meet shortcut)
-  if (typeof raw.hangoutLink === 'string') return raw.hangoutLink
-  // Fall back to conferenceLink if present
-  if (typeof raw.conferenceLink === 'string') return raw.conferenceLink
-  return undefined
-}
-
 interface ResolvedEvent {
   event: blocks.CalendarEvent
   loaded: blocks.CalendarEvent | null

apps/x/apps/renderer/src/lib/calendar-event.ts

@@ -0,0 +1,15 @@
+/**
+ * Extract a video conference link from raw Google Calendar event JSON.
+ * Checks conferenceData.entryPoints (video type), hangoutLink, then falls back
+ * to a top-level conferenceLink if present.
+ */
+export function extractConferenceLink(raw: Record<string, unknown>): string | undefined {
+  const confData = raw.conferenceData as { entryPoints?: { entryPointType?: string; uri?: string }[] } | undefined
+  if (confData?.entryPoints) {
+    const video = confData.entryPoints.find(ep => ep.entryPointType === 'video')
+    if (video?.uri) return video.uri
+  }
+  if (typeof raw.hangoutLink === 'string') return raw.hangoutLink
+  if (typeof raw.conferenceLink === 'string') return raw.conferenceLink
+  return undefined
+}