feat(ai): add tool use (function calling) to AI assistant

.claude/settings.local.json

@@ -76,11 +76,7 @@
       "Bash(npx vitest:*)",
       "Bash(do echo:*)",
       "Bash(do gh:*)",
-      "Bash(npx tsc:*)",
-      "Bash(git stash:*)",
-      "Bash(git rm:*)",
-      "Bash(turbo typecheck:*)",
-      "Bash(npx turbo:*)"
+      "Bash(git tag:*)"
     ]
   }
 }

CLAUDE.md

@@ -15,13 +15,17 @@
 ```
 apps/
   desktop/           # Electron app (main, preload, renderer)
-  docs-site/         # VitePress documentation
+  web/               # Next.js marketing site + docs
 packages/
+  ai-core/           # Provider-agnostic AI: streaming, LLM providers, context builder
   core/              # Domain logic + markdown parsing
+  command-registry/  # Command palette registry
+  plugin-api/        # Plugin system interfaces
   storage-core/      # Storage interfaces (pure TS)
   storage-sqlite/    # SQLite adapter (peerDep for better-sqlite3)
   licensing/         # License validation
   product-config/    # Product configuration
+  sync-core/         # Sync engine
 ```
 
 ## Commands
@@ -67,6 +71,12 @@ Pattern for workspace packages with native deps:
 }
 ```
 
+## Type Version Alignment
+
+`@types/react` is pinned to `18.3.27` via `pnpm.overrides` in root `package.json`. This prevents type mismatches when packages like `lucide-react` resolve a different `@types/react` version than the app uses.
+
+**If you see `'X' cannot be used as a JSX component` errors:** Check that `pnpm.overrides` in root `package.json` still pins `@types/react` to match the React version used by `apps/desktop`.
+
 ## Testing
 
 - `pnpm test` runs all tests **except** storage-sqlite (safe to run always)
@@ -138,6 +148,13 @@ git pull origin develop
 git checkout -b feature/my-feature
 ```
 
+**Keep branch in sync (do this daily or before pushing):**
+
+```bash
+git fetch origin develop
+git rebase origin/develop
+```
+
 **Creating PR:**
 
 ```bash
@@ -153,6 +170,16 @@ git pull origin develop
 git branch -d feature/my-feature
 ```
 
+### Branch Hygiene (Critical)
+
+Long-lived branches cause painful merge conflicts. Follow these rules:
+
+- **Rebase daily:** `git fetch origin develop && git rebase origin/develop` before starting work each day
+- **Small PRs:** Prefer 3 small PRs over 1 large one. Split by layer (types → logic → UI)
+- **Max branch lifetime:** 2-3 days. If work takes longer, split into incremental PRs
+- **Don't touch unrelated files:** Avoid changes to `package.json`, lockfiles, or `apps/web` unless that's the PR's purpose — these are high-conflict files
+- **Rebase before pushing:** Always rebase against latest develop before `git push` to catch conflicts early
+
 ### Commit Messages
 
 Use conventional commits:
@@ -251,6 +278,41 @@ case 'tag':
 - [ ] Sidebar uses `useNavigation()` hook
 - [ ] No implicit flags (`!== null`)
 
+## AI Architecture
+
+The AI system lives in `packages/ai-core` with a provider-agnostic, streaming-first design.
+
+```
+Renderer (AiPanel) → IPC → Main (ipc-ai.ts) → AIService → ProviderRegistry → Provider → SSE stream
+                   ← batched LLMEvents (text/error/done) ←
+```
+
+**Key packages and files:**
+
+- `packages/ai-core/` — LLMProvider interface, ProviderRegistry, AnthropicProvider, ContextBuilder, AIService
+- `apps/desktop/src/main/ai/ipc-ai.ts` — IPC bridge, 50ms batched event streaming
+- `apps/desktop/src/preload/index.ts` — `window.readied.ai` API (chat, onEvent, cancel)
+- `apps/desktop/src/renderer/components/ai/AiPanel.tsx` — Chat UI with streaming
+
+**Adding a new LLM provider:**
+
+1. Create `packages/ai-core/src/providers/my-provider.ts` implementing `LLMProvider`
+2. Register in `ProviderRegistry` at `apps/desktop/src/main/ai/ipc-ai.ts`
+3. Add option to `apps/desktop/src/renderer/pages/settings/sections/AiSection.tsx`
+
+**Key types:**
+
+- `LLMEvent` — Protocol: `text` (delta), `error` (with code), `done`, `tool_call`, `tool_result`
+- `ChatOptions` — Provider, model, messages, tools, maxTokens
+- `LLMProvider` — `chat(options): AsyncGenerator<LLMEvent>` + `models()` + `validateKey()`
+
+**Rules:**
+
+- **No SDK dependencies in ai-core:** Providers use native `fetch` + SSE parsing
+- **Streaming only:** No request/response pattern — everything streams via `LLMEvent`
+- **Single panel instance:** Both Cmd+K and Sparkles button toggle the same AiPanel in App.tsx via CustomEvent (`readied:ai:toggle-panel`)
+- **Settings store is source of truth:** API key, model, and provider come from Zustand settings store (`selectAi` selector), not plugin config
+
 ## Documentation
 
 - **Architecture decisions:** `plan.md`

apps/desktop/src/main/ai/built-in-tools.ts

@@ -0,0 +1,140 @@
+// apps/desktop/src/main/ai/built-in-tools.ts
+import type { ToolRegistry } from '@readied/ai-core';
+
+/**
+ * Register built-in AI tools for note operations.
+ *
+ * Read tools (auto-execute): search_notes, read_note, list_notebooks
+ * Write tools (require confirmation): create_note, insert_text, replace_selection
+ *
+ * insert_text and replace_selection execute in the renderer (they need editor access).
+ * They delegate via IPC: main → renderer → main.
+ */
+export function registerBuiltInTools(
+  registry: ToolRegistry,
+  deps: {
+    searchNotes: (
+      query: string,
+      limit?: number
+    ) => Promise<Array<{ id: string; title: string; snippet: string }>>;
+    readNote: (id: string) => Promise<{ id: string; title: string; content: string } | null>;
+    listNotebooks: () => Promise<Array<{ id: string; name: string; noteCount: number }>>;
+    createNote: (title: string, content: string, notebookId?: string) => Promise<{ id: string }>;
+  }
+): void {
+  registry.register({
+    name: 'search_notes',
+    description: 'Search notes by keyword query. Returns matching note IDs, titles, and snippets.',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search query' },
+        limit: { type: 'number', description: 'Max results (default 10)' },
+      },
+      required: ['query'],
+    },
+    requiresConfirmation: false,
+    execute: async args => {
+      const results = await deps.searchNotes(args.query as string, (args.limit as number) ?? 10);
+      return { ok: true, content: JSON.stringify(results) };
+    },
+  });
+
+  registry.register({
+    name: 'read_note',
+    description: 'Read the full content of a note by its ID.',
+    parameters: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Note ID' },
+      },
+      required: ['id'],
+    },
+    requiresConfirmation: false,
+    execute: async args => {
+      const note = await deps.readNote(args.id as string);
+      if (!note) return { ok: false, content: 'Note not found', error: 'Note not found' };
+      return { ok: true, content: JSON.stringify(note) };
+    },
+  });
+
+  registry.register({
+    name: 'list_notebooks',
+    description: 'List all notebooks with their names and note counts.',
+    parameters: {
+      type: 'object',
+      properties: {},
+    },
+    requiresConfirmation: false,
+    execute: async () => {
+      const notebooks = await deps.listNotebooks();
+      return { ok: true, content: JSON.stringify(notebooks) };
+    },
+  });
+
+  registry.register({
+    name: 'create_note',
+    description: 'Create a new note in a notebook.',
+    parameters: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'Note title' },
+        content: { type: 'string', description: 'Note content in markdown' },
+        notebookId: {
+          type: 'string',
+          description: 'Target notebook ID (optional, uses default)',
+        },
+      },
+      required: ['title', 'content'],
+    },
+    requiresConfirmation: true,
+    execute: async args => {
+      const result = await deps.createNote(
+        args.title as string,
+        args.content as string,
+        args.notebookId as string | undefined
+      );
+      return { ok: true, content: JSON.stringify(result) };
+    },
+  });
+
+  registry.register({
+    name: 'insert_text',
+    description: 'Insert text into the current note at the cursor position or at the end.',
+    parameters: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'Text to insert' },
+        position: {
+          type: 'string',
+          description: "Where to insert: 'cursor' (default) or 'end'",
+        },
+      },
+      required: ['text'],
+    },
+    requiresConfirmation: true,
+    rendererOnly: true,
+    execute: async () => {
+      // Execution handled by ipc-ai.ts via executeToolInRenderer
+      return { ok: false, content: 'Not reachable', error: 'Renderer tool called without IPC' };
+    },
+  });
+
+  registry.register({
+    name: 'replace_selection',
+    description: 'Replace the currently selected text in the editor.',
+    parameters: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'Replacement text' },
+      },
+      required: ['text'],
+    },
+    requiresConfirmation: true,
+    rendererOnly: true,
+    execute: async () => {
+      // Execution handled by ipc-ai.ts via executeToolInRenderer
+      return { ok: false, content: 'Not reachable', error: 'Renderer tool called without IPC' };
+    },
+  });
+}