fix: AI chat receives live editor content instead of stale disk content

handleContentChange now syncs content to tab state on every editor
change (not just on Cmd+S save). This ensures the AI panel's context
snapshot always contains the current editor body, fixing the bug where
the AI reported empty note bodies for unsaved edits.

Root cause: pendingContentRef buffered content for save but never
updated notes.tabs[].content, so activeTab?.content (used by the AI
context builder) always reflected the last-saved disk content.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude-pid

@@ -1 +1 @@
-45402
+91305

.codescenerc

@@ -0,0 +1,9 @@
+{
+  "exclude": [
+    "tools/",
+    "scripts/",
+    "src-tauri/gen/",
+    "coverage/",
+    "dist/"
+  ]
+}

.github/workflows/release.yml

@@ -55,6 +55,11 @@ jobs:
           node-version: '22'
           cache: 'pnpm'
 
+      - name: Setup Bun (required for bundle-qmd.sh)
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@stable
         with:
@@ -80,6 +85,24 @@ jobs:
           jq --arg v "$VERSION" '.version = $v' src-tauri/tauri.conf.json > tmp.json && mv tmp.json src-tauri/tauri.conf.json
           sed -i '' "s/^version = \".*\"/version = \"$VERSION\"/" src-tauri/Cargo.toml
 
+      - name: Import Apple Developer certificate into keychain
+        env:
+          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
+          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+        run: |
+          # Decode and import the certificate so codesign can use it in beforeBuildCommand
+          CERT_PATH="$RUNNER_TEMP/apple_cert.p12"
+          KEYCHAIN_PATH="$RUNNER_TEMP/laputa-signing.keychain-db"
+          KEYCHAIN_PASSWORD="$(uuidgen)"
+          echo "$APPLE_CERTIFICATE" | base64 --decode > "$CERT_PATH"
+          security create-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
+          security set-keychain-settings -lut 21600 "$KEYCHAIN_PATH"
+          security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
+          security import "$CERT_PATH" -P "$APPLE_CERTIFICATE_PASSWORD" -A -t cert -f pkcs12 -k "$KEYCHAIN_PATH"
+          security list-keychain -d user -s "$KEYCHAIN_PATH"
+          security set-key-partition-list -S apple-tool:,apple: -s -k "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
+          echo "KEYCHAIN_PATH=$KEYCHAIN_PATH" >> "$GITHUB_ENV"
+
       - name: Build Tauri app (with signing + notarization)
         env:
           TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
@@ -153,7 +176,7 @@ jobs:
           REPO="refactoringhq/laputa-app"
 
           ARM_SIG=$(cat updater-aarch64/*.app.tar.gz.sig)
-          ARM_DMG=$(ls dmg-aarch64/*.dmg | xargs basename)
+          ARM_TARBALL=$(ls updater-aarch64/*.app.tar.gz | xargs basename)
 
           cat > latest.json << EOF
           {
@@ -163,7 +186,7 @@ jobs:
             "platforms": {
               "darwin-aarch64": {
                 "signature": "${ARM_SIG}",
-                "url": "https://github.com/${REPO}/releases/download/${TAG}/${ARM_DMG}"
+                "url": "https://github.com/${REPO}/releases/download/${TAG}/${ARM_TARBALL}"
               }
             }
           }

.husky/pre-push

@@ -47,26 +47,26 @@ fi
 
 # ── 0. TypeScript + Vite build ──────────────────────────────────────────
 echo ""
-echo "📦 [0/4] TypeScript + Vite build..."
+echo "📦 [0/5] TypeScript + Vite build..."
 pnpm exec tsc --noEmit
 pnpm build
 echo "  ✅ Build OK"
 
 # ── 1. Frontend coverage (≥70%) — includes all unit tests ───────────────
 echo ""
-echo "📊 [1/4] Frontend tests + coverage (≥70%)..."
+echo "📊 [1/5] Frontend tests + coverage (≥70%)..."
 pnpm test:coverage --silent
 echo "  ✅ Frontend coverage OK"
 
 # ── 2. Rust lint (clippy + fmt) — fast, run before coverage ─────────────
 echo ""
 if [ "$RUST_CHANGED" = true ]; then
-  echo "🔧 [2/4] Clippy + rustfmt..."
+  echo "🔧 [2/5] Clippy + rustfmt..."
   cargo clippy --manifest-path=src-tauri/Cargo.toml -- -D warnings
   cargo fmt --manifest-path=src-tauri/Cargo.toml -- --check
   echo "  ✅ Rust lint OK"
 else
-  echo "⏭️  [2/4] Rust lint — skipped (no src-tauri/ changes)"
+  echo "⏭️  [2/5] Rust lint — skipped (no src-tauri/ changes)"
 fi
 
 # ── 3. Rust coverage (≥85% lines) ──────────────────────────────────────
@@ -75,9 +75,9 @@ if [ "$RUST_CHANGED" = true ]; then
   LLVM_COV_FLAGS="--no-clean"
   if [ "${LAPUTA_FULL_COVERAGE:-0}" = "1" ]; then
     LLVM_COV_FLAGS=""
-    echo "🦀 [3/4] Rust coverage — FULL (LAPUTA_FULL_COVERAGE=1)..."
+    echo "🦀 [3/5] Rust coverage — FULL (LAPUTA_FULL_COVERAGE=1)..."
   else
-    echo "🦀 [3/4] Rust coverage (≥85%, incremental)..."
+    echo "🦀 [3/5] Rust coverage (≥85%, incremental)..."
   fi
   # Unset GIT_DIR so git tests create isolated repos without inheriting hook context
   unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE
@@ -90,12 +90,23 @@ if [ "$RUST_CHANGED" = true ]; then
     -- --test-threads=1
   echo "  ✅ Rust coverage OK"
 else
-  echo "⏭️  [3/4] Rust coverage — skipped (no src-tauri/ changes)"
+  echo "⏭️  [3/5] Rust coverage — skipped (no src-tauri/ changes)"
 fi
 
-# ── 4. CodeScene code health gate (≥9.2) ────────────────────────────────
+# ── 4. Playwright smoke tests (if any exist) ──────────────────────────
 echo ""
-echo "🏥 [4/4] CodeScene code health gate (≥9.2)..."
+SMOKE_FILES=$(find tests/smoke -name '*.spec.ts' 2>/dev/null | head -1)
+if [ -n "$SMOKE_FILES" ]; then
+  echo "🎭 [4/5] Playwright smoke tests..."
+  pnpm playwright:smoke
+  echo "  ✅ Smoke tests OK"
+else
+  echo "⏭️  [4/5] Playwright smoke tests — skipped (no tests/smoke/*.spec.ts)"
+fi
+
+# ── 5. CodeScene code health gate (≥9.2) ────────────────────────────────
+echo ""
+echo "🏥 [5/5] CodeScene code health gate (≥9.2)..."
 if [ -z "$CODESCENE_PAT" ] || [ -z "$CODESCENE_PROJECT_ID" ]; then
   echo "  ⚠️  CODESCENE_PAT or CODESCENE_PROJECT_ID not set — skipping"
 else

CLAUDE.md

@@ -15,11 +15,40 @@ pre_commit_code_health_safeguard    # CodeScene ≥9.2 — if it fails, fix stru
 
 **CI is a safety net, not a discovery tool.** If CI catches something you didn't catch locally, that's a process failure. All these tools are available locally — use them while you code, not just at the end.
 
-## ⛔ BEFORE FIRING laputa-task-done — QA on real vault
+## ⛔ BEFORE FIRING laputa-task-done — Two-phase QA (mandatory)
 
-> **⚠️ TAURI APP ONLY — never test in browser (`pnpm dev` / localhost)**
-> The browser dev server has a fake HTTP server (`/api/*` routes, mock handlers) that doesn't exist in the real Tauri app.
-> If it works in the browser but crashes in Tauri, it's broken. Always test in `pnpm tauri dev`.
+### Phase 1: Playwright browser QA (headless, you do this yourself)
+
+Test every acceptance criterion using Playwright against the dev server **before** marking done. This catches 80% of bugs before Brian sees them.
+
+```bash
+# 1. Start the dev server (use your worktree port)
+pnpm dev --port <N> &
+DEV_PID=$!
+sleep 3  # wait for vite to be ready
+
+# 2. Run Playwright smoke test for this task
+BASE_URL="http://localhost:<N>" npx playwright test tests/smoke/<slug>.spec.ts
+
+# 3. Or run all smoke tests
+BASE_URL="http://localhost:<N>" pnpm playwright:smoke
+
+kill $DEV_PID
+```
+
+**What to test in Playwright:**
+- Every command palette entry from the spec → open `Cmd+K`, type the command name, verify it appears and executes
+- Every keyboard shortcut → send keydown events, verify UI state changes
+- Every UI element described in the spec → verify it renders, is focusable, responds to Tab
+- Edge cases: empty state, long text, rapid keypresses
+
+**Playwright is non-negotiable even if tests pass.** Unit tests verify code; Playwright verifies the user experience in the real browser. Both are required.
+
+> **⚠️ Browser dev server limits**: the dev server uses mock Tauri handlers (`src/mock-tauri.ts`) — file system operations, git commands, and native dialogs are mocked. Test those via `pnpm tauri dev` in Phase 2 if the task touches them.
+
+### Phase 2: Native Tauri QA (Brian does this after you push)
+
+Brian installs the release build and runs keyboard-only QA on the native app. You don't do Phase 2 — but Phase 1 must pass before you fire the done signal, or Brian's QA will fail and the task goes back to To Rework.
 
 1. Acquire lockfile: `echo $$ > /tmp/laputa-qa.lock && trap "rm -f /tmp/laputa-qa.lock" EXIT`
 2. Kill other instances: `pkill -x laputa 2>/dev/null || true; sleep 1`
@@ -29,6 +58,19 @@ pre_commit_code_health_safeguard    # CodeScene ≥9.2 — if it fails, fix stru
 6. If task touches file save: verify `git -C ~/Laputa diff` shows changes
 7. If QA fails → fix and re-run. Do NOT fire the signal until it passes.
 
+**⚠️ QA ≠ tests. QA means using the app as a user.**
+- "Tests pass" is NOT QA. Tests verify code, QA verifies the user experience.
+- The QA comment must describe what you did as a user: "Opened app → Cmd+K → typed 'Trash' → pressed Enter → note disappeared from list → restarted app → note still not visible"
+- Every QA comment must include: the exact keyboard/command palette steps used, what was visible before and after, and any edge case tested.
+- If you cannot test a feature using keyboard only (osascript shortcuts + command palette), the feature is not keyboard-first → QA fails.
+
+**⚠️ Test in a clean environment when the feature depends on state.**
+If a feature involves indexing, fresh installs, first-time setup, or anything that only runs once:
+- **Do not test in the existing dev vault** — it already has the state you're trying to test.
+- **Create a new empty vault** for the test: Cmd+K → "New Vault" (or equivalent), pick a temp folder like `/tmp/test-vault-<slug>`, then test the full first-time flow from scratch.
+- This applies to: search indexing, vault init, getting-started setup, any "on first open" logic.
+- If you can't reproduce the fresh-install scenario locally, the feature is untestable → do not fire done.
+
 Fire done signal only after QA passes:
 ```bash
 rm -f /tmp/laputa-qa.lock
@@ -73,14 +115,70 @@ Tauri v2 + React + TypeScript desktop app. Reads a vault of markdown files with
 
 - **Never develop on `main`** — always on `task/<slug>` branch
 - **Commit every 20–30 min** — atomic commits, one concern per commit (`feat:`, `fix:`, `refactor:`, `test:`, `docs:`)
-- **Update docs/** when changing architecture, abstractions, or significant design
-- **Test as you go** — write tests alongside code, not after
+- **Update docs/** when changing architecture, abstractions, or significant design (mandatory — see rule below)
 
-## Testing
+## ⛔ DOCS — Keep docs/ in sync with code (mandatory)
+
+After any significant feature change, update the relevant `docs/` files **in the same commit**:
+
+- **`docs/ARCHITECTURE.md`** — stack, system overview, component structure, Tauri commands, data flow, backend modules
+- **`docs/ABSTRACTIONS.md`** — domain models, VaultEntry fields, entity types, key abstractions, integration patterns
+- **`docs/GETTING-STARTED.md`** — directory structure, key files, common tasks, test commands, onboarding
+
+**What counts as "significant":**
+- Adding a new Tauri command or backend module
+- Adding a new major component, hook, or feature (not a bugfix)
+- Changing the data model (VaultEntry fields, new types, new config files)
+- Adding a new integration (API, service, transport)
+- Changing the architecture (new panels, new state management, new build steps)
+
+**How to update:**
+1. Read the relevant doc section before making changes
+2. After your code changes, update the doc to reflect the new state
+3. Commit doc changes together with the code — not in a separate follow-up commit
+
+If unsure whether a change is "significant", err on the side of updating. Stale docs are worse than slightly verbose docs.
+
+## TDD — Red/Green/Refactor (mandatory)
+
+**Always use test-driven development.** No production code without a failing test first.
+
+The loop:
+1. **Red** — write a failing test that describes the behavior you want. Run it, confirm it fails for the right reason.
+2. **Green** — write the minimum code to make the test pass. No more, no less.
+3. **Refactor** — clean up the code (extract, rename, simplify) while keeping tests green.
+4. **Commit** — one red/green/refactor cycle = one atomic commit.
+5. Repeat.
+
+**Why this matters:**
+- Forces you to think about behavior before implementation
+- Produces only code that's actually needed (no speculative abstractions)
+- Tests written first are always behavioral and structure-insensitive by construction
+- Tiny cycles = fast feedback, smaller diffs, easier to review
+
+**For bug fixes:**
+1. Write a failing test that reproduces the bug (this is the regression test)
+2. Fix the bug until the test passes
+3. Commit both together: `fix: [bug] — regression test added`
+
+**For Rust:**
+```bash
+cargo watch -x test   # run tests on every save
+```
+
+**For frontend:**
+```bash
+pnpm test --watch     # run tests on every save
+```
+
+**When to deviate:** Pure UI layout/styling work with no logic is the only exception. Everything else — hooks, utilities, Rust commands, state management — must be TDD.
+
+## Testing (quality bar)
 
 - Unit tests must cover real business logic, not "component renders"
-- Every bug fixed manually → add a regression test
-- Every new feature → new tests for new behavior paths
+- Tests test **behavior** (what the code does), not **structure** (how it does it)
+- Every bug fixed → regression test that would have caught it
+- Every new feature → TDD from the start (see above)
 - `pnpm test:coverage` and `cargo llvm-cov` must pass before committing
 
 ## Design File (every UI task)
@@ -103,6 +201,33 @@ node -e "const f=JSON.parse(require('fs').readFileSync('ui-design.pen','utf8'));
 echo '{"children":[],"variables":{}}' > design/<slug>.pen
 ```
 
+## Vault File Retrocompatibility (mandatory for every feature that adds vault files)
+
+Laputa vaults are long-lived. New app versions must work on existing vaults that were created before a feature existed.
+
+**Rule: never assume a vault file exists. Always auto-create if missing.**
+
+Every feature that depends on a vault file or folder must:
+1. **Auto-bootstrap on vault open** — check if the required file/folder exists; if not, create it with defaults. This must be silent and non-blocking.
+2. **Be idempotent** — creating defaults must be safe to run multiple times (never overwrite user data).
+3. **Expose a repair command** — add a `Cmd+K` command like "Restore Default Themes" or "Repair Vault Config" that explicitly re-creates missing files. Users can run this if something is broken.
+
+**General "Repair Vault" command** — when adding a new vault file dependency, register it with the central repair system so that `Cmd+K → "Repair Vault"` fixes everything in one shot.
+
+**Pattern:**
+```
+on vault open:
+  if file X does not exist → create X with defaults  ← silent auto-repair
+  if file X exists but is malformed → log warning, use defaults (don't crash)
+
+on "Repair Vault" command:
+  for each known vault file/folder:
+    if missing → create with defaults
+    if present → leave untouched (idempotent)
+```
+
+This principle applies to: themes, config files, type files, any `.laputa/` subfolder, or any file Laputa expects to find in a vault.
+
 ## macOS / Tauri Gotchas
 
 - `Option+N` on macOS → special chars (`¡`, `™`), not `key:'N'`. Use `e.code` or `Cmd+N`.
@@ -118,6 +243,28 @@ bash ~/.openclaw/skills/laputa-qa/scripts/shortcut.sh "command" "s"
 bash ~/.openclaw/skills/laputa-qa/scripts/click.sh 400 300   # logical coords
 ```
 
+## Menu Bar Discoverability (mandatory for every new command)
+
+The command palette is powerful but not discoverable — users must already know a command exists to find it. The macOS menu bar is where users discover what an app can do.
+
+**Rule: every significant command palette entry must also appear in the menu bar.**
+
+When adding a new command to the palette:
+1. **Identify the right menu bar group** — File, Edit, View, Note, Vault, or create a new group if needed
+2. **Add a menu item** with the same label as the palette command
+3. **Show the keyboard shortcut** next to the menu item (if one exists)
+4. **If no direct shortcut exists**, still add the menu item — it's discoverable and triggers the same action
+
+The menu bar should be organized around what Laputa does:
+- **File** — new note, open vault, switch vault, close
+- **Edit** — undo, redo, find, note actions (rename, trash, duplicate)
+- **View** — view modes, zoom, sidebar, panels
+- **Note** — note-specific actions (move to trash, archive, properties)
+- **Vault** — vault management (themes, config, repair, sync)
+- **Window / Help** — standard macOS items
+
+**This is a QA requirement:** before marking any task done, verify that every new command palette entry has a corresponding menu bar item.
+
 ## Keyboard-First Principle (mandatory for every new feature)
 
 Every feature must be reachable via keyboard. This is both a UX requirement and a QA requirement — Brian tests the native app using keyboard only (osascript key events, no mouse).

demo-vault-v2/.laputa/settings.json

@@ -0,0 +1,3 @@
+{
+  "theme": null
+}

demo-vault-v2/_themes/dark.json

@@ -0,0 +1,33 @@
+{
+  "name": "Dark",
+  "description": "Dark variant with deep navy tones",
+  "colors": {
+    "background": "#0f0f1a",
+    "foreground": "#e0e0e0",
+    "card": "#16162a",
+    "popover": "#1e1e3a",
+    "primary": "#155DFF",
+    "primary-foreground": "#FFFFFF",
+    "secondary": "#2a2a4a",
+    "secondary-foreground": "#e0e0e0",
+    "muted": "#1e1e3a",
+    "muted-foreground": "#888888",
+    "accent": "#2a2a4a",
+    "accent-foreground": "#e0e0e0",
+    "destructive": "#f44336",
+    "border": "#2a2a4a",
+    "input": "#2a2a4a",
+    "ring": "#155DFF",
+    "sidebar-background": "#1a1a2e",
+    "sidebar-foreground": "#e0e0e0",
+    "sidebar-border": "#2a2a4a",
+    "sidebar-accent": "#2a2a4a"
+  },
+  "typography": {
+    "font-family": "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
+    "font-size-base": "14px"
+  },
+  "spacing": {
+    "sidebar-width": "250px"
+  }
+}

demo-vault-v2/_themes/default.json

@@ -0,0 +1,33 @@
+{
+  "name": "Default",
+  "description": "Light theme with warm, paper-like tones",
+  "colors": {
+    "background": "#FFFFFF",
+    "foreground": "#37352F",
+    "card": "#FFFFFF",
+    "popover": "#FFFFFF",
+    "primary": "#155DFF",
+    "primary-foreground": "#FFFFFF",
+    "secondary": "#EBEBEA",
+    "secondary-foreground": "#37352F",
+    "muted": "#F0F0EF",
+    "muted-foreground": "#787774",
+    "accent": "#EBEBEA",
+    "accent-foreground": "#37352F",
+    "destructive": "#E03E3E",
+    "border": "#E9E9E7",
+    "input": "#E9E9E7",
+    "ring": "#155DFF",
+    "sidebar-background": "#F7F6F3",
+    "sidebar-foreground": "#37352F",
+    "sidebar-border": "#E9E9E7",
+    "sidebar-accent": "#EBEBEA"
+  },
+  "typography": {
+    "font-family": "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
+    "font-size-base": "14px"
+  },
+  "spacing": {
+    "sidebar-width": "250px"
+  }
+}

demo-vault-v2/_themes/minimal.json

@@ -0,0 +1,33 @@
+{
+  "name": "Minimal",
+  "description": "High contrast, minimal chrome",
+  "colors": {
+    "background": "#FAFAFA",
+    "foreground": "#111111",
+    "card": "#FFFFFF",
+    "popover": "#FFFFFF",
+    "primary": "#000000",
+    "primary-foreground": "#FFFFFF",
+    "secondary": "#F0F0F0",
+    "secondary-foreground": "#111111",
+    "muted": "#F5F5F5",
+    "muted-foreground": "#666666",
+    "accent": "#F0F0F0",
+    "accent-foreground": "#111111",
+    "destructive": "#CC0000",
+    "border": "#E0E0E0",
+    "input": "#E0E0E0",
+    "ring": "#000000",
+    "sidebar-background": "#F5F5F5",
+    "sidebar-foreground": "#111111",
+    "sidebar-border": "#E0E0E0",
+    "sidebar-accent": "#E8E8E8"
+  },
+  "typography": {
+    "font-family": "'SF Mono', 'Menlo', monospace",
+    "font-size-base": "13px"
+  },
+  "spacing": {
+    "sidebar-width": "220px"
+  }
+}

demo-vault-v2/_themes/untitled-2.json

@@ -0,0 +1,33 @@
+{
+  "colors": {
+    "accent": "#EBEBEA",
+    "accent-foreground": "#37352F",
+    "background": "#FFFFFF",
+    "border": "#E9E9E7",
+    "card": "#FFFFFF",
+    "destructive": "#E03E3E",
+    "foreground": "#37352F",
+    "input": "#E9E9E7",
+    "muted": "#F0F0EF",
+    "muted-foreground": "#787774",
+    "popover": "#FFFFFF",
+    "primary": "#155DFF",
+    "primary-foreground": "#FFFFFF",
+    "ring": "#155DFF",
+    "secondary": "#EBEBEA",
+    "secondary-foreground": "#37352F",
+    "sidebar-accent": "#EBEBEA",
+    "sidebar-background": "#F7F6F3",
+    "sidebar-border": "#E9E9E7",
+    "sidebar-foreground": "#37352F"
+  },
+  "description": "Light theme with warm, paper-like tones",
+  "name": "Untitled Theme",
+  "spacing": {
+    "sidebar-width": "250px"
+  },
+  "typography": {
+    "font-family": "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
+    "font-size-base": "14px"
+  }
+}

demo-vault-v2/_themes/untitled-3.json

@@ -0,0 +1,33 @@
+{
+  "colors": {
+    "accent": "#EBEBEA",
+    "accent-foreground": "#37352F",
+    "background": "#FFFFFF",
+    "border": "#E9E9E7",
+    "card": "#FFFFFF",
+    "destructive": "#E03E3E",
+    "foreground": "#37352F",
+    "input": "#E9E9E7",
+    "muted": "#F0F0EF",
+    "muted-foreground": "#787774",
+    "popover": "#FFFFFF",
+    "primary": "#155DFF",
+    "primary-foreground": "#FFFFFF",
+    "ring": "#155DFF",
+    "secondary": "#EBEBEA",
+    "secondary-foreground": "#37352F",
+    "sidebar-accent": "#EBEBEA",
+    "sidebar-background": "#F7F6F3",
+    "sidebar-border": "#E9E9E7",
+    "sidebar-foreground": "#37352F"
+  },
+  "description": "Light theme with warm, paper-like tones",
+  "name": "Untitled Theme",
+  "spacing": {
+    "sidebar-width": "250px"
+  },
+  "typography": {
+    "font-family": "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
+    "font-size-base": "14px"
+  }
+}

demo-vault-v2/_themes/untitled-4.json

@@ -0,0 +1,33 @@
+{
+  "colors": {
+    "accent": "#EBEBEA",
+    "accent-foreground": "#37352F",
+    "background": "#FFFFFF",
+    "border": "#E9E9E7",
+    "card": "#FFFFFF",
+    "destructive": "#E03E3E",
+    "foreground": "#37352F",
+    "input": "#E9E9E7",
+    "muted": "#F0F0EF",
+    "muted-foreground": "#787774",
+    "popover": "#FFFFFF",
+    "primary": "#155DFF",
+    "primary-foreground": "#FFFFFF",
+    "ring": "#155DFF",
+    "secondary": "#EBEBEA",
+    "secondary-foreground": "#37352F",
+    "sidebar-accent": "#EBEBEA",
+    "sidebar-background": "#F7F6F3",
+    "sidebar-border": "#E9E9E7",
+    "sidebar-foreground": "#37352F"
+  },
+  "description": "Light theme with warm, paper-like tones",
+  "name": "Untitled Theme",
+  "spacing": {
+    "sidebar-width": "250px"
+  },
+  "typography": {
+    "font-family": "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
+    "font-size-base": "14px"
+  }
+}

demo-vault-v2/_themes/untitled.json

@@ -0,0 +1,33 @@
+{
+  "colors": {
+    "accent": "#EBEBEA",
+    "accent-foreground": "#37352F",
+    "background": "#FFFFFF",
+    "border": "#E9E9E7",
+    "card": "#FFFFFF",
+    "destructive": "#E03E3E",
+    "foreground": "#37352F",
+    "input": "#E9E9E7",
+    "muted": "#F0F0EF",
+    "muted-foreground": "#787774",
+    "popover": "#FFFFFF",
+    "primary": "#155DFF",
+    "primary-foreground": "#FFFFFF",
+    "ring": "#155DFF",
+    "secondary": "#EBEBEA",
+    "secondary-foreground": "#37352F",
+    "sidebar-accent": "#EBEBEA",
+    "sidebar-background": "#F7F6F3",
+    "sidebar-border": "#E9E9E7",
+    "sidebar-foreground": "#37352F"
+  },
+  "description": "Light theme with warm, paper-like tones",
+  "name": "Untitled Theme",
+  "spacing": {
+    "sidebar-width": "250px"
+  },
+  "typography": {
+    "font-family": "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
+    "font-size-base": "14px"
+  }
+}

demo-vault-v2/config/ui.config.md

@@ -0,0 +1,5 @@
+---
+type: config
+zoom: 1.3
+view_mode: all
+---

demo-vault-v2/note/note-the-innovators-dilemma.md

@@ -4,6 +4,8 @@ Is A: Note
 Author: "Clayton Christensen"
 Topics: ["[[topic-saas-business]]"]
 URL: "https://example.com/innovators-dilemma"
+trashed: true
+trashed_at: 2026-03-04
 ---
 # The Innovator's Dilemma
 *Clayton Christensen*

demo-vault-v2/note/wikilinks-qa-test.md

@@ -0,0 +1,5 @@
+# Wikilinks QA Test
+
+See [[ProjectX]] and [[Team Goals|Goals]] for details on the project timeline.
+
+This is a test note for QA purposes.

demo-vault-v2/theme/dark.md

@@ -0,0 +1,54 @@
+---
+Is A: Theme
+Description: Dark variant with deep navy tones
+background: "#0f0f1a"
+foreground: "#e0e0e0"
+card: "#16162a"
+popover: "#1e1e3a"
+primary: "#155DFF"
+primary-foreground: "#FFFFFF"
+secondary: "#2a2a4a"
+secondary-foreground: "#e0e0e0"
+muted: "#1e1e3a"
+muted-foreground: "#888888"
+accent: "#2a2a4a"
+accent-foreground: "#e0e0e0"
+destructive: "#f44336"
+border: "#2a2a4a"
+input: "#2a2a4a"
+ring: "#155DFF"
+sidebar: "#1a1a2e"
+sidebar-foreground: "#e0e0e0"
+sidebar-border: "#2a2a4a"
+sidebar-accent: "#2a2a4a"
+text-primary: "#e0e0e0"
+text-secondary: "#888888"
+text-muted: "#666666"
+text-heading: "#e0e0e0"
+bg-primary: "#0f0f1a"
+bg-sidebar: "#1a1a2e"
+bg-hover: "#2a2a4a"
+bg-hover-subtle: "#1e1e3a"
+bg-selected: "#155DFF22"
+border-primary: "#2a2a4a"
+accent-blue: "#155DFF"
+accent-green: "#00B38B"
+accent-orange: "#D9730D"
+accent-red: "#f44336"
+accent-purple: "#A932FF"
+accent-yellow: "#F0B100"
+accent-blue-light: "#155DFF33"
+accent-green-light: "#00B38B33"
+accent-purple-light: "#A932FF33"
+accent-red-light: "#f4433633"
+accent-yellow-light: "#F0B10033"
+font-family: "'Inter', -apple-system, BlinkMacSystemFont, sans-serif"
+font-size-base: 14px
+editor-font-size: 16
+editor-line-height: 1.5
+editor-max-width: 720
+---
+
+# Dark Theme
+
+A dark theme with deep navy tones for comfortable night-time reading.

demo-vault-v2/theme/default.md

@@ -0,0 +1,54 @@
+---
+Is A: Theme
+Description: Light theme with warm, paper-like tones
+background: "#FFFFFF"
+foreground: "#37352F"
+card: "#FFFFFF"
+popover: "#FFFFFF"
+primary: "#155DFF"
+primary-foreground: "#FFFFFF"
+secondary: "#EBEBEA"
+secondary-foreground: "#37352F"
+muted: "#F0F0EF"
+muted-foreground: "#787774"
+accent: "#EBEBEA"
+accent-foreground: "#37352F"
+destructive: "#E03E3E"
+border: "#E9E9E7"
+input: "#E9E9E7"
+ring: "#155DFF"
+sidebar: "#F7F6F3"
+sidebar-foreground: "#37352F"
+sidebar-border: "#E9E9E7"
+sidebar-accent: "#EBEBEA"
+text-primary: "#37352F"
+text-secondary: "#787774"
+text-muted: "#B4B4B4"
+text-heading: "#37352F"
+bg-primary: "#FFFFFF"
+bg-sidebar: "#F7F6F3"
+bg-hover: "#EBEBEA"
+bg-hover-subtle: "#F0F0EF"
+bg-selected: "#E8F4FE"
+border-primary: "#E9E9E7"
+accent-blue: "#155DFF"
+accent-green: "#00B38B"
+accent-orange: "#D9730D"
+accent-red: "#E03E3E"
+accent-purple: "#A932FF"
+accent-yellow: "#F0B100"
+accent-blue-light: "#155DFF14"
+accent-green-light: "#00B38B14"
+accent-purple-light: "#A932FF14"
+accent-red-light: "#E03E3E14"
+accent-yellow-light: "#F0B10014"
+font-family: "'Inter', -apple-system, BlinkMacSystemFont, sans-serif"
+font-size-base: 14px
+editor-font-size: 16
+editor-line-height: 1.5
+editor-max-width: 720
+---
+
+# Default Theme
+
+The default light theme for Laputa. Clean and warm, inspired by Notion.

demo-vault-v2/theme/minimal.md

@@ -0,0 +1,54 @@
+---
+Is A: Theme
+Description: High contrast, minimal chrome
+background: "#FAFAFA"
+foreground: "#111111"
+card: "#FFFFFF"
+popover: "#FFFFFF"
+primary: "#000000"
+primary-foreground: "#FFFFFF"
+secondary: "#F0F0F0"
+secondary-foreground: "#111111"
+muted: "#F5F5F5"
+muted-foreground: "#666666"
+accent: "#F0F0F0"
+accent-foreground: "#111111"
+destructive: "#CC0000"
+border: "#E0E0E0"
+input: "#E0E0E0"
+ring: "#000000"
+sidebar: "#F5F5F5"
+sidebar-foreground: "#111111"
+sidebar-border: "#E0E0E0"
+sidebar-accent: "#E8E8E8"
+text-primary: "#111111"
+text-secondary: "#666666"
+text-muted: "#999999"
+text-heading: "#111111"
+bg-primary: "#FAFAFA"
+bg-sidebar: "#F5F5F5"
+bg-hover: "#EBEBEB"
+bg-hover-subtle: "#F5F5F5"
+bg-selected: "#00000014"
+border-primary: "#E0E0E0"
+accent-blue: "#000000"
+accent-green: "#006600"
+accent-orange: "#996600"
+accent-red: "#CC0000"
+accent-purple: "#660099"
+accent-yellow: "#996600"
+accent-blue-light: "#00000014"
+accent-green-light: "#00660014"
+accent-purple-light: "#66009914"
+accent-red-light: "#CC000014"
+accent-yellow-light: "#99660014"
+font-family: "'SF Mono', 'Menlo', monospace"
+font-size-base: 13px
+editor-font-size: 15
+editor-line-height: 1.6
+editor-max-width: 680
+---
+
+# Minimal Theme
+
+High contrast, minimal chrome. Monospace typography throughout.

design/mcp-autodetect-status-bar.pen

@@ -0,0 +1 @@
+{"children":[],"variables":{}}

docs/ABSTRACTIONS.md

@@ -8,24 +8,32 @@ All data lives in markdown files with YAML frontmatter. There is no database —
 
 ### VaultEntry
 
-The core data type representing a single note, defined identically in Rust (`src-tauri/src/vault.rs`) and TypeScript (`src/types.ts`):
+The core data type representing a single note, defined in Rust (`src-tauri/src/vault/mod.rs`) and TypeScript (`src/types.ts`):
 
 ```typescript
 // src/types.ts
 interface VaultEntry {
-  path: string          // Absolute file path: /Users/luca/Laputa/project/my-project.md
-  filename: string      // Just the filename: my-project.md
-  title: string         // Extracted from first # heading, or filename as fallback
-  isA: string | null    // Entity type: Project, Procedure, Person, etc.
-  aliases: string[]     // Alternative names for wikilink resolution
-  belongsTo: string[]   // Parent relationships (wikilinks)
-  relatedTo: string[]   // Related entity links (wikilinks)
-  status: string | null // Active, Done, Paused, Archived, Dropped
-  owner: string | null  // Person responsible
-  cadence: string | null // Update frequency: Weekly, Monthly, etc.
+  path: string              // Absolute file path
+  filename: string          // Just the filename
+  title: string             // From first # heading, or filename fallback
+  isA: string | null        // Entity type: Project, Procedure, Person, etc.
+  aliases: string[]         // Alternative names for wikilink resolution
+  belongsTo: string[]       // Parent relationships (wikilinks)
+  relatedTo: string[]       // Related entity links (wikilinks)
+  relationships: Record<string, string[]>  // All frontmatter fields containing wikilinks
+  outgoingLinks: string[]   // All [[wikilinks]] found in note body
+  status: string | null     // Active, Done, Paused, Archived, Dropped
+  owner: string | null      // Person responsible
+  cadence: string | null    // Update frequency: Weekly, Monthly, etc.
   modifiedAt: number | null // Unix timestamp (seconds)
   createdAt: number | null  // Unix timestamp (seconds)
   fileSize: number
+  wordCount: number | null  // Body word count (excludes frontmatter)
+  snippet: string | null    // First 200 chars of body
+  archived: boolean         // Archived flag
+  trashed: boolean          // Trashed flag
+  trashedAt: number | null  // When trashed (for auto-purge)
+  properties: Record<string, string>  // Scalar frontmatter fields (custom properties)
 }
 ```
 
@@ -47,26 +55,41 @@ Entity type is inferred from the folder structure. The vault is organized by typ
 ├── quarter/        → "Quarter"
 ├── journal/        → "Journal"
 ├── essay/          → "Essay"
-└── evergreen/      → "Evergreen"
+├── evergreen/      → "Evergreen"
+├── theme/          → "Theme"      ← vault-based themes
+└── config/         → "Config"     ← meta-configuration files (agents.md, etc.)
 ```
 
-Mapping logic lives in `vault.rs:parse_md_file()`. If a folder doesn't match any known type, the folder name is capitalized and used as-is.
+Mapping logic lives in `vault/mod.rs:parse_md_file()`. If a folder doesn't match any known type, the folder name is capitalized and used as-is.
 
 ### Types as Files
 
 Each entity type can have a corresponding **type document** in the `type/` folder (e.g., `type/project.md`, `type/person.md`). Type documents:
 
 - Have `Is A: Type` in their frontmatter
-- Describe what the type means, its expected properties, and how it relates to other types
-- Are navigable entities — they appear in the sidebar under "Types" and can be opened/edited like any other note
+- Define type metadata: icon, color, order, sidebar label, template, sort, view, visibility
+- Are navigable entities — they appear in the sidebar under "Types" and can be opened/edited like any note
 - Serve as the "definition" for their type category
 
+**Type document properties** (read by Rust and used in the UI):
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `icon` | string | Phosphor icon name (kebab-case, e.g., "cooking-pot") |
+| `color` | string | Accent color: red, purple, blue, green, yellow, orange |
+| `order` | number | Sidebar display order (lower = higher priority) |
+| `sidebar_label` | string | Custom label overriding auto-pluralization |
+| `template` | string | Markdown template for new notes of this type |
+| `sort` | string | Default sort: "modified:desc", "title:asc", "property:Priority:asc" |
+| `view` | string | Default view mode: "all", "editor-list", "editor-only" |
+| `visible` | bool | Whether type appears in sidebar (default: true) |
+
 **Type relationship**: When any entry has an `isA` value (e.g., "Project"), the Rust backend automatically adds a `"Type"` entry to its `relationships` map pointing to `[[type/project]]`. This makes the type navigable from the Inspector panel.
 
 **UI behavior**:
-- Clicking a section group header (e.g., "Projects") pins the type document at the top of the NoteList if it exists, with instances listed below
+- Clicking a section group header pins the type document at the top of the NoteList if it exists
 - Viewing a type document in entity view shows an "Instances" group listing all entries of that type
-- The Type field in the Inspector properties panel is rendered as a clickable chip that navigates to the type document
+- The Type field in the Inspector is rendered as a clickable chip that navigates to the type document
 
 ### Frontmatter Format
 
@@ -88,24 +111,48 @@ aliases:
 ---
 ```
 
-Supported value types (defined in `src-tauri/src/frontmatter.rs` as `FrontmatterValue`):
+Supported value types (defined in `src-tauri/src/frontmatter/yaml.rs` as `FrontmatterValue`):
 - **String**: `status: Active`
 - **Number**: `priority: 5`
 - **Bool**: `archived: true`
 - **List**: Multi-line `  - item` or inline `[item1, item2]`
 - **Null**: `owner:` (empty value)
 
+### Custom Relationships
+
+The Rust parser scans all frontmatter keys for fields containing `[[wikilinks]]`. Any non-standard field with wikilink values is captured in the `relationships` HashMap:
+
+```yaml
+---
+Topics:
+  - "[[topic/writing]]"
+  - "[[topic/productivity]]"
+Key People:
+  - "[[person/matteo-cellini]]"
+---
+```
+
+Becomes: `relationships["Topics"] = ["[[topic/writing]]", "[[topic/productivity]]"]`
+
+This enables arbitrary, extensible relationship types without code changes.
+
+### Outgoing Links
+
+All `[[wikilinks]]` in the note body (not frontmatter) are extracted by regex and stored in `outgoingLinks`. Used for backlink detection and relationship graphs.
+
 ### Title Extraction
 
-Title comes from the first `# Heading` in the markdown body. If none is found, the filename (without `.md`) is used as fallback. This logic lives in `vault.rs:extract_title()`.
+Title comes from the first `# Heading` in the markdown body. If none is found, the filename (without `.md`) is used as fallback. Logic in `vault/parsing.rs:extract_title()`.
 
 ### Sidebar Selection
 
 Navigation state is modeled as a discriminated union:
 
 ```typescript
+type SidebarFilter = 'all' | 'archived' | 'trash' | 'changes' | 'pulse'
+
 type SidebarSelection =
-  | { kind: 'filter'; filter: 'all' | 'favorites' }
+  | { kind: 'filter'; filter: SidebarFilter }
   | { kind: 'sectionGroup'; type: string }    // e.g. type: 'Project'
   | { kind: 'entity'; entry: VaultEntry }      // specific entity selected
   | { kind: 'topic'; entry: VaultEntry }        // topic selected
@@ -115,49 +162,60 @@ type SidebarSelection =
 
 ### Vault Scanning (Rust)
 
-`vault::scan_vault(path)` in `src-tauri/src/vault.rs`:
+`vault::scan_vault(path)` in `src-tauri/src/vault/mod.rs`:
 
 1. Validates the path exists and is a directory
-2. Uses `walkdir` to recursively traverse the directory (follows symlinks)
+2. Uses `walkdir` to recursively traverse (follows symlinks)
 3. Filters to `.md` files only
 4. For each file, calls `parse_md_file()`:
-   - Reads file content with `fs::read_to_string()`
+   - Reads content with `fs::read_to_string()`
    - Parses frontmatter with `gray_matter::Matter::<YAML>`
    - Extracts title from first `#` heading
-   - Infers entity type from parent folder name
-   - Parses dates (`created_at`, `created_time`) as ISO 8601 to Unix timestamps
-   - Collects file metadata (size, modification time)
-5. Sorts results by `modified_at` descending (newest first)
+   - Infers entity type from parent folder name (or explicit `Is A`/`type` frontmatter)
+   - Parses dates as ISO 8601 to Unix timestamps
+   - Extracts relationships, outgoing links, custom properties, word count, snippet
+5. Sorts by `modified_at` descending
 6. Skips unparseable files with a warning log
 
+### Vault Caching
+
+`vault::scan_vault_cached(path)` wraps scanning with git-based caching:
+
+1. Reads `.laputa-cache.json` if it exists
+2. Compares cache version, vault path, and git HEAD commit hash
+3. If cache is valid and same commit → only re-parse uncommitted changed files
+4. If different commit → use `git diff` to find changed files → selective re-parse
+5. If no cache → full scan
+6. Writes updated cache after every scan
+
 ### Frontmatter Manipulation (Rust)
 
-`frontmatter::update_frontmatter_content()` in `src-tauri/src/frontmatter.rs` performs line-by-line YAML editing:
+`frontmatter/ops.rs:update_frontmatter_content()` performs line-by-line YAML editing:
 
 1. Finds the frontmatter block between `---` delimiters
-2. Iterates through lines looking for the target key (handles quoted keys like `"Is A"`)
+2. Iterates through lines looking for the target key
 3. If found: replaces the value (consuming multi-line list items if present)
-4. If not found: appends the new key-value at the end of the frontmatter
-5. If no frontmatter exists: creates a new `---` block with the key-value
+4. If not found: appends the new key-value at the end
+5. If no frontmatter exists: creates a new `---` block
 
 The `with_frontmatter()` helper wraps this in a read-transform-write cycle on the actual file.
 
 ### Content Loading
 
-- **Tauri mode**: Content is loaded on-demand when a tab is opened via `invoke('get_note_content', { path })`
-- **Browser mode**: All content is loaded at startup from `MOCK_CONTENT` in `mock-tauri.ts`
+- **Tauri mode**: Content loaded on-demand when a tab is opened via `invoke('get_note_content', { path })`
+- **Browser mode**: All content loaded at startup from mock data
 - Content for backlink detection (`allContent`) is stored in memory as `Record<string, string>`
 
 ## Git Integration
 
-Git operations live in `src-tauri/src/git.rs`. All operations shell out to the `git` CLI (not libgit2).
+Git operations live in `src-tauri/src/git/`. All operations shell out to the `git` CLI (not libgit2).
 
 ### Data Types
 
 ```typescript
 interface GitCommit {
-  hash: string       // Full SHA-1
-  shortHash: string  // First 7 chars
+  hash: string
+  shortHash: string
   message: string
   author: string
   date: number       // Unix timestamp
@@ -168,32 +226,54 @@ interface ModifiedFile {
   relativePath: string  // Relative to vault root
   status: 'modified' | 'added' | 'deleted' | 'untracked' | 'renamed'
 }
+
+interface PulseCommit {
+  hash: string
+  shortHash: string
+  message: string
+  date: number
+  githubUrl: string | null
+  files: PulseFile[]
+  added: number
+  modified: number
+  deleted: number
+}
 ```
 
 ### Operations
 
-| Operation | Git command | Notes |
-|-----------|------------|-------|
-| File history | `git log --format=%H\|%h\|%an\|%aI\|%s -n 20 -- <file>` | Last 20 commits for a file |
-| Modified files | `git status --porcelain` | Filtered to `.md` files only |
-| File diff | `git diff -- <file>`, fallback to `--cached`, then synthetic diff for untracked | Unified diff format |
-| Commit | `git add -A && git commit -m "<message>"` | Stages all changes |
-| Push | `git push` | Pushes to upstream of current branch |
+| Module | Operation | Notes |
+|--------|-----------|-------|
+| `history.rs` | File history | `git log` — last 20 commits per file |
+| `status.rs` | Modified files | `git status --porcelain` — filtered to `.md` |
+| `status.rs` | File diff | `git diff`, fallback to `--cached`, then synthetic for untracked |
+| `commit.rs` | Commit | `git add -A && git commit -m "..."` |
+| `remote.rs` | Pull / Push | `git pull --rebase` / `git push` |
+| `conflict.rs` | Conflict resolution | Detect conflicts, resolve with ours/theirs/manual |
+| `pulse.rs` | Activity feed | `git log` with `--name-status` for file changes |
+
+### Auto-Sync
+
+`useAutoSync` hook handles automatic git sync:
+- Configurable interval (from app settings: `auto_pull_interval_minutes`)
+- Pulls on interval, pushes after commits
+- Detects merge conflicts → opens `ConflictResolverModal`
 
 ### Frontend Integration
 
-- **Modified file badges**: Loaded at startup, shown in sidebar and breadcrumb bar
-- **Diff view**: Loaded on-demand when user clicks the diff toggle in the breadcrumb bar
-- **Git history**: Loaded when active tab changes, shown in Inspector panel
-- **Commit dialog**: Triggered from sidebar, runs commit + push
+- **Modified file badges**: Orange dots in sidebar and tab bar
+- **Diff view**: Toggle in breadcrumb bar → shows unified diff
+- **Git history**: Shown in Inspector panel for active note
+- **Commit dialog**: Triggered from sidebar or Cmd+K
+- **Pulse view**: Activity feed when Pulse filter is selected
 
 ## BlockNote Customization
 
-The editor uses [BlockNote](https://www.blocknotejs.org/) (not CodeMirror 6) for rich text editing.
+The editor uses [BlockNote](https://www.blocknotejs.org/) for rich text editing, with CodeMirror 6 available as a raw editing alternative.
 
 ### Custom Wikilink Inline Content
 
-Defined in `src/components/Editor.tsx`:
+Defined in `src/components/editorSchema.tsx`:
 
 ```typescript
 const WikiLink = createReactInlineContentSpec(
@@ -202,69 +282,196 @@ const WikiLink = createReactInlineContentSpec(
     propSchema: { target: { default: "" } },
     content: "none",
   },
-  {
-    render: (props) => (
-      <span className="wikilink" data-target={props.inlineContent.props.target}>
-        {props.inlineContent.props.target}
-      </span>
-    ),
-  }
+  { render: (props) => <span className="wikilink">...</span> }
 )
-
-const schema = BlockNoteSchema.create({
-  inlineContentSpecs: {
-    ...defaultInlineContentSpecs,
-    wikilink: WikiLink,
-  },
-})
 ```
 
 ### Markdown-to-BlockNote Pipeline
 
-Since BlockNote doesn't natively understand `[[wikilinks]]`, content goes through a preprocessing pipeline in `src/utils/wikilinks.ts`:
-
 ```
 Raw markdown
   → splitFrontmatter() → [yaml, body]
   → preProcessWikilinks(body) → replaces [[target]] with Unicode placeholder tokens
   → editor.tryParseMarkdownToBlocks() → BlockNote block tree
-  → injectWikilinks(blocks) → walks tree, replaces placeholder text with wikilink inline content nodes
+  → injectWikilinks(blocks) → walks tree, replaces placeholders with wikilink inline content nodes
   → editor.replaceBlocks()
 ```
 
-Placeholder tokens use `\u2039` (single left-pointing angle quotation mark) and `\u203A` (single right-pointing) to avoid colliding with markdown syntax.
+Placeholder tokens use `\u2039` and `\u203A` to avoid colliding with markdown syntax.
+
+### BlockNote-to-Markdown Pipeline (Save)
+
+```
+BlockNote blocks
+  → editor.blocksToMarkdownLossy()
+  → postProcessWikilinks() → restore [[target]] syntax from wikilink nodes
+  → prepend frontmatter yaml
+  → invoke('save_note_content', { path, content })
+```
 
 ### Wikilink Navigation
 
 Two navigation mechanisms:
 
-1. **Click handler**: A DOM event listener on `.editor__blocknote-container` catches clicks on `.wikilink` elements and calls `onNavigateWikilink(target)`.
+1. **Click handler**: DOM event listener on `.editor__blocknote-container` catches clicks on `.wikilink` elements → `onNavigateWikilink(target)`.
+2. **Suggestion menu**: Typing `[[` triggers `SuggestionMenuController` with filtered vault entries.
 
-2. **Suggestion menu**: Typing `[[` triggers BlockNote's `SuggestionMenuController`, which shows a filtered list of all vault entries. Selecting one inserts a wikilink inline content node.
+Wikilink resolution (`useNoteActions`) uses fuzzy matching: exact title → alias → path stem → filename stem → slug-to-words.
 
-Wikilink resolution in `useNoteActions.handleNavigateWikilink()` uses fuzzy matching:
-- Exact title match
-- Alias match
-- Path stem match (e.g., `person/matteo-cellini`)
-- Filename stem match
-- Slug-to-words match (e.g., `matteo-cellini` → `matteo cellini`)
+### Raw Editor Mode
+
+Toggle via Cmd+K → "Raw Editor" or breadcrumb bar button. Uses CodeMirror 6 (`useCodeMirror` hook) to edit the raw markdown + frontmatter directly. Changes saved via the same `save_note_content` command.
 
 ## Theme System
 
 See [THEMING.md](./THEMING.md) for the full theme system documentation.
 
-In brief: `src/theme.json` defines editor typography and styling as nested JSON. The `useEditorTheme` hook flattens it into CSS custom properties that are applied as inline styles on the BlockNote container.
+### Overview
+
+Two-layer theming:
+1. **Global CSS variables** (`src/index.css`): App-wide colors via `:root`, bridged to Tailwind v4
+2. **Editor theme** (`src/theme.json`): BlockNote typography, flattened to CSS vars by `useEditorTheme`
+
+### Vault-Based Themes
+
+Themes are markdown notes in `theme/` with `Is A: Theme` frontmatter. Each property becomes a CSS variable with `--` prefix.
+
+```yaml
+---
+Is A: Theme
+Description: Light theme with warm, paper-like tones
+background: "#FFFFFF"
+foreground: "#37352F"
+accent-blue: "#155DFF"
+editor-font-size: 16
+editor-line-height: 1.5
+---
+```
+
+### ThemeManager
+
+`useThemeManager` hook manages the theme lifecycle:
+
+```typescript
+interface ThemeManager {
+  themes: ThemeFile[]
+  activeThemeId: string | null
+  activeTheme: ThemeFile | null
+  isDark: boolean
+  switchTheme(themeId: string): Promise<void>
+  createTheme(name?: string): Promise<string>
+  reloadThemes(): Promise<void>
+  updateThemeProperty(key: string, value: string): Promise<void>
+}
+```
+
+- Detects dark backgrounds via luminance calculation → sets `color-scheme` and `data-theme-mode`
+- Live preview: re-applies when active theme note is saved
+- Three built-in themes: Default (light), Dark (deep navy), Minimal (high contrast)
+- Legacy JSON themes (`_themes/*.json`) supported for backward compatibility
+
+### Theme Property Editor
+
+`ThemePropertyEditor` component provides an interactive UI for editing theme properties. Uses `themeSchema.ts` to determine input types (color picker, number slider, text field) based on property names and values.
 
 ## Inspector Abstraction
 
-The Inspector panel (`src/components/Inspector.tsx`) is composed of four sub-panels:
+The Inspector panel (`src/components/Inspector.tsx`) is composed of sub-panels:
 
-1. **DynamicPropertiesPanel** (`src/components/DynamicPropertiesPanel.tsx`): Renders frontmatter as editable key-value pairs with two distinct sections:
-   - **Editable properties** (top): frontmatter fields the user can modify — shown with interactive hover styling (`hover:bg-muted`), cursor pointer, and click-to-edit. Includes Type badge, Status pill, boolean toggles, array tag pills, and text fields.
-   - **Info section** (bottom, separated by border): read-only derived metadata — Modified, Created, Words, File Size. Uses muted text color (`--text-muted`) with no hover states or click interaction. These fields are computed from file metadata and content, not from frontmatter.
-   - Keys in `SKIP_KEYS` (`aliases`, `notion_id`, `workspace`, `is_a`, `Is A`) are hidden from the editable section since they are either internal or already displayed elsewhere (e.g., `is_a` is shown via the TypeRow badge).
-2. **Relationships**: Shows `belongs_to` and `related_to` wikilinks as clickable chips.
-3. **Backlinks**: Scans `allContent` for notes that reference the current note via `[[title]]` or `[[path]]`.
-4. **Git History**: Shows the last few commits from `gitHistory` state.
+1. **DynamicPropertiesPanel** (`src/components/DynamicPropertiesPanel.tsx`): Renders frontmatter as editable key-value pairs:
+   - **Editable properties** (top): Type badge, Status pill with dropdown, boolean toggles, array tag pills, text fields. Click-to-edit interaction.
+   - **Info section** (bottom, separated by border): Read-only derived metadata — Modified, Created, Words, File Size. Uses muted styling with no interaction.
+   - Keys in `SKIP_KEYS` (`aliases`, `notion_id`, `workspace`, `is_a`, `Is A`) are hidden from the editable section.
 
-Frontmatter parsing on the TypeScript side is handled by `src/utils/frontmatter.ts:parseFrontmatter()`, a lightweight YAML parser that handles strings, booleans, inline arrays, and multi-line lists.
+2. **RelationshipsPanel**: Shows `belongs_to`, `related_to`, and all custom relationship fields as clickable wikilink chips.
+
+3. **BacklinksPanel**: Scans `allContent` for notes that reference the current note via `[[title]]` or `[[path]]`.
+
+4. **GitHistoryPanel**: Shows recent commits from file history with relative timestamps.
+
+## Search & Indexing
+
+### Search Modes
+
+```typescript
+type SearchMode = 'keyword' | 'semantic' | 'hybrid'
+
+interface SearchResult {
+  title: string
+  path: string
+  snippet: string
+  score: number
+}
+
+interface SearchResponse {
+  results: SearchResult[]
+  elapsedMs: number
+}
+```
+
+### Search Integration
+
+`SearchPanel` component provides the search UI:
+- Mode selector (keyword/semantic/hybrid)
+- Real-time results as user types
+- Click result to open note in editor
+- Shows relevance score and snippet
+
+### Indexing
+
+Managed by `useIndexing` hook:
+- Checks index status on vault load
+- Two-phase indexing: scanning (parse files) → embedding (generate vectors)
+- Progress streamed via Tauri events
+- Incremental updates after git sync
+- Metadata persisted in `.laputa-index.json`
+
+## Vault Management
+
+### Vault Switching
+
+`useVaultSwitcher` hook manages multiple vaults:
+- Persists vault list to `~/.config/com.laputa.app/vaults.json`
+- Switching closes all tabs and resets sidebar
+- Supports adding, removing, hiding/restoring vaults
+- Default vault: Getting Started demo vault
+
+### Vault Config
+
+Per-vault settings stored in `config/ui.config.md`:
+- Editable as a normal note (YAML frontmatter)
+- Managed by `useVaultConfig` hook and `vaultConfigStore`
+- Settings: zoom, view mode, tag colors, status colors, property display modes
+- One-time migration from localStorage (`configMigration.ts`)
+
+### Getting Started / Onboarding
+
+`useOnboarding` hook detects first launch:
+- If vault path doesn't exist → show `WelcomeScreen`
+- User can create Getting Started vault or open existing folder
+- Welcome state tracked in localStorage (`laputa_welcome_dismissed`)
+
+### GitHub Integration
+
+Device Authorization Flow for GitHub-backed vaults:
+- `GitHubDeviceFlow` component handles OAuth
+- `GitHubVaultModal` for cloning existing repos or creating new ones
+- Token persisted in app settings for future git operations
+- `SettingsPanel` shows connection status with disconnect option
+
+## Settings
+
+App-level settings persisted at `~/.config/com.laputa.app/settings.json`:
+
+```typescript
+interface Settings {
+  anthropic_key: string | null
+  openai_key: string | null
+  google_key: string | null
+  github_token: string | null
+  github_username: string | null
+  auto_pull_interval_minutes: number | null
+}
+```
+
+Managed by `useSettings` hook and `SettingsPanel` component.

docs/ARCHITECTURE.md

@@ -9,46 +9,58 @@ Laputa is a personal knowledge and life management desktop app. It reads a vault
 | Desktop shell | Tauri v2 | 2.10.0 |
 | Frontend | React + TypeScript | React 19, TS 5.9 |
 | Editor | BlockNote | 0.46.2 |
+| Raw editor | CodeMirror 6 | - |
 | Styling | Tailwind CSS v4 + CSS variables | 4.1.18 |
 | UI primitives | Radix UI + shadcn/ui | - |
 | Icons | Phosphor Icons + Lucide | - |
 | Build | Vite | 7.3.1 |
 | Backend language | Rust (edition 2021) | 1.77.2 |
 | Frontmatter parsing | gray_matter | 0.2 |
-| AI | Anthropic Claude API (Haiku 3.5 default) | - |
+| AI (in-app chat) | Anthropic Claude API (Haiku 3.5 default) | - |
+| AI (agent panel) | Claude CLI subprocess (streaming NDJSON) | - |
+| Search | qmd (keyword + semantic + hybrid) | - |
 | MCP | @modelcontextprotocol/sdk | 1.0 |
-| Tests | Vitest (unit), Playwright (E2E), cargo test (Rust) | - |
+| Tests | Vitest (unit), Playwright (E2E/smoke), cargo test (Rust) | - |
 | Package manager | pnpm | - |
 
 ## System Overview
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                      Tauri v2 Window                        │
-│                                                             │
-│  ┌─────────────────── React Frontend ───────────────────┐   │
-│  │                                                      │   │
-│  │  App.tsx (orchestrator)                               │   │
-│  │    ├── Sidebar         (navigation + filters)        │   │
-│  │    ├── NoteList         (filtered note list)          │   │
-│  │    ├── Editor           (BlockNote + tabs + diff)     │   │
-│  │    │     ├── Inspector  (metadata + relationships)    │   │
-│  │    │     └── AIChatPanel (AI assistant + context)     │   │
-│  │    ├── StatusBar        (footer info)                 │   │
-│  │    └── Modals (QuickOpen, CreateNote, CommitDialog)  │   │
-│  │                                                      │   │
-│  └──────────────┬──────────┬──────────────────────────┘   │
-│                 │          │                               │
-│        Tauri IPC│     Vite Proxy / WS                     │
-│  ┌──────────────▼────┐ ┌──▼───────────────────────────┐   │
-│  │   Rust Backend    │ │   External Services          │   │
-│  │  lib.rs → 10 cmds │ │  Anthropic API (Claude)      │   │
-│  │  vault/           │ │  MCP Server (ws://9710)      │   │
-│  │  frontmatter.rs   │ │                              │   │
-│  │  git.rs           │ └──────────────────────────────┘   │
-│  │  ai_chat.rs       │                                    │
-│  └───────────────────┘                                    │
-└─────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────┐
+│                       Tauri v2 Window                            │
+│                                                                  │
+│  ┌──────────────────── React Frontend ────────────────────────┐  │
+│  │                                                            │  │
+│  │  App.tsx (orchestrator)                                    │  │
+│  │    ├── WelcomeScreen     (onboarding / vault-missing)     │  │
+│  │    ├── Sidebar           (navigation + filters + types)   │  │
+│  │    ├── NoteList / PulseView (filtered list / activity)    │  │
+│  │    ├── Editor            (BlockNote + tabs + diff + raw)  │  │
+│  │    │     ├── Inspector   (metadata + relationships)       │  │
+│  │    │     ├── AIChatPanel (API-based chat)                 │  │
+│  │    │     └── AiPanel     (Claude CLI agent + tools)       │  │
+│  │    ├── SearchPanel       (keyword/semantic/hybrid search) │  │
+│  │    ├── SettingsPanel     (API keys, GitHub, zoom, theme)  │  │
+│  │    ├── StatusBar         (vault picker + sync + version)  │  │
+│  │    ├── CommandPalette    (Cmd+K fuzzy command launcher)   │  │
+│  │    └── Modals (CreateNote, CreateType, Commit, GitHub)    │  │
+│  │                                                            │  │
+│  └──────────────┬──────────┬──────────────────────────────────┘  │
+│                 │          │                                      │
+│        Tauri IPC│     Vite Proxy / WS                            │
+│  ┌──────────────▼────┐ ┌──▼────────────────────────────────┐    │
+│  │   Rust Backend    │ │   External Services               │    │
+│  │  lib.rs → 61 cmds │ │  Anthropic API (Claude chat)      │    │
+│  │  vault/           │ │  Claude CLI (agent subprocess)    │    │
+│  │  frontmatter/     │ │  MCP Server (ws://9710, 9711)     │    │
+│  │  git/             │ │  qmd (search/indexing engine)     │    │
+│  │  github/          │ │  GitHub API (OAuth, repos, clone) │    │
+│  │  theme/           │ │                                   │    │
+│  │  search.rs        │ └───────────────────────────────────┘    │
+│  │  indexing.rs      │                                           │
+│  │  claude_cli.rs    │                                           │
+│  └───────────────────┘                                           │
+└──────────────────────────────────────────────────────────────────┘
 ```
 
 ## Four-Panel Layout
@@ -57,71 +69,90 @@ Laputa is a personal knowledge and life management desktop app. It reads a vault
 ┌────────┬─────────────┬─────────────────────────┬────────────┐
 │Sidebar │ Note List   │ Editor                  │ Inspector  │
 │(250px) │ (300px)     │ (flex-1)                │ (280px)    │
-│        │             │                         │ OR         │
-│ All    │ [Search]    │ [Tab Bar]               │ AI Chat    │
-│ Favs   │ [Type Pill] │ [Breadcrumb Bar]        │            │
+│        │ OR          │                         │ OR         │
+│ All    │ Pulse View  │ [Tab Bar]               │ AI Chat    │
+│ Favs   │             │ [Breadcrumb Bar]        │ OR         │
+│ Changes│ [Search]    │                         │ AI Agent   │
+│ Pulse  │ [Sort/Filt] │ # My Note               │            │
 │        │             │                         │ Context    │
-│Projects│ Note 1      │ # My Note               │ Messages   │
-│Experim.│ Note 2      │                         │ Actions    │
-│Respons.│ Note 3      │ Content here...         │ Input      │
-│Procedu.│ ...         │                         │            │
-│People  │             │                         │            │
+│Projects│ Note 1      │ Content here...         │ Messages   │
+│Experim.│ Note 2      │ (BlockNote or Raw)      │ Actions    │
+│Respons.│ Note 3      │                         │ Input      │
+│People  │ ...         │                         │            │
 │Events  │             │                         │            │
 │Topics  │             │                         │            │
 ├────────┴─────────────┴─────────────────────────┴────────────┤
-│ StatusBar: v0.4.2 │ main │ Synced 2m ago │ 3 pending  notes│
-└─────────────────────────────────────────────────────────────┘
+│ StatusBar: v0.4.2 │ main │ Synced 2m ago │ Vault: ~/Laputa │
+└──────────────────────────────────────────────────────────────┘
 ```
 
-- **Sidebar** (150-400px, resizable): Top-level filters (All Notes, Favorites) and collapsible section groups (Projects, Experiments, Responsibilities, etc.)
-- **Note List** (200-500px, resizable): Filtered list of notes matching the sidebar selection. Shows snippets, modified dates, relationship groups, and orange dot indicators for uncommitted modified notes.
-- **Editor** (flex, fills remaining space): Tab bar (with orange modified dots on dirty tabs), breadcrumb bar with word count and modified indicator, BlockNote editor with wikilink support. Can toggle to diff view for modified files. Decomposed into focused subcomponents: `Editor` (orchestrator), `EditorContent` (breadcrumb + editor/diff views), `EditorRightPanel` (inspector/AI toggle), `SingleEditorView` (BlockNote + suggestions), with hooks `useDiffMode` and `useEditorFocus`.
-- **Inspector / AI Chat** (200-500px or 40px collapsed): Toggles between Inspector (frontmatter, relationships, backlinks, git history) and AI Chat panel. The Sparkle icon in the breadcrumb bar toggles between them.
+- **Sidebar** (150-400px, resizable): Top-level filters (All Notes, Favorites, Changes, Pulse) and collapsible type-based section groups. Each type can have a custom icon, color, sort, and visibility set via its type document in `type/`.
+- **Note List / Pulse View** (200-500px, resizable): When a section group or filter is selected, shows filtered notes with snippets, modified dates, and status indicators. When Pulse filter is active, shows `PulseView` — a chronological git activity feed grouped by day.
+- **Editor** (flex, fills remaining space): Tab bar with modified dots, breadcrumb bar with word count, BlockNote rich text editor with wikilink support. Can toggle to diff view (modified files) or raw CodeMirror view. Decomposed into `Editor` (orchestrator), `EditorContent`, `EditorRightPanel`, `SingleEditorView`, with hooks `useDiffMode`, `useEditorFocus`, `useEditorSave`, `useRawMode`.
+- **Inspector / AI Chat / AI Agent** (200-500px or 40px collapsed): Toggles between Inspector (frontmatter, relationships, backlinks, git history), AI Chat panel (API-based), and AI Agent panel (Claude CLI subprocess with tool execution). The Sparkle icon in the breadcrumb bar toggles between them.
 
 Panels are separated by `ResizeHandle` components that support drag-to-resize.
 
-## AI Chat System
+## AI System
 
-### Architecture
+Laputa has two AI interfaces with distinct architectures:
 
-The AI chat feature has three layers:
+### AI Chat (AIChatPanel)
+
+Simple chat mode — no tool execution, streaming text responses.
 
 1. **Frontend** (`AIChatPanel` + `useAIChat` hook) — UI and state management
 2. **API Proxy** (Vite middleware in dev, Rust `ai_chat` command in Tauri) — routes to Anthropic
-3. **MCP Server** (`mcp-server/`) — vault operation tools for AI assistants
+3. **Context picker** — selected notes sent as system context with token estimation
 
-### Data Flow
+### AI Agent (AiPanel)
+
+Full agent mode — spawns Claude CLI as a subprocess with tool access and MCP vault integration.
+
+1. **Frontend** (`AiPanel` + `useAiAgent` hook) — streaming UI with reasoning blocks, tool action cards, and response display
+2. **Backend** (`claude_cli.rs`) — spawns `claude` binary with `--output-format stream-json`, parses NDJSON events
+3. **MCP Integration** — passes vault MCP config via `--mcp-config` flag so the agent can search, read, and modify vault notes
+
+#### Agent Event Flow
 
 ```
-User types message in AIChatPanel
-  → useAIChat.sendMessage(text)
-    → buildSystemPrompt(contextNotes, allContent, model)
-      → Assembles selected notes as system context
-      → Estimates tokens, truncates if needed
-    → streamChat(messages, systemPrompt, model, callbacks)
-      → POST /api/ai/chat (Vite proxy → Anthropic API)
-      → SSE stream parsed, chunks dispatched to onChunk callback
-      → UI updates in real-time as tokens arrive
-    → On completion: message added to conversation history
+User sends message in AiPanel
+  → useAiAgent.sendMessage(text, references)
+    → buildContextSnapshot(activeNote, linkedNotes, openTabs)
+    → invoke('stream_claude_agent', { message, systemPrompt, vaultPath })
+      → Rust spawns: claude -p <msg> --output-format stream-json --mcp-config <json>
+      → NDJSON lines parsed into ClaudeStreamEvent variants:
+          Init, TextDelta, ThinkingDelta, ToolStart, ToolDone, Result, Error, Done
+      → Events emitted via Tauri: app_handle.emit("claude-agent-stream", &event)
+    → Frontend listener routes events:
+        onText → accumulate response (revealed on Done)
+        onThinking → show reasoning block (collapsed on first text)
+        onToolStart → add AiActionCard with spinner
+        onToolDone → update card with output
+        onDone → reveal full response, detect file operations
 ```
 
-### Context Picker
+#### File Operation Detection
 
-The context picker controls which notes are sent to the AI as context:
+When the agent writes or edits vault files, `useAiAgent` detects this from tool inputs (Write/Edit tool JSON) and calls `onFileCreated` or `onFileModified` callbacks to trigger vault reload.
 
-- **Current note** is auto-added when the panel opens
-- **Add button** opens a search dropdown to select additional notes
-- **Token estimation** shows approximate context size (~4 chars/token)
-- **Truncation** kicks in when context exceeds 60% of model limit (108k tokens)
-- Context pills show selected notes with remove buttons
+### Context Building
 
-### API Key Management
+Both AI modes use context from the active note and linked entries. The agent panel (`ai-context.ts`) builds a structured JSON snapshot:
 
-- Stored in `localStorage` under key `laputa:anthropic-api-key`
-- Configurable via the key icon in the AI Chat header
-- When no key is set, falls back to mock responses for testing
+```json
+{
+  "activeNote": { "path", "title", "type", "frontmatter", "content" },
+  "linkedNotes": [{ "path", "title", "content" }],
+  "openTabs": [{ "title", "snippet" }],
+  "vaultMetadata": { "noteTypes", "stats", "filter" },
+  "references": [{ "title", "path", "type" }]
+}
+```
 
-### Models
+Token budget: 60% of 180k context limit (~108k tokens max). Active note gets priority, then linked notes, then truncation.
+
+### Models (Chat mode)
 
 | Model | ID | Use case |
 |-------|----|----------|
@@ -129,11 +160,17 @@ The context picker controls which notes are sent to the AI as context:
 | Sonnet 4 | `claude-sonnet-4-20250514` | Balanced |
 | Opus 4 | `claude-opus-4-20250514` | Most capable |
 
-### MCP Server
+### API Key Management
+
+- Stored in app settings (`~/.config/com.laputa.app/settings.json`) under `anthropic_key`
+- Configurable via Settings panel (also supports `openai_key`, `google_key`)
+- Claude CLI (agent mode) uses its own authentication — no API key needed
+
+## MCP Server
 
 The MCP server (`mcp-server/`) exposes vault operations as tools for AI assistants (Claude Code, Cursor, or any MCP-compatible client).
 
-#### Tool Surface (14 tools)
+### Tool Surface (14 tools)
 
 | Tool | Params | Description |
 |------|--------|-------------|
@@ -146,30 +183,28 @@ The MCP server (`mcp-server/`) exposes vault operations as tools for AI assistan
 | `delete_note` | `path` | Delete a note file from the vault |
 | `link_notes` | `source_path, property, target_title` | Add a target to an array property in frontmatter |
 | `list_notes` | `[type_filter], [sort]` | List all notes, optionally filtered by type |
-| `vault_context` | — | Get vault summary: entity types + 20 recent notes |
+| `vault_context` | — | Get vault summary: entity types + 20 recent notes + configFiles |
 | `ui_open_note` | `path` | Open a note in the Laputa UI editor |
 | `ui_open_tab` | `path` | Open a note in a new UI tab |
 | `ui_highlight` | `element, [path]` | Highlight a UI element (editor, tab, properties, notelist) |
 | `ui_set_filter` | `type` | Set the sidebar filter to a specific type |
 
-#### Transports
+### Transports
 
 - **stdio** — standard MCP transport for Claude Code / Cursor (`node mcp-server/index.js`)
 - **WebSocket** — live bridge for Laputa app integration:
   - Port **9710**: Tool bridge — AI/Claude clients call vault tools here
   - Port **9711**: UI bridge — Frontend listens for UI action broadcasts from MCP tools
 
-#### Auto-Registration
+### Auto-Registration
 
 On app startup, Laputa automatically registers itself as an MCP server in:
 - `~/.claude/mcp.json` (Claude Code)
 - `~/.cursor/mcp.json` (Cursor)
 
-The registration is non-destructive (additive — preserves other MCP servers) and uses `upsert` semantics. The entry points to `mcp-server/index.js` with the active vault path as `VAULT_PATH` env var.
+Registration is non-destructive (additive, preserves other servers) and uses `upsert` semantics. The `useMcpStatus` hook tracks registration state (`checking | installed | not_installed | no_claude_cli`).
 
-Registration also runs from the frontend via the `useMcpRegistration` hook and `register_mcp_tools` Tauri command, ensuring the config stays up-to-date when the vault path changes.
-
-#### Architecture
+### Architecture
 
 ```
 ┌─────────────────────────────────────────────────────┐
@@ -200,16 +235,16 @@ The WebSocket bridge enables real-time vault operations from both the frontend a
 
 ```
 Frontend (useMcpBridge) ←→ ws://localhost:9710 ←→ ws-bridge.js ←→ vault.js
-MCP stdio tools         ←→ ws://localhost:9711 ←→ Frontend UI actions
+MCP stdio tools         ←→ ws://localhost:9711 ←→ Frontend UI actions (useAiActivity)
 ```
 
 **Tool bridge protocol** (port 9710):
 - Request: `{ "id": "req-1", "tool": "search_notes", "args": { "query": "test" } }`
 - Response: `{ "id": "req-1", "result": { ... } }`
-- Error: `{ "id": "req-1", "error": "message" }`
 
 **UI bridge protocol** (port 9711):
 - Broadcast: `{ "type": "ui_action", "action": "open_note", "path": "..." }`
+- `useAiActivity` hook receives these and applies them (highlight with 800ms feedback, open note, set filter, etc.)
 
 ### Rust MCP Module
 
@@ -223,29 +258,132 @@ MCP stdio tools         ←→ ws://localhost:9711 ←→ Frontend UI actions
 
 The `WsBridgeChild` state wrapper in `lib.rs` ensures the bridge process is killed on app exit via `RunEvent::Exit` handler.
 
-### Rust Backend (Tauri)
+## Search & Indexing
 
-The `ai_chat` Tauri command (`src-tauri/src/ai_chat.rs`) provides a non-streaming alternative:
-- Uses `reqwest` to call the Anthropic Messages API directly
-- API key from `ANTHROPIC_API_KEY` environment variable
-- Returns full response (not streamed)
-- Used in production Tauri builds where Vite proxy is unavailable
+### Search Engine
 
-### Files
+Search uses the external `qmd` binary (semantic search engine) with three modes:
 
-| File | Purpose |
-|------|---------|
-| `src/components/AIChatPanel.tsx` | Main UI: context bar, messages, input, quick actions |
-| `src/hooks/useAIChat.ts` | Chat state: messages, streaming, send/retry/clear |
-| `src/hooks/useMcpBridge.ts` | WebSocket client for MCP vault tool calls |
-| `src/hooks/useMcpRegistration.ts` | Auto-registers Laputa MCP on vault load |
-| `src/utils/ai-chat.ts` | API client, token estimation, context builder |
-| `src-tauri/src/ai_chat.rs` | Rust Anthropic API client (non-streaming) |
-| `src-tauri/src/mcp.rs` | MCP server spawning + config registration |
-| `mcp-server/index.js` | MCP server entry (stdio transport, 14 tools) |
-| `mcp-server/vault.js` | Vault file operations (9 functions) |
-| `mcp-server/ws-bridge.js` | WebSocket bridge server (tool + UI bridges) |
-| `mcp-server/test.js` | 26 unit tests for all vault.js functions |
+| Mode | Command | Description |
+|------|---------|-------------|
+| `keyword` | `qmd search` | Term matching (default) |
+| `semantic` | `qmd vsearch` | Vector similarity search |
+| `hybrid` | `qmd query` | Combined keyword + semantic |
+
+### Indexing Flow
+
+```
+Vault opened
+  → check_index_status() → parse qmd status output
+  → if stale or missing:
+    → start_indexing() (two phases):
+        Phase 1 (Scanning): qmd update — scan all .md files
+        Phase 2 (Embedding): qmd embed — generate vector embeddings
+    → Progress streamed via Tauri "indexing-progress" event
+    → Metadata saved to .laputa-index.json (last_indexed_commit, timestamp)
+  → run_incremental_update() for subsequent changes
+```
+
+Embedding failure is non-fatal — keyword search still works.
+
+### qmd Binary Resolution
+
+1. Bundled macOS app resource: `<app>/Contents/Resources/qmd/qmd`
+2. Dev mode: `CARGO_MANIFEST_DIR/resources/qmd/qmd`
+3. System locations: `~/.bun/bin/qmd`, `/usr/local/bin/qmd`, `/opt/homebrew/bin/qmd`
+4. PATH lookup via `which qmd`
+5. Auto-install via `bun install -g qmd` if missing
+
+## Vault Cache System
+
+The vault cache (`src-tauri/src/vault/cache.rs`) accelerates vault scanning using git-based incremental updates.
+
+### Cache File
+
+`.laputa-cache.json` at vault root. Stores: vault path, git HEAD commit hash, all VaultEntry objects. Version: v5 (bumped on VaultEntry field changes to force full rescan).
+
+### Three Cache Strategies
+
+1. **Same Commit (Cache Hit)**: Git HEAD matches cached hash → only re-parse uncommitted changed files via `git status --porcelain`
+2. **Different Commit (Incremental Update)**: Uses `git diff <old>..<new> --name-only` to find changed files + uncommitted changes → selective re-parse
+3. **No Cache / Corrupt Cache (Full Scan)**: Recursive `walkdir` of all `.md` files → full parse
+
+Cache auto-excludes itself from git via `.git/info/exclude`.
+
+## Theme System
+
+See [THEMING.md](./THEMING.md) for the full theme system documentation.
+
+### Two-Layer Architecture
+
+1. **Global CSS variables** (`src/index.css`): App-wide colors, borders, backgrounds. Bridged to Tailwind v4 via `@theme inline`.
+2. **Editor theme** (`src/theme.json`): BlockNote-specific typography. Flattened to CSS vars by `useEditorTheme`.
+
+### Vault-Based Themes
+
+Themes are markdown notes in the `theme/` folder with `Is A: Theme` frontmatter. Each frontmatter property becomes a CSS variable. Managed by `useThemeManager` hook and the `src-tauri/src/theme/` Rust module (create, seed, defaults).
+
+- **Vault settings**: `.laputa/settings.json` stores the active theme reference
+- **Legacy support**: `_themes/*.json` files still supported for backward compatibility
+- **Built-in themes**: Default (light), Dark, Minimal — auto-seeded on vault open
+- **Live preview**: Re-applies when the active theme note is saved
+
+## Vault Management
+
+### Vault List
+
+Persisted at `~/.config/com.laputa.app/vaults.json`:
+```json
+{
+  "vaults": [{ "label": "My Vault", "path": "/path/to/vault" }],
+  "active_vault": "/path/to/vault",
+  "hidden_defaults": []
+}
+```
+
+Managed by `useVaultSwitcher` hook. Switching vaults closes all tabs and resets sidebar.
+
+### Vault Config
+
+Per-vault UI settings stored in `config/ui.config.md` (YAML frontmatter in a markdown note):
+- `zoom`: Float zoom level (0.8–1.5)
+- `view_mode`: "all" | "editor-list" | "editor-only"
+- `tag_colors`, `status_colors`: Custom color overrides
+- `property_display_modes`: Property display preferences
+
+### Getting Started Vault
+
+On first launch, `useOnboarding` checks if the default vault exists. If not, shows `WelcomeScreen` with two options:
+- **Create Getting Started vault** → calls `create_getting_started_vault()` Tauri command
+- **Open an existing folder** → system file picker
+
+### GitHub OAuth Integration
+
+Implements GitHub Device Authorization Flow for cloning/creating GitHub-backed vaults.
+
+**Flow:**
+1. User clicks "Login with GitHub" in Settings panel
+2. `github_device_flow_start()` returns a user code + verification URL
+3. User authorizes at `github.com/login/device`
+4. App polls `github_device_flow_poll()` until authorized
+5. Token stored in `~/.config/com.laputa.app/settings.json`
+
+**Vault operations:**
+- `GitHubVaultModal`: Clone existing repo or create new private/public repo
+- `clone_repo()`: Clones with token-injected HTTPS URL
+- Token persists for future git push/pull operations
+
+## Pulse View
+
+`PulseView` is a git activity feed that replaces the NoteList when the Pulse filter is selected.
+
+- Groups commits by day ("Today", "Yesterday", or full date)
+- Shows commit message, short hash, timestamp, and changed files
+- Files have status icons (added/modified/deleted) and are clickable to open in editor
+- Links to GitHub commits when `githubUrl` is available
+- Infinite scroll pagination (20 commits per page) via Intersection Observer
+
+Backend: `get_vault_pulse` Tauri command parses `git log` with `--name-status`.
 
 ## Data Flow
 
@@ -253,93 +391,201 @@ The `ai_chat` Tauri command (`src-tauri/src/ai_chat.rs`) provides a non-streamin
 
 ```
 1. Tauri setup:
-   a. run_startup_tasks() → purge trash, migrate frontmatter, register MCP config
+   a. run_startup_tasks() → purge trash, migrate frontmatter, seed themes, migrate AGENTS.md, seed config files, register MCP
    b. spawn_ws_bridge() → start MCP WebSocket bridge (ports 9710, 9711)
 2. App mounts
-3. useVaultLoader fires:
-   a. isTauri() ? invoke('list_vault') : mockInvoke('list_vault')
-      → VaultEntry[] stored in state
-   b. Load all content (mock mode) or on-demand (Tauri mode)
-   c. invoke('get_modified_files') → ModifiedFile[] stored in state
-   d. useMcpRegistration → invoke('register_mcp_tools') → ensures MCP config current
-4. User clicks note in NoteList
-4. useNoteActions.handleSelectNote:
-   a. invoke('get_note_content') → raw markdown string
+3. useOnboarding checks vault exists → WelcomeScreen if not
+4. useVaultLoader fires:
+   a. invoke('list_vault', { path }) → scan_vault_cached() → VaultEntry[]
+   b. Load modified files via invoke('get_modified_files')
+   c. useMcpStatus → register MCP if needed
+   d. useThemeManager → load and apply active theme
+   e. useIndexing → check index status, trigger incremental update if needed
+5. User clicks note in NoteList
+6. useNoteActions.handleSelectNote:
+   a. invoke('get_note_content') → raw markdown
    b. Add tab { entry, content } to tabs state
    c. Set activeTabPath
-5. Editor renders BlockNoteTab:
+7. Editor renders BlockNoteTab:
    a. splitFrontmatter(content) → [yaml, body]
    b. preProcessWikilinks(body) → replaces [[target]] with tokens
    c. editor.tryParseMarkdownToBlocks(preprocessed)
    d. injectWikilinks(blocks) → replaces tokens with wikilink nodes
    e. editor.replaceBlocks()
-6. Inspector renders frontmatter parsed from content
+8. Inspector renders frontmatter parsed from content
 ```
 
-### Frontmatter Edit Flow
+### Auto-Save Flow
 
 ```
-User edits property in Inspector
-  → handleUpdateFrontmatter(path, key, value)
-    → Tauri: invoke('update_frontmatter') → Rust reads file, modifies YAML, writes back
-    → Mock: updateMockFrontmatter() → client-side YAML manipulation
-  → Update tab content in state
-  → Update allContent for backlink recalculation
-  → Toast: "Property updated"
+Editor content changes
+  → useEditorSave detects change (debounced)
+    → serialize BlockNote blocks → markdown
+    → postProcessWikilinks → restore [[target]] syntax
+    → invoke('save_note_content', { path, content })
+    → Update tab status indicator
 ```
 
-### Git Flow
+### Git Sync Flow
 
 ```
-User clicks Commit button → CommitDialog opens
-  → handleCommitPush(message)
-    → invoke('git_commit') → git add -A && git commit -m "..."
-    → invoke('git_push') → git push
+useAutoSync (configurable interval, default from settings):
+  → invoke('git_pull') → GitPullResult
+    → if conflicts → ConflictResolverModal
+    → if fast-forward → reload vault
+  → invoke('git_push') → GitPushResult
+
+Manual commit:
+  → CommitDialog → invoke('git_commit', { message })
+    → invoke('git_push')
     → Reload modified files
-    → Toast: "Committed and pushed"
 ```
 
 ## Vault Module Structure
 
 The vault backend (`src-tauri/src/vault/`) is split into focused submodules:
 
-| File | Purpose | CodeScene Health |
-|------|---------|-----------------|
-| `mod.rs` | Core types (`VaultEntry`, `Frontmatter`), `parse_md_file`, `scan_vault`, relationship extraction | 10.0 |
-| `parsing.rs` | Text processing: snippet extraction, markdown stripping, ISO date parsing, `extract_title` | 9.68 |
-| `cache.rs` | Git-based incremental vault caching (`scan_vault_cached`), git helpers | 9.68 |
-| `trash.rs` | `purge_trash` — deletes trashed notes older than 30 days | 9.38 |
-| `rename.rs` | `rename_note` — renames files and updates wikilinks across the vault | 9.68 |
-| `image.rs` | `save_image` — saves base64-encoded attachments with sanitized filenames | 10.0 |
+| File | Purpose |
+|------|---------|
+| `mod.rs` | Core types (`VaultEntry`, `Frontmatter`), `parse_md_file`, `scan_vault`, relationship/link extraction |
+| `parsing.rs` | Text processing: snippet extraction, markdown stripping, ISO date parsing, `extract_title` |
+| `cache.rs` | Git-based incremental vault caching (`scan_vault_cached`), git helpers |
+| `trash.rs` | `purge_trash` — deletes trashed notes older than 30 days |
+| `rename.rs` | `rename_note` — renames files and updates wikilinks across the vault |
+| `image.rs` | `save_image` — saves base64-encoded attachments with sanitized filenames |
+| `migration.rs` | Frontmatter migration utilities |
+| `config_seed.rs` | Seeds `config/` folder, migrates `AGENTS.md`, repairs missing config files |
+| `getting_started.rs` | Creates the Getting Started demo vault |
 
-Public API (re-exported from `mod.rs`): `scan_vault_cached`, `save_image`, `rename_note`, `RenameResult`, `purge_trash`, `get_note_content`, `parse_md_file`, `VaultEntry`.
+## Rust Backend Modules
 
-## Tauri IPC Commands
+| Module | Purpose |
+|--------|---------|
+| `vault/` | Vault scanning, caching, parsing, trash, rename, image, migration |
+| `frontmatter/` | YAML frontmatter read/write (`mod.rs`, `yaml.rs`, `ops.rs`) |
+| `git/` | Git operations (`commit.rs`, `status.rs`, `history.rs`, `conflict.rs`, `remote.rs`, `pulse.rs`) |
+| `github/` | GitHub OAuth + API (`auth.rs`, `api.rs`, `clone.rs`) |
+| `theme/` | Theme management (`mod.rs`, `create.rs`, `defaults.rs`, `seed.rs`) |
+| `search.rs` | qmd search integration (keyword/semantic/hybrid) |
+| `indexing.rs` | qmd indexing with progress streaming |
+| `claude_cli.rs` | Claude CLI subprocess spawning + NDJSON stream parsing |
+| `ai_chat.rs` | Direct Anthropic API client (non-streaming, for Tauri builds) |
+| `mcp.rs` | MCP server spawning + config registration |
+| `commands.rs` | All 61 Tauri command handlers |
+| `settings.rs` | App settings persistence |
+| `vault_config.rs` | Per-vault UI config |
+| `vault_list.rs` | Vault list persistence |
+| `menu.rs` | Native macOS menu bar |
 
-All commands are defined in `src-tauri/src/lib.rs` and registered via `tauri::generate_handler![]`.
+## Tauri IPC Commands (61 total)
 
-| Command | Params | Returns | Backend function |
-|---------|--------|---------|-----------------|
-| `list_vault` | `path` | `Vec<VaultEntry>` | `vault::scan_vault()` |
-| `get_note_content` | `path` | `String` | `vault::get_note_content()` |
-| `update_frontmatter` | `path, key, value` | `String` (updated content) | `frontmatter::with_frontmatter()` |
-| `delete_frontmatter_property` | `path, key` | `String` (updated content) | `frontmatter::with_frontmatter()` |
-| `get_file_history` | `vault_path, path` | `Vec<GitCommit>` | `git::get_file_history()` |
-| `get_modified_files` | `vault_path` | `Vec<ModifiedFile>` | `git::get_modified_files()` |
-| `get_file_diff` | `vault_path, path` | `String` (unified diff) | `git::get_file_diff()` |
-| `git_commit` | `vault_path, message` | `String` | `git::git_commit()` |
-| `git_push` | `vault_path` | `String` | `git::git_push()` |
-| `ai_chat` | `request: AiChatRequest` | `AiChatResponse` | `ai_chat::send_chat()` |
-| `register_mcp_tools` | `vault_path` | `String` ("registered" or "updated") | `mcp::register_mcp()` |
+### Vault Operations
 
-All commands return `Result<T, String>`. Errors are serialized as JSON error objects to the frontend.
+| Command | Description |
+|---------|-------------|
+| `list_vault` | Scan vault (cached) → `Vec<VaultEntry>` |
+| `get_note_content` | Read note file content |
+| `save_note_content` | Write note content to disk |
+| `delete_note` | Move note to trash |
+| `rename_note` | Rename note + update cross-vault wikilinks |
+| `batch_archive_notes` | Archive multiple notes |
+| `batch_trash_notes` | Trash multiple notes |
+| `purge_trash` | Delete notes trashed >30 days ago |
+| `check_vault_exists` | Check if vault path exists |
+| `create_getting_started_vault` | Bootstrap demo vault |
+
+### Frontmatter
+
+| Command | Description |
+|---------|-------------|
+| `update_frontmatter` | Update a frontmatter property |
+| `delete_frontmatter_property` | Remove a frontmatter property |
+
+### Git
+
+| Command | Description |
+|---------|-------------|
+| `git_commit` | Stage all + commit |
+| `git_pull` | Pull from remote |
+| `git_push` | Push to remote |
+| `git_resolve_conflict` | Resolve a merge conflict |
+| `git_commit_conflict_resolution` | Commit conflict resolution |
+| `get_file_history` | Last N commits for a file |
+| `get_modified_files` | `git status` filtered to .md |
+| `get_file_diff` | Unified diff for a file |
+| `get_file_diff_at_commit` | Diff at a specific commit |
+| `get_conflict_files` | List conflicted files |
+| `get_conflict_mode` | Get conflict resolution mode |
+| `get_vault_pulse` | Git activity feed (paginated) |
+| `get_last_commit_info` | Latest commit metadata |
+
+### GitHub
+
+| Command | Description |
+|---------|-------------|
+| `github_device_flow_start` | Begin OAuth device flow |
+| `github_device_flow_poll` | Poll for authorization |
+| `github_get_user` | Get authenticated user info |
+| `github_list_repos` | List user's repos |
+| `github_create_repo` | Create new repo |
+| `clone_repo` | Clone repo with token auth |
+
+### Search & Indexing
+
+| Command | Description |
+|---------|-------------|
+| `search_vault` | Search via qmd (keyword/semantic/hybrid) |
+| `get_index_status` | Check qmd index state |
+| `start_indexing` | Full index with progress streaming |
+| `trigger_incremental_index` | Incremental index update |
+
+### Theme
+
+| Command | Description |
+|---------|-------------|
+| `list_themes` | List all themes (legacy JSON) |
+| `get_theme` | Read a theme file |
+| `get_vault_settings` | Read `.laputa/settings.json` |
+| `save_vault_settings` | Write vault settings |
+| `set_active_theme` | Set active theme ID |
+| `create_theme` | Create JSON theme from template |
+| `create_vault_theme` | Create markdown theme note |
+| `ensure_vault_themes` | Seed default themes if missing |
+| `restore_default_themes` | Restore all default themes |
+| `repair_vault` | Restore default themes + missing config files |
+
+### AI & MCP
+
+| Command | Description |
+|---------|-------------|
+| `ai_chat` | Direct Anthropic API call (non-streaming) |
+| `stream_claude_chat` | Claude CLI chat mode (streaming) |
+| `stream_claude_agent` | Claude CLI agent mode (streaming + tools) |
+| `check_claude_cli` | Check if Claude CLI is available |
+| `register_mcp_tools` | Register MCP in Claude/Cursor config |
+| `check_mcp_status` | Check MCP registration state |
+
+### Settings & Config
+
+| Command | Description |
+|---------|-------------|
+| `get_settings` | Load app settings |
+| `save_settings` | Save app settings |
+| `load_vault_list` | Load vault list |
+| `save_vault_list` | Save vault list |
+| `get_vault_config` | Load per-vault UI config |
+| `save_vault_config` | Save per-vault UI config |
+| `get_default_vault_path` | Get default vault path |
+| `get_build_number` | Get app build number |
+| `save_image` | Save base64 image to vault |
+| `copy_image_to_vault` | Copy image file to vault |
+| `update_menu_state` | Update native menu checkmarks |
 
 ## Mock Layer
 
-When running outside Tauri (browser at `localhost:5201`), `src/mock-tauri.ts` provides a transparent mock layer:
+When running outside Tauri (browser at `localhost:5173`), `src/mock-tauri.ts` provides a transparent mock layer:
 
 ```typescript
-// In hooks, the pattern is always:
 if (isTauri()) {
   result = await invoke<T>('command_name', { args })
 } else {
@@ -347,14 +593,7 @@ if (isTauri()) {
 }
 ```
 
-The mock layer includes:
-- **15 sample entries** across all entity types (Project, Responsibility, Procedure, Experiment, Note, Person, Event, Topic, Essay)
-- **Full markdown content** with realistic frontmatter for each entry
-- **Mock git history, modified files, and diff output**
-- **Mock AI chat responses** with context-aware answers (summarize, expand, grammar)
-- `addMockEntry()` and `updateMockContent()` for runtime updates
-
-This means the entire UI can be developed and tested in Chrome without the Rust backend.
+The mock layer includes sample entries across all entity types, full markdown content with realistic frontmatter, mock git history, mock AI responses, and mock pulse commits.
 
 ## State Management
 
@@ -362,11 +601,18 @@ No Redux or global context. State lives in the root `App.tsx` and custom hooks:
 
 | State owner | State | Purpose |
 |-------------|-------|---------|
-| `App.tsx` | `selection`, panel widths, dialog visibility, toast, `showAIChat` | UI state |
+| `App.tsx` | `selection`, panel widths, dialog visibility, toast, view mode | UI state |
 | `useVaultLoader` | `entries`, `allContent`, `modifiedFiles` | Vault data |
 | `useNoteActions` | `tabs`, `activeTabPath` | Open tabs and note operations |
-| `useAIChat` | `messages`, `isStreaming`, `streamingContent` | AI conversation state |
-| `useMcpBridge` | `connected`, tool methods | MCP WebSocket connection |
+| `useTabManagement` | Tab ordering, pinning, swapping | Tab lifecycle |
+| `useVaultSwitcher` | `vaultPath`, `extraVaults` | Vault switching |
+| `useThemeManager` | `themes`, `activeThemeId`, `isDark` | Theme state |
+| `useAIChat` | `messages`, `isStreaming` | AI chat conversation |
+| `useAiAgent` | `messages`, `status`, tool actions | AI agent conversation |
+| `useAutoSync` | Sync interval, pull/push state | Git auto-sync |
+| `useIndexing` | Index status, progress | Search indexing |
+| `useSettings` | App settings (API keys, GitHub token) | Persistent settings |
+| `useVaultConfig` | Per-vault UI preferences | Vault-specific config |
 
 Data flows unidirectionally: `App` passes data and callbacks as props to child components. No child-to-child communication — everything goes through `App`.
 
@@ -374,10 +620,14 @@ Data flows unidirectionally: `App` passes data and callbacks as props to child c
 
 | Shortcut | Action |
 |----------|--------|
-| Cmd+P | Open Quick Open palette |
-| Cmd+N | Open Create Note dialog |
-| Cmd+S | Show "Saved" toast |
+| Cmd+K | Open command palette |
+| Cmd+P | Open quick open palette |
+| Cmd+N | Create new note |
+| Cmd+S | Save current note |
 | Cmd+W | Close active tab |
+| Cmd+Z / Cmd+Shift+Z | Undo / Redo |
+| Cmd+1–9 | Switch to tab N |
+| Cmd+[ / Cmd+] | Navigate back / forward |
 | `[[` in editor | Open wikilink suggestion menu |
 
 ## Auto-Release & In-App Updates
@@ -399,47 +649,22 @@ push to main
       → generate latest.json (per-arch + universal platform entries)
       → publish GitHub Release with all assets + auto-generated notes
   → pages job:
-      → fetch all releases via gh api
       → build static HTML release history page
-      → deploy to gh-pages via peaceiris/actions-gh-pages
+      → deploy to gh-pages
 ```
 
 ### Versioning
 
-Format: `0.YYYYMMDD.GITHUB_RUN_NUMBER` (e.g. `0.20260223.42`). The `0.` prefix keeps it SemVer-compatible while making it clear these are date-based auto-releases. The version is stamped into both `tauri.conf.json` and `Cargo.toml` dynamically in the workflow.
+Format: `0.YYYYMMDD.GITHUB_RUN_NUMBER` (e.g. `0.20260223.42`). Stamped into `tauri.conf.json` and `Cargo.toml` dynamically.
 
-### Universal Binary
-
-macOS builds produce both `aarch64-apple-darwin` and `x86_64-apple-darwin` in parallel. The release job merges them with `lipo` — copying the arm64 `.app` as the base and replacing only the main executable with a universal fat binary. The per-arch updater tarballs are also uploaded so the Tauri updater downloads only the relevant architecture (smaller download).
-
-### Updater Endpoint
-
-The Tauri updater plugin is configured to fetch:
-```
-https://github.com/refactoringhq/laputa-app/releases/latest/download/latest.json
-```
-
-This JSON manifest contains `version`, `pub_date`, `notes`, and per-platform entries (`darwin-aarch64`, `darwin-x86_64`) with `url` and `signature` fields. The updater compares the manifest version against the running app version, downloads the matching platform artifact, verifies the signature, and installs it.
-
-### In-App Update UI
+### In-App Updates
 
 ```
 App startup (3s delay)
   → useUpdater.check()
-    → idle (no update) → no UI shown
-    → available → UpdateBanner: "Laputa X.Y.Z is available" + Release Notes + Update Now + X
-      → user clicks Update Now → downloading → progress bar
-        → download complete → ready → "Restart to apply" + Restart Now button
-          → user clicks Restart → relaunch()
-    → network error / 404 → fail silently, no UI
+    → idle (no update) → no UI
+    → available → UpdateBanner with release notes + "Update Now"
+      → downloading → progress bar
+        → ready → "Restart to apply" + Restart Now
+    → network error → fail silently
 ```
-
-| Component | File | Purpose |
-|-----------|------|---------|
-| `useUpdater` | `src/hooks/useUpdater.ts` | State machine: idle → available → downloading → ready → error |
-| `UpdateBanner` | `src/components/UpdateBanner.tsx` | Top-of-app notification bar |
-| `restartApp` | `src/hooks/useUpdater.ts` | Calls `@tauri-apps/plugin-process` relaunch |
-
-### GitHub Pages
-
-Release history site at `https://refactoringhq.github.io/laputa-app/`. Auto-updated by the workflow after each release. The page loads `releases.json` (deployed alongside) and renders each release with date, notes, and `.dmg` download links. Linked from the in-app "Release Notes" button.

docs/GETTING-STARTED.md

@@ -7,6 +7,7 @@ How to navigate the codebase, run the app, and find what you need.
 - **Node.js** 18+ and **pnpm**
 - **Rust** 1.77.2+ (for the Tauri backend)
 - **git** CLI (required by the git integration features)
+- **qmd** (optional — for search indexing; auto-installed if missing)
 
 ## Quick Start
 
@@ -24,7 +25,7 @@ pnpm tauri dev
 # Run tests
 pnpm test          # Vitest unit tests
 cargo test         # Rust tests (from src-tauri/)
-pnpm test:e2e      # Playwright E2E tests
+pnpm playwright:smoke  # Playwright smoke tests
 ```
 
 ## Directory Structure
@@ -33,39 +34,94 @@ pnpm test:e2e      # Playwright E2E tests
 laputa-app/
 ├── src/                          # React frontend
 │   ├── main.tsx                  # Entry point (renders <App />)
-│   ├── App.tsx                   # Root component — orchestrates 4-panel layout
+│   ├── App.tsx                   # Root component — orchestrates layout + state
 │   ├── App.css                   # App shell layout styles
-│   ├── types.ts                  # Shared TS types (VaultEntry, GitCommit, etc.)
+│   ├── types.ts                  # Shared TS types (VaultEntry, Settings, etc.)
 │   ├── mock-tauri.ts             # Mock Tauri layer for browser testing
 │   ├── theme.json                # Editor theme configuration
 │   ├── index.css                 # Global CSS variables + Tailwind setup
 │   │
-│   ├── components/               # UI components
-│   │   ├── Sidebar.tsx           # Left panel: filters + section groups
+│   ├── components/               # UI components (~98 files)
+│   │   ├── Sidebar.tsx           # Left panel: filters + type groups
+│   │   ├── SidebarParts.tsx      # Sidebar subcomponents
 │   │   ├── NoteList.tsx          # Second panel: filtered note list
-│   │   ├── Editor.tsx            # Third panel: tabs + BlockNote + diff
+│   │   ├── NoteItem.tsx          # Individual note item
+│   │   ├── PulseView.tsx         # Git activity feed (replaces NoteList)
+│   │   ├── Editor.tsx            # Third panel: tabs + editor orchestration
+│   │   ├── EditorContent.tsx     # Editor content area
+│   │   ├── EditorRightPanel.tsx  # Right panel toggle
+│   │   ├── editorSchema.tsx      # BlockNote schema + wikilink type
+│   │   ├── RawEditorView.tsx     # CodeMirror raw editor
 │   │   ├── Inspector.tsx         # Fourth panel: metadata + relationships
 │   │   ├── DynamicPropertiesPanel.tsx  # Editable frontmatter properties
-│   │   ├── EditableValue.tsx     # Inline value editor component
-│   │   ├── DiffView.tsx          # Git diff viewer
-│   │   ├── ResizeHandle.tsx      # Draggable panel divider
-│   │   ├── StatusBar.tsx         # Bottom status bar
-│   │   ├── QuickOpenPalette.tsx  # Cmd+P command palette
-│   │   ├── CreateNoteDialog.tsx  # New note modal
+│   │   ├── AIChatPanel.tsx       # AI chat (API-based)
+│   │   ├── AiPanel.tsx           # AI agent (Claude CLI subprocess)
+│   │   ├── AiMessage.tsx         # Agent message display
+│   │   ├── AiActionCard.tsx      # Agent tool action cards
+│   │   ├── SearchPanel.tsx       # Search interface
+│   │   ├── SettingsPanel.tsx     # App settings
+│   │   ├── StatusBar.tsx         # Bottom bar: vault picker + sync
+│   │   ├── CommandPalette.tsx    # Cmd+K command launcher
+│   │   ├── TabBar.tsx            # Tab management
+│   │   ├── BreadcrumbBar.tsx     # Breadcrumb + word count + actions
+│   │   ├── WelcomeScreen.tsx     # Onboarding screen
+│   │   ├── GitHubVaultModal.tsx  # GitHub vault clone/create
+│   │   ├── GitHubDeviceFlow.tsx  # GitHub OAuth device flow
+│   │   ├── ThemePropertyEditor.tsx # Interactive theme editor
+│   │   ├── ConflictResolverModal.tsx # Git conflict resolution
 │   │   ├── CommitDialog.tsx      # Git commit modal
-│   │   ├── Toast.tsx             # Toast notifications
-│   │   ├── Editor.css            # Editor layout styles
-│   │   ├── EditorTheme.css       # BlockNote theme overrides
-│   │   └── ui/                   # shadcn/ui primitives (button, dialog, etc.)
+│   │   ├── CreateNoteDialog.tsx  # New note modal
+│   │   ├── CreateTypeDialog.tsx  # New type modal
+│   │   ├── UpdateBanner.tsx      # In-app update notification
+│   │   ├── inspector/            # Inspector sub-panels
+│   │   │   ├── BacklinksPanel.tsx
+│   │   │   ├── RelationshipsPanel.tsx
+│   │   │   ├── GitHistoryPanel.tsx
+│   │   │   └── ...
+│   │   └── ui/                   # shadcn/ui primitives
+│   │       ├── button.tsx, dialog.tsx, input.tsx, ...
 │   │
-│   ├── hooks/                    # Custom React hooks
-│   │   ├── useVaultLoader.ts     # Loads vault entries, git status, content
-│   │   ├── useNoteActions.ts     # Tab management, frontmatter CRUD, navigation
-│   │   └── useTheme.ts           # Flattens theme.json into CSS variables
+│   ├── hooks/                    # Custom React hooks (~87 files)
+│   │   ├── useVaultLoader.ts     # Loads vault entries + content
+│   │   ├── useVaultSwitcher.ts   # Multi-vault management
+│   │   ├── useVaultConfig.ts     # Per-vault UI settings
+│   │   ├── useNoteActions.ts     # Tab management, navigation, CRUD
+│   │   ├── useTabManagement.ts   # Tab ordering + lifecycle
+│   │   ├── useAIChat.ts          # AI chat state
+│   │   ├── useAiAgent.ts         # AI agent state + tool tracking
+│   │   ├── useAiActivity.ts      # MCP UI bridge listener
+│   │   ├── useAutoSync.ts        # Auto git pull/push
+│   │   ├── useConflictResolver.ts # Git conflict handling
+│   │   ├── useEditorSave.ts      # Auto-save with debounce
+│   │   ├── useTheme.ts           # Flatten theme.json → CSS vars
+│   │   ├── useThemeManager.ts    # Vault theme lifecycle
+│   │   ├── useIndexing.ts        # Search indexing management
+│   │   ├── useNoteSearch.ts      # Note search
+│   │   ├── useCommandRegistry.ts # Command palette registry
+│   │   ├── useAppCommands.ts     # App-level commands
+│   │   ├── useAppKeyboard.ts     # Keyboard shortcuts
+│   │   ├── useSettings.ts        # App settings
+│   │   ├── useOnboarding.ts      # First-launch flow
+│   │   ├── useCodeMirror.ts      # CodeMirror raw editor
+│   │   ├── useMcpBridge.ts       # MCP WebSocket client
+│   │   ├── useMcpStatus.ts       # MCP registration status
+│   │   ├── useUpdater.ts         # In-app updates
+│   │   └── ...
 │   │
-│   ├── utils/                    # Pure utility functions
-│   │   ├── frontmatter.ts        # TypeScript YAML frontmatter parser
-│   │   └── wikilinks.ts          # Wikilink preprocessing + word count
+│   ├── utils/                    # Pure utility functions (~48 files)
+│   │   ├── wikilinks.ts          # Wikilink preprocessing pipeline
+│   │   ├── frontmatter.ts        # TypeScript YAML parser
+│   │   ├── ai-agent.ts           # Agent stream utilities
+│   │   ├── ai-chat.ts            # Chat API client + token estimation
+│   │   ├── ai-context.ts         # Context snapshot builder
+│   │   ├── noteListHelpers.ts    # Sorting, filtering, date formatting
+│   │   ├── themeSchema.ts        # Theme editor schema builder
+│   │   ├── configMigration.ts    # localStorage → vault config migration
+│   │   ├── iconRegistry.ts       # Phosphor icon registry
+│   │   ├── propertyTypes.ts      # Property type definitions
+│   │   ├── vaultListStore.ts     # Vault list persistence
+│   │   ├── vaultConfigStore.ts   # Vault config store
+│   │   └── ...
 │   │
 │   ├── lib/
 │   │   └── utils.ts              # Tailwind merge + cn() helper
@@ -78,28 +134,58 @@ laputa-app/
 │   ├── build.rs                  # Tauri build script
 │   ├── tauri.conf.json           # Tauri app configuration
 │   ├── capabilities/             # Tauri v2 security capabilities
-│   │   └── default.json
 │   ├── src/
 │   │   ├── main.rs               # Entry point (calls lib::run())
-│   │   ├── lib.rs                # Tauri command registration (9 commands)
-│   │   ├── vault.rs              # Vault scanning + markdown parsing
-│   │   ├── frontmatter.rs        # YAML frontmatter manipulation
-│   │   └── git.rs                # Git CLI operations
+│   │   ├── lib.rs                # Tauri setup + command registration (61 commands)
+│   │   ├── commands.rs           # All Tauri command handlers
+│   │   ├── vault/                # Vault module
+│   │   │   ├── mod.rs            # Core types, parse_md_file, scan_vault
+│   │   │   ├── cache.rs          # Git-based incremental caching
+│   │   │   ├── parsing.rs        # Text processing + title extraction
+│   │   │   ├── trash.rs          # Trash auto-purge
+│   │   │   ├── rename.rs         # Rename + cross-vault wikilink update
+│   │   │   ├── image.rs          # Image attachment saving
+│   │   │   ├── migration.rs      # Frontmatter migration
+│   │   │   └── getting_started.rs # Getting Started vault creation
+│   │   ├── frontmatter/          # Frontmatter module
+│   │   │   ├── mod.rs, yaml.rs, ops.rs
+│   │   ├── git/                  # Git module
+│   │   │   ├── mod.rs, commit.rs, status.rs, history.rs
+│   │   │   ├── conflict.rs, remote.rs, pulse.rs
+│   │   ├── github/               # GitHub module
+│   │   │   ├── mod.rs, auth.rs, api.rs, clone.rs
+│   │   ├── theme/                # Theme module
+│   │   │   ├── mod.rs, create.rs, defaults.rs, seed.rs
+│   │   ├── search.rs             # qmd search integration
+│   │   ├── indexing.rs           # qmd indexing + progress streaming
+│   │   ├── claude_cli.rs         # Claude CLI subprocess management
+│   │   ├── ai_chat.rs            # Direct Anthropic API client
+│   │   ├── mcp.rs                # MCP server lifecycle + registration
+│   │   ├── settings.rs           # App settings persistence
+│   │   ├── vault_config.rs       # Per-vault UI config
+│   │   ├── vault_list.rs         # Vault list persistence
+│   │   └── menu.rs               # Native macOS menu bar
 │   └── icons/                    # App icons
 │
-├── e2e/                          # Playwright E2E tests
-│   ├── app.spec.ts               # App loading tests
-│   ├── core-flows.spec.ts        # Main user workflows
-│   ├── keyboard-shortcuts.spec.ts
-│   ├── quick-open.spec.ts
-│   ├── screenshot.spec.ts        # Visual regression screenshots
-│   └── ...
+├── mcp-server/                   # MCP bridge (Node.js)
+│   ├── index.js                  # MCP server entry (stdio, 14 tools)
+│   ├── vault.js                  # Vault file operations
+│   ├── ws-bridge.js              # WebSocket bridge (ports 9710, 9711)
+│   ├── test.js                   # MCP server tests
+│   └── package.json
+│
+├── e2e/                          # Playwright E2E tests (~26 specs)
+├── tests/smoke/                  # Smoke tests (~10 specs)
+├── design/                       # Per-task design files
+├── demo-vault-v2/                # Getting Started demo vault
+├── scripts/                      # Build/utility scripts
 │
 ├── package.json                  # Frontend dependencies + scripts
 ├── vite.config.ts                # Vite bundler config
 ├── tsconfig.json                 # TypeScript config
 ├── playwright.config.ts          # E2E test config
-├── CLAUDE.md                     # Project instructions for Claude
+├── ui-design.pen                 # Master design file
+├── CLAUDE.md                     # Project instructions
 └── docs/                         # This documentation
 ```
 
@@ -109,9 +195,10 @@ laputa-app/
 
 | File | Why it matters |
 |------|---------------|
-| `src/App.tsx` | The root component. Shows how the 4-panel layout is assembled and how state flows between components. |
+| `src/App.tsx` | Root component. Shows the 4-panel layout, state flow, and how all features connect. |
 | `src/types.ts` | All shared TypeScript types. Read this first to understand the data model. |
-| `src-tauri/src/lib.rs` | All 9 Tauri commands in one place. This is the frontend-backend API surface. |
+| `src-tauri/src/commands.rs` | All 61 Tauri command handlers. This is the frontend-backend API surface. |
+| `src-tauri/src/lib.rs` | Tauri setup, command registration, startup tasks, WebSocket bridge lifecycle. |
 
 ### Data layer
 
@@ -119,31 +206,55 @@ laputa-app/
 |------|---------------|
 | `src/hooks/useVaultLoader.ts` | How vault data is loaded and managed. The Tauri/mock branching pattern. |
 | `src/hooks/useNoteActions.ts` | Tab management, wikilink navigation, frontmatter CRUD. The biggest hook. |
+| `src/hooks/useVaultSwitcher.ts` | Multi-vault management, vault switching, Getting Started vault. |
 | `src/mock-tauri.ts` | Mock data for browser testing. Shows the shape of all Tauri responses. |
 
 ### Backend
 
 | File | Why it matters |
 |------|---------------|
-| `src-tauri/src/vault.rs` | Vault scanning, frontmatter parsing, entity type inference. The core backend logic. |
-| `src-tauri/src/frontmatter.rs` | YAML manipulation — how properties are updated/deleted in files. |
-| `src-tauri/src/git.rs` | All git operations. Shells out to git CLI. |
+| `src-tauri/src/vault/mod.rs` | Vault scanning, frontmatter parsing, entity type inference, relationship extraction. |
+| `src-tauri/src/vault/cache.rs` | Git-based incremental caching — how large vaults load fast. |
+| `src-tauri/src/frontmatter/ops.rs` | YAML manipulation — how properties are updated/deleted in files. |
+| `src-tauri/src/git/` | All git operations (commit, pull, push, conflicts, pulse). |
+| `src-tauri/src/github/` | GitHub OAuth device flow + repo clone/create. |
+| `src-tauri/src/search.rs` | qmd search integration (keyword/semantic/hybrid). |
+| `src-tauri/src/claude_cli.rs` | Claude CLI subprocess spawning + NDJSON stream parsing. |
 
 ### Editor
 
 | File | Why it matters |
 |------|---------------|
-| `src/components/Editor.tsx` | BlockNote setup, custom wikilink schema, tab bar, breadcrumb bar, diff toggle. |
-| `src/utils/wikilinks.ts` | The wikilink preprocessing pipeline (markdown → BlockNote blocks with wikilinks). |
-| `src/components/EditorTheme.css` | BlockNote CSS overrides for typography and styling. |
+| `src/components/Editor.tsx` | BlockNote setup, tab bar, breadcrumb bar, diff/raw toggle. |
+| `src/components/editorSchema.tsx` | Custom wikilink inline content type definition. |
+| `src/utils/wikilinks.ts` | Wikilink preprocessing pipeline (markdown ↔ BlockNote). |
+| `src/components/RawEditorView.tsx` | CodeMirror 6 raw markdown editor. |
 
-### Styling
+### AI
 
 | File | Why it matters |
 |------|---------------|
-| `src/index.css` | All CSS custom properties (colors, spacing). The design token source of truth. |
+| `src/components/AiPanel.tsx` | AI agent panel — Claude CLI with tool execution, reasoning, actions. |
+| `src/components/AIChatPanel.tsx` | AI chat panel — API-based chat without tools. |
+| `src/hooks/useAiAgent.ts` | Agent state: messages, streaming, tool tracking, file detection. |
+| `src/utils/ai-context.ts` | Context snapshot builder for AI conversations. |
+
+### Styling & Themes
+
+| File | Why it matters |
+|------|---------------|
+| `src/index.css` | All CSS custom properties. The design token source of truth. |
 | `src/theme.json` | Editor-specific theme (fonts, headings, lists, code blocks). |
-| `src/hooks/useTheme.ts` | Converts theme.json into CSS variables for the editor. |
+| `src/hooks/useThemeManager.ts` | Vault theme lifecycle (switch, create, apply, live preview). |
+| `docs/THEMING.md` | Full theme system documentation. |
+
+### Settings & Config
+
+| File | Why it matters |
+|------|---------------|
+| `src/hooks/useSettings.ts` | App settings (API keys, GitHub token, sync interval). |
+| `src/hooks/useVaultConfig.ts` | Per-vault UI preferences (zoom, view mode, colors). |
+| `src/components/SettingsPanel.tsx` | Settings UI including GitHub OAuth connection. |
 
 ## Architecture Patterns
 
@@ -169,13 +280,15 @@ No global state management (no Redux, no Context). `App.tsx` owns the state and
 
 ```typescript
 type SidebarSelection =
-  | { kind: 'filter'; filter: 'all' | 'favorites' }
+  | { kind: 'filter'; filter: SidebarFilter }
   | { kind: 'sectionGroup'; type: string }
   | { kind: 'entity'; entry: VaultEntry }
   | { kind: 'topic'; entry: VaultEntry }
 ```
 
-This pattern makes it easy to handle all selection states exhaustively.
+### Command Registry
+
+`useCommandRegistry` + `useAppCommands` build a centralized command registry. Commands are registered with labels, shortcuts, and handlers. The `CommandPalette` (Cmd+K) fuzzy-searches this registry. The native macOS menu bar also triggers commands via `useMenuEvents`.
 
 ## Running Tests
 
@@ -183,26 +296,28 @@ This pattern makes it easy to handle all selection states exhaustively.
 # Unit tests (fast, no browser)
 pnpm test
 
-# Rust tests
-cd src-tauri && cargo test
+# Unit tests with coverage (must pass ≥70%)
+pnpm test:coverage
 
-# E2E tests (requires dev server)
-pnpm test:e2e
+# Rust tests
+cargo test
+
+# Rust coverage (must pass ≥85% line coverage)
+cargo llvm-cov --manifest-path src-tauri/Cargo.toml --no-clean --fail-under-lines 85
+
+# Playwright smoke tests (requires dev server)
+BASE_URL="http://localhost:5173" pnpm playwright:smoke
 
 # Single Playwright test
-npx playwright test e2e/screenshot.spec.ts
-
-# Visual verification screenshots
-npx playwright test e2e/screenshot.spec.ts
-# Screenshots saved to test-results/
+BASE_URL="http://localhost:5173" npx playwright test tests/smoke/<slug>.spec.ts
 ```
 
 ## Common Tasks
 
 ### Add a new Tauri command
 
-1. Write the Rust function in `vault.rs`, `git.rs`, or a new module
-2. Add `#[tauri::command]` wrapper in `lib.rs`
+1. Write the Rust function in the appropriate module (`vault/`, `git/`, etc.)
+2. Add a command handler in `commands.rs`
 3. Register it in the `generate_handler![]` macro in `lib.rs`
 4. Call it from the frontend via `invoke()` in the appropriate hook
 5. Add a mock handler in `mock-tauri.ts`
@@ -217,6 +332,25 @@ npx playwright test e2e/screenshot.spec.ts
 ### Add a new entity type
 
 1. Create the folder in the vault (e.g., `~/Laputa/mytype/`)
-2. Add the folder → type mapping in `vault.rs:parse_md_file()` (the `match` on folder names)
-3. The sidebar section groups are defined as `SECTION_GROUPS` in `Sidebar.tsx` — add it there
-4. Update `CreateNoteDialog.tsx` type options if users should be able to create it
+2. Create a type document: `type/mytype.md` with `Is A: Type` frontmatter (icon, color, order, etc.)
+3. The sidebar section groups are auto-generated from type documents — no code change needed if `visible: true`
+4. Update `CreateNoteDialog.tsx` type options if users should be able to create it from the dialog
+
+### Add a command palette entry
+
+1. Register the command in `useAppCommands.ts` via the command registry
+2. Add a corresponding menu bar item in `menu.rs` for discoverability
+3. If it has a keyboard shortcut, register it in `useAppKeyboard.ts`
+
+### Add or modify a theme
+
+1. **Vault-based** (preferred): Create/edit a markdown note in `theme/` with `Is A: Theme` frontmatter
+2. **Programmatic**: Edit defaults in `src-tauri/src/theme/defaults.rs`
+3. See `docs/THEMING.md` for the full property reference
+
+### Work with the AI agent
+
+1. **Agent system prompt**: Edit `src/utils/ai-agent.ts` (inline system prompt string)
+2. **Context building**: Edit `src/utils/ai-context.ts` for what data is sent to the agent
+3. **Tool action display**: Edit `src/components/AiActionCard.tsx`
+4. **Claude CLI arguments**: Edit `src-tauri/src/claude_cli.rs` (`run_agent_stream()`)

eslint.config.js

@@ -6,7 +6,7 @@ import tseslint from 'typescript-eslint'
 import { defineConfig, globalIgnores } from 'eslint/config'
 
 export default defineConfig([
-  globalIgnores(['dist', 'coverage', 'src-tauri/resources/', 'src-tauri/target/']),
+  globalIgnores(['dist', 'coverage', 'src-tauri/resources/', 'src-tauri/target/', 'tools/']),
   {
     files: ['**/*.{ts,tsx}'],
     extends: [

mcp-server/index.js

@@ -1,21 +1,17 @@
 #!/usr/bin/env node
 /**
- * Laputa MCP Server — provides vault operation tools for AI assistants.
+ * Laputa MCP Server — lightweight vault tools for AI agents.
  *
- * Usage:
- *   VAULT_PATH=/path/to/vault node index.js
+ * The agent has full shell access (bash, read, write, edit).
+ * These MCP tools provide Laputa-specific capabilities that
+ * native tools cannot replace:
  *
- * Tools:
- *   - open_note / read_note: Read a note by path
- *   - create_note: Create a new note with title and optional frontmatter
- *   - search_notes: Search notes by title or content
- *   - append_to_note: Append text to an existing note
- *   - edit_note_frontmatter: Merge a patch into a note's YAML frontmatter
- *   - delete_note: Delete a note file
- *   - link_notes: Add a title to an array property in a note's frontmatter
- *   - list_notes: List all notes, optionally filtered by type
- *   - vault_context: Get vault types and recent notes
- *   - ui_open_note / ui_open_tab / ui_highlight / ui_set_filter: UI actions
+ *   - search_notes: full-text search across vault notes
+ *   - get_vault_context: vault structure overview (types, note count, folders)
+ *   - get_note: parsed frontmatter + content (convenience over raw cat)
+ *   - open_note: signal Laputa UI to open a note as a tab
+ *   - highlight_editor: visually highlight a UI element (editor, tab, etc.)
+ *   - refresh_vault: trigger vault rescan so new/modified files appear
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
@@ -23,70 +19,47 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js'
-import {
-  readNote, createNote, searchNotes, appendToNote,
-  editNoteFrontmatter, deleteNote, linkNotes, listNotes, vaultContext,
-} from './vault.js'
-import { startUiBridge } from './ws-bridge.js'
+import WebSocket from 'ws'
+import { searchNotes, getNote, vaultContext } from './vault.js'
 
 const VAULT_PATH = process.env.VAULT_PATH || process.env.HOME + '/Laputa'
 const WS_UI_PORT = parseInt(process.env.WS_UI_PORT || '9711', 10)
+const WS_UI_URL = `ws://localhost:${WS_UI_PORT}`
 
-// Start the UI bridge so stdio-based MCP tools can broadcast UI actions.
-// If the port is already in use (e.g. by the running Laputa app), continue
-// without the bridge — vault tools still work via stdio MCP.
-let uiBridge = null
-startUiBridge(WS_UI_PORT).then((bridge) => {
-  uiBridge = bridge
-})
+// Connect as a WebSocket CLIENT to the UI bridge (run by ws-bridge.js).
+// The bridge relays messages to all other clients (the React frontend).
+let uiSocket = null
+const RECONNECT_INTERVAL_MS = 3000
+
+function connectUiBridge() {
+  try {
+    const ws = new WebSocket(WS_UI_URL)
+    ws.on('open', () => {
+      uiSocket = ws
+      console.error(`[mcp] Connected to UI bridge at ${WS_UI_URL}`)
+    })
+    ws.on('close', () => {
+      uiSocket = null
+      setTimeout(connectUiBridge, RECONNECT_INTERVAL_MS)
+    })
+    ws.on('error', () => {
+      // Silent — bridge may not be running yet, will retry
+    })
+  } catch {
+    setTimeout(connectUiBridge, RECONNECT_INTERVAL_MS)
+  }
+}
+connectUiBridge()
 
 function broadcastUiAction(action, payload) {
-  if (!uiBridge) return
-  const msg = JSON.stringify({ type: 'ui_action', action, ...payload })
-  for (const client of uiBridge.clients) {
-    if (client.readyState === 1) client.send(msg)
-  }
+  if (!uiSocket || uiSocket.readyState !== WebSocket.OPEN) return
+  uiSocket.send(JSON.stringify({ type: 'ui_action', action, ...payload }))
 }
 
 const TOOLS = [
-  {
-    name: 'open_note',
-    description: 'Open and read a note from the vault by its relative path',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: { type: 'string', description: 'Relative path to the note (e.g. "project/my-project.md")' },
-      },
-      required: ['path'],
-    },
-  },
-  {
-    name: 'read_note',
-    description: 'Read the full content of a note',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: { type: 'string', description: 'Relative path to the note' },
-      },
-      required: ['path'],
-    },
-  },
-  {
-    name: 'create_note',
-    description: 'Create a new note in the vault with a title and optional frontmatter',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: { type: 'string', description: 'Relative path for the new note (e.g. "note/my-idea.md")' },
-        title: { type: 'string', description: 'Title of the note' },
-        is_a: { type: 'string', description: 'Entity type (Project, Note, Experiment, etc.)' },
-      },
-      required: ['path', 'title'],
-    },
-  },
   {
     name: 'search_notes',
-    description: 'Search notes in the vault by title or content',
+    description: 'Full-text search across vault notes by title or content. Returns matching paths, titles, and snippets.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -97,72 +70,24 @@ const TOOLS = [
     },
   },
   {
-    name: 'append_to_note',
-    description: 'Append text to the end of an existing note',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: { type: 'string', description: 'Relative path to the note' },
-        text: { type: 'string', description: 'Text to append' },
-      },
-      required: ['path', 'text'],
-    },
-  },
-  {
-    name: 'edit_note_frontmatter',
-    description: 'Merge a patch object into a note\'s YAML frontmatter',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: { type: 'string', description: 'Relative path to the note' },
-        patch: { type: 'object', description: 'Key-value pairs to merge into frontmatter' },
-      },
-      required: ['path', 'patch'],
-    },
-  },
-  {
-    name: 'delete_note',
-    description: 'Delete a note file from the vault',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: { type: 'string', description: 'Relative path to the note to delete' },
-      },
-      required: ['path'],
-    },
-  },
-  {
-    name: 'link_notes',
-    description: 'Add a target title to an array property in a note\'s frontmatter (e.g. add "Marco" to people: [])',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        source_path: { type: 'string', description: 'Relative path to the source note' },
-        property: { type: 'string', description: 'Frontmatter property name (e.g. "people", "tags")' },
-        target_title: { type: 'string', description: 'Title to add to the array' },
-      },
-      required: ['source_path', 'property', 'target_title'],
-    },
-  },
-  {
-    name: 'list_notes',
-    description: 'List all notes in the vault, optionally filtered by type frontmatter field',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        type_filter: { type: 'string', description: 'Filter by type frontmatter value' },
-        sort: { type: 'string', enum: ['title', 'mtime'], description: 'Sort order (default: title)' },
-      },
-    },
-  },
-  {
-    name: 'vault_context',
-    description: 'Get vault context: unique entity types and 20 most recently modified notes',
+    name: 'get_vault_context',
+    description: 'Get vault orientation: entity types, total note count, top-level folders, and 20 most recently modified notes.',
     inputSchema: { type: 'object', properties: {} },
   },
   {
-    name: 'ui_open_note',
-    description: 'Open a note in the Laputa UI editor',
+    name: 'get_note',
+    description: 'Read a note with parsed YAML frontmatter and markdown content. Returns {path, frontmatter, content}.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Relative path to the note (e.g. "project/my-project.md")' },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'open_note',
+    description: 'Open a note in the Laputa UI as a new tab. Use after creating or editing a note so the user can see it.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -172,68 +97,36 @@ const TOOLS = [
     },
   },
   {
-    name: 'ui_open_tab',
-    description: 'Open a note in a new tab in the Laputa UI',
+    name: 'highlight_editor',
+    description: 'Visually highlight a UI element in Laputa (editor, tab, properties panel, or note list). The highlight auto-clears after a short delay.',
     inputSchema: {
       type: 'object',
       properties: {
-        path: { type: 'string', description: 'Relative path to the note' },
-      },
-      required: ['path'],
-    },
-  },
-  {
-    name: 'ui_highlight',
-    description: 'Highlight a UI element in the Laputa interface',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        element: { type: 'string', enum: ['editor', 'tab', 'properties', 'notelist'], description: 'UI element to highlight' },
-        path: { type: 'string', description: 'Relative path to the note (optional)' },
+        element: { type: 'string', enum: ['editor', 'tab', 'properties', 'notelist'], description: 'Which UI element to highlight' },
+        path: { type: 'string', description: 'Optional note path to associate with the highlight' },
       },
       required: ['element'],
     },
   },
   {
-    name: 'ui_set_filter',
-    description: 'Set the sidebar filter to show notes of a specific type',
+    name: 'refresh_vault',
+    description: 'Trigger a vault rescan so new or modified files appear immediately in the Laputa note list.',
     inputSchema: {
       type: 'object',
       properties: {
-        type: { type: 'string', description: 'Type to filter by' },
+        path: { type: 'string', description: 'Optional specific note path that changed' },
       },
-      required: ['type'],
     },
   },
 ]
 
 const TOOL_HANDLERS = {
-  open_note: handleReadNote,
-  read_note: handleReadNote,
-  create_note: handleCreateNote,
   search_notes: handleSearchNotes,
-  append_to_note: handleAppendToNote,
-  edit_note_frontmatter: handleEditFrontmatter,
-  delete_note: handleDeleteNote,
-  link_notes: handleLinkNotes,
-  list_notes: handleListNotes,
-  vault_context: handleVaultContext,
-  ui_open_note: handleUiOpenNote,
-  ui_open_tab: handleUiOpenTab,
-  ui_highlight: handleUiHighlight,
-  ui_set_filter: handleUiSetFilter,
-}
-
-async function handleReadNote(args) {
-  const content = await readNote(VAULT_PATH, args.path)
-  return { content: [{ type: 'text', text: content }] }
-}
-
-async function handleCreateNote(args) {
-  const frontmatter = {}
-  if (args.is_a) frontmatter.is_a = args.is_a
-  const absPath = await createNote(VAULT_PATH, args.path, args.title, frontmatter)
-  return { content: [{ type: 'text', text: `Created note at ${absPath}` }] }
+  get_vault_context: handleVaultContext,
+  get_note: handleGetNote,
+  open_note: handleOpenNote,
+  highlight_editor: handleHighlightEditor,
+  refresh_vault: handleRefreshVault,
 }
 
 async function handleSearchNotes(args) {
@@ -244,63 +137,38 @@ async function handleSearchNotes(args) {
   return { content: [{ type: 'text', text }] }
 }
 
-async function handleAppendToNote(args) {
-  await appendToNote(VAULT_PATH, args.path, args.text)
-  return { content: [{ type: 'text', text: `Appended text to ${args.path}` }] }
-}
-
-async function handleEditFrontmatter(args) {
-  const updated = await editNoteFrontmatter(VAULT_PATH, args.path, args.patch)
-  return { content: [{ type: 'text', text: JSON.stringify(updated) }] }
-}
-
-async function handleDeleteNote(args) {
-  await deleteNote(VAULT_PATH, args.path)
-  return { content: [{ type: 'text', text: `Deleted ${args.path}` }] }
-}
-
-async function handleLinkNotes(args) {
-  const arr = await linkNotes(VAULT_PATH, args.source_path, args.property, args.target_title)
-  return { content: [{ type: 'text', text: `${args.property}: [${arr.join(', ')}]` }] }
-}
-
-async function handleListNotes(args) {
-  const notes = await listNotes(VAULT_PATH, args.type_filter, args.sort)
-  const text = notes.length === 0
-    ? 'No notes found.'
-    : notes.map(n => `${n.title} (${n.path})${n.type ? ` [${n.type}]` : ''}`).join('\n')
-  return { content: [{ type: 'text', text }] }
-}
-
 async function handleVaultContext() {
   const ctx = await vaultContext(VAULT_PATH)
   return { content: [{ type: 'text', text: JSON.stringify(ctx, null, 2) }] }
 }
 
-function handleUiOpenNote(args) {
-  broadcastUiAction('open_note', { path: args.path })
-  return { content: [{ type: 'text', text: `Opening ${args.path} in UI` }] }
+async function handleGetNote(args) {
+  const note = await getNote(VAULT_PATH, args.path)
+  return { content: [{ type: 'text', text: JSON.stringify(note, null, 2) }] }
 }
 
-function handleUiOpenTab(args) {
+function handleOpenNote(args) {
+  // Refresh vault first so the new/modified note appears in the note list,
+  // then signal the UI to open it in a tab.
+  broadcastUiAction('vault_changed', { path: args.path })
   broadcastUiAction('open_tab', { path: args.path })
-  return { content: [{ type: 'text', text: `Opening tab for ${args.path}` }] }
+  return { content: [{ type: 'text', text: `Opening ${args.path} in Laputa` }] }
 }
 
-function handleUiHighlight(args) {
+function handleHighlightEditor(args) {
   broadcastUiAction('highlight', { element: args.element, path: args.path })
   return { content: [{ type: 'text', text: `Highlighting ${args.element}` }] }
 }
 
-function handleUiSetFilter(args) {
-  broadcastUiAction('set_filter', { type: args.type })
-  return { content: [{ type: 'text', text: `Filter set to ${args.type}` }] }
+function handleRefreshVault(args) {
+  broadcastUiAction('vault_changed', { path: args?.path })
+  return { content: [{ type: 'text', text: 'Vault refresh triggered' }] }
 }
 
 // --- Server setup ---
 
 const server = new Server(
-  { name: 'laputa-mcp-server', version: '0.1.0' },
+  { name: 'laputa-mcp-server', version: '0.3.0' },
   { capabilities: { tools: {} } },
 )
 

mcp-server/test.js

@@ -4,8 +4,7 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 import os from 'node:os'
 import {
-  readNote, createNote, searchNotes, appendToNote, findMarkdownFiles,
-  editNoteFrontmatter, deleteNote, linkNotes, listNotes, vaultContext,
+  findMarkdownFiles, getNote, searchNotes, vaultContext,
 } from './vault.js'
 
 let tmpDir
@@ -65,39 +64,23 @@ describe('findMarkdownFiles', () => {
   })
 })
 
-describe('readNote', () => {
-  it('should read a note by relative path', async () => {
-    const content = await readNote(tmpDir, 'project/test-project.md')
-    assert.ok(content.includes('Test Project'))
-    assert.ok(content.includes('is_a: Project'))
+describe('getNote', () => {
+  it('should read a note with parsed frontmatter', async () => {
+    const note = await getNote(tmpDir, 'project/test-project.md')
+    assert.equal(note.path, 'project/test-project.md')
+    assert.equal(note.frontmatter.title, 'Test Project')
+    assert.equal(note.frontmatter.is_a, 'Project')
+    assert.ok(note.content.includes('test project for the MCP server'))
   })
 
   it('should throw for missing notes', async () => {
     await assert.rejects(
-      () => readNote(tmpDir, 'nonexistent.md'),
+      () => getNote(tmpDir, 'nonexistent.md'),
       { code: 'ENOENT' }
     )
   })
 })
 
-describe('createNote', () => {
-  it('should create a note with frontmatter', async () => {
-    const absPath = await createNote(tmpDir, 'note/new-note.md', 'My New Note', { is_a: 'Note' })
-    assert.ok(absPath.endsWith('new-note.md'))
-
-    const content = await fs.readFile(absPath, 'utf-8')
-    assert.ok(content.includes('title: My New Note'))
-    assert.ok(content.includes('is_a: Note'))
-    assert.ok(content.includes('# My New Note'))
-  })
-
-  it('should create parent directories', async () => {
-    const absPath = await createNote(tmpDir, 'deep/nested/dir/note.md', 'Deep Note')
-    const content = await fs.readFile(absPath, 'utf-8')
-    assert.ok(content.includes('# Deep Note'))
-  })
-})
-
 describe('searchNotes', () => {
   it('should find notes matching title', async () => {
     const results = await searchNotes(tmpDir, 'Test Project')
@@ -121,123 +104,6 @@ describe('searchNotes', () => {
   })
 })
 
-describe('appendToNote', () => {
-  it('should append text to a note', async () => {
-    await appendToNote(tmpDir, 'note/daily-log.md', '## Evening Update\nFinished testing.')
-    const content = await readNote(tmpDir, 'note/daily-log.md')
-    assert.ok(content.includes('## Evening Update'))
-    assert.ok(content.includes('Finished testing.'))
-  })
-})
-
-describe('editNoteFrontmatter', () => {
-  it('should merge a patch into frontmatter', async () => {
-    const updated = await editNoteFrontmatter(tmpDir, 'project/test-project.md', { status: 'Completed', priority: 'High' })
-    assert.equal(updated.status, 'Completed')
-    assert.equal(updated.priority, 'High')
-    assert.equal(updated.title, 'Test Project')
-  })
-
-  it('should preserve existing frontmatter fields', async () => {
-    const content = await readNote(tmpDir, 'project/test-project.md')
-    assert.ok(content.includes('is_a: Project'))
-    assert.ok(content.includes('status: Completed'))
-  })
-
-  it('should throw for missing file', async () => {
-    await assert.rejects(
-      () => editNoteFrontmatter(tmpDir, 'nonexistent.md', { foo: 'bar' }),
-      { code: 'ENOENT' }
-    )
-  })
-})
-
-describe('deleteNote', () => {
-  it('should delete an existing note', async () => {
-    const delPath = 'note/to-delete.md'
-    await createNote(tmpDir, delPath, 'To Delete')
-    const absPath = path.join(tmpDir, delPath)
-
-    // Verify it exists
-    await fs.access(absPath)
-
-    await deleteNote(tmpDir, delPath)
-
-    await assert.rejects(
-      () => fs.access(absPath),
-      { code: 'ENOENT' }
-    )
-  })
-
-  it('should throw for missing file', async () => {
-    await assert.rejects(
-      () => deleteNote(tmpDir, 'nonexistent.md'),
-      { code: 'ENOENT' }
-    )
-  })
-})
-
-describe('linkNotes', () => {
-  it('should add a target to an array property', async () => {
-    const linkPath = 'project/link-test.md'
-    await createNote(tmpDir, linkPath, 'Link Test', { is_a: 'Project' })
-
-    const result = await linkNotes(tmpDir, linkPath, 'related_to', '[[note/daily-log]]')
-    assert.deepEqual(result, ['[[note/daily-log]]'])
-  })
-
-  it('should not duplicate existing links', async () => {
-    const linkPath = 'project/link-test.md'
-
-    await linkNotes(tmpDir, linkPath, 'related_to', '[[note/daily-log]]')
-    const result = await linkNotes(tmpDir, linkPath, 'related_to', '[[note/daily-log]]')
-    assert.equal(result.length, 1)
-  })
-
-  it('should add multiple distinct links', async () => {
-    const linkPath = 'project/link-test.md'
-
-    await linkNotes(tmpDir, linkPath, 'related_to', '[[project/test-project]]')
-    const result = await linkNotes(tmpDir, linkPath, 'related_to', '[[project/test-project]]')
-    // Should have daily-log and test-project
-    assert.ok(result.includes('[[note/daily-log]]'))
-    assert.ok(result.includes('[[project/test-project]]'))
-    assert.equal(result.length, 2)
-  })
-})
-
-describe('listNotes', () => {
-  it('should list all notes sorted by title', async () => {
-    const notes = await listNotes(tmpDir)
-    assert.ok(notes.length >= 3)
-    // Verify sorted by title
-    for (let i = 1; i < notes.length; i++) {
-      assert.ok(notes[i - 1].title.localeCompare(notes[i].title) <= 0)
-    }
-  })
-
-  it('should filter by type', async () => {
-    const projects = await listNotes(tmpDir, 'Project')
-    assert.ok(projects.length >= 1)
-    for (const n of projects) {
-      assert.equal(n.type, 'Project')
-    }
-  })
-
-  it('should return empty for unknown type', async () => {
-    const notes = await listNotes(tmpDir, 'UnknownType12345')
-    assert.equal(notes.length, 0)
-  })
-
-  it('should support mtime sorting', async () => {
-    const notes = await listNotes(tmpDir, undefined, 'mtime')
-    assert.ok(notes.length >= 1)
-    // Just verify it returns results without crashing
-    assert.ok(notes[0].path)
-    assert.ok(notes[0].title)
-  })
-})
-
 describe('vaultContext', () => {
   it('should return types, recent notes, and vault path', async () => {
     const ctx = await vaultContext(tmpDir)
@@ -264,4 +130,15 @@ describe('vaultContext', () => {
       assert.ok(note.title)
     }
   })
+
+  it('should include folders', async () => {
+    const ctx = await vaultContext(tmpDir)
+    assert.ok(ctx.folders.includes('project/'))
+    assert.ok(ctx.folders.includes('note/'))
+  })
+
+  it('should report correct note count', async () => {
+    const ctx = await vaultContext(tmpDir)
+    assert.equal(ctx.noteCount, 3)
+  })
 })

mcp-server/vault.js

@@ -1,5 +1,6 @@
 /**
- * Vault operations — file I/O for Laputa markdown vault.
+ * Vault operations — read-only helpers for Laputa markdown vault.
+ * Write operations are handled by the agent's native bash/write/edit tools.
  */
 import fs from 'node:fs/promises'
 import path from 'node:path'
@@ -26,36 +27,20 @@ export async function findMarkdownFiles(dir) {
 }
 
 /**
- * Read a note's content by path (absolute or relative to vault).
+ * Read a note with parsed frontmatter and content.
  * @param {string} vaultPath
  * @param {string} notePath
- * @returns {Promise<string>}
+ * @returns {Promise<{path: string, frontmatter: Record<string, unknown>, content: string}>}
  */
-export async function readNote(vaultPath, notePath) {
+export async function getNote(vaultPath, notePath) {
   const absPath = path.isAbsolute(notePath) ? notePath : path.join(vaultPath, notePath)
-  return fs.readFile(absPath, 'utf-8')
-}
-
-/**
- * Create a new note with optional frontmatter.
- * @param {string} vaultPath
- * @param {string} relativePath
- * @param {string} title
- * @param {Record<string, string>} [frontmatter]
- * @returns {Promise<string>} The absolute path of the created file.
- */
-export async function createNote(vaultPath, relativePath, title, frontmatter = {}) {
-  const absPath = path.join(vaultPath, relativePath)
-  await fs.mkdir(path.dirname(absPath), { recursive: true })
-
-  const fmEntries = { title, ...frontmatter }
-  const fmLines = Object.entries(fmEntries)
-    .map(([k, v]) => `${k}: ${v}`)
-    .join('\n')
-
-  const content = `---\n${fmLines}\n---\n\n# ${title}\n\n`
-  await fs.writeFile(absPath, content, 'utf-8')
-  return absPath
+  const raw = await fs.readFile(absPath, 'utf-8')
+  const parsed = matter(raw)
+  return {
+    path: path.relative(vaultPath, absPath),
+    frontmatter: parsed.data,
+    content: parsed.content.trim(),
+  }
 }
 
 /**
@@ -92,110 +77,14 @@ export async function searchNotes(vaultPath, query, limit = 10) {
 }
 
 /**
- * Append text to the end of a note.
+ * Get vault context: unique types, note count, top-level folders, and 20 most recent notes.
  * @param {string} vaultPath
- * @param {string} notePath
- * @param {string} text
- * @returns {Promise<void>}
- */
-export async function appendToNote(vaultPath, notePath, text) {
-  const absPath = path.isAbsolute(notePath) ? notePath : path.join(vaultPath, notePath)
-  const current = await fs.readFile(absPath, 'utf-8')
-  const separator = current.endsWith('\n') ? '\n' : '\n\n'
-  await fs.writeFile(absPath, current + separator + text + '\n', 'utf-8')
-}
-
-/**
- * Merge a patch object into a note's YAML frontmatter.
- * @param {string} vaultPath
- * @param {string} notePath
- * @param {Record<string, unknown>} patch
- * @returns {Promise<Record<string, unknown>>} The updated frontmatter.
- */
-export async function editNoteFrontmatter(vaultPath, notePath, patch) {
-  const absPath = path.isAbsolute(notePath) ? notePath : path.join(vaultPath, notePath)
-  const raw = await fs.readFile(absPath, 'utf-8')
-  const parsed = matter(raw)
-  Object.assign(parsed.data, patch)
-  const updated = matter.stringify(parsed.content, parsed.data)
-  await fs.writeFile(absPath, updated, 'utf-8')
-  return parsed.data
-}
-
-/**
- * Delete a note file.
- * @param {string} vaultPath
- * @param {string} notePath
- * @returns {Promise<void>}
- */
-export async function deleteNote(vaultPath, notePath) {
-  const absPath = path.isAbsolute(notePath) ? notePath : path.join(vaultPath, notePath)
-  await fs.unlink(absPath)
-}
-
-/**
- * Add a target title to an array property in a note's frontmatter.
- * Creates the property as an array if it doesn't exist.
- * @param {string} vaultPath
- * @param {string} sourcePath
- * @param {string} property
- * @param {string} targetTitle
- * @returns {Promise<string[]>} The updated array.
- */
-export async function linkNotes(vaultPath, sourcePath, property, targetTitle) {
-  const absPath = path.isAbsolute(sourcePath) ? sourcePath : path.join(vaultPath, sourcePath)
-  const raw = await fs.readFile(absPath, 'utf-8')
-  const parsed = matter(raw)
-  const current = Array.isArray(parsed.data[property]) ? parsed.data[property] : []
-  if (!current.includes(targetTitle)) {
-    current.push(targetTitle)
-  }
-  parsed.data[property] = current
-  const updated = matter.stringify(parsed.content, parsed.data)
-  await fs.writeFile(absPath, updated, 'utf-8')
-  return current
-}
-
-/**
- * List all notes in the vault, optionally filtered by type.
- * @param {string} vaultPath
- * @param {string} [typeFilter]
- * @param {string} [sort] - 'title' or 'mtime' (default: 'title')
- * @returns {Promise<Array<{path: string, title: string, type: string|null}>>}
- */
-export async function listNotes(vaultPath, typeFilter, sort = 'title') {
-  const files = await findMarkdownFiles(vaultPath)
-  const notes = await Promise.all(files.map(async (filePath) => {
-    const raw = await fs.readFile(filePath, 'utf-8')
-    const parsed = matter(raw)
-    const relativePath = path.relative(vaultPath, filePath)
-    const title = parsed.data.title || extractTitle(raw, path.basename(filePath, '.md'))
-    const type = parsed.data.type || parsed.data.is_a || null
-    const stat = sort === 'mtime' ? await fs.stat(filePath) : null
-    return { path: relativePath, title, type, mtime: stat?.mtimeMs ?? 0 }
-  }))
-
-  const filtered = typeFilter
-    ? notes.filter(n => n.type === typeFilter)
-    : notes
-
-  if (sort === 'mtime') {
-    filtered.sort((a, b) => b.mtime - a.mtime)
-  } else {
-    filtered.sort((a, b) => a.title.localeCompare(b.title))
-  }
-
-  return filtered.map(({ mtime: _mtime, ...rest }) => rest)
-}
-
-/**
- * Get vault context: unique types and 20 most recent notes.
- * @param {string} vaultPath
- * @returns {Promise<{types: string[], recentNotes: Array<{path: string, title: string, type: string|null}>, vaultPath: string}>}
+ * @returns {Promise<{types: string[], noteCount: number, folders: string[], recentNotes: Array<{path: string, title: string, type: string|null}>, vaultPath: string}>}
  */
 export async function vaultContext(vaultPath) {
   const files = await findMarkdownFiles(vaultPath)
   const typesSet = new Set()
+  const foldersSet = new Set()
   const notesWithMtime = []
 
   for (const filePath of files) {
@@ -203,9 +92,12 @@ export async function vaultContext(vaultPath) {
     const parsed = matter(raw)
     const type = parsed.data.type || parsed.data.is_a || null
     if (type) typesSet.add(type)
+    const rel = path.relative(vaultPath, filePath)
+    const topFolder = rel.split(path.sep)[0]
+    if (topFolder !== rel) foldersSet.add(topFolder + '/')
     const stat = await fs.stat(filePath)
     notesWithMtime.push({
-      path: path.relative(vaultPath, filePath),
+      path: rel,
       title: parsed.data.title || extractTitle(raw, path.basename(filePath, '.md')),
       type,
       mtime: stat.mtimeMs,
@@ -215,7 +107,24 @@ export async function vaultContext(vaultPath) {
   notesWithMtime.sort((a, b) => b.mtime - a.mtime)
   const recentNotes = notesWithMtime.slice(0, 20).map(({ mtime: _mtime, ...rest }) => rest)
 
-  return { types: [...typesSet].sort(), recentNotes, vaultPath }
+  // Read config files for AI agent context
+  const configFiles = {}
+  try {
+    const agentsPath = path.join(vaultPath, 'config', 'agents.md')
+    const agentsContent = await fs.readFile(agentsPath, 'utf-8')
+    configFiles.agents = agentsContent
+  } catch {
+    // config/agents.md may not exist yet
+  }
+
+  return {
+    types: [...typesSet].sort(),
+    noteCount: files.length,
+    folders: [...foldersSet].sort(),
+    recentNotes,
+    configFiles,
+    vaultPath,
+  }
 }
 
 // --- Helpers ---

mcp-server/ws-bridge.js

@@ -22,8 +22,7 @@
 import { createServer } from 'node:http'
 import { WebSocketServer } from 'ws'
 import {
-  readNote, createNote, searchNotes, appendToNote,
-  editNoteFrontmatter, deleteNote, linkNotes, listNotes, vaultContext,
+  getNote, searchNotes, vaultContext,
 } from './vault.js'
 
 const VAULT_PATH = process.env.VAULT_PATH || process.env.HOME + '/Laputa'
@@ -41,27 +40,18 @@ function broadcastUiAction(action, payload) {
   }
 }
 
-function buildFrontmatter(args) {
-  const fm = {}
-  if (args.is_a) fm.is_a = args.is_a
-  return fm
-}
 
 const TOOL_HANDLERS = {
-  open_note: (args) => readNote(VAULT_PATH, args.path).then(text => ({ content: text })),
-  read_note: (args) => readNote(VAULT_PATH, args.path).then(text => ({ content: text })),
-  create_note: (args) => createNote(VAULT_PATH, args.path, args.title, buildFrontmatter(args)),
+  open_note: (args) => getNote(VAULT_PATH, args.path).then(note => ({ content: note.content, frontmatter: note.frontmatter })),
+  read_note: (args) => getNote(VAULT_PATH, args.path).then(note => ({ content: note.content, frontmatter: note.frontmatter })),
   search_notes: (args) => searchNotes(VAULT_PATH, args.query, args.limit),
-  append_to_note: (args) => appendToNote(VAULT_PATH, args.path, args.text).then(() => ({ ok: true })),
-  edit_note_frontmatter: (args) => editNoteFrontmatter(VAULT_PATH, args.path, args.patch),
-  delete_note: (args) => deleteNote(VAULT_PATH, args.path).then(() => ({ ok: true })),
-  link_notes: (args) => linkNotes(VAULT_PATH, args.source_path, args.property, args.target_title),
-  list_notes: (args) => listNotes(VAULT_PATH, args.type_filter, args.sort),
   vault_context: () => vaultContext(VAULT_PATH),
-  ui_open_note: (args) => { broadcastUiAction('open_note', { path: args.path }); return { ok: true } },
-  ui_open_tab: (args) => { broadcastUiAction('open_tab', { path: args.path }); return { ok: true } },
+  ui_open_note: (args) => { broadcastUiAction('vault_changed', { path: args.path }); broadcastUiAction('open_note', { path: args.path }); return { ok: true } },
+  ui_open_tab: (args) => { broadcastUiAction('vault_changed', { path: args.path }); broadcastUiAction('open_tab', { path: args.path }); return { ok: true } },
   ui_highlight: (args) => { broadcastUiAction('highlight', { element: args.element, path: args.path }); return { ok: true } },
-  ui_set_filter: (args) => { broadcastUiAction('set_filter', { type: args.type }); return { ok: true } },
+  ui_set_filter: (args) => { broadcastUiAction('set_filter', { filterType: args.type }); return { ok: true } },
+  highlight_editor: (args) => { broadcastUiAction('highlight', { element: args.element, path: args.path }); return { ok: true } },
+  refresh_vault: (args) => { broadcastUiAction('vault_changed', { path: args?.path }); return { ok: true } },
 }
 
 async function handleMessage(data) {
@@ -101,8 +91,15 @@ export function startUiBridge(port = WS_UI_PORT) {
 
     httpServer.listen(port, () => {
       const wss = new WebSocketServer({ server: httpServer })
-      wss.on('connection', () => {
+      wss.on('connection', (ws) => {
         console.error(`[ws-bridge] UI client connected on port ${port}`)
+        // Relay: when a client sends a message, broadcast to all OTHER clients.
+        // This allows the MCP stdio server (connected as a client) to reach the frontend.
+        ws.on('message', (raw) => {
+          for (const client of wss.clients) {
+            if (client !== ws && client.readyState === 1) client.send(raw.toString())
+          }
+        })
       })
       uiBridge = wss
       console.error(`[ws-bridge] UI bridge listening on ws://localhost:${port}`)

package.json

@@ -13,6 +13,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "playwright test",
+    "playwright:smoke": "playwright test tests/smoke/",
     "test:coverage": "vitest run --coverage",
     "prepare": "husky"
   },
@@ -72,6 +73,7 @@
     "@types/node": "^24.10.1",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
+    "@types/ws": "^8.18.1",
     "@vitejs/plugin-react": "^5.1.1",
     "@vitest/coverage-v8": "^4.0.18",
     "esbuild": "^0.27.3",
@@ -85,6 +87,7 @@
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.48.0",
     "vite": "^7.3.1",
-    "vitest": "^4.0.18"
+    "vitest": "^4.0.18",
+    "ws": "^8.19.0"
   }
 }

playwright.config.ts

@@ -1,15 +1,18 @@
 import { defineConfig } from '@playwright/test'
 
 export default defineConfig({
-  testDir: './e2e',
-  timeout: 30000,
+  testDir: './tests/smoke',
+  timeout: 15_000,
+  retries: 0,
   workers: 1,
   use: {
-    baseURL: 'http://localhost:5173',
+    baseURL: process.env.BASE_URL || 'http://localhost:5201',
+    headless: true,
   },
+  projects: [{ name: 'chromium', use: { browserName: 'chromium' } }],
   webServer: {
-    command: 'pnpm dev',
-    port: 5173,
+    command: `pnpm dev --port ${process.env.BASE_URL?.match(/:(\d+)/)?.[1] || '5201'}`,
+    url: process.env.BASE_URL || 'http://localhost:5201',
     reuseExistingServer: true,
   },
 })

pnpm-lock.yaml

@@ -168,6 +168,9 @@ importers:
       '@types/react-dom':
         specifier: ^19.2.3
         version: 19.2.3(@types/react@19.2.14)
+      '@types/ws':
+        specifier: ^8.18.1
+        version: 8.18.1
       '@vitejs/plugin-react':
         specifier: ^5.1.1
         version: 5.1.4(vite@7.3.1(@types/node@24.10.13)(jiti@2.6.1)(lightningcss@1.30.2))
@@ -210,6 +213,9 @@ importers:
       vitest:
         specifier: ^4.0.18
         version: 4.0.18(@types/node@24.10.13)(jiti@2.6.1)(jsdom@28.0.0)(lightningcss@1.30.2)
+      ws:
+        specifier: ^8.19.0
+        version: 8.19.0
 
   mcp-server:
     dependencies:
@@ -2043,6 +2049,9 @@ packages:
   '@types/use-sync-external-store@1.5.0':
     resolution: {integrity: sha512-5dyB8nLC/qogMrlCizZnYWQTA4lnb/v+It+sqNl5YnSRAPMlIqY/X0Xn+gZw8vOL+TgTTr28VEbn3uf8fUtAkw==}
 
+  '@types/ws@8.18.1':
+    resolution: {integrity: sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==}
+
   '@typescript-eslint/eslint-plugin@8.55.0':
     resolution: {integrity: sha512-1y/MVSz0NglV1ijHC8OT49mPJ4qhPYjiK08YUQVbIOyu+5k862LKUHFkpKHWu//zmr7hDR2rhwUm6gnCGNmGBQ==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
@@ -6011,6 +6020,10 @@ snapshots:
 
   '@types/use-sync-external-store@1.5.0': {}
 
+  '@types/ws@8.18.1':
+    dependencies:
+      '@types/node': 24.10.13
+
   '@typescript-eslint/eslint-plugin@8.55.0(@typescript-eslint/parser@8.55.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)':
     dependencies:
       '@eslint-community/regexpp': 4.12.2

scripts/bundle-qmd.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+# Bundle qmd into a self-contained directory for Tauri resource embedding.
+#
+# Output: src-tauri/resources/qmd/
+#   qmd                                  — compiled standalone binary
+#   node_modules/sqlite-vec/             — JS shim for sqlite-vec
+#   node_modules/sqlite-vec-darwin-arm64/ — native .dylib (arm64)
+#   node_modules/sqlite-vec-darwin-x64/  — native .dylib (x64)
+#   node_modules/node-llama-cpp/         — stub (keyword search only)
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$SCRIPT_DIR/.."
+OUT="$ROOT/src-tauri/resources/qmd"
+
+# ---------- locate tools ----------
+find_bun() {
+  for c in \
+    "$HOME/.bun/bin/bun" \
+    "/opt/homebrew/bin/bun" \
+    "/usr/local/bin/bun"; do
+    [[ -x "$c" ]] && { echo "$c"; return 0; }
+  done
+  command -v bun 2>/dev/null && return 0
+  return 1
+}
+
+BUN=$(find_bun) || { echo "ERROR: bun not found — install from https://bun.sh" >&2; exit 1; }
+echo "Using bun: $BUN"
+
+# ---------- locate qmd source ----------
+# Prefer bundled source in tools/qmd/ (works in CI and dev),
+# then fall back to globally installed qmd on dev machines.
+QMD_SRC=""
+for c in \
+  "$ROOT/tools/qmd" \
+  "$HOME/.bun/install/global/node_modules/qmd" \
+  "/opt/homebrew/lib/node_modules/qmd" \
+  "/usr/local/lib/node_modules/qmd"; do
+  [[ -f "$c/src/qmd.ts" ]] && { QMD_SRC="$c"; break; }
+done
+
+[[ -n "$QMD_SRC" ]] || { echo "ERROR: qmd source not found. tools/qmd/ is missing or incomplete." >&2; exit 1; }
+echo "Using qmd source: $QMD_SRC"
+
+# Install qmd dependencies if needed (for CI where node_modules don't exist yet)
+if [[ ! -d "$QMD_SRC/node_modules" ]]; then
+  echo "Installing qmd dependencies..."
+  (cd "$QMD_SRC" && "$BUN" install --frozen-lockfile)
+fi
+
+# ---------- compile ----------
+echo "Compiling qmd with bun build --compile..."
+mkdir -p "$OUT"
+
+(cd "$QMD_SRC" && "$BUN" build --compile \
+  "src/qmd.ts" \
+  --outfile "$OUT/qmd" \
+  --external node-llama-cpp \
+  --external sqlite-vec \
+  --external sqlite-vec-darwin-arm64 \
+  --external sqlite-vec-darwin-x64)
+
+chmod +x "$OUT/qmd"
+
+# ---------- bundle sqlite-vec ----------
+echo "Bundling sqlite-vec native extensions..."
+
+# Find sqlite-vec packages — prefer node_modules in QMD_SRC (after bun install),
+# fall back to bun global cache for dev machines.
+NM="$QMD_SRC/node_modules"
+
+find_pkg() {
+  local pkg="$1"
+  # Check node_modules from bun install in QMD_SRC first
+  if [[ -d "$NM/$pkg" ]]; then
+    echo "$NM/$pkg"; return 0
+  fi
+  # Fall back to bun global cache
+  local cache_dir
+  cache_dir=$(find "$HOME/.bun/install/cache" -maxdepth 1 -name "${pkg}@*" -type d 2>/dev/null | head -1)
+  [[ -n "$cache_dir" ]] && echo "$cache_dir" && return 0
+  return 1
+}
+
+# sqlite-vec JS shim
+SQLVEC_DIR=$(find_pkg "sqlite-vec") || { echo "ERROR: sqlite-vec not found" >&2; exit 1; }
+mkdir -p "$OUT/node_modules/sqlite-vec"
+cp "$SQLVEC_DIR/index.mjs" "$OUT/node_modules/sqlite-vec/index.mjs"
+cp "$SQLVEC_DIR/package.json" "$OUT/node_modules/sqlite-vec/package.json"
+[[ -f "$SQLVEC_DIR/index.cjs" ]] && cp "$SQLVEC_DIR/index.cjs" "$OUT/node_modules/sqlite-vec/index.cjs"
+
+# sqlite-vec-darwin-arm64
+ARM64_DIR=$(find_pkg "sqlite-vec-darwin-arm64") || true
+if [[ -n "$ARM64_DIR" ]]; then
+  mkdir -p "$OUT/node_modules/sqlite-vec-darwin-arm64"
+  cp "$ARM64_DIR/vec0.dylib" "$OUT/node_modules/sqlite-vec-darwin-arm64/vec0.dylib"
+  cp "$ARM64_DIR/package.json" "$OUT/node_modules/sqlite-vec-darwin-arm64/package.json"
+  echo "  ✓ arm64 dylib"
+fi
+
+# sqlite-vec-darwin-x64
+X64_DIR=$(find_pkg "sqlite-vec-darwin-x64") || true
+if [[ -n "$X64_DIR" ]]; then
+  mkdir -p "$OUT/node_modules/sqlite-vec-darwin-x64"
+  cp "$X64_DIR/vec0.dylib" "$OUT/node_modules/sqlite-vec-darwin-x64/vec0.dylib"
+  cp "$X64_DIR/package.json" "$OUT/node_modules/sqlite-vec-darwin-x64/package.json"
+  echo "  ✓ x64 dylib"
+fi
+
+# ---------- stub node-llama-cpp ----------
+echo "Creating node-llama-cpp stub (keyword search only)..."
+mkdir -p "$OUT/node_modules/node-llama-cpp"
+
+cat > "$OUT/node_modules/node-llama-cpp/package.json" << 'PJSON'
+{"name":"node-llama-cpp","version":"0.0.0-stub","type":"module","main":"index.js"}
+PJSON
+
+cat > "$OUT/node_modules/node-llama-cpp/index.js" << 'STUB'
+// Stub: node-llama-cpp not bundled — semantic search unavailable, keyword search works.
+const unavailable = (name) => (...args) => {
+  throw new Error(`${name}() unavailable: node-llama-cpp not bundled. Keyword search still works.`);
+};
+export const getLlama = unavailable("getLlama");
+export const resolveModelFile = unavailable("resolveModelFile");
+export class LlamaChatSession {
+  constructor() { throw new Error("LlamaChatSession unavailable"); }
+}
+export const LlamaLogLevel = { Error: 0, Warn: 1, Info: 2, Debug: 3 };
+STUB
+
+# ---------- code signing (macOS) ----------
+# In CI (APPLE_SIGNING_IDENTITY set): sign with Developer ID + hardened runtime (required for notarization)
+# In dev (no identity): ad-hoc sign to remove quarantine
+if [[ "$(uname)" == "Darwin" ]] && command -v codesign &>/dev/null; then
+  SIGN_ID="${APPLE_SIGNING_IDENTITY:--}"
+  if [[ "$SIGN_ID" != "-" ]]; then
+    echo "Signing bundled binaries with Developer ID: $SIGN_ID"
+    SIGN_OPTS=(--force --sign "$SIGN_ID" --options runtime --timestamp)
+  else
+    echo "Ad-hoc signing bundled binaries (dev mode)..."
+    SIGN_OPTS=(--force --sign -)
+  fi
+  codesign "${SIGN_OPTS[@]}" "$OUT/qmd" 2>/dev/null && echo "  ✓ qmd signed" || echo "  ⚠ qmd signing failed (non-fatal)"
+  while IFS= read -r -d '' dylib; do
+    codesign "${SIGN_OPTS[@]}" "$dylib" 2>/dev/null && echo "  ✓ $(basename "$dylib") signed" || echo "  ⚠ $(basename "$dylib") signing failed (non-fatal)"
+  done < <(find "$OUT/node_modules" -name "*.dylib" -print0)
+fi
+
+# ---------- summary ----------
+echo ""
+echo "qmd bundled → $OUT/"
+du -sh "$OUT/qmd"
+du -sh "$OUT/node_modules"
+echo "Done."

src-tauri/.gitignore

@@ -2,3 +2,7 @@
 # will have compiled files and executables
 /target/
 /gen/schemas
+
+# Generated by build scripts
+/resources/mcp-server/
+/resources/qmd/

src-tauri/build.rs

@@ -1,3 +1,13 @@
 fn main() {
+    // Ensure resource directories exist for the Tauri build.
+    // These are gitignored and populated by scripts (bundle-qmd.sh, bundle-mcp-server.mjs).
+    // Without a placeholder, `tauri build` / `cargo test` fails if the scripts haven't run.
+    for dir in ["resources/qmd", "resources/mcp-server"] {
+        let path = std::path::Path::new(dir);
+        if !path.exists() {
+            std::fs::create_dir_all(path).ok();
+            std::fs::write(path.join(".placeholder"), "").ok();
+        }
+    }
     tauri_build::build()
 }

src-tauri/src/claude_cli.rs

@@ -19,6 +19,8 @@ pub enum ClaudeStreamEvent {
     Init { session_id: String },
     /// Incremental text chunk.
     TextDelta { text: String },
+    /// Incremental thinking/reasoning chunk.
+    ThinkingDelta { text: String },
     /// A tool call started (agent mode only).
     ToolStart {
         tool_name: String,
@@ -127,7 +129,7 @@ where
 {
     let bin = find_claude_binary()?;
     let args = build_chat_args(&req);
-    run_claude_subprocess(&bin, &args, &mut emit)
+    run_claude_subprocess(&bin, &args, None, &mut emit)
 }
 
 /// Build CLI arguments for a chat stream request.
@@ -158,17 +160,18 @@ fn build_chat_args(req: &ChatStreamRequest) -> Vec<String> {
     args
 }
 
-/// Spawn `claude -p` with MCP vault tools for an agent task and stream events.
+/// Spawn `claude -p` with full tool access and MCP vault tools for an agent task.
 pub fn run_agent_stream<F>(req: AgentStreamRequest, mut emit: F) -> Result<String, String>
 where
     F: FnMut(ClaudeStreamEvent),
 {
     let bin = find_claude_binary()?;
     let args = build_agent_args(&req)?;
-    run_claude_subprocess(&bin, &args, &mut emit)
+    run_claude_subprocess(&bin, &args, Some(&req.vault_path), &mut emit)
 }
 
 /// Build CLI arguments for an agent stream request.
+/// Native tools (bash, read, write, edit) are enabled by default — no `--tools ""`.
 fn build_agent_args(req: &AgentStreamRequest) -> Result<Vec<String>, String> {
     let mcp_config = build_mcp_config(&req.vault_path)?;
 
@@ -179,8 +182,6 @@ fn build_agent_args(req: &AgentStreamRequest) -> Result<Vec<String>, String> {
         "stream-json".into(),
         "--verbose".into(),
         "--include-partial-messages".into(),
-        "--tools".into(),
-        String::new(), // disable built-in tools; MCP tools remain
         "--mcp-config".into(),
         mcp_config,
         "--dangerously-skip-permissions".into(),
@@ -227,15 +228,25 @@ struct StreamState {
 }
 
 /// Core subprocess runner shared by chat and agent modes.
-fn run_claude_subprocess<F>(bin: &PathBuf, args: &[String], emit: &mut F) -> Result<String, String>
+/// When `cwd` is `Some`, the subprocess starts with that working directory.
+fn run_claude_subprocess<F>(
+    bin: &PathBuf,
+    args: &[String],
+    cwd: Option<&str>,
+    emit: &mut F,
+) -> Result<String, String>
 where
     F: FnMut(ClaudeStreamEvent),
 {
-    let mut child = Command::new(bin)
-        .args(args)
+    let mut cmd = Command::new(bin);
+    cmd.args(args)
         .env_remove("CLAUDECODE") // prevent "nested session" guard
         .stdout(Stdio::piped())
-        .stderr(Stdio::piped())
+        .stderr(Stdio::piped());
+    if let Some(dir) = cwd {
+        cmd.current_dir(dir);
+    }
+    let mut child = cmd
         .spawn()
         .map_err(|e| format!("Failed to spawn claude: {e}"))?;
 
@@ -402,6 +413,13 @@ where
                         });
                     }
                 }
+                Some("thinking_delta") => {
+                    if let Some(text) = delta["thinking"].as_str() {
+                        emit(ClaudeStreamEvent::ThinkingDelta {
+                            text: text.to_string(),
+                        });
+                    }
+                }
                 Some("input_json_delta") => {
                     if let (Some(partial), Some(ref tid)) =
                         (delta["partial_json"].as_str(), &state.current_tool_id)
@@ -804,7 +822,7 @@ mod tests {
         std::fs::write(&path, script).unwrap();
         std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)).unwrap();
         let mut events = vec![];
-        let result = run_claude_subprocess(&path, args, &mut |e| events.push(e));
+        let result = run_claude_subprocess(&path, args, None, &mut |e| events.push(e));
         (result, events)
     }
 
@@ -955,6 +973,8 @@ mod tests {
             assert!(args.contains(&"--dangerously-skip-permissions".to_string()));
             assert!(args.contains(&"--no-session-persistence".to_string()));
             assert!(!args.contains(&"--append-system-prompt".to_string()));
+            // Native tools must NOT be disabled
+            assert!(!args.contains(&"--tools".to_string()));
         }
     }
 
@@ -1026,7 +1046,7 @@ mod tests {
     fn run_subprocess_spawn_failure() {
         let fake_bin = PathBuf::from("/nonexistent/binary/path");
         let mut events = vec![];
-        let result = run_claude_subprocess(&fake_bin, &[], &mut |e| events.push(e));
+        let result = run_claude_subprocess(&fake_bin, &[], None, &mut |e| events.push(e));
         assert!(result.is_err());
         assert!(result.unwrap_err().contains("Failed to spawn"));
     }

src-tauri/src/commands.rs

@@ -0,0 +1,673 @@
+use std::borrow::Cow;
+
+use crate::ai_chat::{AiChatRequest, AiChatResponse};
+use crate::claude_cli::{
+    AgentStreamRequest, ChatStreamRequest, ClaudeCliStatus, ClaudeStreamEvent,
+};
+use crate::frontmatter::FrontmatterValue;
+use crate::git::{
+    GitCommit, GitPullResult, GitPushResult, LastCommitInfo, ModifiedFile, PulseCommit,
+};
+use crate::github::{DeviceFlowPollResult, DeviceFlowStart, GitHubUser, GithubRepo};
+use crate::indexing::{IndexStatus, IndexingProgress};
+use crate::search::SearchResponse;
+use crate::settings::Settings;
+use crate::theme::{ThemeFile, VaultSettings};
+use crate::vault::{RenameResult, VaultEntry};
+use crate::vault_config::VaultConfig;
+use crate::vault_list::VaultList;
+use crate::{
+    frontmatter, git, github, indexing, menu, search, theme, vault, vault_config, vault_list,
+};
+
+/// Expand a leading `~` or `~/` in a path string to the user's home directory.
+/// Returns the original string unchanged if it doesn't start with `~` or if the
+/// home directory cannot be determined.
+pub fn expand_tilde(path: &str) -> Cow<'_, str> {
+    if path == "~" {
+        if let Some(home) = dirs::home_dir() {
+            return Cow::Owned(home.to_string_lossy().into_owned());
+        }
+    } else if let Some(rest) = path.strip_prefix("~/") {
+        if let Some(home) = dirs::home_dir() {
+            return Cow::Owned(format!("{}/{}", home.to_string_lossy(), rest));
+        }
+    }
+    Cow::Borrowed(path)
+}
+
+pub fn parse_build_label(version: &str) -> String {
+    let parts: Vec<&str> = version.split('.').collect();
+    match parts.as_slice() {
+        [_, minor, patch] if minor.len() >= 6 => format!("b{}", patch),
+        [_, _, _] => "dev".to_string(),
+        _ => "b?".to_string(),
+    }
+}
+
+pub fn emit_unavailable(app_handle: &tauri::AppHandle) {
+    use tauri::Emitter;
+    let _ = app_handle.emit(
+        "indexing-progress",
+        IndexingProgress {
+            phase: "unavailable".to_string(),
+            current: 0,
+            total: 0,
+            done: true,
+            error: Some("qmd not available".to_string()),
+        },
+    );
+}
+
+// ── Vault commands ──────────────────────────────────────────────────────────
+
+#[tauri::command]
+pub fn list_vault(path: String) -> Result<Vec<VaultEntry>, String> {
+    let path = expand_tilde(&path);
+    vault::scan_vault_cached(std::path::Path::new(path.as_ref()))
+}
+
+#[tauri::command]
+pub fn get_note_content(path: String) -> Result<String, String> {
+    let path = expand_tilde(&path);
+    vault::get_note_content(std::path::Path::new(path.as_ref()))
+}
+
+#[tauri::command]
+pub fn save_note_content(path: String, content: String) -> Result<(), String> {
+    let path = expand_tilde(&path);
+    vault::save_note_content(&path, &content)
+}
+
+#[tauri::command]
+pub fn rename_note(
+    vault_path: String,
+    old_path: String,
+    new_title: String,
+) -> Result<RenameResult, String> {
+    let vault_path = expand_tilde(&vault_path);
+    let old_path = expand_tilde(&old_path);
+    vault::rename_note(&vault_path, &old_path, &new_title)
+}
+
+#[tauri::command]
+pub fn purge_trash(vault_path: String) -> Result<Vec<String>, String> {
+    let vault_path = expand_tilde(&vault_path);
+    vault::purge_trash(&vault_path)
+}
+
+#[tauri::command]
+pub fn delete_note(path: String) -> Result<String, String> {
+    let path = expand_tilde(&path);
+    vault::delete_note(&path)
+}
+
+#[tauri::command]
+pub fn migrate_is_a_to_type(vault_path: String) -> Result<usize, String> {
+    let vault_path = expand_tilde(&vault_path);
+    vault::migrate_is_a_to_type(&vault_path)
+}
+
+#[tauri::command]
+pub fn create_getting_started_vault(target_path: Option<String>) -> Result<String, String> {
+    let path = match target_path {
+        Some(p) if !p.is_empty() => expand_tilde(&p).into_owned(),
+        _ => vault::default_vault_path()?.to_string_lossy().to_string(),
+    };
+    vault::create_getting_started_vault(&path)
+}
+
+#[tauri::command]
+pub fn check_vault_exists(path: String) -> bool {
+    let path = expand_tilde(&path);
+    vault::vault_exists(&path)
+}
+
+#[tauri::command]
+pub fn get_default_vault_path() -> Result<String, String> {
+    vault::default_vault_path().map(|p| p.to_string_lossy().to_string())
+}
+
+#[tauri::command]
+pub fn save_image(vault_path: String, filename: String, data: String) -> Result<String, String> {
+    let vault_path = expand_tilde(&vault_path);
+    vault::save_image(&vault_path, &filename, &data)
+}
+
+#[tauri::command]
+pub fn copy_image_to_vault(vault_path: String, source_path: String) -> Result<String, String> {
+    let vault_path = expand_tilde(&vault_path);
+    vault::copy_image_to_vault(&vault_path, &source_path)
+}
+
+// ── Frontmatter commands ────────────────────────────────────────────────────
+
+#[tauri::command]
+pub fn update_frontmatter(
+    path: String,
+    key: String,
+    value: FrontmatterValue,
+) -> Result<String, String> {
+    let path = expand_tilde(&path);
+    frontmatter::update_frontmatter(&path, &key, value)
+}
+
+#[tauri::command]
+pub fn delete_frontmatter_property(path: String, key: String) -> Result<String, String> {
+    let path = expand_tilde(&path);
+    frontmatter::delete_frontmatter_property(&path, &key)
+}
+
+#[tauri::command]
+pub fn batch_archive_notes(paths: Vec<String>) -> Result<usize, String> {
+    let mut count = 0;
+    for path in &paths {
+        let path = expand_tilde(path);
+        frontmatter::update_frontmatter(&path, "Archived", FrontmatterValue::Bool(true))?;
+        count += 1;
+    }
+    Ok(count)
+}
+
+#[tauri::command]
+pub fn batch_trash_notes(paths: Vec<String>) -> Result<usize, String> {
+    let now = chrono::Utc::now().format("%Y-%m-%dT%H:%M:%SZ").to_string();
+    let mut count = 0;
+    for path in &paths {
+        let path = expand_tilde(path);
+        frontmatter::update_frontmatter(&path, "Trashed", FrontmatterValue::Bool(true))?;
+        frontmatter::update_frontmatter(
+            &path,
+            "Trashed at",
+            FrontmatterValue::String(now.clone()),
+        )?;
+        count += 1;
+    }
+    Ok(count)
+}
+
+// ── Git commands ────────────────────────────────────────────────────────────
+
+#[tauri::command]
+pub fn get_file_history(vault_path: String, path: String) -> Result<Vec<GitCommit>, String> {
+    let vault_path = expand_tilde(&vault_path);
+    let path = expand_tilde(&path);
+    git::get_file_history(&vault_path, &path)
+}
+
+#[tauri::command]
+pub fn get_modified_files(vault_path: String) -> Result<Vec<ModifiedFile>, String> {
+    let vault_path = expand_tilde(&vault_path);
+    git::get_modified_files(&vault_path)
+}
+
+#[tauri::command]
+pub fn get_file_diff(vault_path: String, path: String) -> Result<String, String> {
+    let vault_path = expand_tilde(&vault_path);
+    let path = expand_tilde(&path);
+    git::get_file_diff(&vault_path, &path)
+}
+
+#[tauri::command]
+pub fn get_file_diff_at_commit(
+    vault_path: String,
+    path: String,
+    commit_hash: String,
+) -> Result<String, String> {
+    let vault_path = expand_tilde(&vault_path);
+    let path = expand_tilde(&path);
+    git::get_file_diff_at_commit(&vault_path, &path, &commit_hash)
+}
+
+#[tauri::command]
+pub fn get_vault_pulse(
+    vault_path: String,
+    limit: Option<usize>,
+    skip: Option<usize>,
+) -> Result<Vec<PulseCommit>, String> {
+    let vault_path = expand_tilde(&vault_path);
+    let limit = limit.unwrap_or(20);
+    let skip = skip.unwrap_or(0);
+    git::get_vault_pulse(&vault_path, limit, skip)
+}
+
+#[tauri::command]
+pub fn git_commit(vault_path: String, message: String) -> Result<String, String> {
+    let vault_path = expand_tilde(&vault_path);
+    git::git_commit(&vault_path, &message)
+}
+
+#[tauri::command]
+pub fn get_last_commit_info(vault_path: String) -> Result<Option<LastCommitInfo>, String> {
+    let vault_path = expand_tilde(&vault_path);
+    git::get_last_commit_info(&vault_path)
+}
+
+#[tauri::command]
+pub fn git_pull(vault_path: String) -> Result<GitPullResult, String> {
+    let vault_path = expand_tilde(&vault_path);
+    git::git_pull(&vault_path)
+}
+
+#[tauri::command]
+pub fn get_conflict_files(vault_path: String) -> Result<Vec<String>, String> {
+    let vault_path = expand_tilde(&vault_path);
+    git::get_conflict_files(&vault_path)
+}
+
+#[tauri::command]
+pub fn get_conflict_mode(vault_path: String) -> String {
+    let vault_path = expand_tilde(&vault_path);
+    git::get_conflict_mode(&vault_path)
+}
+
+#[tauri::command]
+pub fn git_resolve_conflict(
+    vault_path: String,
+    file: String,
+    strategy: String,
+) -> Result<(), String> {
+    let vault_path = expand_tilde(&vault_path);
+    git::git_resolve_conflict(&vault_path, &file, &strategy)
+}
+
+#[tauri::command]
+pub fn git_commit_conflict_resolution(vault_path: String) -> Result<String, String> {
+    let vault_path = expand_tilde(&vault_path);
+    git::git_commit_conflict_resolution(&vault_path)
+}
+
+#[tauri::command]
+pub fn git_push(vault_path: String) -> Result<GitPushResult, String> {
+    let vault_path = expand_tilde(&vault_path);
+    git::git_push(&vault_path)
+}
+
+// ── GitHub commands ─────────────────────────────────────────────────────────
+
+#[tauri::command]
+pub async fn github_list_repos(token: String) -> Result<Vec<GithubRepo>, String> {
+    github::github_list_repos(&token).await
+}
+
+#[tauri::command]
+pub async fn github_create_repo(
+    token: String,
+    name: String,
+    private: bool,
+) -> Result<GithubRepo, String> {
+    github::github_create_repo(&token, &name, private).await
+}
+
+#[tauri::command]
+pub fn clone_repo(url: String, token: String, local_path: String) -> Result<String, String> {
+    let local_path = expand_tilde(&local_path);
+    github::clone_repo(&url, &token, &local_path)
+}
+
+#[tauri::command]
+pub async fn github_device_flow_start() -> Result<DeviceFlowStart, String> {
+    github::github_device_flow_start().await
+}
+
+#[tauri::command]
+pub async fn github_device_flow_poll(device_code: String) -> Result<DeviceFlowPollResult, String> {
+    github::github_device_flow_poll(&device_code).await
+}
+
+#[tauri::command]
+pub async fn github_get_user(token: String) -> Result<GitHubUser, String> {
+    github::github_get_user(&token).await
+}
+
+// ── AI / Claude commands ────────────────────────────────────────────────────
+
+#[tauri::command]
+pub async fn ai_chat(request: AiChatRequest) -> Result<AiChatResponse, String> {
+    crate::ai_chat::send_chat(request).await
+}
+
+#[tauri::command]
+pub fn check_claude_cli() -> ClaudeCliStatus {
+    crate::claude_cli::check_cli()
+}
+
+#[tauri::command]
+pub async fn stream_claude_chat(
+    app_handle: tauri::AppHandle,
+    request: ChatStreamRequest,
+) -> Result<String, String> {
+    use tauri::Emitter;
+    tokio::task::spawn_blocking(move || {
+        crate::claude_cli::run_chat_stream(request, |event: ClaudeStreamEvent| {
+            let _ = app_handle.emit("claude-stream", &event);
+        })
+    })
+    .await
+    .map_err(|e| format!("Task failed: {e}"))?
+}
+
+#[tauri::command]
+pub async fn stream_claude_agent(
+    app_handle: tauri::AppHandle,
+    request: AgentStreamRequest,
+) -> Result<String, String> {
+    use tauri::Emitter;
+    tokio::task::spawn_blocking(move || {
+        crate::claude_cli::run_agent_stream(request, |event: ClaudeStreamEvent| {
+            let _ = app_handle.emit("claude-agent-stream", &event);
+        })
+    })
+    .await
+    .map_err(|e| format!("Task failed: {e}"))?
+}
+
+// ── Search & indexing commands ──────────────────────────────────────────────
+
+#[tauri::command]
+pub async fn search_vault(
+    vault_path: String,
+    query: String,
+    mode: String,
+    limit: Option<usize>,
+) -> Result<SearchResponse, String> {
+    let vault_path = expand_tilde(&vault_path).into_owned();
+    let limit = limit.unwrap_or(20);
+    tokio::task::spawn_blocking(move || search::search_vault(&vault_path, &query, &mode, limit))
+        .await
+        .map_err(|e| format!("Search task failed: {}", e))?
+}
+
+#[tauri::command]
+pub fn get_index_status(vault_path: String) -> IndexStatus {
+    let vault_path = expand_tilde(&vault_path);
+    indexing::check_index_status(&vault_path)
+}
+
+#[tauri::command]
+pub async fn start_indexing(
+    app_handle: tauri::AppHandle,
+    vault_path: String,
+) -> Result<(), String> {
+    use tauri::Emitter;
+    let vault_path = expand_tilde(&vault_path).into_owned();
+    tokio::task::spawn_blocking(move || {
+        if indexing::find_qmd_binary().is_none() {
+            log::info!("qmd binary not found — attempting auto-install via bun");
+            let _ = app_handle.emit(
+                "indexing-progress",
+                IndexingProgress {
+                    phase: "installing".to_string(),
+                    current: 0,
+                    total: 0,
+                    done: false,
+                    error: None,
+                },
+            );
+
+            match indexing::try_auto_install_qmd() {
+                Ok(()) if indexing::find_qmd_binary().is_some() => {
+                    log::info!("qmd auto-installed successfully, proceeding with indexing");
+                }
+                Ok(()) => {
+                    log::warn!("qmd auto-install reported success but binary still not found");
+                    emit_unavailable(&app_handle);
+                    return Err("qmd not available after install".to_string());
+                }
+                Err(e) => {
+                    log::info!("qmd auto-install failed: {e}");
+                    emit_unavailable(&app_handle);
+                    return Err(format!("qmd not available: {e}"));
+                }
+            }
+        }
+
+        indexing::run_full_index(&vault_path, |progress| {
+            let _ = app_handle.emit("indexing-progress", &progress);
+        })
+    })
+    .await
+    .map_err(|e| format!("Indexing task failed: {e}"))?
+}
+
+#[tauri::command]
+pub async fn trigger_incremental_index(vault_path: String) -> Result<(), String> {
+    let vault_path = expand_tilde(&vault_path).into_owned();
+    tokio::task::spawn_blocking(move || indexing::run_incremental_update(&vault_path))
+        .await
+        .map_err(|e| format!("Incremental index failed: {e}"))?
+}
+
+// ── MCP commands ────────────────────────────────────────────────────────────
+
+#[tauri::command]
+pub async fn register_mcp_tools(vault_path: String) -> Result<String, String> {
+    let vault_path = expand_tilde(&vault_path).into_owned();
+    tokio::task::spawn_blocking(move || crate::mcp::register_mcp(&vault_path))
+        .await
+        .map_err(|e| format!("Registration task failed: {e}"))?
+}
+
+#[tauri::command]
+pub async fn check_mcp_status() -> Result<crate::mcp::McpStatus, String> {
+    tokio::task::spawn_blocking(crate::mcp::check_mcp_status)
+        .await
+        .map_err(|e| format!("MCP status check failed: {e}"))
+}
+
+// ── Theme commands ──────────────────────────────────────────────────────────
+
+#[tauri::command]
+pub fn list_themes(vault_path: String) -> Result<Vec<ThemeFile>, String> {
+    let vault_path = expand_tilde(&vault_path);
+    theme::list_themes(&vault_path)
+}
+
+#[tauri::command]
+pub fn get_theme(vault_path: String, theme_id: String) -> Result<ThemeFile, String> {
+    let vault_path = expand_tilde(&vault_path);
+    theme::get_theme(&vault_path, &theme_id)
+}
+
+#[tauri::command]
+pub fn get_vault_settings(vault_path: String) -> Result<VaultSettings, String> {
+    let vault_path = expand_tilde(&vault_path);
+    theme::get_vault_settings(&vault_path)
+}
+
+#[tauri::command]
+pub fn save_vault_settings(vault_path: String, settings: VaultSettings) -> Result<(), String> {
+    let vault_path = expand_tilde(&vault_path);
+    theme::save_vault_settings(&vault_path, settings)
+}
+
+#[tauri::command]
+pub fn set_active_theme(vault_path: String, theme_id: Option<String>) -> Result<(), String> {
+    let vault_path = expand_tilde(&vault_path);
+    theme::set_active_theme(&vault_path, theme_id.as_deref())
+}
+
+#[tauri::command]
+pub fn create_theme(vault_path: String, source_id: Option<String>) -> Result<String, String> {
+    let vault_path = expand_tilde(&vault_path);
+    theme::create_theme(&vault_path, source_id.as_deref())
+}
+
+#[tauri::command]
+pub fn create_vault_theme(vault_path: String, name: Option<String>) -> Result<String, String> {
+    let vault_path = expand_tilde(&vault_path);
+    theme::create_vault_theme(&vault_path, name.as_deref())
+}
+
+#[tauri::command]
+pub fn ensure_vault_themes(vault_path: String) -> Result<(), String> {
+    let vault_path = expand_tilde(&vault_path);
+    theme::ensure_vault_themes(&vault_path)
+}
+
+#[tauri::command]
+pub fn restore_default_themes(vault_path: String) -> Result<String, String> {
+    let vault_path = expand_tilde(&vault_path);
+    theme::restore_default_themes(&vault_path)
+}
+
+#[tauri::command]
+pub fn repair_vault(vault_path: String) -> Result<String, String> {
+    let vault_path = expand_tilde(&vault_path);
+    // Repair themes
+    theme::restore_default_themes(&vault_path)?;
+    // Repair config files (config/agents.md, type/config.md, AGENTS.md stub)
+    vault::repair_config_files(&vault_path)?;
+    Ok("Vault repaired".to_string())
+}
+
+// ── Settings & config commands ──────────────────────────────────────────────
+
+#[tauri::command]
+pub fn get_build_number(app_handle: tauri::AppHandle) -> String {
+    let version = app_handle.package_info().version.to_string();
+    parse_build_label(&version)
+}
+
+#[tauri::command]
+pub fn update_menu_state(
+    app_handle: tauri::AppHandle,
+    has_active_note: bool,
+    has_modified_files: Option<bool>,
+    has_conflicts: Option<bool>,
+) -> Result<(), String> {
+    menu::set_note_items_enabled(&app_handle, has_active_note);
+    if let Some(v) = has_modified_files {
+        menu::set_git_commit_items_enabled(&app_handle, v);
+    }
+    if let Some(v) = has_conflicts {
+        menu::set_git_conflict_items_enabled(&app_handle, v);
+    }
+    Ok(())
+}
+
+#[tauri::command]
+pub fn get_settings() -> Result<Settings, String> {
+    crate::settings::get_settings()
+}
+
+#[tauri::command]
+pub fn save_settings(settings: Settings) -> Result<(), String> {
+    crate::settings::save_settings(settings)
+}
+
+#[tauri::command]
+pub fn load_vault_list() -> Result<VaultList, String> {
+    vault_list::load_vault_list()
+}
+
+#[tauri::command]
+pub fn save_vault_list(list: VaultList) -> Result<(), String> {
+    vault_list::save_vault_list(&list)
+}
+
+#[tauri::command]
+pub fn get_vault_config(vault_path: String) -> Result<VaultConfig, String> {
+    let vault_path = expand_tilde(&vault_path);
+    vault_config::get_vault_config(&vault_path)
+}
+
+#[tauri::command]
+pub fn save_vault_config(vault_path: String, config: VaultConfig) -> Result<(), String> {
+    let vault_path = expand_tilde(&vault_path);
+    vault_config::save_vault_config(&vault_path, config)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn expand_tilde_with_subpath() {
+        let home = dirs::home_dir().unwrap();
+        let result = expand_tilde("~/Documents/vault");
+        assert_eq!(result, format!("{}/Documents/vault", home.display()));
+    }
+
+    #[test]
+    fn expand_tilde_alone() {
+        let home = dirs::home_dir().unwrap();
+        let result = expand_tilde("~");
+        assert_eq!(result, home.to_string_lossy());
+    }
+
+    #[test]
+    fn expand_tilde_noop_for_absolute_path() {
+        let result = expand_tilde("/usr/local/bin");
+        assert_eq!(result, "/usr/local/bin");
+    }
+
+    #[test]
+    fn expand_tilde_noop_for_relative_path() {
+        let result = expand_tilde("some/relative/path");
+        assert_eq!(result, "some/relative/path");
+    }
+
+    #[test]
+    fn expand_tilde_noop_for_tilde_in_middle() {
+        let result = expand_tilde("/home/~user/path");
+        assert_eq!(result, "/home/~user/path");
+    }
+
+    #[test]
+    fn parse_build_label_release_version() {
+        assert_eq!(parse_build_label("0.20260303.281"), "b281");
+        assert_eq!(parse_build_label("0.20251215.42"), "b42");
+    }
+
+    #[test]
+    fn parse_build_label_dev_version() {
+        assert_eq!(parse_build_label("0.1.0"), "dev");
+        assert_eq!(parse_build_label("0.0.0"), "dev");
+    }
+
+    #[test]
+    fn parse_build_label_malformed() {
+        assert_eq!(parse_build_label("invalid"), "b?");
+        assert_eq!(parse_build_label(""), "b?");
+    }
+
+    #[test]
+    fn test_batch_archive_notes() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let note = dir.path().join("note.md");
+        std::fs::write(&note, "---\nStatus: Active\n---\n# Note\n").unwrap();
+
+        let result = batch_archive_notes(vec![note.to_str().unwrap().to_string()]);
+        assert_eq!(result.unwrap(), 1);
+
+        let content = std::fs::read_to_string(&note).unwrap();
+        assert!(content.contains("Archived: true"));
+        assert!(content.contains("Status: Active"));
+    }
+
+    #[test]
+    fn test_batch_trash_notes() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let note = dir.path().join("note.md");
+        std::fs::write(&note, "---\nStatus: Active\n---\n# Note\n").unwrap();
+
+        let result = batch_trash_notes(vec![note.to_str().unwrap().to_string()]);
+        assert_eq!(result.unwrap(), 1);
+
+        let content = std::fs::read_to_string(&note).unwrap();
+        assert!(content.contains("Trashed: true"));
+        assert!(content.contains("Trashed at"));
+    }
+
+    #[test]
+    fn test_check_vault_exists_false() {
+        assert!(!check_vault_exists("/nonexistent/path/abc123".to_string()));
+    }
+
+    #[test]
+    fn test_get_default_vault_path_returns_ok() {
+        let result = get_default_vault_path();
+        assert!(result.is_ok());
+    }
+}

src-tauri/src/frontmatter.rs

@@ -1,827 +0,0 @@
-use serde::{Deserialize, Serialize};
-use std::fs;
-use std::path::Path;
-
-/// Value type for frontmatter updates
-#[derive(Debug, Serialize, Deserialize, Clone)]
-#[serde(untagged)]
-pub enum FrontmatterValue {
-    String(String),
-    Number(f64),
-    Bool(bool),
-    List(Vec<String>),
-    Null,
-}
-
-/// Characters that require a YAML string value to be quoted.
-fn has_yaml_special_chars(s: &str) -> bool {
-    s.contains(':') || s.contains('#')
-}
-
-/// Check if a string starts with a YAML collection indicator (array or map).
-fn starts_as_yaml_collection(s: &str) -> bool {
-    s.starts_with('[') || s.starts_with('{')
-}
-
-/// Check whether a YAML string value needs quoting to avoid ambiguity.
-fn needs_yaml_quoting(s: &str) -> bool {
-    has_yaml_special_chars(s)
-        || starts_as_yaml_collection(s)
-        || matches!(s, "true" | "false" | "null")
-        || s.parse::<f64>().is_ok()
-}
-
-/// Quote a string value for YAML, escaping internal double quotes.
-fn quote_yaml_string(s: &str) -> String {
-    format!("\"{}\"", s.replace('\"', "\\\""))
-}
-
-/// Format a single YAML list item as `  - "value"`.
-fn format_list_item(item: &str) -> String {
-    format!("  - {}", quote_yaml_string(item))
-}
-
-/// Format a multi-line string as a YAML block scalar (`|`).
-/// Each line is indented by 2 spaces; empty lines are preserved as blank.
-fn format_block_scalar(s: &str) -> String {
-    let indented = s
-        .lines()
-        .map(|l| {
-            if l.is_empty() {
-                String::new()
-            } else {
-                format!("  {}", l)
-            }
-        })
-        .collect::<Vec<_>>()
-        .join("\n");
-    format!("|\n{}", indented)
-}
-
-/// Format a number for YAML (integers without decimal, floats with).
-fn format_yaml_number(n: f64) -> String {
-    if n.fract() == 0.0 {
-        format!("{}", n as i64)
-    } else {
-        format!("{}", n)
-    }
-}
-
-impl FrontmatterValue {
-    pub fn to_yaml_value(&self) -> String {
-        match self {
-            FrontmatterValue::String(s) => {
-                if s.contains('\n') {
-                    format_block_scalar(s)
-                } else if needs_yaml_quoting(s) {
-                    quote_yaml_string(s)
-                } else {
-                    s.clone()
-                }
-            }
-            FrontmatterValue::Number(n) => format_yaml_number(*n),
-            FrontmatterValue::Bool(b) => if *b { "true" } else { "false" }.to_string(),
-            FrontmatterValue::List(items) if items.is_empty() => "[]".to_string(),
-            FrontmatterValue::List(items) => items
-                .iter()
-                .map(|item| format_list_item(item))
-                .collect::<Vec<_>>()
-                .join("\n"),
-            FrontmatterValue::Null => "null".to_string(),
-        }
-    }
-}
-
-/// Check whether a YAML key needs quoting (contains spaces, special chars, etc.).
-fn needs_key_quoting(key: &str) -> bool {
-    key.chars()
-        .any(|c| !c.is_ascii_alphanumeric() && c != '_' && c != '-')
-}
-
-/// Format a key for YAML output (quote if necessary)
-pub fn format_yaml_key(key: &str) -> String {
-    if needs_key_quoting(key) {
-        format!("\"{}\"", key)
-    } else {
-        key.to_string()
-    }
-}
-
-/// Check if a line defines a specific key (handles quoted and unquoted keys)
-fn line_is_key(line: &str, key: &str) -> bool {
-    let trimmed = line.trim_start();
-
-    if trimmed.starts_with(key) && trimmed[key.len()..].starts_with(':') {
-        return true;
-    }
-
-    let dq = format!("\"{}\":", key);
-    if trimmed.starts_with(&dq) {
-        return true;
-    }
-
-    let sq = format!("'{}\':", key);
-    if trimmed.starts_with(&sq) {
-        return true;
-    }
-
-    false
-}
-
-/// Format a key-value pair as one or more YAML lines.
-fn format_yaml_field(key: &str, value: &FrontmatterValue) -> Vec<String> {
-    let yaml_key = format_yaml_key(key);
-    let yaml_value = value.to_yaml_value();
-    if yaml_value.starts_with("|\n") {
-        // Block scalar: key and indicator on the same line, content follows
-        vec![format!("{}: {}", yaml_key, yaml_value)]
-    } else if yaml_value.contains('\n') {
-        vec![format!("{}:", yaml_key), yaml_value]
-    } else {
-        vec![format!("{}: {}", yaml_key, yaml_value)]
-    }
-}
-
-/// Check if a line continues the previous key's value (indented list item,
-/// block scalar content, or blank line inside a block scalar).
-fn is_value_continuation(line: &str) -> bool {
-    line.is_empty() || line.starts_with("  ") || line.starts_with('\t')
-}
-
-/// Split content into frontmatter body and the rest after the closing `---`.
-/// Returns `(fm_content, rest)` where `fm_content` is between the opening and closing `---`.
-fn split_frontmatter(content: &str) -> Result<(&str, &str), String> {
-    let after_open = &content[4..];
-    // Handle empty frontmatter: closing --- immediately after opening ---\n
-    if let Some(stripped) = after_open.strip_prefix("---") {
-        return Ok(("", stripped));
-    }
-    let fm_end = after_open
-        .find("\n---")
-        .map(|i| i + 4)
-        .ok_or_else(|| "Malformed frontmatter: no closing ---".to_string())?;
-    Ok((&content[4..fm_end], &content[fm_end + 4..]))
-}
-
-/// Wrap content in a new frontmatter block containing a single field.
-fn prepend_new_frontmatter(content: &str, key: &str, value: &FrontmatterValue) -> String {
-    let field_lines = format_yaml_field(key, value);
-    format!("---\n{}\n---\n{}", field_lines.join("\n"), content)
-}
-
-/// Apply a field update to existing frontmatter lines.
-/// Replaces the matching key (and its list continuations) with the new value,
-/// or appends if the key is not found. If `value` is None, removes the key.
-fn apply_field_update(lines: &[&str], key: &str, value: Option<&FrontmatterValue>) -> Vec<String> {
-    let mut new_lines: Vec<String> = Vec::new();
-    let mut found_key = false;
-    let mut i = 0;
-
-    while i < lines.len() {
-        if !line_is_key(lines[i], key) {
-            new_lines.push(lines[i].to_string());
-            i += 1;
-            continue;
-        }
-
-        found_key = true;
-        i += 1;
-        // Skip continuation lines belonging to this key (lists, block scalars)
-        while i < lines.len() && is_value_continuation(lines[i]) {
-            i += 1;
-        }
-        // Insert replacement value (if any)
-        if let Some(v) = value {
-            new_lines.extend(format_yaml_field(key, v));
-        }
-    }
-
-    if let (false, Some(v)) = (found_key, value) {
-        new_lines.extend(format_yaml_field(key, v));
-    }
-
-    new_lines
-}
-
-/// Internal function to update frontmatter content
-pub fn update_frontmatter_content(
-    content: &str,
-    key: &str,
-    value: Option<FrontmatterValue>,
-) -> Result<String, String> {
-    if !content.starts_with("---\n") {
-        return match value {
-            Some(v) => Ok(prepend_new_frontmatter(content, key, &v)),
-            None => Ok(content.to_string()),
-        };
-    }
-
-    let (fm_content, rest) = split_frontmatter(content)?;
-    let lines: Vec<&str> = fm_content.lines().collect();
-    let new_lines = apply_field_update(&lines, key, value.as_ref());
-    let new_fm = new_lines.join("\n");
-    Ok(format!("---\n{}\n---{}", new_fm, rest))
-}
-
-/// Helper to read a file, apply a frontmatter transformation, and write back.
-pub fn with_frontmatter<F>(path: &str, transform: F) -> Result<String, String>
-where
-    F: FnOnce(&str) -> Result<String, String>,
-{
-    let file_path = Path::new(path);
-    if !file_path.exists() {
-        return Err(format!("File does not exist: {}", path));
-    }
-
-    let content =
-        fs::read_to_string(file_path).map_err(|e| format!("Failed to read {}: {}", path, e))?;
-
-    let updated = transform(&content)?;
-
-    fs::write(file_path, &updated).map_err(|e| format!("Failed to write {}: {}", path, e))?;
-
-    Ok(updated)
-}
-
-/// Update a single frontmatter property in a markdown file.
-pub fn update_frontmatter(
-    path: &str,
-    key: &str,
-    value: FrontmatterValue,
-) -> Result<String, String> {
-    with_frontmatter(path, |content| {
-        update_frontmatter_content(content, key, Some(value.clone()))
-    })
-}
-
-/// Delete a frontmatter property from a markdown file.
-pub fn delete_frontmatter_property(path: &str, key: &str) -> Result<String, String> {
-    with_frontmatter(path, |content| {
-        update_frontmatter_content(content, key, None)
-    })
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_update_frontmatter_string() {
-        let content = "---\nStatus: Draft\n---\n# Test\n";
-        let updated = update_frontmatter_content(
-            content,
-            "Status",
-            Some(FrontmatterValue::String("Active".to_string())),
-        )
-        .unwrap();
-        assert!(updated.contains("Status: Active"));
-        assert!(!updated.contains("Status: Draft"));
-    }
-
-    #[test]
-    fn test_update_frontmatter_add_new_key() {
-        let content = "---\nStatus: Draft\n---\n# Test\n";
-        let updated = update_frontmatter_content(
-            content,
-            "Owner",
-            Some(FrontmatterValue::String("Luca".to_string())),
-        )
-        .unwrap();
-        assert!(updated.contains("Owner: Luca"));
-        assert!(updated.contains("Status: Draft"));
-    }
-
-    #[test]
-    fn test_update_frontmatter_quoted_key() {
-        let content = "---\n\"Is A\": Note\n---\n# Test\n";
-        let updated = update_frontmatter_content(
-            content,
-            "Is A",
-            Some(FrontmatterValue::String("Project".to_string())),
-        )
-        .unwrap();
-        assert!(updated.contains("\"Is A\": Project"));
-        assert!(!updated.contains("Note"));
-    }
-
-    #[test]
-    fn test_update_frontmatter_list() {
-        let content = "---\nStatus: Draft\n---\n# Test\n";
-        let updated = update_frontmatter_content(
-            content,
-            "aliases",
-            Some(FrontmatterValue::List(vec![
-                "Alias1".to_string(),
-                "Alias2".to_string(),
-            ])),
-        )
-        .unwrap();
-        assert!(updated.contains("aliases:"));
-        assert!(updated.contains("  - \"Alias1\""));
-        assert!(updated.contains("  - \"Alias2\""));
-    }
-
-    #[test]
-    fn test_update_frontmatter_replace_list() {
-        let content = "---\naliases:\n  - Old1\n  - Old2\nStatus: Draft\n---\n# Test\n";
-        let updated = update_frontmatter_content(
-            content,
-            "aliases",
-            Some(FrontmatterValue::List(vec!["New1".to_string()])),
-        )
-        .unwrap();
-        assert!(updated.contains("  - \"New1\""));
-        assert!(!updated.contains("Old1"));
-        assert!(!updated.contains("Old2"));
-        assert!(updated.contains("Status: Draft"));
-    }
-
-    #[test]
-    fn test_delete_frontmatter_property() {
-        let content = "---\nStatus: Draft\nOwner: Luca\n---\n# Test\n";
-        let updated = update_frontmatter_content(content, "Owner", None).unwrap();
-        assert!(!updated.contains("Owner"));
-        assert!(updated.contains("Status: Draft"));
-    }
-
-    #[test]
-    fn test_delete_frontmatter_list_property() {
-        let content = "---\naliases:\n  - Alias1\n  - Alias2\nStatus: Draft\n---\n# Test\n";
-        let updated = update_frontmatter_content(content, "aliases", None).unwrap();
-        assert!(!updated.contains("aliases"));
-        assert!(!updated.contains("Alias1"));
-        assert!(updated.contains("Status: Draft"));
-    }
-
-    #[test]
-    fn test_update_frontmatter_no_existing() {
-        let content = "# Test\n\nSome content here.";
-        let updated = update_frontmatter_content(
-            content,
-            "Status",
-            Some(FrontmatterValue::String("Draft".to_string())),
-        )
-        .unwrap();
-        assert!(updated.starts_with("---\n"));
-        assert!(updated.contains("Status: Draft"));
-        assert!(updated.contains("# Test"));
-    }
-
-    #[test]
-    fn test_update_frontmatter_bool() {
-        let content = "---\nStatus: Draft\n---\n# Test\n";
-        let updated =
-            update_frontmatter_content(content, "Reviewed", Some(FrontmatterValue::Bool(true)))
-                .unwrap();
-        assert!(updated.contains("Reviewed: true"));
-    }
-
-    #[test]
-    fn test_format_yaml_key_simple() {
-        assert_eq!(format_yaml_key("Status"), "Status");
-        assert_eq!(format_yaml_key("is_a"), "is_a");
-    }
-
-    #[test]
-    fn test_format_yaml_key_with_spaces() {
-        assert_eq!(format_yaml_key("Is A"), "\"Is A\"");
-        assert_eq!(format_yaml_key("Created at"), "\"Created at\"");
-    }
-
-    // --- to_yaml_value quoting tests ---
-
-    #[test]
-    fn test_to_yaml_value_string_needs_quoting_colon() {
-        let v = FrontmatterValue::String("key: value".to_string());
-        assert_eq!(v.to_yaml_value(), "\"key: value\"");
-    }
-
-    #[test]
-    fn test_to_yaml_value_string_needs_quoting_hash() {
-        let v = FrontmatterValue::String("has # comment".to_string());
-        assert_eq!(v.to_yaml_value(), "\"has # comment\"");
-    }
-
-    #[test]
-    fn test_to_yaml_value_string_needs_quoting_bracket() {
-        let v = FrontmatterValue::String("[array-like]".to_string());
-        assert_eq!(v.to_yaml_value(), "\"[array-like]\"");
-    }
-
-    #[test]
-    fn test_to_yaml_value_string_needs_quoting_brace() {
-        let v = FrontmatterValue::String("{object-like}".to_string());
-        assert_eq!(v.to_yaml_value(), "\"{object-like}\"");
-    }
-
-    #[test]
-    fn test_to_yaml_value_string_needs_quoting_bool_like() {
-        assert_eq!(
-            FrontmatterValue::String("true".to_string()).to_yaml_value(),
-            "\"true\""
-        );
-        assert_eq!(
-            FrontmatterValue::String("false".to_string()).to_yaml_value(),
-            "\"false\""
-        );
-    }
-
-    #[test]
-    fn test_to_yaml_value_string_needs_quoting_null_like() {
-        assert_eq!(
-            FrontmatterValue::String("null".to_string()).to_yaml_value(),
-            "\"null\""
-        );
-    }
-
-    #[test]
-    fn test_to_yaml_value_string_needs_quoting_number_like() {
-        assert_eq!(
-            FrontmatterValue::String("42".to_string()).to_yaml_value(),
-            "\"42\""
-        );
-        assert_eq!(
-            FrontmatterValue::String("3.14".to_string()).to_yaml_value(),
-            "\"3.14\""
-        );
-    }
-
-    #[test]
-    fn test_to_yaml_value_string_plain() {
-        let v = FrontmatterValue::String("Hello World".to_string());
-        assert_eq!(v.to_yaml_value(), "Hello World");
-    }
-
-    #[test]
-    fn test_to_yaml_value_number_integer() {
-        let v = FrontmatterValue::Number(42.0);
-        assert_eq!(v.to_yaml_value(), "42");
-    }
-
-    #[test]
-    fn test_to_yaml_value_number_float() {
-        let v = FrontmatterValue::Number(3.14);
-        assert_eq!(v.to_yaml_value(), "3.14");
-    }
-
-    #[test]
-    fn test_to_yaml_value_null() {
-        assert_eq!(FrontmatterValue::Null.to_yaml_value(), "null");
-    }
-
-    #[test]
-    fn test_to_yaml_value_empty_list() {
-        let v = FrontmatterValue::List(vec![]);
-        assert_eq!(v.to_yaml_value(), "[]");
-    }
-
-    #[test]
-    fn test_to_yaml_value_list_with_colon() {
-        let v = FrontmatterValue::List(vec!["key: value".to_string()]);
-        assert_eq!(v.to_yaml_value(), "  - \"key: value\"");
-    }
-
-    // --- update_frontmatter_content additional type tests ---
-
-    #[test]
-    fn test_update_frontmatter_number() {
-        let content = "---\nStatus: Draft\n---\n# Test\n";
-        let updated =
-            update_frontmatter_content(content, "Priority", Some(FrontmatterValue::Number(5.0)))
-                .unwrap();
-        assert!(updated.contains("Priority: 5"));
-    }
-
-    #[test]
-    fn test_update_frontmatter_number_float() {
-        let content = "---\nStatus: Draft\n---\n# Test\n";
-        let updated =
-            update_frontmatter_content(content, "Score", Some(FrontmatterValue::Number(9.5)))
-                .unwrap();
-        assert!(updated.contains("Score: 9.5"));
-    }
-
-    #[test]
-    fn test_update_frontmatter_null() {
-        let content = "---\nStatus: Draft\n---\n# Test\n";
-        let updated =
-            update_frontmatter_content(content, "ClearMe", Some(FrontmatterValue::Null)).unwrap();
-        assert!(updated.contains("ClearMe: null"));
-    }
-
-    #[test]
-    fn test_update_frontmatter_empty_list() {
-        let content = "---\nStatus: Draft\n---\n# Test\n";
-        let updated =
-            update_frontmatter_content(content, "tags", Some(FrontmatterValue::List(vec![])))
-                .unwrap();
-        assert!(updated.contains("tags: []"));
-    }
-
-    #[test]
-    fn test_update_frontmatter_malformed_no_closing_fence() {
-        let content = "---\nStatus: Draft\nNo closing fence here";
-        let result = update_frontmatter_content(
-            content,
-            "Status",
-            Some(FrontmatterValue::String("Active".to_string())),
-        );
-        assert!(result.is_err());
-        assert!(result.unwrap_err().contains("Malformed frontmatter"));
-    }
-
-    // --- delete non-existent key (should be no-op) ---
-
-    #[test]
-    fn test_delete_nonexistent_key_noop() {
-        let content = "---\nStatus: Draft\n---\n# Test\n";
-        let updated = update_frontmatter_content(content, "NonExistent", None).unwrap();
-        assert_eq!(updated, content);
-    }
-
-    #[test]
-    fn test_delete_from_no_frontmatter_noop() {
-        let content = "# Test\n\nSome content.";
-        let updated = update_frontmatter_content(content, "NonExistent", None).unwrap();
-        assert_eq!(updated, content);
-    }
-
-    // --- line_is_key tests ---
-
-    #[test]
-    fn test_line_is_key_unquoted() {
-        assert!(line_is_key("Status: Draft", "Status"));
-        assert!(!line_is_key("Status: Draft", "Owner"));
-    }
-
-    #[test]
-    fn test_line_is_key_double_quoted() {
-        assert!(line_is_key("\"Is A\": Note", "Is A"));
-        assert!(!line_is_key("\"Is A\": Note", "Status"));
-    }
-
-    #[test]
-    fn test_line_is_key_single_quoted() {
-        assert!(line_is_key("'Is A': Note", "Is A"));
-    }
-
-    #[test]
-    fn test_line_is_key_leading_whitespace() {
-        assert!(line_is_key("  Status: Draft", "Status"));
-    }
-
-    #[test]
-    fn test_line_is_key_partial_match() {
-        // "StatusBar" should not match key "Status"
-        assert!(!line_is_key("StatusBar: value", "Status"));
-    }
-
-    // --- with_frontmatter error cases ---
-
-    #[test]
-    fn test_with_frontmatter_file_not_found() {
-        let result = with_frontmatter("/nonexistent/path/file.md", |c| Ok(c.to_string()));
-        assert!(result.is_err());
-        assert!(result.unwrap_err().contains("does not exist"));
-    }
-
-    // --- roundtrip tests ---
-
-    #[test]
-    fn test_roundtrip_update_string() {
-        let content = "---\nStatus: Draft\n---\n# Test\n";
-        let updated = update_frontmatter_content(
-            content,
-            "Status",
-            Some(FrontmatterValue::String("Active".to_string())),
-        )
-        .unwrap();
-        // Parse back with gray_matter
-        let matter = gray_matter::Matter::<gray_matter::engine::YAML>::new();
-        let parsed = matter.parse(&updated);
-        let data = parsed.data.unwrap();
-        if let gray_matter::Pod::Hash(map) = data {
-            assert_eq!(map.get("Status").unwrap().as_string().unwrap(), "Active");
-        } else {
-            panic!("Expected hash");
-        }
-    }
-
-    #[test]
-    fn test_roundtrip_update_list() {
-        let content = "---\nStatus: Draft\n---\n# Test\n";
-        let updated = update_frontmatter_content(
-            content,
-            "aliases",
-            Some(FrontmatterValue::List(vec![
-                "A".to_string(),
-                "B".to_string(),
-            ])),
-        )
-        .unwrap();
-        let matter = gray_matter::Matter::<gray_matter::engine::YAML>::new();
-        let parsed = matter.parse(&updated);
-        let data = parsed.data.unwrap();
-        if let gray_matter::Pod::Hash(map) = data {
-            let aliases = map.get("aliases").unwrap();
-            if let gray_matter::Pod::Array(arr) = aliases {
-                assert_eq!(arr.len(), 2);
-                assert_eq!(arr[0].as_string().unwrap(), "A");
-                assert_eq!(arr[1].as_string().unwrap(), "B");
-            } else {
-                panic!("Expected array");
-            }
-        } else {
-            panic!("Expected hash");
-        }
-    }
-
-    #[test]
-    fn test_roundtrip_add_then_delete() {
-        let content = "---\nStatus: Draft\n---\n# Test\n";
-        let with_owner = update_frontmatter_content(
-            content,
-            "Owner",
-            Some(FrontmatterValue::String("Luca".to_string())),
-        )
-        .unwrap();
-        assert!(with_owner.contains("Owner: Luca"));
-        let without_owner = update_frontmatter_content(&with_owner, "Owner", None).unwrap();
-        assert!(!without_owner.contains("Owner"));
-        assert!(without_owner.contains("Status: Draft"));
-    }
-
-    // --- format_yaml_key additional tests ---
-
-    #[test]
-    fn test_format_yaml_key_with_colon() {
-        assert_eq!(format_yaml_key("key:value"), "\"key:value\"");
-    }
-
-    #[test]
-    fn test_format_yaml_key_with_hash() {
-        assert_eq!(format_yaml_key("has#tag"), "\"has#tag\"");
-    }
-
-    #[test]
-    fn test_format_yaml_key_with_period() {
-        assert_eq!(format_yaml_key("key.name"), "\"key.name\"");
-    }
-
-    // --- split_frontmatter / empty frontmatter edge cases ---
-
-    #[test]
-    fn test_split_frontmatter_empty_block() {
-        // ---\n---\n  (no fields between opening and closing ---)
-        let result = split_frontmatter("---\n---\n");
-        assert!(
-            result.is_ok(),
-            "split_frontmatter should handle empty frontmatter block"
-        );
-        let (fm, rest) = result.unwrap();
-        assert_eq!(fm, "");
-        assert_eq!(rest, "\n");
-    }
-
-    #[test]
-    fn test_split_frontmatter_empty_block_no_trailing_newline() {
-        // ---\n---  (no trailing newline)
-        let result = split_frontmatter("---\n---");
-        assert!(
-            result.is_ok(),
-            "split_frontmatter should handle empty frontmatter without trailing newline"
-        );
-    }
-
-    #[test]
-    fn test_split_frontmatter_empty_block_with_body() {
-        // ---\n---\n\n# Title\n
-        let result = split_frontmatter("---\n---\n\n# Title\n");
-        assert!(
-            result.is_ok(),
-            "split_frontmatter should handle empty frontmatter with body"
-        );
-        let (fm, rest) = result.unwrap();
-        assert_eq!(fm, "");
-        assert!(rest.contains("# Title"));
-    }
-
-    #[test]
-    fn test_update_frontmatter_empty_block() {
-        let content = "---\n---\n\n# Test\n";
-        let result = update_frontmatter_content(
-            content,
-            "title",
-            Some(FrontmatterValue::String("New Title".to_string())),
-        );
-        assert!(
-            result.is_ok(),
-            "update_frontmatter_content should handle empty frontmatter block"
-        );
-        let updated = result.unwrap();
-        assert!(updated.contains("title: New Title"));
-    }
-
-    // --- block scalar (multi-line string) tests ---
-
-    #[test]
-    fn test_to_yaml_value_multiline_uses_block_scalar() {
-        let v = FrontmatterValue::String("line 1\nline 2\nline 3".to_string());
-        let yaml = v.to_yaml_value();
-        assert!(yaml.starts_with("|\n"));
-        assert!(yaml.contains("  line 1"));
-        assert!(yaml.contains("  line 2"));
-    }
-
-    #[test]
-    fn test_format_yaml_field_block_scalar() {
-        let v = FrontmatterValue::String("## Objective\n\n## Timeline".to_string());
-        let lines = format_yaml_field("template", &v);
-        assert_eq!(lines.len(), 1);
-        assert!(lines[0].starts_with("template: |\n"));
-        assert!(lines[0].contains("  ## Objective"));
-        assert!(lines[0].contains("  ## Timeline"));
-    }
-
-    #[test]
-    fn test_update_frontmatter_block_scalar_add() {
-        let content = "---\ntype: Type\n---\n# Project\n";
-        let template = "## Objective\n\n## Timeline";
-        let updated = update_frontmatter_content(
-            content,
-            "template",
-            Some(FrontmatterValue::String(template.to_string())),
-        )
-        .unwrap();
-        assert!(updated.contains("template: |"));
-        assert!(updated.contains("  ## Objective"));
-        assert!(updated.contains("  ## Timeline"));
-        assert!(updated.contains("type: Type"));
-    }
-
-    #[test]
-    fn test_update_frontmatter_block_scalar_replace() {
-        let content = "---\ntype: Type\ntemplate: |\n  ## Old\n  \n  ## Stuff\ncolor: green\n---\n# Project\n";
-        let new_template = "## New\n\n## Content";
-        let updated = update_frontmatter_content(
-            content,
-            "template",
-            Some(FrontmatterValue::String(new_template.to_string())),
-        )
-        .unwrap();
-        assert!(updated.contains("  ## New"));
-        assert!(updated.contains("  ## Content"));
-        assert!(!updated.contains("## Old"));
-        assert!(!updated.contains("## Stuff"));
-        assert!(updated.contains("color: green"));
-    }
-
-    #[test]
-    fn test_delete_frontmatter_block_scalar() {
-        let content =
-            "---\ntype: Type\ntemplate: |\n  ## Heading\n  \n  ## Body\ncolor: green\n---\n# Project\n";
-        let updated = update_frontmatter_content(content, "template", None).unwrap();
-        assert!(!updated.contains("template"));
-        assert!(!updated.contains("## Heading"));
-        assert!(updated.contains("color: green"));
-    }
-
-    #[test]
-    fn test_roundtrip_block_scalar() {
-        let content = "---\ntype: Type\n---\n# Project\n";
-        let template = "## Objective\n\nDescribe the goal.\n\n## Timeline\n\nKey dates.";
-        let updated = update_frontmatter_content(
-            content,
-            "template",
-            Some(FrontmatterValue::String(template.to_string())),
-        )
-        .unwrap();
-        // Parse back with gray_matter
-        let matter = gray_matter::Matter::<gray_matter::engine::YAML>::new();
-        let parsed = matter.parse(&updated);
-        let data = parsed.data.unwrap();
-        if let gray_matter::Pod::Hash(map) = data {
-            let roundtripped = map.get("template").unwrap().as_string().unwrap();
-            assert!(roundtripped.contains("## Objective"));
-            assert!(roundtripped.contains("## Timeline"));
-            assert!(roundtripped.contains("Describe the goal."));
-        } else {
-            panic!("Expected hash");
-        }
-    }
-
-    #[test]
-    fn test_update_frontmatter_no_body_after_closing() {
-        // Frontmatter with title, no body after closing ---
-        let content = "---\ntitle: Old\n---\n";
-        let result = update_frontmatter_content(
-            content,
-            "title",
-            Some(FrontmatterValue::String("New".to_string())),
-        );
-        assert!(result.is_ok());
-        let updated = result.unwrap();
-        assert!(updated.contains("title: New"));
-        assert!(!updated.contains("title: Old"));
-    }
-}

src-tauri/src/frontmatter/mod.rs

@@ -0,0 +1,207 @@
+mod ops;
+mod yaml;
+
+use std::fs;
+use std::path::Path;
+
+pub use ops::update_frontmatter_content;
+pub use yaml::{format_yaml_key, FrontmatterValue};
+
+/// Helper to read a file, apply a frontmatter transformation, and write back.
+pub fn with_frontmatter<F>(path: &str, transform: F) -> Result<String, String>
+where
+    F: FnOnce(&str) -> Result<String, String>,
+{
+    let file_path = Path::new(path);
+    if !file_path.exists() {
+        return Err(format!("File does not exist: {}", path));
+    }
+
+    let content =
+        fs::read_to_string(file_path).map_err(|e| format!("Failed to read {}: {}", path, e))?;
+
+    let updated = transform(&content)?;
+
+    fs::write(file_path, &updated).map_err(|e| format!("Failed to write {}: {}", path, e))?;
+
+    Ok(updated)
+}
+
+/// Update a single frontmatter property in a markdown file.
+pub fn update_frontmatter(
+    path: &str,
+    key: &str,
+    value: FrontmatterValue,
+) -> Result<String, String> {
+    with_frontmatter(path, |content| {
+        update_frontmatter_content(content, key, Some(value.clone()))
+    })
+}
+
+/// Delete a frontmatter property from a markdown file.
+pub fn delete_frontmatter_property(path: &str, key: &str) -> Result<String, String> {
+    with_frontmatter(path, |content| {
+        update_frontmatter_content(content, key, None)
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_with_frontmatter_file_not_found() {
+        let result = with_frontmatter("/nonexistent/path/file.md", |c| Ok(c.to_string()));
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("does not exist"));
+    }
+
+    #[test]
+    fn test_roundtrip_update_string() {
+        let content = "---\nStatus: Draft\n---\n# Test\n";
+        let updated = update_frontmatter_content(
+            content,
+            "Status",
+            Some(FrontmatterValue::String("Active".to_string())),
+        )
+        .unwrap();
+        let matter = gray_matter::Matter::<gray_matter::engine::YAML>::new();
+        let parsed = matter.parse(&updated);
+        let data = parsed.data.unwrap();
+        if let gray_matter::Pod::Hash(map) = data {
+            assert_eq!(map.get("Status").unwrap().as_string().unwrap(), "Active");
+        } else {
+            panic!("Expected hash");
+        }
+    }
+
+    #[test]
+    fn test_roundtrip_update_list() {
+        let content = "---\nStatus: Draft\n---\n# Test\n";
+        let updated = update_frontmatter_content(
+            content,
+            "aliases",
+            Some(FrontmatterValue::List(vec![
+                "A".to_string(),
+                "B".to_string(),
+            ])),
+        )
+        .unwrap();
+        let matter = gray_matter::Matter::<gray_matter::engine::YAML>::new();
+        let parsed = matter.parse(&updated);
+        let data = parsed.data.unwrap();
+        if let gray_matter::Pod::Hash(map) = data {
+            let aliases = map.get("aliases").unwrap();
+            if let gray_matter::Pod::Array(arr) = aliases {
+                assert_eq!(arr.len(), 2);
+                assert_eq!(arr[0].as_string().unwrap(), "A");
+                assert_eq!(arr[1].as_string().unwrap(), "B");
+            } else {
+                panic!("Expected array");
+            }
+        } else {
+            panic!("Expected hash");
+        }
+    }
+
+    #[test]
+    fn test_roundtrip_add_then_delete() {
+        let content = "---\nStatus: Draft\n---\n# Test\n";
+        let with_owner = update_frontmatter_content(
+            content,
+            "Owner",
+            Some(FrontmatterValue::String("Luca".to_string())),
+        )
+        .unwrap();
+        assert!(with_owner.contains("Owner: Luca"));
+        let without_owner = update_frontmatter_content(&with_owner, "Owner", None).unwrap();
+        assert!(!without_owner.contains("Owner"));
+        assert!(without_owner.contains("Status: Draft"));
+    }
+
+    #[test]
+    fn test_update_frontmatter_empty_block() {
+        let content = "---\n---\n\n# Test\n";
+        let result = update_frontmatter_content(
+            content,
+            "title",
+            Some(FrontmatterValue::String("New Title".to_string())),
+        );
+        assert!(result.is_ok());
+        assert!(result.unwrap().contains("title: New Title"));
+    }
+
+    #[test]
+    fn test_update_frontmatter_block_scalar_add() {
+        let content = "---\ntype: Type\n---\n# Project\n";
+        let template = "## Objective\n\n## Timeline";
+        let updated = update_frontmatter_content(
+            content,
+            "template",
+            Some(FrontmatterValue::String(template.to_string())),
+        )
+        .unwrap();
+        assert!(updated.contains("template: |"));
+        assert!(updated.contains("  ## Objective"));
+        assert!(updated.contains("type: Type"));
+    }
+
+    #[test]
+    fn test_update_frontmatter_block_scalar_replace() {
+        let content = "---\ntype: Type\ntemplate: |\n  ## Old\n  \n  ## Stuff\ncolor: green\n---\n# Project\n";
+        let updated = update_frontmatter_content(
+            content,
+            "template",
+            Some(FrontmatterValue::String("## New\n\n## Content".to_string())),
+        )
+        .unwrap();
+        assert!(updated.contains("  ## New"));
+        assert!(!updated.contains("## Old"));
+        assert!(updated.contains("color: green"));
+    }
+
+    #[test]
+    fn test_delete_frontmatter_block_scalar() {
+        let content =
+            "---\ntype: Type\ntemplate: |\n  ## Heading\n  \n  ## Body\ncolor: green\n---\n# Project\n";
+        let updated = update_frontmatter_content(content, "template", None).unwrap();
+        assert!(!updated.contains("template"));
+        assert!(updated.contains("color: green"));
+    }
+
+    #[test]
+    fn test_update_frontmatter_no_body_after_closing() {
+        let content = "---\ntitle: Old\n---\n";
+        let updated = update_frontmatter_content(
+            content,
+            "title",
+            Some(FrontmatterValue::String("New".to_string())),
+        )
+        .unwrap();
+        assert!(updated.contains("title: New"));
+        assert!(!updated.contains("title: Old"));
+    }
+
+    #[test]
+    fn test_roundtrip_block_scalar() {
+        let content = "---\ntype: Type\n---\n# Project\n";
+        let template = "## Objective\n\nDescribe the goal.\n\n## Timeline\n\nKey dates.";
+        let updated = update_frontmatter_content(
+            content,
+            "template",
+            Some(FrontmatterValue::String(template.to_string())),
+        )
+        .unwrap();
+        let matter = gray_matter::Matter::<gray_matter::engine::YAML>::new();
+        let parsed = matter.parse(&updated);
+        let data = parsed.data.unwrap();
+        if let gray_matter::Pod::Hash(map) = data {
+            let roundtripped = map.get("template").unwrap().as_string().unwrap();
+            assert!(roundtripped.contains("## Objective"));
+            assert!(roundtripped.contains("## Timeline"));
+            assert!(roundtripped.contains("Describe the goal."));
+        } else {
+            panic!("Expected hash");
+        }
+    }
+}

src-tauri/src/frontmatter/ops.rs

@@ -0,0 +1,331 @@
+use super::yaml::{format_yaml_field, FrontmatterValue};
+
+/// Check if a line defines a specific key (handles quoted and unquoted keys)
+fn line_is_key(line: &str, key: &str) -> bool {
+    let trimmed = line.trim_start();
+
+    if trimmed.starts_with(key) && trimmed[key.len()..].starts_with(':') {
+        return true;
+    }
+
+    let dq = format!("\"{}\":", key);
+    if trimmed.starts_with(&dq) {
+        return true;
+    }
+
+    let sq = format!("'{}\':", key);
+    if trimmed.starts_with(&sq) {
+        return true;
+    }
+
+    false
+}
+
+/// Check if a line continues the previous key's value (indented list item,
+/// block scalar content, or blank line inside a block scalar).
+fn is_value_continuation(line: &str) -> bool {
+    line.is_empty() || line.starts_with("  ") || line.starts_with('\t')
+}
+
+/// Split content into frontmatter body and the rest after the closing `---`.
+/// Returns `(fm_content, rest)` where `fm_content` is between the opening and closing `---`.
+fn split_frontmatter(content: &str) -> Result<(&str, &str), String> {
+    let after_open = &content[4..];
+    // Handle empty frontmatter: closing --- immediately after opening ---\n
+    if let Some(stripped) = after_open.strip_prefix("---") {
+        return Ok(("", stripped));
+    }
+    let fm_end = after_open
+        .find("\n---")
+        .map(|i| i + 4)
+        .ok_or_else(|| "Malformed frontmatter: no closing ---".to_string())?;
+    Ok((&content[4..fm_end], &content[fm_end + 4..]))
+}
+
+/// Wrap content in a new frontmatter block containing a single field.
+fn prepend_new_frontmatter(content: &str, key: &str, value: &FrontmatterValue) -> String {
+    let field_lines = format_yaml_field(key, value);
+    format!("---\n{}\n---\n{}", field_lines.join("\n"), content)
+}
+
+/// Apply a field update to existing frontmatter lines.
+/// Replaces the matching key (and its list continuations) with the new value,
+/// or appends if the key is not found. If `value` is None, removes the key.
+fn apply_field_update(lines: &[&str], key: &str, value: Option<&FrontmatterValue>) -> Vec<String> {
+    let mut new_lines: Vec<String> = Vec::new();
+    let mut found_key = false;
+    let mut i = 0;
+
+    while i < lines.len() {
+        if !line_is_key(lines[i], key) {
+            new_lines.push(lines[i].to_string());
+            i += 1;
+            continue;
+        }
+
+        found_key = true;
+        i += 1;
+        // Skip continuation lines belonging to this key (lists, block scalars)
+        while i < lines.len() && is_value_continuation(lines[i]) {
+            i += 1;
+        }
+        // Insert replacement value (if any)
+        if let Some(v) = value {
+            new_lines.extend(format_yaml_field(key, v));
+        }
+    }
+
+    if let (false, Some(v)) = (found_key, value) {
+        new_lines.extend(format_yaml_field(key, v));
+    }
+
+    new_lines
+}
+
+/// Internal function to update frontmatter content
+pub fn update_frontmatter_content(
+    content: &str,
+    key: &str,
+    value: Option<FrontmatterValue>,
+) -> Result<String, String> {
+    if !content.starts_with("---\n") {
+        return match value {
+            Some(v) => Ok(prepend_new_frontmatter(content, key, &v)),
+            None => Ok(content.to_string()),
+        };
+    }
+
+    let (fm_content, rest) = split_frontmatter(content)?;
+    let lines: Vec<&str> = fm_content.lines().collect();
+    let new_lines = apply_field_update(&lines, key, value.as_ref());
+    let new_fm = new_lines.join("\n");
+    Ok(format!("---\n{}\n---{}", new_fm, rest))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_update_frontmatter_string() {
+        let content = "---\nStatus: Draft\n---\n# Test\n";
+        let updated = update_frontmatter_content(
+            content,
+            "Status",
+            Some(FrontmatterValue::String("Active".to_string())),
+        )
+        .unwrap();
+        assert!(updated.contains("Status: Active"));
+        assert!(!updated.contains("Status: Draft"));
+    }
+
+    #[test]
+    fn test_update_frontmatter_add_new_key() {
+        let content = "---\nStatus: Draft\n---\n# Test\n";
+        let updated = update_frontmatter_content(
+            content,
+            "Owner",
+            Some(FrontmatterValue::String("Luca".to_string())),
+        )
+        .unwrap();
+        assert!(updated.contains("Owner: Luca"));
+        assert!(updated.contains("Status: Draft"));
+    }
+
+    #[test]
+    fn test_update_frontmatter_quoted_key() {
+        let content = "---\n\"Is A\": Note\n---\n# Test\n";
+        let updated = update_frontmatter_content(
+            content,
+            "Is A",
+            Some(FrontmatterValue::String("Project".to_string())),
+        )
+        .unwrap();
+        assert!(updated.contains("\"Is A\": Project"));
+        assert!(!updated.contains("Note"));
+    }
+
+    #[test]
+    fn test_update_frontmatter_list() {
+        let content = "---\nStatus: Draft\n---\n# Test\n";
+        let updated = update_frontmatter_content(
+            content,
+            "aliases",
+            Some(FrontmatterValue::List(vec![
+                "Alias1".to_string(),
+                "Alias2".to_string(),
+            ])),
+        )
+        .unwrap();
+        assert!(updated.contains("aliases:"));
+        assert!(updated.contains("  - \"Alias1\""));
+        assert!(updated.contains("  - \"Alias2\""));
+    }
+
+    #[test]
+    fn test_update_frontmatter_replace_list() {
+        let content = "---\naliases:\n  - Old1\n  - Old2\nStatus: Draft\n---\n# Test\n";
+        let updated = update_frontmatter_content(
+            content,
+            "aliases",
+            Some(FrontmatterValue::List(vec!["New1".to_string()])),
+        )
+        .unwrap();
+        assert!(updated.contains("  - \"New1\""));
+        assert!(!updated.contains("Old1"));
+        assert!(!updated.contains("Old2"));
+        assert!(updated.contains("Status: Draft"));
+    }
+
+    #[test]
+    fn test_delete_frontmatter_property() {
+        let content = "---\nStatus: Draft\nOwner: Luca\n---\n# Test\n";
+        let updated = update_frontmatter_content(content, "Owner", None).unwrap();
+        assert!(!updated.contains("Owner"));
+        assert!(updated.contains("Status: Draft"));
+    }
+
+    #[test]
+    fn test_delete_frontmatter_list_property() {
+        let content = "---\naliases:\n  - Alias1\n  - Alias2\nStatus: Draft\n---\n# Test\n";
+        let updated = update_frontmatter_content(content, "aliases", None).unwrap();
+        assert!(!updated.contains("aliases"));
+        assert!(!updated.contains("Alias1"));
+        assert!(updated.contains("Status: Draft"));
+    }
+
+    #[test]
+    fn test_update_frontmatter_no_existing() {
+        let content = "# Test\n\nSome content here.";
+        let updated = update_frontmatter_content(
+            content,
+            "Status",
+            Some(FrontmatterValue::String("Draft".to_string())),
+        )
+        .unwrap();
+        assert!(updated.starts_with("---\n"));
+        assert!(updated.contains("Status: Draft"));
+        assert!(updated.contains("# Test"));
+    }
+
+    #[test]
+    fn test_update_frontmatter_bool() {
+        let content = "---\nStatus: Draft\n---\n# Test\n";
+        let updated =
+            update_frontmatter_content(content, "Reviewed", Some(FrontmatterValue::Bool(true)))
+                .unwrap();
+        assert!(updated.contains("Reviewed: true"));
+    }
+
+    #[test]
+    fn test_update_frontmatter_number() {
+        let content = "---\nStatus: Draft\n---\n# Test\n";
+        let updated =
+            update_frontmatter_content(content, "Priority", Some(FrontmatterValue::Number(5.0)))
+                .unwrap();
+        assert!(updated.contains("Priority: 5"));
+    }
+
+    #[test]
+    fn test_update_frontmatter_number_float() {
+        let content = "---\nStatus: Draft\n---\n# Test\n";
+        let updated =
+            update_frontmatter_content(content, "Score", Some(FrontmatterValue::Number(9.5)))
+                .unwrap();
+        assert!(updated.contains("Score: 9.5"));
+    }
+
+    #[test]
+    fn test_update_frontmatter_null() {
+        let content = "---\nStatus: Draft\n---\n# Test\n";
+        let updated =
+            update_frontmatter_content(content, "ClearMe", Some(FrontmatterValue::Null)).unwrap();
+        assert!(updated.contains("ClearMe: null"));
+    }
+
+    #[test]
+    fn test_update_frontmatter_empty_list() {
+        let content = "---\nStatus: Draft\n---\n# Test\n";
+        let updated =
+            update_frontmatter_content(content, "tags", Some(FrontmatterValue::List(vec![])))
+                .unwrap();
+        assert!(updated.contains("tags: []"));
+    }
+
+    #[test]
+    fn test_update_frontmatter_malformed_no_closing_fence() {
+        let content = "---\nStatus: Draft\nNo closing fence here";
+        let result = update_frontmatter_content(
+            content,
+            "Status",
+            Some(FrontmatterValue::String("Active".to_string())),
+        );
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("Malformed frontmatter"));
+    }
+
+    #[test]
+    fn test_delete_nonexistent_key_noop() {
+        let content = "---\nStatus: Draft\n---\n# Test\n";
+        let updated = update_frontmatter_content(content, "NonExistent", None).unwrap();
+        assert_eq!(updated, content);
+    }
+
+    #[test]
+    fn test_delete_from_no_frontmatter_noop() {
+        let content = "# Test\n\nSome content.";
+        let updated = update_frontmatter_content(content, "NonExistent", None).unwrap();
+        assert_eq!(updated, content);
+    }
+
+    #[test]
+    fn test_line_is_key_unquoted() {
+        assert!(line_is_key("Status: Draft", "Status"));
+        assert!(!line_is_key("Status: Draft", "Owner"));
+    }
+
+    #[test]
+    fn test_line_is_key_double_quoted() {
+        assert!(line_is_key("\"Is A\": Note", "Is A"));
+        assert!(!line_is_key("\"Is A\": Note", "Status"));
+    }
+
+    #[test]
+    fn test_line_is_key_single_quoted() {
+        assert!(line_is_key("'Is A': Note", "Is A"));
+    }
+
+    #[test]
+    fn test_line_is_key_leading_whitespace() {
+        assert!(line_is_key("  Status: Draft", "Status"));
+    }
+
+    #[test]
+    fn test_line_is_key_partial_match() {
+        assert!(!line_is_key("StatusBar: value", "Status"));
+    }
+
+    #[test]
+    fn test_split_frontmatter_empty_block() {
+        let result = split_frontmatter("---\n---\n");
+        assert!(result.is_ok());
+        let (fm, rest) = result.unwrap();
+        assert_eq!(fm, "");
+        assert_eq!(rest, "\n");
+    }
+
+    #[test]
+    fn test_split_frontmatter_empty_block_no_trailing_newline() {
+        let result = split_frontmatter("---\n---");
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn test_split_frontmatter_empty_block_with_body() {
+        let result = split_frontmatter("---\n---\n\n# Title\n");
+        assert!(result.is_ok());
+        let (fm, rest) = result.unwrap();
+        assert_eq!(fm, "");
+        assert!(rest.contains("# Title"));
+    }
+}

src-tauri/src/frontmatter/yaml.rs

@@ -0,0 +1,262 @@
+use serde::{Deserialize, Serialize};
+
+/// Value type for frontmatter updates
+#[derive(Debug, Serialize, Deserialize, Clone)]
+#[serde(untagged)]
+pub enum FrontmatterValue {
+    String(String),
+    Number(f64),
+    Bool(bool),
+    List(Vec<String>),
+    Null,
+}
+
+/// Characters that require a YAML string value to be quoted.
+fn has_yaml_special_chars(s: &str) -> bool {
+    s.contains(':') || s.contains('#')
+}
+
+/// Check if a string starts with a YAML collection indicator (array or map).
+fn starts_as_yaml_collection(s: &str) -> bool {
+    s.starts_with('[') || s.starts_with('{')
+}
+
+/// Check whether a YAML string value needs quoting to avoid ambiguity.
+fn needs_yaml_quoting(s: &str) -> bool {
+    has_yaml_special_chars(s)
+        || starts_as_yaml_collection(s)
+        || matches!(s, "true" | "false" | "null")
+        || s.parse::<f64>().is_ok()
+}
+
+/// Quote a string value for YAML, escaping internal double quotes.
+fn quote_yaml_string(s: &str) -> String {
+    format!("\"{}\"", s.replace('\"', "\\\""))
+}
+
+/// Format a single YAML list item as `  - "value"`.
+fn format_list_item(item: &str) -> String {
+    format!("  - {}", quote_yaml_string(item))
+}
+
+/// Format a multi-line string as a YAML block scalar (`|`).
+/// Each line is indented by 2 spaces; empty lines are preserved as blank.
+fn format_block_scalar(s: &str) -> String {
+    let indented = s
+        .lines()
+        .map(|l| {
+            if l.is_empty() {
+                String::new()
+            } else {
+                format!("  {}", l)
+            }
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+    format!("|\n{}", indented)
+}
+
+/// Format a number for YAML (integers without decimal, floats with).
+fn format_yaml_number(n: f64) -> String {
+    if n.fract() == 0.0 {
+        format!("{}", n as i64)
+    } else {
+        format!("{}", n)
+    }
+}
+
+impl FrontmatterValue {
+    pub fn to_yaml_value(&self) -> String {
+        match self {
+            FrontmatterValue::String(s) => {
+                if s.contains('\n') {
+                    format_block_scalar(s)
+                } else if needs_yaml_quoting(s) {
+                    quote_yaml_string(s)
+                } else {
+                    s.clone()
+                }
+            }
+            FrontmatterValue::Number(n) => format_yaml_number(*n),
+            FrontmatterValue::Bool(b) => if *b { "true" } else { "false" }.to_string(),
+            FrontmatterValue::List(items) if items.is_empty() => "[]".to_string(),
+            FrontmatterValue::List(items) => items
+                .iter()
+                .map(|item| format_list_item(item))
+                .collect::<Vec<_>>()
+                .join("\n"),
+            FrontmatterValue::Null => "null".to_string(),
+        }
+    }
+}
+
+/// Check whether a YAML key needs quoting (contains spaces, special chars, etc.).
+fn needs_key_quoting(key: &str) -> bool {
+    key.chars()
+        .any(|c| !c.is_ascii_alphanumeric() && c != '_' && c != '-')
+}
+
+/// Format a key for YAML output (quote if necessary)
+pub fn format_yaml_key(key: &str) -> String {
+    if needs_key_quoting(key) {
+        format!("\"{}\"", key)
+    } else {
+        key.to_string()
+    }
+}
+
+/// Format a key-value pair as one or more YAML lines.
+pub fn format_yaml_field(key: &str, value: &FrontmatterValue) -> Vec<String> {
+    let yaml_key = format_yaml_key(key);
+    let yaml_value = value.to_yaml_value();
+    if yaml_value.starts_with("|\n") {
+        // Block scalar: key and indicator on the same line, content follows
+        vec![format!("{}: {}", yaml_key, yaml_value)]
+    } else if yaml_value.contains('\n') {
+        vec![format!("{}:", yaml_key), yaml_value]
+    } else {
+        vec![format!("{}: {}", yaml_key, yaml_value)]
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_to_yaml_value_string_needs_quoting_colon() {
+        let v = FrontmatterValue::String("key: value".to_string());
+        assert_eq!(v.to_yaml_value(), "\"key: value\"");
+    }
+
+    #[test]
+    fn test_to_yaml_value_string_needs_quoting_hash() {
+        let v = FrontmatterValue::String("has # comment".to_string());
+        assert_eq!(v.to_yaml_value(), "\"has # comment\"");
+    }
+
+    #[test]
+    fn test_to_yaml_value_string_needs_quoting_bracket() {
+        let v = FrontmatterValue::String("[array-like]".to_string());
+        assert_eq!(v.to_yaml_value(), "\"[array-like]\"");
+    }
+
+    #[test]
+    fn test_to_yaml_value_string_needs_quoting_brace() {
+        let v = FrontmatterValue::String("{object-like}".to_string());
+        assert_eq!(v.to_yaml_value(), "\"{object-like}\"");
+    }
+
+    #[test]
+    fn test_to_yaml_value_string_needs_quoting_bool_like() {
+        assert_eq!(
+            FrontmatterValue::String("true".to_string()).to_yaml_value(),
+            "\"true\""
+        );
+        assert_eq!(
+            FrontmatterValue::String("false".to_string()).to_yaml_value(),
+            "\"false\""
+        );
+    }
+
+    #[test]
+    fn test_to_yaml_value_string_needs_quoting_null_like() {
+        assert_eq!(
+            FrontmatterValue::String("null".to_string()).to_yaml_value(),
+            "\"null\""
+        );
+    }
+
+    #[test]
+    fn test_to_yaml_value_string_needs_quoting_number_like() {
+        assert_eq!(
+            FrontmatterValue::String("42".to_string()).to_yaml_value(),
+            "\"42\""
+        );
+        assert_eq!(
+            FrontmatterValue::String("3.14".to_string()).to_yaml_value(),
+            "\"3.14\""
+        );
+    }
+
+    #[test]
+    fn test_to_yaml_value_string_plain() {
+        let v = FrontmatterValue::String("Hello World".to_string());
+        assert_eq!(v.to_yaml_value(), "Hello World");
+    }
+
+    #[test]
+    fn test_to_yaml_value_number_integer() {
+        let v = FrontmatterValue::Number(42.0);
+        assert_eq!(v.to_yaml_value(), "42");
+    }
+
+    #[test]
+    fn test_to_yaml_value_number_float() {
+        let v = FrontmatterValue::Number(3.125);
+        assert_eq!(v.to_yaml_value(), "3.125");
+    }
+
+    #[test]
+    fn test_to_yaml_value_null() {
+        assert_eq!(FrontmatterValue::Null.to_yaml_value(), "null");
+    }
+
+    #[test]
+    fn test_to_yaml_value_empty_list() {
+        let v = FrontmatterValue::List(vec![]);
+        assert_eq!(v.to_yaml_value(), "[]");
+    }
+
+    #[test]
+    fn test_to_yaml_value_list_with_colon() {
+        let v = FrontmatterValue::List(vec!["key: value".to_string()]);
+        assert_eq!(v.to_yaml_value(), "  - \"key: value\"");
+    }
+
+    #[test]
+    fn test_to_yaml_value_multiline_uses_block_scalar() {
+        let v = FrontmatterValue::String("line 1\nline 2\nline 3".to_string());
+        let yaml = v.to_yaml_value();
+        assert!(yaml.starts_with("|\n"));
+        assert!(yaml.contains("  line 1"));
+        assert!(yaml.contains("  line 2"));
+    }
+
+    #[test]
+    fn test_format_yaml_key_simple() {
+        assert_eq!(format_yaml_key("Status"), "Status");
+        assert_eq!(format_yaml_key("is_a"), "is_a");
+    }
+
+    #[test]
+    fn test_format_yaml_key_with_spaces() {
+        assert_eq!(format_yaml_key("Is A"), "\"Is A\"");
+        assert_eq!(format_yaml_key("Created at"), "\"Created at\"");
+    }
+
+    #[test]
+    fn test_format_yaml_key_with_colon() {
+        assert_eq!(format_yaml_key("key:value"), "\"key:value\"");
+    }
+
+    #[test]
+    fn test_format_yaml_key_with_hash() {
+        assert_eq!(format_yaml_key("has#tag"), "\"has#tag\"");
+    }
+
+    #[test]
+    fn test_format_yaml_key_with_period() {
+        assert_eq!(format_yaml_key("key.name"), "\"key.name\"");
+    }
+
+    #[test]
+    fn test_format_yaml_field_block_scalar() {
+        let v = FrontmatterValue::String("## Objective\n\n## Timeline".to_string());
+        let lines = format_yaml_field("template", &v);
+        assert_eq!(lines.len(), 1);
+        assert!(lines[0].starts_with("template: |\n"));
+        assert!(lines[0].contains("  ## Objective"));
+        assert!(lines[0].contains("  ## Timeline"));
+    }
+}

src-tauri/src/git/commit.rs

@@ -0,0 +1,87 @@
+use std::path::Path;
+use std::process::Command;
+
+/// Commit all changes with a message.
+pub fn git_commit(vault_path: &str, message: &str) -> Result<String, String> {
+    let vault = Path::new(vault_path);
+
+    // Stage all changes
+    let add = Command::new("git")
+        .args(["add", "-A"])
+        .current_dir(vault)
+        .output()
+        .map_err(|e| format!("Failed to run git add: {}", e))?;
+
+    if !add.status.success() {
+        let stderr = String::from_utf8_lossy(&add.stderr);
+        return Err(format!("git add failed: {}", stderr));
+    }
+
+    // Commit
+    let commit = Command::new("git")
+        .args(["commit", "-m", message])
+        .current_dir(vault)
+        .output()
+        .map_err(|e| format!("Failed to run git commit: {}", e))?;
+
+    if !commit.status.success() {
+        let stderr = String::from_utf8_lossy(&commit.stderr);
+        let stdout = String::from_utf8_lossy(&commit.stdout);
+        // git writes "nothing to commit" to stdout, not stderr
+        let detail = if stderr.trim().is_empty() {
+            stdout
+        } else {
+            stderr
+        };
+        return Err(format!("git commit failed: {}", detail.trim()));
+    }
+
+    Ok(String::from_utf8_lossy(&commit.stdout).to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::git::tests::setup_git_repo;
+    use std::fs;
+    use std::process::Command;
+
+    #[test]
+    fn test_git_commit() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+
+        fs::write(vault.join("commit-test.md"), "# Test\n").unwrap();
+
+        let result = git_commit(vault.to_str().unwrap(), "Test commit");
+        assert!(result.is_ok());
+
+        // Verify the commit exists
+        let log = Command::new("git")
+            .args(["log", "--oneline", "-1"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        let log_str = String::from_utf8_lossy(&log.stdout);
+        assert!(log_str.contains("Test commit"));
+    }
+
+    #[test]
+    fn test_commit_nothing_to_commit_returns_error() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let vp = vault.to_str().unwrap();
+
+        // Create and commit, so working tree is clean
+        fs::write(vault.join("clean.md"), "# Clean\n").unwrap();
+        git_commit(vp, "initial").unwrap();
+
+        // Committing again with no changes should fail
+        let result = git_commit(vp, "nothing here");
+        assert!(result.is_err(), "Commit should fail when nothing to commit");
+        assert!(
+            result.unwrap_err().contains("nothing to commit"),
+            "Error should mention 'nothing to commit'"
+        );
+    }
+}

src-tauri/src/git/conflict.rs

@@ -0,0 +1,366 @@
+use std::path::Path;
+use std::process::Command;
+
+use super::run_git;
+
+/// List files with merge conflicts (unmerged paths).
+///
+/// Uses `git ls-files --unmerged` instead of `git diff --diff-filter=U` because
+/// ls-files reliably detects unmerged index entries even when the merge state is
+/// stale (e.g. after a reboot or when MERGE_HEAD is missing).
+pub fn get_conflict_files(vault_path: &str) -> Result<Vec<String>, String> {
+    let vault = Path::new(vault_path);
+    let output = Command::new("git")
+        .args(["ls-files", "--unmerged"])
+        .current_dir(vault)
+        .output()
+        .map_err(|e| format!("Failed to check conflicts: {}", e))?;
+
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    // Each unmerged file appears multiple times (once per stage: base/ours/theirs).
+    // Format: "<mode> <hash> <stage>\t<path>"
+    let mut files: Vec<String> = stdout
+        .lines()
+        .filter_map(|line| line.split('\t').nth(1).map(|s| s.to_string()))
+        .collect();
+    files.sort();
+    files.dedup();
+    Ok(files)
+}
+
+/// Resolve a single conflict file by choosing "ours" or "theirs" strategy,
+/// then stage the result.
+pub fn git_resolve_conflict(vault_path: &str, file: &str, strategy: &str) -> Result<(), String> {
+    let vault = Path::new(vault_path);
+
+    let checkout_flag = match strategy {
+        "ours" => "--ours",
+        "theirs" => "--theirs",
+        _ => {
+            return Err(format!(
+                "Invalid strategy '{}': must be 'ours' or 'theirs'",
+                strategy
+            ))
+        }
+    };
+
+    run_git(vault, &["checkout", checkout_flag, "--", file])?;
+    run_git(vault, &["add", "--", file])?;
+
+    Ok(())
+}
+
+/// Check whether a rebase is currently in progress.
+pub fn is_rebase_in_progress(vault_path: &str) -> bool {
+    let vault = Path::new(vault_path);
+    let git_dir = vault.join(".git");
+    git_dir.join("rebase-merge").exists() || git_dir.join("rebase-apply").exists()
+}
+
+/// Check whether a merge is currently in progress.
+pub fn is_merge_in_progress(vault_path: &str) -> bool {
+    Path::new(vault_path)
+        .join(".git")
+        .join("MERGE_HEAD")
+        .exists()
+}
+
+/// Returns the current conflict mode: "rebase", "merge", or "none".
+pub fn get_conflict_mode(vault_path: &str) -> String {
+    if is_rebase_in_progress(vault_path) {
+        "rebase".to_string()
+    } else if is_merge_in_progress(vault_path) {
+        "merge".to_string()
+    } else {
+        "none".to_string()
+    }
+}
+
+/// Commit after all conflicts have been resolved.
+/// Detects whether the repo is in a merge or rebase state and uses the
+/// appropriate command (`git commit` vs `git rebase --continue`).
+pub fn git_commit_conflict_resolution(vault_path: &str) -> Result<String, String> {
+    let vault = Path::new(vault_path);
+
+    // Verify no remaining conflicts
+    let remaining = get_conflict_files(vault_path)?;
+    if !remaining.is_empty() {
+        return Err(format!(
+            "Cannot commit: {} file(s) still have unresolved conflicts",
+            remaining.len()
+        ));
+    }
+
+    let mode = get_conflict_mode(vault_path);
+    let output = match mode.as_str() {
+        "rebase" => Command::new("git")
+            .args(["rebase", "--continue"])
+            .env("GIT_EDITOR", "true")
+            .current_dir(vault)
+            .output()
+            .map_err(|e| format!("Failed to run git rebase --continue: {}", e))?,
+        _ => Command::new("git")
+            .args(["commit", "-m", "Resolve merge conflicts"])
+            .current_dir(vault)
+            .output()
+            .map_err(|e| format!("Failed to run git commit: {}", e))?,
+    };
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        let detail = if stderr.trim().is_empty() {
+            stdout
+        } else {
+            stderr
+        };
+        let cmd_name = if mode == "rebase" {
+            "git rebase --continue"
+        } else {
+            "git commit"
+        };
+        return Err(format!("{} failed: {}", cmd_name, detail.trim()));
+    }
+
+    Ok(String::from_utf8_lossy(&output.stdout).to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::git::tests::{setup_git_repo, setup_remote_pair};
+    use crate::git::{git_commit, git_pull, git_push};
+    use std::fs;
+    use std::process::Command;
+    use tempfile::TempDir;
+
+    #[test]
+    fn test_get_conflict_files_empty_when_clean() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let vp = vault.to_str().unwrap();
+
+        fs::write(vault.join("note.md"), "# Note\n").unwrap();
+        git_commit(vp, "initial").unwrap();
+
+        let conflicts = get_conflict_files(vp).unwrap();
+        assert!(conflicts.is_empty());
+    }
+
+    #[test]
+    fn test_resolve_conflict_invalid_strategy() {
+        let (_bare, _clone_a, clone_b) = setup_conflict_pair();
+        let vp_b = clone_b.path().to_str().unwrap();
+
+        let result = git_resolve_conflict(vp_b, "conflict.md", "invalid");
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("Invalid strategy"));
+    }
+
+    #[test]
+    fn test_conflict_mode_none_for_clean_repo() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let vp = vault.to_str().unwrap();
+
+        fs::write(vault.join("note.md"), "# Note\n").unwrap();
+        git_commit(vp, "initial").unwrap();
+
+        assert_eq!(get_conflict_mode(vp), "none");
+        assert!(!is_rebase_in_progress(vp));
+        assert!(!is_merge_in_progress(vp));
+    }
+
+    /// Set up a pair of clones that have a merge conflict on the same file.
+    /// Returns (bare, clone_a, clone_b) where clone_b has an unresolved conflict.
+    fn setup_conflict_pair() -> (TempDir, TempDir, TempDir) {
+        let (bare_dir, clone_a_dir, clone_b_dir) = setup_remote_pair();
+
+        let vp_a = clone_a_dir.path().to_str().unwrap();
+        let vp_b = clone_b_dir.path().to_str().unwrap();
+
+        // A creates the file and pushes
+        fs::write(clone_a_dir.path().join("conflict.md"), "# Original\n").unwrap();
+        git_commit(vp_a, "create conflict.md").unwrap();
+        git_push(vp_a).unwrap();
+
+        // B pulls to get the file
+        git_pull(vp_b).unwrap();
+
+        // A modifies and pushes
+        fs::write(clone_a_dir.path().join("conflict.md"), "# Version A\n").unwrap();
+        git_commit(vp_a, "A's change").unwrap();
+        git_push(vp_a).unwrap();
+
+        // B modifies the same file locally and commits
+        fs::write(clone_b_dir.path().join("conflict.md"), "# Version B\n").unwrap();
+        git_commit(vp_b, "B's change").unwrap();
+
+        // B pulls — this causes a merge conflict
+        let result = git_pull(vp_b).unwrap();
+        assert_eq!(result.status, "conflict");
+
+        (bare_dir, clone_a_dir, clone_b_dir)
+    }
+
+    #[test]
+    fn test_resolve_conflict_ours() {
+        let (_bare, _clone_a, clone_b) = setup_conflict_pair();
+        let vp_b = clone_b.path().to_str().unwrap();
+
+        let conflicts = get_conflict_files(vp_b).unwrap();
+        assert!(conflicts.contains(&"conflict.md".to_string()));
+
+        git_resolve_conflict(vp_b, "conflict.md", "ours").unwrap();
+
+        let remaining = get_conflict_files(vp_b).unwrap();
+        assert!(remaining.is_empty());
+
+        let content = fs::read_to_string(clone_b.path().join("conflict.md")).unwrap();
+        assert_eq!(content, "# Version B\n");
+    }
+
+    #[test]
+    fn test_resolve_conflict_theirs() {
+        let (_bare, _clone_a, clone_b) = setup_conflict_pair();
+        let vp_b = clone_b.path().to_str().unwrap();
+
+        git_resolve_conflict(vp_b, "conflict.md", "theirs").unwrap();
+
+        let remaining = get_conflict_files(vp_b).unwrap();
+        assert!(remaining.is_empty());
+
+        let content = fs::read_to_string(clone_b.path().join("conflict.md")).unwrap();
+        assert_eq!(content, "# Version A\n");
+    }
+
+    #[test]
+    fn test_commit_conflict_resolution() {
+        let (_bare, _clone_a, clone_b) = setup_conflict_pair();
+        let vp_b = clone_b.path().to_str().unwrap();
+
+        git_resolve_conflict(vp_b, "conflict.md", "ours").unwrap();
+
+        let result = git_commit_conflict_resolution(vp_b);
+        assert!(result.is_ok());
+
+        let log = Command::new("git")
+            .args(["log", "--oneline", "-1"])
+            .current_dir(clone_b.path())
+            .output()
+            .unwrap();
+        let log_str = String::from_utf8_lossy(&log.stdout);
+        assert!(log_str.contains("Resolve merge conflicts"));
+    }
+
+    #[test]
+    fn test_commit_conflict_resolution_fails_with_unresolved() {
+        let (_bare, _clone_a, clone_b) = setup_conflict_pair();
+        let vp_b = clone_b.path().to_str().unwrap();
+
+        let result = git_commit_conflict_resolution(vp_b);
+        assert!(result.is_err());
+        assert!(result
+            .unwrap_err()
+            .contains("still have unresolved conflicts"));
+    }
+
+    #[test]
+    fn test_conflict_mode_merge_during_merge_conflict() {
+        let (_bare, _clone_a, clone_b) = setup_conflict_pair();
+        let vp_b = clone_b.path().to_str().unwrap();
+
+        assert_eq!(get_conflict_mode(vp_b), "merge");
+        assert!(is_merge_in_progress(vp_b));
+        assert!(!is_rebase_in_progress(vp_b));
+    }
+
+    #[test]
+    fn test_commit_conflict_resolution_merge_mode() {
+        let (_bare, _clone_a, clone_b) = setup_conflict_pair();
+        let vp_b = clone_b.path().to_str().unwrap();
+
+        assert_eq!(get_conflict_mode(vp_b), "merge");
+
+        git_resolve_conflict(vp_b, "conflict.md", "ours").unwrap();
+        let result = git_commit_conflict_resolution(vp_b);
+        assert!(result.is_ok());
+
+        assert_eq!(get_conflict_mode(vp_b), "none");
+    }
+
+    /// Set up a rebase conflict: clone_b has diverged from origin and
+    /// `git pull --rebase` causes a conflict.
+    fn setup_rebase_conflict_pair() -> (TempDir, TempDir, TempDir) {
+        let (bare_dir, clone_a_dir, clone_b_dir) = setup_remote_pair();
+
+        let vp_a = clone_a_dir.path().to_str().unwrap();
+        let vp_b = clone_b_dir.path().to_str().unwrap();
+
+        fs::write(clone_a_dir.path().join("conflict.md"), "# Original\n").unwrap();
+        git_commit(vp_a, "create conflict.md").unwrap();
+        git_push(vp_a).unwrap();
+
+        git_pull(vp_b).unwrap();
+
+        fs::write(clone_a_dir.path().join("conflict.md"), "# Version A\n").unwrap();
+        git_commit(vp_a, "A's change").unwrap();
+        git_push(vp_a).unwrap();
+
+        fs::write(clone_b_dir.path().join("conflict.md"), "# Version B\n").unwrap();
+        git_commit(vp_b, "B's change").unwrap();
+
+        let output = Command::new("git")
+            .args(["pull", "--rebase"])
+            .current_dir(clone_b_dir.path())
+            .output()
+            .unwrap();
+
+        assert!(
+            !output.status.success(),
+            "Expected rebase conflict, but pull succeeded"
+        );
+
+        (bare_dir, clone_a_dir, clone_b_dir)
+    }
+
+    #[test]
+    fn test_conflict_mode_rebase_during_rebase_conflict() {
+        let (_bare, _clone_a, clone_b) = setup_rebase_conflict_pair();
+        let vp_b = clone_b.path().to_str().unwrap();
+
+        assert_eq!(get_conflict_mode(vp_b), "rebase");
+        assert!(is_rebase_in_progress(vp_b));
+        assert!(!is_merge_in_progress(vp_b));
+    }
+
+    #[test]
+    fn test_get_conflict_files_during_rebase() {
+        let (_bare, _clone_a, clone_b) = setup_rebase_conflict_pair();
+        let vp_b = clone_b.path().to_str().unwrap();
+
+        let conflicts = get_conflict_files(vp_b).unwrap();
+        assert!(
+            conflicts.contains(&"conflict.md".to_string()),
+            "Should detect conflict.md during rebase, got: {:?}",
+            conflicts
+        );
+    }
+
+    #[test]
+    fn test_resolve_and_continue_rebase() {
+        let (_bare, _clone_a, clone_b) = setup_rebase_conflict_pair();
+        let vp_b = clone_b.path().to_str().unwrap();
+
+        assert_eq!(get_conflict_mode(vp_b), "rebase");
+
+        git_resolve_conflict(vp_b, "conflict.md", "theirs").unwrap();
+        let remaining = get_conflict_files(vp_b).unwrap();
+        assert!(remaining.is_empty());
+
+        let result = git_commit_conflict_resolution(vp_b);
+        assert!(result.is_ok(), "rebase --continue failed: {:?}", result);
+
+        assert_eq!(get_conflict_mode(vp_b), "none");
+    }
+}

src-tauri/src/git/history.rs

@@ -0,0 +1,349 @@
+use std::path::Path;
+use std::process::Command;
+
+use super::GitCommit;
+
+/// Get git log history for a specific file in the vault.
+pub fn get_file_history(vault_path: &str, file_path: &str) -> Result<Vec<GitCommit>, String> {
+    let vault = Path::new(vault_path);
+    let file = Path::new(file_path);
+
+    let relative = file
+        .strip_prefix(vault)
+        .map_err(|_| format!("File {} is not inside vault {}", file_path, vault_path))?;
+
+    let relative_str = relative
+        .to_str()
+        .ok_or_else(|| "Invalid UTF-8 in path".to_string())?;
+
+    let output = Command::new("git")
+        .args([
+            "log",
+            "--format=%H|%h|%an|%aI|%s",
+            "-n",
+            "20",
+            "--",
+            relative_str,
+        ])
+        .current_dir(vault)
+        .output()
+        .map_err(|e| format!("Failed to run git log: {}", e))?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        // No commits yet is not an error - just return empty history
+        if stderr.contains("does not have any commits yet") {
+            return Ok(Vec::new());
+        }
+        return Err(format!("git log failed: {}", stderr));
+    }
+
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let commits = stdout
+        .lines()
+        .filter(|line| !line.is_empty())
+        .filter_map(|line| {
+            // Format: hash|short_hash|author|date|message
+            // Use splitn(5) so message (last) can contain '|'
+            let parts: Vec<&str> = line.splitn(5, '|').collect();
+            if parts.len() != 5 {
+                return None;
+            }
+            let date = chrono::DateTime::parse_from_rfc3339(parts[3])
+                .map(|dt| dt.timestamp())
+                .unwrap_or(0);
+
+            Some(GitCommit {
+                hash: parts[0].to_string(),
+                short_hash: parts[1].to_string(),
+                author: parts[2].to_string(),
+                date,
+                message: parts[4].to_string(),
+            })
+        })
+        .collect();
+
+    Ok(commits)
+}
+
+/// Get git diff for a specific file.
+pub fn get_file_diff(vault_path: &str, file_path: &str) -> Result<String, String> {
+    let vault = Path::new(vault_path);
+    let file = Path::new(file_path);
+
+    let relative = file
+        .strip_prefix(vault)
+        .map_err(|_| format!("File {} is not inside vault {}", file_path, vault_path))?;
+
+    let relative_str = relative
+        .to_str()
+        .ok_or_else(|| "Invalid UTF-8 in path".to_string())?;
+
+    // First try tracked file diff
+    let output = Command::new("git")
+        .args(["diff", "--", relative_str])
+        .current_dir(vault)
+        .output()
+        .map_err(|e| format!("Failed to run git diff: {}", e))?;
+
+    let stdout = String::from_utf8_lossy(&output.stdout).to_string();
+
+    // If no diff (maybe staged or untracked), try diff --cached
+    if stdout.is_empty() {
+        let cached = Command::new("git")
+            .args(["diff", "--cached", "--", relative_str])
+            .current_dir(vault)
+            .output()
+            .map_err(|e| format!("Failed to run git diff --cached: {}", e))?;
+
+        let cached_stdout = String::from_utf8_lossy(&cached.stdout).to_string();
+        if !cached_stdout.is_empty() {
+            return Ok(cached_stdout);
+        }
+
+        // Try showing untracked file as all-new
+        let status = Command::new("git")
+            .args(["status", "--porcelain", "--", relative_str])
+            .current_dir(vault)
+            .output()
+            .map_err(|e| format!("Failed to run git status: {}", e))?;
+
+        let status_out = String::from_utf8_lossy(&status.stdout);
+        if status_out.starts_with("??") {
+            // Untracked file: show entire content as added
+            let content =
+                std::fs::read_to_string(file).map_err(|e| format!("Failed to read file: {}", e))?;
+            let lines: Vec<String> = content.lines().map(|l| format!("+{}", l)).collect();
+            return Ok(format!(
+                "diff --git a/{0} b/{0}\nnew file\n--- /dev/null\n+++ b/{0}\n@@ -0,0 +1,{1} @@\n{2}",
+                relative_str,
+                lines.len(),
+                lines.join("\n")
+            ));
+        }
+    }
+
+    Ok(stdout)
+}
+
+/// Get git diff for a specific file at a given commit (compared to its parent).
+pub fn get_file_diff_at_commit(
+    vault_path: &str,
+    file_path: &str,
+    commit_hash: &str,
+) -> Result<String, String> {
+    let vault = Path::new(vault_path);
+    let file = Path::new(file_path);
+
+    let relative = file
+        .strip_prefix(vault)
+        .map_err(|_| format!("File {} is not inside vault {}", file_path, vault_path))?;
+
+    let relative_str = relative
+        .to_str()
+        .ok_or_else(|| "Invalid UTF-8 in path".to_string())?;
+
+    // Show diff between commit^ and commit for this file
+    let output = Command::new("git")
+        .args([
+            "diff",
+            &format!("{}^", commit_hash),
+            commit_hash,
+            "--",
+            relative_str,
+        ])
+        .current_dir(vault)
+        .output()
+        .map_err(|e| format!("Failed to run git diff: {}", e))?;
+
+    let stdout = String::from_utf8_lossy(&output.stdout).to_string();
+
+    // If diff is empty, it might be the initial commit (no parent).
+    // Fall back to showing the full file content as added.
+    if stdout.is_empty() {
+        let show = Command::new("git")
+            .args(["show", &format!("{}:{}", commit_hash, relative_str)])
+            .current_dir(vault)
+            .output()
+            .map_err(|e| format!("Failed to run git show: {}", e))?;
+
+        if show.status.success() {
+            let content = String::from_utf8_lossy(&show.stdout);
+            let lines: Vec<String> = content.lines().map(|l| format!("+{}", l)).collect();
+            return Ok(format!(
+                "diff --git a/{0} b/{0}\nnew file\n--- /dev/null\n+++ b/{0}\n@@ -0,0 +1,{1} @@\n{2}",
+                relative_str,
+                lines.len(),
+                lines.join("\n")
+            ));
+        }
+    }
+
+    Ok(stdout)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::git::tests::setup_git_repo;
+    use std::fs;
+    use std::process::Command;
+
+    #[test]
+    fn test_get_file_history_with_commits() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let file = vault.join("test.md");
+
+        fs::write(&file, "# Initial\n").unwrap();
+        Command::new("git")
+            .args(["add", "test.md"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        Command::new("git")
+            .args(["commit", "-m", "Initial commit"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        fs::write(&file, "# Updated\n\nNew content.").unwrap();
+        Command::new("git")
+            .args(["add", "test.md"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        Command::new("git")
+            .args(["commit", "-m", "Update test"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        let history = get_file_history(vault.to_str().unwrap(), file.to_str().unwrap()).unwrap();
+
+        assert_eq!(history.len(), 2);
+        assert_eq!(history[0].message, "Update test");
+        assert_eq!(history[1].message, "Initial commit");
+        assert_eq!(history[0].author, "Test User");
+        assert!(!history[0].hash.is_empty());
+        assert!(!history[0].short_hash.is_empty());
+    }
+
+    #[test]
+    fn test_get_file_history_no_commits() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let file = vault.join("new.md");
+        fs::write(&file, "# New\n").unwrap();
+
+        let history = get_file_history(vault.to_str().unwrap(), file.to_str().unwrap()).unwrap();
+
+        assert!(history.is_empty());
+    }
+
+    #[test]
+    fn test_get_file_diff() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let file = vault.join("diff-test.md");
+
+        fs::write(&file, "# Test\n\nOriginal content.").unwrap();
+        Command::new("git")
+            .args(["add", "diff-test.md"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        Command::new("git")
+            .args(["commit", "-m", "Add diff-test"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        fs::write(&file, "# Test\n\nModified content.").unwrap();
+
+        let diff = get_file_diff(vault.to_str().unwrap(), file.to_str().unwrap()).unwrap();
+
+        assert!(!diff.is_empty());
+        assert!(diff.contains("-Original content."));
+        assert!(diff.contains("+Modified content."));
+    }
+
+    #[test]
+    fn test_get_file_diff_at_commit() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let file = vault.join("diff-at-commit.md");
+
+        fs::write(&file, "# First\n\nOriginal content.").unwrap();
+        Command::new("git")
+            .args(["add", "diff-at-commit.md"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        Command::new("git")
+            .args(["commit", "-m", "First commit"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        fs::write(&file, "# First\n\nModified content.").unwrap();
+        Command::new("git")
+            .args(["add", "diff-at-commit.md"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        Command::new("git")
+            .args(["commit", "-m", "Second commit"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        // Get hash of second commit
+        let log = Command::new("git")
+            .args(["log", "--format=%H", "-1"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        let hash = String::from_utf8_lossy(&log.stdout).trim().to_string();
+
+        let diff = get_file_diff_at_commit(vault.to_str().unwrap(), file.to_str().unwrap(), &hash)
+            .unwrap();
+
+        assert!(!diff.is_empty());
+        assert!(diff.contains("-Original content."));
+        assert!(diff.contains("+Modified content."));
+    }
+
+    #[test]
+    fn test_get_file_diff_at_initial_commit() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let file = vault.join("initial.md");
+
+        fs::write(&file, "# Initial\n\nHello world.").unwrap();
+        Command::new("git")
+            .args(["add", "initial.md"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        Command::new("git")
+            .args(["commit", "-m", "Initial commit"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        let log = Command::new("git")
+            .args(["log", "--format=%H", "-1"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        let hash = String::from_utf8_lossy(&log.stdout).trim().to_string();
+
+        let diff = get_file_diff_at_commit(vault.to_str().unwrap(), file.to_str().unwrap(), &hash)
+            .unwrap();
+
+        assert!(!diff.is_empty());
+        assert!(diff.contains("+# Initial"));
+        assert!(diff.contains("+Hello world."));
+    }
+}

src-tauri/src/git/mod.rs

@@ -0,0 +1,352 @@
+mod commit;
+mod conflict;
+mod history;
+mod pulse;
+mod remote;
+mod status;
+
+use std::path::Path;
+use std::process::Command;
+
+pub use commit::git_commit;
+pub use conflict::{
+    get_conflict_files, get_conflict_mode, git_commit_conflict_resolution, git_resolve_conflict,
+    is_merge_in_progress, is_rebase_in_progress,
+};
+pub use history::{get_file_diff, get_file_diff_at_commit, get_file_history};
+pub use pulse::{get_last_commit_info, get_vault_pulse, LastCommitInfo, PulseCommit, PulseFile};
+pub use remote::{git_pull, git_push, has_remote, GitPullResult, GitPushResult};
+pub use status::{get_modified_files, ModifiedFile};
+
+use serde::Serialize;
+
+#[derive(Debug, Serialize, Clone)]
+pub struct GitCommit {
+    pub hash: String,
+    #[serde(rename = "shortHash")]
+    pub short_hash: String,
+    pub message: String,
+    pub author: String,
+    pub date: i64,
+}
+
+/// Initialize a new git repository, stage all files, and create an initial commit.
+pub fn init_repo(path: &str) -> Result<(), String> {
+    let dir = Path::new(path);
+
+    run_git(dir, &["init"])?;
+    ensure_author_config(dir)?;
+
+    // Write .gitignore before the first commit so machine-specific and
+    // macOS metadata files are never tracked and don't cause conflicts.
+    let gitignore_path = dir.join(".gitignore");
+    if !gitignore_path.exists() {
+        std::fs::write(
+            &gitignore_path,
+            "# Laputa app files (machine-specific, never commit)\n\
+.laputa-cache.json\n\
+.laputa/settings.json\n\
+\n\
+# macOS\n\
+.DS_Store\n\
+.AppleDouble\n\
+.LSOverride\n\
+\n\
+# Thumbnails\n\
+._*\n\
+\n\
+# Editors\n\
+.vscode/\n\
+.idea/\n\
+*.swp\n\
+*.swo\n",
+        )
+        .map_err(|e| format!("Failed to write .gitignore: {}", e))?;
+    }
+
+    run_git(dir, &["add", "."])?;
+    run_git(dir, &["commit", "-m", "Initial vault setup"])?;
+
+    Ok(())
+}
+
+/// Run a git command in the given directory, returning an error on failure.
+fn run_git(dir: &Path, args: &[&str]) -> Result<(), String> {
+    let output = Command::new("git")
+        .args(args)
+        .current_dir(dir)
+        .output()
+        .map_err(|e| format!("Failed to run git {}: {}", args[0], e))?;
+
+    if output.status.success() {
+        return Ok(());
+    }
+
+    Err(format!(
+        "git {} failed: {}",
+        args[0],
+        String::from_utf8_lossy(&output.stderr)
+    ))
+}
+
+/// Set local user.name and user.email if not already configured.
+fn ensure_author_config(dir: &Path) -> Result<(), String> {
+    for (key, fallback) in [("user.name", "Laputa"), ("user.email", "vault@laputa.app")] {
+        let check = Command::new("git")
+            .args(["config", key])
+            .current_dir(dir)
+            .output()
+            .map_err(|e| format!("Failed to check git config: {}", e))?;
+
+        let value = String::from_utf8_lossy(&check.stdout);
+        if !check.status.success() || value.trim().is_empty() {
+            run_git(dir, &["config", key, fallback])?;
+        }
+    }
+    Ok(())
+}
+
+/// Extract "owner/repo" from a GitHub remote URL.
+/// Supports HTTPS (https://github.com/owner/repo.git) and
+/// SSH (git@github.com:owner/repo.git) formats.
+fn parse_github_repo_path(url: &str) -> Option<String> {
+    let trimmed = url.trim();
+
+    // SSH format: git@github.com:owner/repo.git
+    if let Some(rest) = trimmed.strip_prefix("git@github.com:") {
+        let path = rest.strip_suffix(".git").unwrap_or(rest);
+        if path.contains('/') {
+            return Some(path.to_string());
+        }
+    }
+
+    // HTTPS format: https://github.com/owner/repo.git
+    // Also handle token-embedded URLs: https://token@github.com/owner/repo.git
+    if trimmed.contains("github.com/") {
+        let after = trimmed.split("github.com/").nth(1)?;
+        let path = after.strip_suffix(".git").unwrap_or(after);
+        if path.contains('/') {
+            return Some(path.to_string());
+        }
+    }
+
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+    use std::process::Command;
+    use tempfile::TempDir;
+
+    pub(crate) fn setup_git_repo() -> TempDir {
+        let dir = TempDir::new().unwrap();
+        let path = dir.path();
+
+        Command::new("git")
+            .args(["init"])
+            .current_dir(path)
+            .output()
+            .unwrap();
+
+        Command::new("git")
+            .args(["config", "user.email", "test@test.com"])
+            .current_dir(path)
+            .output()
+            .unwrap();
+
+        Command::new("git")
+            .args(["config", "user.name", "Test User"])
+            .current_dir(path)
+            .output()
+            .unwrap();
+
+        dir
+    }
+
+    /// Set up a bare "remote" and a clone that acts as the working vault.
+    pub(crate) fn setup_remote_pair() -> (TempDir, TempDir, TempDir) {
+        let bare_dir = TempDir::new().unwrap();
+        let bare = bare_dir.path();
+
+        Command::new("git")
+            .args(["init", "--bare"])
+            .current_dir(bare)
+            .output()
+            .unwrap();
+
+        let clone_a_dir = TempDir::new().unwrap();
+        Command::new("git")
+            .args(["clone", bare.to_str().unwrap(), "."])
+            .current_dir(clone_a_dir.path())
+            .output()
+            .unwrap();
+        for cmd in &[
+            &["config", "user.email", "a@test.com"][..],
+            &["config", "user.name", "User A"][..],
+        ] {
+            Command::new("git")
+                .args(*cmd)
+                .current_dir(clone_a_dir.path())
+                .output()
+                .unwrap();
+        }
+
+        let clone_b_dir = TempDir::new().unwrap();
+        Command::new("git")
+            .args(["clone", bare.to_str().unwrap(), "."])
+            .current_dir(clone_b_dir.path())
+            .output()
+            .unwrap();
+        for cmd in &[
+            &["config", "user.email", "b@test.com"][..],
+            &["config", "user.name", "User B"][..],
+        ] {
+            Command::new("git")
+                .args(*cmd)
+                .current_dir(clone_b_dir.path())
+                .output()
+                .unwrap();
+        }
+
+        (bare_dir, clone_a_dir, clone_b_dir)
+    }
+
+    #[test]
+    fn test_init_repo_creates_git_directory() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("new-vault");
+        fs::create_dir_all(&vault).unwrap();
+        fs::write(vault.join("note.md"), "# Test\n").unwrap();
+
+        init_repo(vault.to_str().unwrap()).unwrap();
+
+        assert!(vault.join(".git").exists());
+    }
+
+    #[test]
+    fn test_init_repo_creates_initial_commit() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("new-vault");
+        fs::create_dir_all(&vault).unwrap();
+        fs::write(vault.join("note.md"), "# Test\n").unwrap();
+
+        init_repo(vault.to_str().unwrap()).unwrap();
+
+        let log = Command::new("git")
+            .args(["log", "--oneline"])
+            .current_dir(&vault)
+            .output()
+            .unwrap();
+        let log_str = String::from_utf8_lossy(&log.stdout);
+        assert!(log_str.contains("Initial vault setup"));
+    }
+
+    #[test]
+    fn test_init_repo_stages_all_files() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("new-vault");
+        fs::create_dir_all(vault.join("sub")).unwrap();
+        fs::write(vault.join("note.md"), "# Test\n").unwrap();
+        fs::write(vault.join("sub/nested.md"), "# Nested\n").unwrap();
+
+        init_repo(vault.to_str().unwrap()).unwrap();
+
+        let status = Command::new("git")
+            .args(["status", "--porcelain"])
+            .current_dir(&vault)
+            .output()
+            .unwrap();
+        assert!(
+            String::from_utf8_lossy(&status.stdout).trim().is_empty(),
+            "All files should be committed"
+        );
+    }
+
+    #[test]
+    fn test_init_repo_creates_gitignore_with_ds_store() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("new-vault");
+        fs::create_dir_all(&vault).unwrap();
+        fs::write(vault.join("note.md"), "# Test\n").unwrap();
+
+        init_repo(vault.to_str().unwrap()).unwrap();
+
+        let gitignore = vault.join(".gitignore");
+        assert!(
+            gitignore.exists(),
+            ".gitignore should be created by init_repo"
+        );
+        let content = fs::read_to_string(&gitignore).unwrap();
+        assert!(
+            content.contains(".DS_Store"),
+            ".gitignore should exclude .DS_Store"
+        );
+        assert!(
+            content.contains(".laputa-cache.json"),
+            ".gitignore should exclude .laputa-cache.json"
+        );
+        assert!(
+            content.contains(".laputa/settings.json"),
+            ".gitignore should exclude settings.json"
+        );
+    }
+
+    #[test]
+    fn test_init_repo_does_not_overwrite_existing_gitignore() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("new-vault");
+        fs::create_dir_all(&vault).unwrap();
+        fs::write(vault.join("note.md"), "# Test\n").unwrap();
+        fs::write(vault.join(".gitignore"), "custom-rule\n").unwrap();
+
+        init_repo(vault.to_str().unwrap()).unwrap();
+
+        let content = fs::read_to_string(vault.join(".gitignore")).unwrap();
+        assert_eq!(
+            content, "custom-rule\n",
+            "existing .gitignore should not be overwritten"
+        );
+    }
+
+    #[test]
+    fn test_parse_github_repo_path_https() {
+        assert_eq!(
+            parse_github_repo_path("https://github.com/owner/repo.git"),
+            Some("owner/repo".to_string())
+        );
+        assert_eq!(
+            parse_github_repo_path("https://github.com/owner/repo"),
+            Some("owner/repo".to_string())
+        );
+    }
+
+    #[test]
+    fn test_parse_github_repo_path_ssh() {
+        assert_eq!(
+            parse_github_repo_path("git@github.com:owner/repo.git"),
+            Some("owner/repo".to_string())
+        );
+        assert_eq!(
+            parse_github_repo_path("git@github.com:owner/repo"),
+            Some("owner/repo".to_string())
+        );
+    }
+
+    #[test]
+    fn test_parse_github_repo_path_token_embedded() {
+        assert_eq!(
+            parse_github_repo_path("https://gho_abc123@github.com/owner/repo.git"),
+            Some("owner/repo".to_string())
+        );
+    }
+
+    #[test]
+    fn test_parse_github_repo_path_non_github() {
+        assert_eq!(
+            parse_github_repo_path("https://gitlab.com/owner/repo.git"),
+            None
+        );
+    }
+}

src-tauri/src/git/pulse.rs

@@ -0,0 +1,487 @@
+use serde::Serialize;
+use std::path::Path;
+use std::process::Command;
+
+use super::parse_github_repo_path;
+
+#[derive(Debug, Serialize, Clone)]
+pub struct PulseFile {
+    pub path: String,
+    pub status: String,
+    pub title: String,
+}
+
+#[derive(Debug, Serialize, Clone)]
+pub struct PulseCommit {
+    pub hash: String,
+    #[serde(rename = "shortHash")]
+    pub short_hash: String,
+    pub message: String,
+    pub date: i64,
+    #[serde(rename = "githubUrl")]
+    pub github_url: Option<String>,
+    pub files: Vec<PulseFile>,
+    pub added: usize,
+    pub modified: usize,
+    pub deleted: usize,
+}
+
+#[derive(Debug, Serialize, Clone)]
+pub struct LastCommitInfo {
+    #[serde(rename = "shortHash")]
+    pub short_hash: String,
+    #[serde(rename = "commitUrl")]
+    pub commit_url: Option<String>,
+}
+
+fn title_from_path(path: &str) -> String {
+    path.rsplit('/')
+        .next()
+        .unwrap_or(path)
+        .strip_suffix(".md")
+        .unwrap_or(path)
+        .replace('-', " ")
+}
+
+fn parse_file_status(code: &str) -> &str {
+    match code {
+        "A" => "added",
+        "M" => "modified",
+        "D" => "deleted",
+        _ => "modified",
+    }
+}
+
+/// Get the pulse (commit activity feed) for a vault, showing only .md file changes.
+/// `skip` offsets into the commit list for pagination; `limit` caps how many to return.
+pub fn get_vault_pulse(
+    vault_path: &str,
+    limit: usize,
+    skip: usize,
+) -> Result<Vec<PulseCommit>, String> {
+    let vault = Path::new(vault_path);
+
+    if !vault.join(".git").exists() {
+        return Err("Not a git repository".to_string());
+    }
+
+    let limit_str = limit.to_string();
+    let skip_str = skip.to_string();
+    let output = Command::new("git")
+        .args([
+            "log",
+            "--name-status",
+            "--pretty=format:%H|%h|%s|%aI",
+            "--diff-filter=ADM",
+            "-n",
+            &limit_str,
+            "--skip",
+            &skip_str,
+            "--",
+            "*.md",
+        ])
+        .current_dir(vault)
+        .output()
+        .map_err(|e| format!("Failed to run git log: {}", e))?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        if stderr.contains("does not have any commits yet") {
+            return Ok(Vec::new());
+        }
+        return Err(format!("git log failed: {}", stderr));
+    }
+
+    let github_base = get_github_base_url(vault_path);
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    Ok(parse_pulse_output(&stdout, &github_base))
+}
+
+fn get_github_base_url(vault_path: &str) -> Option<String> {
+    let vault = Path::new(vault_path);
+    let output = Command::new("git")
+        .args(["remote", "get-url", "origin"])
+        .current_dir(vault)
+        .output()
+        .ok()?;
+
+    if !output.status.success() {
+        return None;
+    }
+
+    let url = String::from_utf8_lossy(&output.stdout).trim().to_string();
+    let repo_path = parse_github_repo_path(&url)?;
+    Some(format!("https://github.com/{}", repo_path))
+}
+
+fn parse_pulse_output(stdout: &str, github_base: &Option<String>) -> Vec<PulseCommit> {
+    let mut commits: Vec<PulseCommit> = Vec::new();
+    let mut current: Option<PulseCommit> = None;
+
+    for line in stdout.lines() {
+        if line.is_empty() {
+            continue;
+        }
+
+        if line.contains('|')
+            && !line.starts_with(|c: char| {
+                c.is_ascii_uppercase() && line.len() > 1 && line.as_bytes().get(1) == Some(&b'\t')
+            })
+        {
+            // Commit header line: hash|short_hash|message|date
+            if let Some(commit) = current.take() {
+                commits.push(commit);
+            }
+            let parts: Vec<&str> = line.splitn(4, '|').collect();
+            if parts.len() == 4 {
+                let hash = parts[0];
+                let date = chrono::DateTime::parse_from_rfc3339(parts[3])
+                    .map(|dt| dt.timestamp())
+                    .unwrap_or(0);
+                let github_url = github_base
+                    .as_ref()
+                    .map(|base| format!("{}/commit/{}", base, hash));
+
+                current = Some(PulseCommit {
+                    hash: hash.to_string(),
+                    short_hash: parts[1].to_string(),
+                    message: parts[2].to_string(),
+                    date,
+                    github_url,
+                    files: Vec::new(),
+                    added: 0,
+                    modified: 0,
+                    deleted: 0,
+                });
+            }
+        } else if let Some(ref mut commit) = current {
+            // File status line: A\tpath or M\tpath
+            let file_parts: Vec<&str> = line.splitn(2, '\t').collect();
+            if file_parts.len() == 2 {
+                let status = parse_file_status(file_parts[0].trim());
+                let path = file_parts[1].trim();
+                match status {
+                    "added" => commit.added += 1,
+                    "deleted" => commit.deleted += 1,
+                    _ => commit.modified += 1,
+                }
+                commit.files.push(PulseFile {
+                    path: path.to_string(),
+                    status: status.to_string(),
+                    title: title_from_path(path),
+                });
+            }
+        }
+    }
+
+    if let Some(commit) = current {
+        commits.push(commit);
+    }
+
+    commits
+}
+
+/// Get the last commit's short hash and a GitHub URL (if remote is GitHub).
+pub fn get_last_commit_info(vault_path: &str) -> Result<Option<LastCommitInfo>, String> {
+    let vault = Path::new(vault_path);
+
+    let output = Command::new("git")
+        .args(["log", "-1", "--format=%H|%h"])
+        .current_dir(vault)
+        .output()
+        .map_err(|e| format!("Failed to run git log: {}", e))?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        if stderr.contains("does not have any commits yet") {
+            return Ok(None);
+        }
+        return Err(format!("git log failed: {}", stderr));
+    }
+
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let line = stdout.trim();
+    if line.is_empty() {
+        return Ok(None);
+    }
+
+    let parts: Vec<&str> = line.splitn(2, '|').collect();
+    if parts.len() != 2 {
+        return Ok(None);
+    }
+
+    let full_hash = parts[0];
+    let short_hash = parts[1].to_string();
+
+    let commit_url = get_github_commit_url(vault_path, full_hash);
+
+    Ok(Some(LastCommitInfo {
+        short_hash,
+        commit_url,
+    }))
+}
+
+/// Try to build a GitHub commit URL from the origin remote URL.
+fn get_github_commit_url(vault_path: &str, full_hash: &str) -> Option<String> {
+    let vault = Path::new(vault_path);
+    let output = Command::new("git")
+        .args(["remote", "get-url", "origin"])
+        .current_dir(vault)
+        .output()
+        .ok()?;
+
+    if !output.status.success() {
+        return None;
+    }
+
+    let url = String::from_utf8_lossy(&output.stdout).trim().to_string();
+    let repo_path = parse_github_repo_path(&url)?;
+    Some(format!(
+        "https://github.com/{}/commit/{}",
+        repo_path, full_hash
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::git::git_commit;
+    use crate::git::tests::setup_git_repo;
+    use std::fs;
+    use std::process::Command;
+    use tempfile::TempDir;
+
+    #[test]
+    fn test_get_vault_pulse_with_commits() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let vp = vault.to_str().unwrap();
+
+        fs::write(vault.join("note.md"), "# Note\n").unwrap();
+        git_commit(vp, "Add note").unwrap();
+
+        fs::write(vault.join("project.md"), "# Project\n").unwrap();
+        git_commit(vp, "Add project").unwrap();
+
+        let pulse = get_vault_pulse(vp, 30, 0).unwrap();
+
+        assert_eq!(pulse.len(), 2);
+        assert_eq!(pulse[0].message, "Add project");
+        assert_eq!(pulse[1].message, "Add note");
+        assert_eq!(pulse[0].files.len(), 1);
+        assert_eq!(pulse[0].files[0].path, "project.md");
+        assert_eq!(pulse[0].files[0].status, "added");
+        assert_eq!(pulse[0].added, 1);
+        assert_eq!(pulse[0].modified, 0);
+        assert!(!pulse[0].short_hash.is_empty());
+    }
+
+    #[test]
+    fn test_get_vault_pulse_no_git() {
+        let dir = TempDir::new().unwrap();
+        let vp = dir.path().to_str().unwrap();
+
+        let result = get_vault_pulse(vp, 30, 0);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("Not a git repository"));
+    }
+
+    #[test]
+    fn test_get_vault_pulse_empty_repo() {
+        let dir = setup_git_repo();
+        let vp = dir.path().to_str().unwrap();
+
+        let pulse = get_vault_pulse(vp, 30, 0).unwrap();
+        assert!(pulse.is_empty());
+    }
+
+    #[test]
+    fn test_get_vault_pulse_only_md_files() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let vp = vault.to_str().unwrap();
+
+        fs::write(vault.join("note.md"), "# Note\n").unwrap();
+        fs::write(vault.join("config.json"), "{}").unwrap();
+        git_commit(vp, "Add files").unwrap();
+
+        let pulse = get_vault_pulse(vp, 30, 0).unwrap();
+        assert_eq!(pulse.len(), 1);
+        assert_eq!(pulse[0].files.len(), 1);
+        assert_eq!(pulse[0].files[0].path, "note.md");
+    }
+
+    #[test]
+    fn test_get_vault_pulse_respects_limit() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let vp = vault.to_str().unwrap();
+
+        for i in 0..5 {
+            fs::write(
+                vault.join(format!("note{}.md", i)),
+                format!("# Note {}\n", i),
+            )
+            .unwrap();
+            git_commit(vp, &format!("Add note {}", i)).unwrap();
+        }
+
+        let pulse = get_vault_pulse(vp, 3, 0).unwrap();
+        assert_eq!(pulse.len(), 3);
+    }
+
+    #[test]
+    fn test_get_vault_pulse_modified_and_deleted() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let vp = vault.to_str().unwrap();
+
+        fs::write(vault.join("note.md"), "# Note\n").unwrap();
+        git_commit(vp, "Add note").unwrap();
+
+        fs::write(vault.join("note.md"), "# Updated\n").unwrap();
+        git_commit(vp, "Update note").unwrap();
+
+        let pulse = get_vault_pulse(vp, 30, 0).unwrap();
+        assert_eq!(pulse[0].message, "Update note");
+        assert_eq!(pulse[0].files[0].status, "modified");
+        assert_eq!(pulse[0].modified, 1);
+    }
+
+    #[test]
+    fn test_get_vault_pulse_github_url() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let vp = vault.to_str().unwrap();
+
+        fs::write(vault.join("note.md"), "# Note\n").unwrap();
+        git_commit(vp, "Add note").unwrap();
+
+        Command::new("git")
+            .args([
+                "remote",
+                "add",
+                "origin",
+                "https://github.com/owner/repo.git",
+            ])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        let pulse = get_vault_pulse(vp, 30, 0).unwrap();
+        assert!(pulse[0].github_url.is_some());
+        let url = pulse[0].github_url.as_ref().unwrap();
+        assert!(url.starts_with("https://github.com/owner/repo/commit/"));
+    }
+
+    #[test]
+    fn test_get_vault_pulse_no_github_url_without_remote() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let vp = vault.to_str().unwrap();
+
+        fs::write(vault.join("note.md"), "# Note\n").unwrap();
+        git_commit(vp, "Add note").unwrap();
+
+        let pulse = get_vault_pulse(vp, 30, 0).unwrap();
+        assert!(pulse[0].github_url.is_none());
+    }
+
+    #[test]
+    fn test_title_from_path() {
+        assert_eq!(title_from_path("note/my-project.md"), "my project");
+        assert_eq!(title_from_path("simple.md"), "simple");
+        assert_eq!(title_from_path("deep/nested/file.md"), "file");
+    }
+
+    #[test]
+    fn test_parse_pulse_output_basic() {
+        let stdout =
+            "abc123|abc123d|Add notes|2026-03-05T10:00:00+01:00\nA\tnote.md\nM\tproject.md\n";
+        let commits = parse_pulse_output(stdout, &None);
+
+        assert_eq!(commits.len(), 1);
+        assert_eq!(commits[0].message, "Add notes");
+        assert_eq!(commits[0].files.len(), 2);
+        assert_eq!(commits[0].files[0].status, "added");
+        assert_eq!(commits[0].files[1].status, "modified");
+        assert_eq!(commits[0].added, 1);
+        assert_eq!(commits[0].modified, 1);
+        assert!(commits[0].github_url.is_none());
+    }
+
+    #[test]
+    fn test_parse_pulse_output_with_github() {
+        let stdout = "abc123|abc123d|Msg|2026-03-05T10:00:00+01:00\nA\tnote.md\n";
+        let base = Some("https://github.com/o/r".to_string());
+        let commits = parse_pulse_output(stdout, &base);
+
+        assert_eq!(
+            commits[0].github_url.as_deref(),
+            Some("https://github.com/o/r/commit/abc123")
+        );
+    }
+
+    #[test]
+    fn test_parse_pulse_output_multiple_commits() {
+        let stdout = "aaa|aaa1234|First|2026-03-05T10:00:00+01:00\nA\ta.md\n\nbbb|bbb1234|Second|2026-03-04T10:00:00+01:00\nM\tb.md\nD\tc.md\n";
+        let commits = parse_pulse_output(stdout, &None);
+
+        assert_eq!(commits.len(), 2);
+        assert_eq!(commits[0].message, "First");
+        assert_eq!(commits[1].message, "Second");
+        assert_eq!(commits[1].files.len(), 2);
+        assert_eq!(commits[1].deleted, 1);
+    }
+
+    #[test]
+    fn test_get_last_commit_info_with_commit() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let vp = vault.to_str().unwrap();
+
+        fs::write(vault.join("note.md"), "# Note\n").unwrap();
+        git_commit(vp, "initial").unwrap();
+
+        let info = get_last_commit_info(vp).unwrap();
+        assert!(info.is_some());
+        let info = info.unwrap();
+        assert_eq!(info.short_hash.len(), 7);
+        assert!(info.commit_url.is_none());
+    }
+
+    #[test]
+    fn test_get_last_commit_info_no_commits() {
+        let dir = setup_git_repo();
+        let vp = dir.path().to_str().unwrap();
+
+        let info = get_last_commit_info(vp).unwrap();
+        assert!(info.is_none());
+    }
+
+    #[test]
+    fn test_get_last_commit_info_with_github_remote() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let vp = vault.to_str().unwrap();
+
+        fs::write(vault.join("note.md"), "# Note\n").unwrap();
+        git_commit(vp, "initial").unwrap();
+
+        Command::new("git")
+            .args([
+                "remote",
+                "add",
+                "origin",
+                "https://github.com/lucaong/laputa-vault.git",
+            ])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        let info = get_last_commit_info(vp).unwrap().unwrap();
+        assert!(info.commit_url.is_some());
+        let url = info.commit_url.unwrap();
+        assert!(url.starts_with("https://github.com/lucaong/laputa-vault/commit/"));
+    }
+}

src-tauri/src/git/remote.rs

@@ -0,0 +1,410 @@
+use serde::{Deserialize, Serialize};
+use std::path::Path;
+use std::process::Command;
+
+use super::conflict::get_conflict_files;
+
+#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
+pub struct GitPullResult {
+    pub status: String, // "up_to_date" | "updated" | "conflict" | "no_remote" | "error"
+    pub message: String,
+    #[serde(rename = "updatedFiles")]
+    pub updated_files: Vec<String>,
+    #[serde(rename = "conflictFiles")]
+    pub conflict_files: Vec<String>,
+}
+
+/// Check whether the vault repo has at least one remote configured.
+pub fn has_remote(vault_path: &str) -> Result<bool, String> {
+    let vault = Path::new(vault_path);
+    let output = Command::new("git")
+        .args(["remote"])
+        .current_dir(vault)
+        .output()
+        .map_err(|e| format!("Failed to run git remote: {}", e))?;
+
+    Ok(!String::from_utf8_lossy(&output.stdout).trim().is_empty())
+}
+
+/// Pull latest changes from remote. Uses --no-rebase to merge.
+/// Returns a structured result with status and affected files.
+pub fn git_pull(vault_path: &str) -> Result<GitPullResult, String> {
+    let vault = Path::new(vault_path);
+
+    if !has_remote(vault_path)? {
+        return Ok(GitPullResult {
+            status: "no_remote".to_string(),
+            message: "No remote configured".to_string(),
+            updated_files: vec![],
+            conflict_files: vec![],
+        });
+    }
+
+    let output = Command::new("git")
+        .args(["pull", "--no-rebase"])
+        .current_dir(vault)
+        .output()
+        .map_err(|e| format!("Failed to run git pull: {}", e))?;
+
+    let stdout = String::from_utf8_lossy(&output.stdout).to_string();
+    let stderr = String::from_utf8_lossy(&output.stderr).to_string();
+
+    if output.status.success() {
+        if stdout.contains("Already up to date") || stdout.contains("Already up-to-date") {
+            return Ok(GitPullResult {
+                status: "up_to_date".to_string(),
+                message: "Already up to date".to_string(),
+                updated_files: vec![],
+                conflict_files: vec![],
+            });
+        }
+        let updated = parse_updated_files(&stdout);
+        return Ok(GitPullResult {
+            status: "updated".to_string(),
+            message: format!("{} file(s) updated", updated.len()),
+            updated_files: updated,
+            conflict_files: vec![],
+        });
+    }
+
+    // Check for merge conflicts
+    let conflicts = get_conflict_files(vault_path).unwrap_or_default();
+    if !conflicts.is_empty() {
+        return Ok(GitPullResult {
+            status: "conflict".to_string(),
+            message: format!("Merge conflict in {} file(s)", conflicts.len()),
+            updated_files: vec![],
+            conflict_files: conflicts,
+        });
+    }
+
+    // Network error or other failure — report as error
+    let detail = if stderr.trim().is_empty() {
+        stdout.trim().to_string()
+    } else {
+        stderr.trim().to_string()
+    };
+    Ok(GitPullResult {
+        status: "error".to_string(),
+        message: detail,
+        updated_files: vec![],
+        conflict_files: vec![],
+    })
+}
+
+/// Parse `git pull` output to extract updated file paths.
+fn parse_updated_files(stdout: &str) -> Vec<String> {
+    stdout
+        .lines()
+        .filter_map(|line| {
+            let trimmed = line.trim();
+            // Lines like " path/to/file.md | 5 ++-" in diffstat
+            if trimmed.contains('|') {
+                let path = trimmed.split('|').next()?.trim();
+                if !path.is_empty() {
+                    return Some(path.to_string());
+                }
+            }
+            None
+        })
+        .collect()
+}
+
+#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
+pub struct GitPushResult {
+    pub status: String, // "ok" | "rejected" | "auth_error" | "network_error" | "error"
+    pub message: String,
+}
+
+/// Classify a git push stderr message into a user-friendly status and message.
+pub fn classify_push_error(stderr: &str) -> GitPushResult {
+    let lower = stderr.to_lowercase();
+
+    if lower.contains("non-fast-forward")
+        || lower.contains("[rejected]")
+        || lower.contains("fetch first")
+        || lower.contains("failed to push some refs")
+            && (lower.contains("updates were rejected") || lower.contains("non-fast-forward"))
+    {
+        return GitPushResult {
+            status: "rejected".to_string(),
+            message: "Push rejected: remote has new commits. Pull first, then push.".to_string(),
+        };
+    }
+
+    if lower.contains("authentication failed")
+        || lower.contains("could not read username")
+        || lower.contains("permission denied")
+        || lower.contains("403")
+        || lower.contains("invalid credentials")
+    {
+        return GitPushResult {
+            status: "auth_error".to_string(),
+            message: "Push failed: authentication error. Check your credentials.".to_string(),
+        };
+    }
+
+    if lower.contains("could not resolve host")
+        || lower.contains("unable to access")
+        || lower.contains("connection refused")
+        || lower.contains("network is unreachable")
+        || lower.contains("timed out")
+    {
+        return GitPushResult {
+            status: "network_error".to_string(),
+            message: "Push failed: network error. Check your connection and try again.".to_string(),
+        };
+    }
+
+    // Fallback: extract the hint line if present, otherwise use the full stderr
+    let hint_line = stderr
+        .lines()
+        .find(|l| l.trim_start().starts_with("hint:"))
+        .map(|l| l.trim_start().strip_prefix("hint:").unwrap_or(l).trim())
+        .unwrap_or("")
+        .to_string();
+
+    let detail = if hint_line.is_empty() {
+        stderr.trim().to_string()
+    } else {
+        hint_line
+    };
+
+    GitPushResult {
+        status: "error".to_string(),
+        message: format!("Push failed: {detail}"),
+    }
+}
+
+/// Push to remote.
+pub fn git_push(vault_path: &str) -> Result<GitPushResult, String> {
+    let vault = Path::new(vault_path);
+
+    let output = Command::new("git")
+        .args(["push"])
+        .current_dir(vault)
+        .output()
+        .map_err(|e| format!("Failed to run git push: {}", e))?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        return Ok(classify_push_error(&stderr));
+    }
+
+    Ok(GitPushResult {
+        status: "ok".to_string(),
+        message: "Pushed to remote".to_string(),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::git::git_commit;
+    use crate::git::tests::{setup_git_repo, setup_remote_pair};
+    use std::fs;
+    use std::process::Command;
+
+    #[test]
+    fn test_has_remote_returns_false_for_local_repo() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let vp = vault.to_str().unwrap();
+
+        assert!(!has_remote(vp).unwrap());
+    }
+
+    #[test]
+    fn test_has_remote_returns_true_when_remote_exists() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let vp = vault.to_str().unwrap();
+
+        Command::new("git")
+            .args(["remote", "add", "origin", "https://example.com/repo.git"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        assert!(has_remote(vp).unwrap());
+    }
+
+    #[test]
+    fn test_git_pull_no_remote_returns_no_remote() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let vp = vault.to_str().unwrap();
+
+        fs::write(vault.join("note.md"), "# Note\n").unwrap();
+        git_commit(vp, "initial").unwrap();
+
+        let result = git_pull(vp).unwrap();
+        assert_eq!(result.status, "no_remote");
+        assert!(result.updated_files.is_empty());
+        assert!(result.conflict_files.is_empty());
+    }
+
+    #[test]
+    fn test_git_pull_up_to_date() {
+        let (_bare, clone_a, _clone_b) = setup_remote_pair();
+        let vp_a = clone_a.path().to_str().unwrap();
+
+        fs::write(clone_a.path().join("note.md"), "# Note\n").unwrap();
+        git_commit(vp_a, "initial").unwrap();
+        git_push(vp_a).unwrap();
+
+        let result = git_pull(vp_a).unwrap();
+        assert_eq!(result.status, "up_to_date");
+    }
+
+    #[test]
+    fn test_git_pull_updated_files() {
+        let (_bare, clone_a, clone_b) = setup_remote_pair();
+        let vp_a = clone_a.path().to_str().unwrap();
+        let vp_b = clone_b.path().to_str().unwrap();
+
+        fs::write(clone_a.path().join("note.md"), "# Note\n").unwrap();
+        git_commit(vp_a, "initial").unwrap();
+        git_push(vp_a).unwrap();
+
+        git_pull(vp_b).unwrap();
+
+        fs::write(clone_a.path().join("note.md"), "# Updated Note\n").unwrap();
+        git_commit(vp_a, "update note").unwrap();
+        git_push(vp_a).unwrap();
+
+        let result = git_pull(vp_b).unwrap();
+        assert_eq!(result.status, "updated");
+        assert!(result.conflict_files.is_empty());
+    }
+
+    #[test]
+    fn test_parse_updated_files_diffstat() {
+        let stdout =
+            " Fast-forward\n note.md | 2 +-\n project/plan.md | 4 ++--\n 2 files changed\n";
+        let files = parse_updated_files(stdout);
+        assert_eq!(files, vec!["note.md", "project/plan.md"]);
+    }
+
+    #[test]
+    fn test_parse_updated_files_empty() {
+        let stdout = "Already up to date.\n";
+        let files = parse_updated_files(stdout);
+        assert!(files.is_empty());
+    }
+
+    #[test]
+    fn test_classify_push_error_non_fast_forward() {
+        let stderr = r#"To github.com:user/repo.git
+ ! [rejected]        main -> main (non-fast-forward)
+error: failed to push some refs to 'github.com:user/repo.git'
+hint: Updates were rejected because the remote contains work that you do not
+hint: have locally."#;
+        let result = classify_push_error(stderr);
+        assert_eq!(result.status, "rejected");
+        assert!(result.message.contains("Pull first"));
+    }
+
+    #[test]
+    fn test_classify_push_error_fetch_first() {
+        let stderr = "error: failed to push some refs\nhint: Updates were rejected because the tip of your current branch is behind\nhint: its remote counterpart. Integrate the remote changes (e.g.\nhint: 'git pull ...') before pushing again.\nhint: See the 'Note about fast-forwards' in 'git push --help' for details.\n ! [rejected]        main -> main (fetch first)\n";
+        let result = classify_push_error(stderr);
+        assert_eq!(result.status, "rejected");
+    }
+
+    #[test]
+    fn test_classify_push_error_auth_failure() {
+        let stderr = "remote: Permission denied to user/repo.git\nfatal: unable to access 'https://github.com/user/repo.git/': The requested URL returned error: 403";
+        let result = classify_push_error(stderr);
+        assert_eq!(result.status, "auth_error");
+        assert!(result.message.contains("authentication"));
+    }
+
+    #[test]
+    fn test_classify_push_error_network() {
+        let stderr = "fatal: unable to access 'https://github.com/user/repo.git/': Could not resolve host: github.com";
+        let result = classify_push_error(stderr);
+        assert_eq!(result.status, "network_error");
+        assert!(result.message.contains("network"));
+    }
+
+    #[test]
+    fn test_classify_push_error_unknown() {
+        let stderr = "error: something unexpected happened\nhint: Try again later";
+        let result = classify_push_error(stderr);
+        assert_eq!(result.status, "error");
+        assert!(result.message.contains("Try again later"));
+    }
+
+    #[test]
+    fn test_classify_push_error_unknown_no_hint() {
+        let stderr = "error: something totally weird";
+        let result = classify_push_error(stderr);
+        assert_eq!(result.status, "error");
+        assert!(result.message.contains("something totally weird"));
+    }
+
+    #[test]
+    fn test_git_push_result_serialization() {
+        let result = GitPushResult {
+            status: "rejected".to_string(),
+            message: "Push rejected".to_string(),
+        };
+        let json = serde_json::to_string(&result).unwrap();
+        assert!(json.contains("\"rejected\""));
+        let parsed: GitPushResult = serde_json::from_str(&json).unwrap();
+        assert_eq!(parsed.status, "rejected");
+    }
+
+    #[test]
+    fn test_git_push_success_returns_ok() {
+        let (_bare, clone_a, _clone_b) = setup_remote_pair();
+        let vp_a = clone_a.path().to_str().unwrap();
+
+        fs::write(clone_a.path().join("note.md"), "# Note\n").unwrap();
+        git_commit(vp_a, "initial").unwrap();
+        let result = git_push(vp_a).unwrap();
+        assert_eq!(result.status, "ok");
+    }
+
+    #[test]
+    fn test_git_push_rejected_returns_rejected() {
+        let (_bare, clone_a, clone_b) = setup_remote_pair();
+        let vp_a = clone_a.path().to_str().unwrap();
+        let vp_b = clone_b.path().to_str().unwrap();
+
+        // Both clones commit and push — second push should be rejected
+        fs::write(clone_a.path().join("note.md"), "# A\n").unwrap();
+        git_commit(vp_a, "from A").unwrap();
+        git_push(vp_a).unwrap();
+
+        git_pull(vp_b).unwrap();
+        fs::write(clone_b.path().join("note.md"), "# B\n").unwrap();
+        git_commit(vp_b, "from B").unwrap();
+        git_push(vp_b).unwrap();
+
+        // Now A has a new commit but hasn't pulled B's changes
+        fs::write(clone_a.path().join("other.md"), "# Other\n").unwrap();
+        git_commit(vp_a, "from A again").unwrap();
+        let result = git_push(vp_a).unwrap();
+        assert_eq!(result.status, "rejected");
+        assert!(result.message.contains("Pull first"));
+    }
+
+    #[test]
+    fn test_git_pull_result_serialization() {
+        let result = GitPullResult {
+            status: "updated".to_string(),
+            message: "2 file(s) updated".to_string(),
+            updated_files: vec!["note.md".to_string()],
+            conflict_files: vec![],
+        };
+        let json = serde_json::to_string(&result).unwrap();
+        assert!(json.contains("\"updatedFiles\""));
+        assert!(json.contains("\"conflictFiles\""));
+
+        let parsed: GitPullResult = serde_json::from_str(&json).unwrap();
+        assert_eq!(parsed.status, "updated");
+        assert_eq!(parsed.updated_files.len(), 1);
+    }
+}

src-tauri/src/git/status.rs

@@ -0,0 +1,175 @@
+use serde::Serialize;
+use std::path::Path;
+use std::process::Command;
+
+#[derive(Debug, Serialize, Clone)]
+pub struct ModifiedFile {
+    pub path: String,
+    #[serde(rename = "relativePath")]
+    pub relative_path: String,
+    pub status: String,
+}
+
+/// Get list of modified/added/deleted files in the vault (uncommitted changes).
+pub fn get_modified_files(vault_path: &str) -> Result<Vec<ModifiedFile>, String> {
+    let vault = Path::new(vault_path);
+
+    let output = Command::new("git")
+        .args(["status", "--porcelain", "--untracked-files=all"])
+        .current_dir(vault)
+        .output()
+        .map_err(|e| format!("Failed to run git status: {}", e))?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        return Err(format!("git status failed: {}", stderr));
+    }
+
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let files = stdout
+        .lines()
+        .filter(|line| !line.is_empty())
+        .filter_map(|line| {
+            if line.len() < 4 {
+                return None;
+            }
+            let status_code = &line[..2];
+            let path = line[3..].trim().to_string();
+
+            // Only include markdown files
+            if !path.ends_with(".md") {
+                return None;
+            }
+
+            let status = match status_code.trim() {
+                "M" | "MM" | "AM" => "modified",
+                "A" => "added",
+                "D" => "deleted",
+                "??" => "untracked",
+                "R" | "RM" => "renamed",
+                _ => "modified",
+            };
+
+            let full_path = vault.join(&path).to_string_lossy().to_string();
+
+            Some(ModifiedFile {
+                path: full_path,
+                relative_path: path,
+                status: status.to_string(),
+            })
+        })
+        .collect();
+
+    Ok(files)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::git::git_commit;
+    use crate::git::tests::setup_git_repo;
+    use std::fs;
+    use std::process::Command;
+
+    #[test]
+    fn test_get_modified_files() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+
+        // Create and commit a file
+        fs::write(vault.join("note.md"), "# Note\n").unwrap();
+        Command::new("git")
+            .args(["add", "note.md"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        Command::new("git")
+            .args(["commit", "-m", "Add note"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        // Modify it
+        fs::write(vault.join("note.md"), "# Note\n\nUpdated.").unwrap();
+        // Add an untracked file
+        fs::write(vault.join("new.md"), "# New\n").unwrap();
+
+        let modified = get_modified_files(vault.to_str().unwrap()).unwrap();
+
+        assert!(modified.len() >= 2);
+        let statuses: Vec<&str> = modified.iter().map(|f| f.status.as_str()).collect();
+        assert!(statuses.contains(&"modified"));
+        assert!(statuses.contains(&"untracked"));
+    }
+
+    #[test]
+    fn test_get_modified_files_untracked_in_subdirectory() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+
+        // Create initial commit so git is initialized
+        fs::write(vault.join("init.md"), "# Init\n").unwrap();
+        Command::new("git")
+            .args(["add", "init.md"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        Command::new("git")
+            .args(["commit", "-m", "Initial"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        // Create a new untracked file in a subdirectory (simulates new note creation)
+        fs::create_dir_all(vault.join("note")).unwrap();
+        fs::write(vault.join("note/brand-new.md"), "# Brand New\n").unwrap();
+
+        let modified = get_modified_files(vault.to_str().unwrap()).unwrap();
+
+        assert_eq!(modified.len(), 1);
+        assert_eq!(modified[0].status, "untracked");
+        assert_eq!(modified[0].relative_path, "note/brand-new.md");
+        assert!(
+            modified[0].path.ends_with("/note/brand-new.md"),
+            "Full path should end with relative path: {}",
+            modified[0].path
+        );
+    }
+
+    #[test]
+    fn test_commit_flow_modified_files_then_commit_clears() {
+        let dir = setup_git_repo();
+        let vault = dir.path();
+        let vp = vault.to_str().unwrap();
+
+        // Create and commit initial file
+        fs::write(vault.join("flow.md"), "# Original\n").unwrap();
+        git_commit(vp, "initial").unwrap();
+
+        // Modify the file on disk
+        fs::write(vault.join("flow.md"), "# Modified\n").unwrap();
+
+        // get_modified_files should detect the change
+        let modified = get_modified_files(vp).unwrap();
+        assert!(
+            modified.iter().any(|f| f.relative_path == "flow.md"),
+            "Modified file should be detected after write"
+        );
+
+        // Commit the change
+        let result = git_commit(vp, "update flow").unwrap();
+        assert!(
+            result.contains("1 file changed") || result.contains("flow.md"),
+            "Commit output should reference the changed file: {}",
+            result
+        );
+
+        // After commit, get_modified_files should return empty
+        let after = get_modified_files(vp).unwrap();
+        assert!(
+            after.is_empty(),
+            "No modified files should remain after commit, found: {:?}",
+            after
+        );
+    }
+}

src-tauri/src/github.rs

@@ -1,886 +0,0 @@
-use serde::{Deserialize, Serialize};
-use std::path::Path;
-use std::process::Command;
-
-/// GitHub App client ID for OAuth device flow.
-/// To set up: GitHub Settings → Developer settings → GitHub Apps → New GitHub App.
-/// Enable "Device authorization flow" under Optional features. Webhook can be disabled.
-const GITHUB_CLIENT_ID: &str = "Ov23liwee215tDMs9u4L";
-
-#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
-pub struct GithubRepo {
-    pub name: String,
-    pub full_name: String,
-    pub description: Option<String>,
-    pub private: bool,
-    pub clone_url: String,
-    pub html_url: String,
-    pub updated_at: Option<String>,
-}
-
-/// Lists the authenticated user's GitHub repositories.
-pub async fn github_list_repos(token: &str) -> Result<Vec<GithubRepo>, String> {
-    github_list_repos_with_base(token, "https://api.github.com").await
-}
-
-async fn github_list_repos_with_base(
-    token: &str,
-    api_base: &str,
-) -> Result<Vec<GithubRepo>, String> {
-    let client = reqwest::Client::new();
-    let mut all_repos: Vec<GithubRepo> = Vec::new();
-    let mut page = 1u32;
-
-    loop {
-        let url = format!(
-            "{}/user/repos?per_page=100&sort=updated&page={}",
-            api_base, page
-        );
-        let response = client
-            .get(&url)
-            .header("Authorization", format!("Bearer {}", token))
-            .header("Accept", "application/vnd.github+json")
-            .header("User-Agent", "Laputa-App")
-            .header("X-GitHub-Api-Version", "2022-11-28")
-            .send()
-            .await
-            .map_err(|e| format!("GitHub API request failed: {}", e))?;
-
-        if !response.status().is_success() {
-            let status = response.status();
-            let body = response.text().await.unwrap_or_default();
-            return Err(format!("GitHub API error {}: {}", status, body));
-        }
-
-        let repos: Vec<GithubRepo> = response
-            .json()
-            .await
-            .map_err(|e| format!("Failed to parse GitHub response: {}", e))?;
-
-        let count = repos.len();
-        all_repos.extend(repos);
-
-        if count < 100 {
-            break;
-        }
-        page += 1;
-        if page > 10 {
-            break; // safety limit: 1000 repos max
-        }
-    }
-
-    Ok(all_repos)
-}
-
-/// Creates a new GitHub repository for the authenticated user.
-pub async fn github_create_repo(
-    token: &str,
-    name: &str,
-    private: bool,
-) -> Result<GithubRepo, String> {
-    github_create_repo_with_base(token, name, private, "https://api.github.com").await
-}
-
-async fn github_create_repo_with_base(
-    token: &str,
-    name: &str,
-    private: bool,
-    api_base: &str,
-) -> Result<GithubRepo, String> {
-    let client = reqwest::Client::new();
-    let body = serde_json::json!({
-        "name": name,
-        "private": private,
-        "auto_init": true,
-        "description": "Laputa vault"
-    });
-
-    let response = client
-        .post(format!("{}/user/repos", api_base))
-        .header("Authorization", format!("Bearer {}", token))
-        .header("Accept", "application/vnd.github+json")
-        .header("User-Agent", "Laputa-App")
-        .header("X-GitHub-Api-Version", "2022-11-28")
-        .json(&body)
-        .send()
-        .await
-        .map_err(|e| format!("GitHub API request failed: {}", e))?;
-
-    if !response.status().is_success() {
-        let status = response.status();
-        let body = response.text().await.unwrap_or_default();
-        if status.as_u16() == 422 && body.contains("name already exists") {
-            return Err("Repository name already exists on your account".to_string());
-        }
-        return Err(format!("GitHub API error {}: {}", status, body));
-    }
-
-    response
-        .json::<GithubRepo>()
-        .await
-        .map_err(|e| format!("Failed to parse GitHub response: {}", e))
-}
-
-// --- OAuth Device Flow ---
-
-#[derive(Debug, Serialize, Deserialize, PartialEq)]
-pub struct DeviceFlowStart {
-    pub device_code: String,
-    pub user_code: String,
-    pub verification_uri: String,
-    pub expires_in: u64,
-    pub interval: u64,
-}
-
-#[derive(Debug, Serialize, Deserialize, PartialEq)]
-pub struct DeviceFlowPollResult {
-    pub status: String,
-    pub access_token: Option<String>,
-    pub error: Option<String>,
-}
-
-#[derive(Debug, Serialize, Deserialize, PartialEq)]
-pub struct GitHubUser {
-    pub login: String,
-    pub name: Option<String>,
-    pub avatar_url: String,
-}
-
-/// Starts the GitHub OAuth device flow. Returns device code info for user authorization.
-pub async fn github_device_flow_start() -> Result<DeviceFlowStart, String> {
-    github_device_flow_start_with_base("https://github.com").await
-}
-
-async fn github_device_flow_start_with_base(base_url: &str) -> Result<DeviceFlowStart, String> {
-    let client = reqwest::Client::new();
-    let response = client
-        .post(format!("{}/login/device/code", base_url))
-        .header("Accept", "application/json")
-        .header("User-Agent", "Laputa-App")
-        .form(&[("client_id", GITHUB_CLIENT_ID), ("scope", "repo")])
-        .send()
-        .await
-        .map_err(|e| format!("Device flow request failed: {}", e))?;
-
-    if !response.status().is_success() {
-        let status = response.status();
-        let body = response.text().await.unwrap_or_default();
-        if status.as_u16() == 404 {
-            return Err(
-                "GitHub device flow not available. Ensure a GitHub App is registered with \
-                 'Device authorization flow' enabled (Settings → Developer settings → GitHub Apps)."
-                    .to_string(),
-            );
-        }
-        return Err(format!("Device flow start failed ({}): {}", status, body));
-    }
-
-    response
-        .json::<DeviceFlowStart>()
-        .await
-        .map_err(|e| format!("Failed to parse device flow response: {}", e))
-}
-
-/// Polls GitHub for the device flow authorization result.
-pub async fn github_device_flow_poll(device_code: &str) -> Result<DeviceFlowPollResult, String> {
-    github_device_flow_poll_with_base(device_code, "https://github.com").await
-}
-
-async fn github_device_flow_poll_with_base(
-    device_code: &str,
-    base_url: &str,
-) -> Result<DeviceFlowPollResult, String> {
-    let client = reqwest::Client::new();
-    let response = client
-        .post(format!("{}/login/oauth/access_token", base_url))
-        .header("Accept", "application/json")
-        .header("User-Agent", "Laputa-App")
-        .form(&[
-            ("client_id", GITHUB_CLIENT_ID),
-            ("device_code", device_code),
-            ("grant_type", "urn:ietf:params:oauth:grant-type:device_code"),
-        ])
-        .send()
-        .await
-        .map_err(|e| format!("Device flow poll failed: {}", e))?;
-
-    if !response.status().is_success() {
-        let body = response.text().await.unwrap_or_default();
-        return Err(format!("Device flow poll HTTP error: {}", body));
-    }
-
-    #[derive(Deserialize)]
-    struct RawResponse {
-        access_token: Option<String>,
-        error: Option<String>,
-    }
-
-    let raw: RawResponse = response
-        .json()
-        .await
-        .map_err(|e| format!("Failed to parse poll response: {}", e))?;
-
-    if let Some(token) = raw.access_token {
-        Ok(DeviceFlowPollResult {
-            status: "complete".to_string(),
-            access_token: Some(token),
-            error: None,
-        })
-    } else {
-        let error = raw.error.unwrap_or_else(|| "unknown".to_string());
-        let status = match error.as_str() {
-            "authorization_pending" | "slow_down" => "pending",
-            "expired_token" => "expired",
-            _ => "error",
-        };
-        Ok(DeviceFlowPollResult {
-            status: status.to_string(),
-            access_token: None,
-            error: Some(error),
-        })
-    }
-}
-
-/// Gets the authenticated GitHub user's profile.
-pub async fn github_get_user(token: &str) -> Result<GitHubUser, String> {
-    github_get_user_with_base(token, "https://api.github.com").await
-}
-
-async fn github_get_user_with_base(token: &str, api_base: &str) -> Result<GitHubUser, String> {
-    let client = reqwest::Client::new();
-    let response = client
-        .get(format!("{}/user", api_base))
-        .header("Authorization", format!("Bearer {}", token))
-        .header("Accept", "application/vnd.github+json")
-        .header("User-Agent", "Laputa-App")
-        .header("X-GitHub-Api-Version", "2022-11-28")
-        .send()
-        .await
-        .map_err(|e| format!("GitHub user request failed: {}", e))?;
-
-    if !response.status().is_success() {
-        let status = response.status();
-        let body = response.text().await.unwrap_or_default();
-        return Err(format!("GitHub API error {}: {}", status, body));
-    }
-
-    response
-        .json::<GitHubUser>()
-        .await
-        .map_err(|e| format!("Failed to parse user response: {}", e))
-}
-
-/// Clones a GitHub repo to a local path using HTTPS + token auth.
-pub fn clone_repo(url: &str, token: &str, local_path: &str) -> Result<String, String> {
-    let dest = Path::new(local_path);
-
-    if dest.exists()
-        && dest
-            .read_dir()
-            .map(|mut d| d.next().is_some())
-            .unwrap_or(false)
-    {
-        return Err(format!(
-            "Destination '{}' already exists and is not empty",
-            local_path
-        ));
-    }
-
-    // Inject token into HTTPS URL: https://github.com/... → https://oauth2:TOKEN@github.com/...
-    let auth_url = inject_token_into_url(url, token)?;
-
-    let output = Command::new("git")
-        .args(["clone", "--progress", &auth_url, local_path])
-        .output()
-        .map_err(|e| format!("Failed to run git clone: {}", e))?;
-
-    if !output.status.success() {
-        // Clean up partial clone on failure
-        if dest.exists() {
-            let _ = std::fs::remove_dir_all(dest);
-        }
-        let stderr = String::from_utf8_lossy(&output.stderr);
-        return Err(format!("git clone failed: {}", stderr));
-    }
-
-    // Configure the remote to use token auth for future pushes
-    configure_remote_auth(local_path, url, token)?;
-
-    Ok(format!("Cloned to {}", local_path))
-}
-
-/// Injects an OAuth token into an HTTPS GitHub URL.
-fn inject_token_into_url(url: &str, token: &str) -> Result<String, String> {
-    if let Some(rest) = url.strip_prefix("https://github.com/") {
-        Ok(format!("https://oauth2:{}@github.com/{}", token, rest))
-    } else if let Some(rest) = url.strip_prefix("https://") {
-        // Handle URLs that already have a host
-        Ok(format!("https://oauth2:{}@{}", token, rest))
-    } else {
-        Err(format!(
-            "Unsupported URL format: {}. Use an HTTPS URL.",
-            url
-        ))
-    }
-}
-
-/// Sets up the git remote to use token-based HTTPS auth.
-fn configure_remote_auth(local_path: &str, original_url: &str, token: &str) -> Result<(), String> {
-    let auth_url = inject_token_into_url(original_url, token)?;
-    let vault = Path::new(local_path);
-
-    let output = Command::new("git")
-        .args(["remote", "set-url", "origin", &auth_url])
-        .current_dir(vault)
-        .output()
-        .map_err(|e| format!("Failed to configure remote: {}", e))?;
-
-    if !output.status.success() {
-        let stderr = String::from_utf8_lossy(&output.stderr);
-        return Err(format!("Failed to set remote URL: {}", stderr));
-    }
-
-    // Also configure git user if not set
-    let _ = Command::new("git")
-        .args(["config", "user.email", "laputa@app.local"])
-        .current_dir(vault)
-        .output();
-    let _ = Command::new("git")
-        .args(["config", "user.name", "Laputa App"])
-        .current_dir(vault)
-        .output();
-
-    Ok(())
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use std::process::Command as StdCommand;
-
-    // ── Mock helpers ─────────────────────────────────────────────────────────
-
-    async fn mock_json(
-        method: &str,
-        path: &str,
-        status: usize,
-        body: &str,
-    ) -> (mockito::ServerGuard, mockito::Mock) {
-        let mut server = mockito::Server::new_async().await;
-        let mock = server
-            .mock(method, path)
-            .with_status(status)
-            .with_header("content-type", "application/json")
-            .with_body(body)
-            .create_async()
-            .await;
-        (server, mock)
-    }
-
-    async fn mock_poll(body: &str) -> DeviceFlowPollResult {
-        let (server, mock) = mock_json("POST", "/login/oauth/access_token", 200, body).await;
-        let result = github_device_flow_poll_with_base("dev_code_xyz", &server.url())
-            .await
-            .unwrap();
-        mock.assert_async().await;
-        result
-    }
-
-    async fn mock_user(status: usize, body: &str) -> Result<GitHubUser, String> {
-        let (server, mock) = mock_json("GET", "/user", status, body).await;
-        let result = github_get_user_with_base("token", &server.url()).await;
-        mock.assert_async().await;
-        result
-    }
-
-    fn clone_err_contains(url: &str, expected: &str) {
-        let dir = tempfile::TempDir::new().unwrap();
-        let dest = dir.path().join("dest");
-        let result = clone_repo(url, "token", dest.to_str().unwrap());
-        assert!(result.unwrap_err().contains(expected));
-    }
-
-    async fn mock_list_repos(status: usize, body: &str) -> Result<Vec<GithubRepo>, String> {
-        let (server, mock) = mock_json(
-            "GET",
-            "/user/repos?per_page=100&sort=updated&page=1",
-            status,
-            body,
-        )
-        .await;
-        let result = github_list_repos_with_base("token", &server.url()).await;
-        mock.assert_async().await;
-        result
-    }
-
-    async fn mock_create_repo(status: usize, body: &str) -> Result<GithubRepo, String> {
-        let (server, mock) = mock_json("POST", "/user/repos", status, body).await;
-        let result = github_create_repo_with_base("token", "repo", false, &server.url()).await;
-        mock.assert_async().await;
-        result
-    }
-
-    async fn mock_device_start(status: usize, body: &str) -> Result<DeviceFlowStart, String> {
-        let (server, mock) = mock_json("POST", "/login/device/code", status, body).await;
-        let result = github_device_flow_start_with_base(&server.url()).await;
-        mock.assert_async().await;
-        result
-    }
-
-    // ── Sync/pure logic tests ────────────────────────────────────────────────
-
-    #[test]
-    fn test_inject_token_basic_github_url() {
-        let result = inject_token_into_url("https://github.com/user/repo.git", "gho_abc123");
-        assert_eq!(
-            result.unwrap(),
-            "https://oauth2:gho_abc123@github.com/user/repo.git"
-        );
-    }
-
-    #[test]
-    fn test_inject_token_generic_https_url() {
-        let result = inject_token_into_url("https://gitlab.com/user/repo.git", "glpat-abc");
-        assert_eq!(
-            result.unwrap(),
-            "https://oauth2:glpat-abc@gitlab.com/user/repo.git"
-        );
-    }
-
-    #[test]
-    fn test_inject_token_ssh_url_rejected() {
-        let err = inject_token_into_url("git@github.com:user/repo.git", "token").unwrap_err();
-        assert!(err.contains("Unsupported URL format"));
-    }
-
-    #[test]
-    fn test_inject_token_http_url_rejected() {
-        assert!(inject_token_into_url("http://github.com/user/repo.git", "token").is_err());
-    }
-
-    #[test]
-    fn test_inject_token_github_without_dot_git() {
-        let result = inject_token_into_url("https://github.com/user/repo", "tok");
-        assert_eq!(result.unwrap(), "https://oauth2:tok@github.com/user/repo");
-    }
-
-    #[test]
-    fn test_clone_repo_nonempty_dest() {
-        let dir = tempfile::TempDir::new().unwrap();
-        std::fs::write(dir.path().join("existing.txt"), "data").unwrap();
-
-        let result = clone_repo(
-            "https://github.com/test/repo.git",
-            "token",
-            dir.path().to_str().unwrap(),
-        );
-        assert!(result.unwrap_err().contains("not empty"));
-    }
-
-    #[test]
-    fn test_clone_repo_ssh_url_rejected() {
-        clone_err_contains("git@github.com:user/repo.git", "Unsupported URL format");
-    }
-
-    #[test]
-    fn test_clone_repo_empty_dest_allowed() {
-        let dir = tempfile::TempDir::new().unwrap();
-        let dest = dir.path().join("empty-dir");
-        std::fs::create_dir(&dest).unwrap();
-
-        let result = clone_repo(
-            "https://github.com/nonexistent/repo.git",
-            "token",
-            dest.to_str().unwrap(),
-        );
-        // Should fail at git clone, not at directory check
-        assert!(result.unwrap_err().contains("git clone failed"));
-    }
-
-    #[test]
-    fn test_configure_remote_auth_on_git_repo() {
-        let dir = tempfile::TempDir::new().unwrap();
-        let path = dir.path();
-
-        StdCommand::new("git")
-            .args(["init"])
-            .current_dir(path)
-            .output()
-            .unwrap();
-        StdCommand::new("git")
-            .args([
-                "remote",
-                "add",
-                "origin",
-                "https://github.com/user/repo.git",
-            ])
-            .current_dir(path)
-            .output()
-            .unwrap();
-
-        configure_remote_auth(
-            path.to_str().unwrap(),
-            "https://github.com/user/repo.git",
-            "gho_test123",
-        )
-        .unwrap();
-
-        let output = StdCommand::new("git")
-            .args(["remote", "get-url", "origin"])
-            .current_dir(path)
-            .output()
-            .unwrap();
-        let url = String::from_utf8_lossy(&output.stdout).trim().to_string();
-        assert_eq!(url, "https://oauth2:gho_test123@github.com/user/repo.git");
-    }
-
-    // ── Serialization roundtrip tests ────────────────────────────────────────
-
-    #[test]
-    fn test_github_repo_serialization_roundtrip() {
-        let repo = GithubRepo {
-            name: "test-repo".to_string(),
-            full_name: "user/test-repo".to_string(),
-            description: Some("A test repo".to_string()),
-            private: true,
-            clone_url: "https://github.com/user/test-repo.git".to_string(),
-            html_url: "https://github.com/user/test-repo".to_string(),
-            updated_at: Some("2026-02-20T10:00:00Z".to_string()),
-        };
-        let json = serde_json::to_string(&repo).unwrap();
-        assert_eq!(serde_json::from_str::<GithubRepo>(&json).unwrap(), repo);
-    }
-
-    #[test]
-    fn test_github_repo_deserialization_null_fields() {
-        let json = r#"{"name":"r","full_name":"u/r","description":null,"private":false,"clone_url":"https://x","html_url":"https://y","updated_at":null}"#;
-        let repo: GithubRepo = serde_json::from_str(json).unwrap();
-
-        assert_eq!(repo.name, "r");
-        assert!(!repo.private);
-
-        assert!(repo.description.is_none());
-        assert!(repo.updated_at.is_none());
-    }
-
-    #[test]
-    fn test_device_flow_start_serialization_roundtrip() {
-        let start = DeviceFlowStart {
-            device_code: "dc_123".to_string(),
-            user_code: "ABCD-1234".to_string(),
-            verification_uri: "https://github.com/login/device".to_string(),
-            expires_in: 900,
-            interval: 5,
-        };
-        let json = serde_json::to_string(&start).unwrap();
-        assert_eq!(
-            serde_json::from_str::<DeviceFlowStart>(&json).unwrap(),
-            start
-        );
-    }
-
-    #[test]
-    fn test_device_flow_poll_result_roundtrip() {
-        let complete = DeviceFlowPollResult {
-            status: "complete".to_string(),
-            access_token: Some("gho_abc123".to_string()),
-            error: None,
-        };
-        let json = serde_json::to_string(&complete).unwrap();
-        assert_eq!(
-            serde_json::from_str::<DeviceFlowPollResult>(&json).unwrap(),
-            complete
-        );
-
-        let pending = DeviceFlowPollResult {
-            status: "pending".to_string(),
-            access_token: None,
-            error: Some("authorization_pending".to_string()),
-        };
-        let json = serde_json::to_string(&pending).unwrap();
-        assert_eq!(
-            serde_json::from_str::<DeviceFlowPollResult>(&json).unwrap(),
-            pending
-        );
-    }
-
-    #[test]
-    fn test_github_user_serialization_roundtrip() {
-        let user = GitHubUser {
-            login: "lucaong".to_string(),
-            name: Some("Luca Ongaro".to_string()),
-            avatar_url: "https://avatars.githubusercontent.com/u/123".to_string(),
-        };
-        let json = serde_json::to_string(&user).unwrap();
-        assert_eq!(serde_json::from_str::<GitHubUser>(&json).unwrap(), user);
-    }
-
-    #[test]
-    fn test_github_user_deserialization_null_name() {
-        let user: GitHubUser =
-            serde_json::from_str(r#"{"login":"bot","name":null,"avatar_url":"https://x"}"#)
-                .unwrap();
-        assert_eq!(user.login, "bot");
-        assert!(user.name.is_none());
-    }
-
-    // ── HTTP mock: list repos ────────────────────────────────────────────────
-
-    #[tokio::test]
-    async fn test_github_list_repos_success() {
-        let repos = mock_list_repos(
-            200,
-            r#"[{"name":"my-repo","full_name":"user/my-repo","description":"A repo","private":false,"clone_url":"https://github.com/user/my-repo.git","html_url":"https://github.com/user/my-repo","updated_at":"2026-02-01T00:00:00Z"}]"#,
-        )
-        .await
-        .unwrap();
-
-        assert_eq!(repos.len(), 1);
-        assert_eq!(repos[0].name, "my-repo");
-    }
-
-    #[tokio::test]
-    async fn test_github_list_repos_empty() {
-        let repos = mock_list_repos(200, "[]").await.unwrap();
-        assert!(repos.is_empty());
-    }
-
-    #[tokio::test]
-    async fn test_github_list_repos_auth_error() {
-        let err = mock_list_repos(401, r#"{"message":"Bad credentials"}"#)
-            .await
-            .unwrap_err();
-        assert!(err.contains("GitHub API error"));
-    }
-
-    #[tokio::test]
-    async fn test_github_list_repos_paginated() {
-        let mut server = mockito::Server::new_async().await;
-
-        let repos_page1: Vec<serde_json::Value> = (0..100)
-            .map(|i| {
-                serde_json::json!({
-                    "name": format!("repo-{}", i),
-                    "full_name": format!("user/repo-{}", i),
-                    "description": null,
-                    "private": false,
-                    "clone_url": format!("https://github.com/user/repo-{}.git", i),
-                    "html_url": format!("https://github.com/user/repo-{}", i),
-                    "updated_at": null
-                })
-            })
-            .collect();
-
-        let mock1 = server
-            .mock("GET", "/user/repos?per_page=100&sort=updated&page=1")
-            .with_status(200)
-            .with_header("content-type", "application/json")
-            .with_body(serde_json::to_string(&repos_page1).unwrap())
-            .create_async()
-            .await;
-        let mock2 = server
-            .mock("GET", "/user/repos?per_page=100&sort=updated&page=2")
-            .with_status(200)
-            .with_header("content-type", "application/json")
-            .with_body(
-                r#"[{"name":"extra-repo","full_name":"user/extra-repo","description":null,"private":true,"clone_url":"https://github.com/user/extra-repo.git","html_url":"https://github.com/user/extra-repo","updated_at":null}]"#,
-            )
-            .create_async()
-            .await;
-
-        let repos = github_list_repos_with_base("token", &server.url())
-            .await
-            .unwrap();
-        mock1.assert_async().await;
-        mock2.assert_async().await;
-
-        assert_eq!(repos.len(), 101);
-        assert_eq!(repos[100].name, "extra-repo");
-    }
-
-    // ── HTTP mock: create repo ───────────────────────────────────────────────
-
-    #[tokio::test]
-    async fn test_github_create_repo_success() {
-        let repo = mock_create_repo(
-            201,
-            r#"{"name":"new-repo","full_name":"user/new-repo","description":"Laputa vault","private":true,"clone_url":"https://github.com/user/new-repo.git","html_url":"https://github.com/user/new-repo","updated_at":"2026-02-01T00:00:00Z"}"#,
-        )
-        .await
-        .unwrap();
-
-        assert_eq!(repo.name, "new-repo");
-        assert!(repo.private);
-    }
-
-    #[tokio::test]
-    async fn test_github_create_repo_name_exists() {
-        let err = mock_create_repo(
-            422,
-            r#"{"message":"Validation Failed","errors":[{"resource":"Repository","code":"custom","field":"name","message":"name already exists on this account"}]}"#,
-        )
-        .await
-        .unwrap_err();
-        assert!(err.contains("Repository name already exists"));
-    }
-
-    #[tokio::test]
-    async fn test_github_create_repo_server_error() {
-        let err = mock_create_repo(500, r#"{"message":"Internal Server Error"}"#)
-            .await
-            .unwrap_err();
-        assert!(err.contains("GitHub API error 500"));
-    }
-
-    // ── HTTP mock: device flow start ─────────────────────────────────────────
-
-    #[tokio::test]
-    async fn test_github_device_flow_start_success() {
-        let start = mock_device_start(
-            200,
-            r#"{"device_code":"dev_abc","user_code":"ABCD-1234","verification_uri":"https://github.com/login/device","expires_in":900,"interval":5}"#,
-        )
-        .await
-        .unwrap();
-
-        assert_eq!(
-            start,
-            DeviceFlowStart {
-                device_code: "dev_abc".to_string(),
-                user_code: "ABCD-1234".to_string(),
-                verification_uri: "https://github.com/login/device".to_string(),
-                expires_in: 900,
-                interval: 5,
-            }
-        );
-    }
-
-    #[tokio::test]
-    async fn test_github_device_flow_start_error() {
-        let err = mock_device_start(400, "bad request").await.unwrap_err();
-        assert!(err.contains("Device flow start failed"));
-    }
-
-    #[tokio::test]
-    async fn test_github_device_flow_start_404_gives_clear_message() {
-        let err = mock_device_start(404, r#"{"error":"Not Found"}"#)
-            .await
-            .unwrap_err();
-        assert!(err.contains("device flow not available"));
-        assert!(err.contains("Device authorization flow"));
-    }
-
-    // ── HTTP mock: device flow poll ──────────────────────────────────────────
-
-    #[tokio::test]
-    async fn test_github_device_flow_poll_complete() {
-        let poll =
-            mock_poll(r#"{"access_token":"gho_secret123","token_type":"bearer","scope":"repo"}"#)
-                .await;
-        assert_eq!(
-            poll,
-            DeviceFlowPollResult {
-                status: "complete".to_string(),
-                access_token: Some("gho_secret123".to_string()),
-                error: None,
-            }
-        );
-    }
-
-    #[tokio::test]
-    async fn test_github_device_flow_poll_pending() {
-        let poll = mock_poll(
-            r#"{"error":"authorization_pending","error_description":"The authorization request is still pending."}"#,
-        )
-        .await;
-        assert_eq!(poll.status, "pending");
-        assert_eq!(poll.error, Some("authorization_pending".to_string()));
-    }
-
-    #[tokio::test]
-    async fn test_github_device_flow_poll_slow_down() {
-        let poll = mock_poll(r#"{"error":"slow_down"}"#).await;
-        assert_eq!(poll.status, "pending");
-        assert_eq!(poll.error, Some("slow_down".to_string()));
-    }
-
-    #[tokio::test]
-    async fn test_github_device_flow_poll_expired() {
-        let poll = mock_poll(r#"{"error":"expired_token"}"#).await;
-        assert_eq!(poll.status, "expired");
-        assert_eq!(poll.error, Some("expired_token".to_string()));
-    }
-
-    #[tokio::test]
-    async fn test_github_device_flow_poll_other_error() {
-        let poll = mock_poll(r#"{"error":"access_denied"}"#).await;
-        assert_eq!(poll.status, "error");
-        assert_eq!(poll.error, Some("access_denied".to_string()));
-    }
-
-    #[tokio::test]
-    async fn test_github_device_flow_poll_http_error() {
-        let mut server = mockito::Server::new_async().await;
-        let mock = server
-            .mock("POST", "/login/oauth/access_token")
-            .with_status(503)
-            .with_body("Service Unavailable")
-            .create_async()
-            .await;
-
-        let err = github_device_flow_poll_with_base("dev_code_xyz", &server.url())
-            .await
-            .unwrap_err();
-        mock.assert_async().await;
-        assert!(err.contains("Device flow poll HTTP error"));
-    }
-
-    #[tokio::test]
-    async fn test_github_device_flow_poll_unknown_error() {
-        let poll = mock_poll(r#"{}"#).await;
-        assert_eq!(poll.status, "error");
-        assert_eq!(poll.error, Some("unknown".to_string()));
-    }
-
-    // ── HTTP mock: get user ──────────────────────────────────────────────────
-
-    #[tokio::test]
-    async fn test_github_get_user_success() {
-        let user = mock_user(
-            200,
-            r#"{"login":"lucaong","name":"Luca Ongaro","avatar_url":"https://avatars.githubusercontent.com/u/12345"}"#,
-        )
-        .await
-        .unwrap();
-
-        assert_eq!(
-            user,
-            GitHubUser {
-                login: "lucaong".to_string(),
-                name: Some("Luca Ongaro".to_string()),
-                avatar_url: "https://avatars.githubusercontent.com/u/12345".to_string(),
-            }
-        );
-    }
-
-    #[tokio::test]
-    async fn test_github_get_user_unauthorized() {
-        let err = mock_user(401, r#"{"message":"Bad credentials"}"#)
-            .await
-            .unwrap_err();
-        assert!(err.contains("GitHub API error 401"));
-    }
-
-    #[tokio::test]
-    async fn test_github_get_user_null_name() {
-        let user = mock_user(
-            200,
-            r#"{"login":"bot-account","name":null,"avatar_url":"https://avatars.githubusercontent.com/u/99"}"#,
-        )
-        .await
-        .unwrap();
-
-        assert_eq!(user.login, "bot-account");
-        assert!(user.name.is_none());
-    }
-}

src-tauri/src/github/api.rs

@@ -0,0 +1,326 @@
+use super::{GitHubUser, GithubRepo};
+
+/// Lists the authenticated user's GitHub repositories.
+pub async fn github_list_repos(token: &str) -> Result<Vec<GithubRepo>, String> {
+    github_list_repos_with_base(token, "https://api.github.com").await
+}
+
+async fn github_list_repos_with_base(
+    token: &str,
+    api_base: &str,
+) -> Result<Vec<GithubRepo>, String> {
+    let client = reqwest::Client::new();
+    let mut all_repos: Vec<GithubRepo> = Vec::new();
+    let mut page = 1u32;
+
+    loop {
+        let url = format!(
+            "{}/user/repos?per_page=100&sort=updated&page={}",
+            api_base, page
+        );
+        let response = client
+            .get(&url)
+            .header("Authorization", format!("Bearer {}", token))
+            .header("Accept", "application/vnd.github+json")
+            .header("User-Agent", "Laputa-App")
+            .header("X-GitHub-Api-Version", "2022-11-28")
+            .send()
+            .await
+            .map_err(|e| format!("GitHub API request failed: {}", e))?;
+
+        if !response.status().is_success() {
+            let status = response.status();
+            let body = response.text().await.unwrap_or_default();
+            return Err(format!("GitHub API error {}: {}", status, body));
+        }
+
+        let repos: Vec<GithubRepo> = response
+            .json()
+            .await
+            .map_err(|e| format!("Failed to parse GitHub response: {}", e))?;
+
+        let count = repos.len();
+        all_repos.extend(repos);
+
+        if count < 100 {
+            break;
+        }
+        page += 1;
+        if page > 10 {
+            break; // safety limit: 1000 repos max
+        }
+    }
+
+    Ok(all_repos)
+}
+
+/// Creates a new GitHub repository for the authenticated user.
+pub async fn github_create_repo(
+    token: &str,
+    name: &str,
+    private: bool,
+) -> Result<GithubRepo, String> {
+    github_create_repo_with_base(token, name, private, "https://api.github.com").await
+}
+
+async fn github_create_repo_with_base(
+    token: &str,
+    name: &str,
+    private: bool,
+    api_base: &str,
+) -> Result<GithubRepo, String> {
+    let client = reqwest::Client::new();
+    let body = serde_json::json!({
+        "name": name,
+        "private": private,
+        "auto_init": true,
+        "description": "Laputa vault"
+    });
+
+    let response = client
+        .post(format!("{}/user/repos", api_base))
+        .header("Authorization", format!("Bearer {}", token))
+        .header("Accept", "application/vnd.github+json")
+        .header("User-Agent", "Laputa-App")
+        .header("X-GitHub-Api-Version", "2022-11-28")
+        .json(&body)
+        .send()
+        .await
+        .map_err(|e| format!("GitHub API request failed: {}", e))?;
+
+    if !response.status().is_success() {
+        let status = response.status();
+        let body = response.text().await.unwrap_or_default();
+        if status.as_u16() == 422 && body.contains("name already exists") {
+            return Err("Repository name already exists on your account".to_string());
+        }
+        return Err(format!("GitHub API error {}: {}", status, body));
+    }
+
+    response
+        .json::<GithubRepo>()
+        .await
+        .map_err(|e| format!("Failed to parse GitHub response: {}", e))
+}
+
+/// Gets the authenticated GitHub user's profile.
+pub async fn github_get_user(token: &str) -> Result<GitHubUser, String> {
+    github_get_user_with_base(token, "https://api.github.com").await
+}
+
+async fn github_get_user_with_base(token: &str, api_base: &str) -> Result<GitHubUser, String> {
+    let client = reqwest::Client::new();
+    let response = client
+        .get(format!("{}/user", api_base))
+        .header("Authorization", format!("Bearer {}", token))
+        .header("Accept", "application/vnd.github+json")
+        .header("User-Agent", "Laputa-App")
+        .header("X-GitHub-Api-Version", "2022-11-28")
+        .send()
+        .await
+        .map_err(|e| format!("GitHub user request failed: {}", e))?;
+
+    if !response.status().is_success() {
+        let status = response.status();
+        let body = response.text().await.unwrap_or_default();
+        return Err(format!("GitHub API error {}: {}", status, body));
+    }
+
+    response
+        .json::<GitHubUser>()
+        .await
+        .map_err(|e| format!("Failed to parse user response: {}", e))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    async fn mock_json(
+        method: &str,
+        path: &str,
+        status: usize,
+        body: &str,
+    ) -> (mockito::ServerGuard, mockito::Mock) {
+        let mut server = mockito::Server::new_async().await;
+        let mock = server
+            .mock(method, path)
+            .with_status(status)
+            .with_header("content-type", "application/json")
+            .with_body(body)
+            .create_async()
+            .await;
+        (server, mock)
+    }
+
+    async fn mock_list_repos(status: usize, body: &str) -> Result<Vec<GithubRepo>, String> {
+        let (server, mock) = mock_json(
+            "GET",
+            "/user/repos?per_page=100&sort=updated&page=1",
+            status,
+            body,
+        )
+        .await;
+        let result = github_list_repos_with_base("token", &server.url()).await;
+        mock.assert_async().await;
+        result
+    }
+
+    async fn mock_create_repo(status: usize, body: &str) -> Result<GithubRepo, String> {
+        let (server, mock) = mock_json("POST", "/user/repos", status, body).await;
+        let result = github_create_repo_with_base("token", "repo", false, &server.url()).await;
+        mock.assert_async().await;
+        result
+    }
+
+    async fn mock_user(status: usize, body: &str) -> Result<GitHubUser, String> {
+        let (server, mock) = mock_json("GET", "/user", status, body).await;
+        let result = github_get_user_with_base("token", &server.url()).await;
+        mock.assert_async().await;
+        result
+    }
+
+    #[tokio::test]
+    async fn test_github_list_repos_success() {
+        let repos = mock_list_repos(
+            200,
+            r#"[{"name":"my-repo","full_name":"user/my-repo","description":"A repo","private":false,"clone_url":"https://github.com/user/my-repo.git","html_url":"https://github.com/user/my-repo","updated_at":"2026-02-01T00:00:00Z"}]"#,
+        )
+        .await
+        .unwrap();
+
+        assert_eq!(repos.len(), 1);
+        assert_eq!(repos[0].name, "my-repo");
+    }
+
+    #[tokio::test]
+    async fn test_github_list_repos_empty() {
+        let repos = mock_list_repos(200, "[]").await.unwrap();
+        assert!(repos.is_empty());
+    }
+
+    #[tokio::test]
+    async fn test_github_list_repos_auth_error() {
+        let err = mock_list_repos(401, r#"{"message":"Bad credentials"}"#)
+            .await
+            .unwrap_err();
+        assert!(err.contains("GitHub API error"));
+    }
+
+    #[tokio::test]
+    async fn test_github_list_repos_paginated() {
+        let mut server = mockito::Server::new_async().await;
+
+        let repos_page1: Vec<serde_json::Value> = (0..100)
+            .map(|i| {
+                serde_json::json!({
+                    "name": format!("repo-{}", i),
+                    "full_name": format!("user/repo-{}", i),
+                    "description": null,
+                    "private": false,
+                    "clone_url": format!("https://github.com/user/repo-{}.git", i),
+                    "html_url": format!("https://github.com/user/repo-{}", i),
+                    "updated_at": null
+                })
+            })
+            .collect();
+
+        let mock1 = server
+            .mock("GET", "/user/repos?per_page=100&sort=updated&page=1")
+            .with_status(200)
+            .with_header("content-type", "application/json")
+            .with_body(serde_json::to_string(&repos_page1).unwrap())
+            .create_async()
+            .await;
+        let mock2 = server
+            .mock("GET", "/user/repos?per_page=100&sort=updated&page=2")
+            .with_status(200)
+            .with_header("content-type", "application/json")
+            .with_body(
+                r#"[{"name":"extra-repo","full_name":"user/extra-repo","description":null,"private":true,"clone_url":"https://github.com/user/extra-repo.git","html_url":"https://github.com/user/extra-repo","updated_at":null}]"#,
+            )
+            .create_async()
+            .await;
+
+        let repos = github_list_repos_with_base("token", &server.url())
+            .await
+            .unwrap();
+        mock1.assert_async().await;
+        mock2.assert_async().await;
+
+        assert_eq!(repos.len(), 101);
+        assert_eq!(repos[100].name, "extra-repo");
+    }
+
+    #[tokio::test]
+    async fn test_github_create_repo_success() {
+        let repo = mock_create_repo(
+            201,
+            r#"{"name":"new-repo","full_name":"user/new-repo","description":"Laputa vault","private":true,"clone_url":"https://github.com/user/new-repo.git","html_url":"https://github.com/user/new-repo","updated_at":"2026-02-01T00:00:00Z"}"#,
+        )
+        .await
+        .unwrap();
+
+        assert_eq!(repo.name, "new-repo");
+        assert!(repo.private);
+    }
+
+    #[tokio::test]
+    async fn test_github_create_repo_name_exists() {
+        let err = mock_create_repo(
+            422,
+            r#"{"message":"Validation Failed","errors":[{"resource":"Repository","code":"custom","field":"name","message":"name already exists on this account"}]}"#,
+        )
+        .await
+        .unwrap_err();
+        assert!(err.contains("Repository name already exists"));
+    }
+
+    #[tokio::test]
+    async fn test_github_create_repo_server_error() {
+        let err = mock_create_repo(500, r#"{"message":"Internal Server Error"}"#)
+            .await
+            .unwrap_err();
+        assert!(err.contains("GitHub API error 500"));
+    }
+
+    #[tokio::test]
+    async fn test_github_get_user_success() {
+        let user = mock_user(
+            200,
+            r#"{"login":"lucaong","name":"Luca Ongaro","avatar_url":"https://avatars.githubusercontent.com/u/12345"}"#,
+        )
+        .await
+        .unwrap();
+
+        assert_eq!(
+            user,
+            GitHubUser {
+                login: "lucaong".to_string(),
+                name: Some("Luca Ongaro".to_string()),
+                avatar_url: "https://avatars.githubusercontent.com/u/12345".to_string(),
+            }
+        );
+    }
+
+    #[tokio::test]
+    async fn test_github_get_user_unauthorized() {
+        let err = mock_user(401, r#"{"message":"Bad credentials"}"#)
+            .await
+            .unwrap_err();
+        assert!(err.contains("GitHub API error 401"));
+    }
+
+    #[tokio::test]
+    async fn test_github_get_user_null_name() {
+        let user = mock_user(
+            200,
+            r#"{"login":"bot-account","name":null,"avatar_url":"https://avatars.githubusercontent.com/u/99"}"#,
+        )
+        .await
+        .unwrap();
+
+        assert_eq!(user.login, "bot-account");
+        assert!(user.name.is_none());
+    }
+}

src-tauri/src/github/auth.rs

@@ -0,0 +1,242 @@
+use serde::Deserialize;
+
+use super::{DeviceFlowPollResult, DeviceFlowStart, GITHUB_CLIENT_ID};
+
+/// Starts the GitHub OAuth device flow. Returns device code info for user authorization.
+pub async fn github_device_flow_start() -> Result<DeviceFlowStart, String> {
+    github_device_flow_start_with_base("https://github.com").await
+}
+
+async fn github_device_flow_start_with_base(base_url: &str) -> Result<DeviceFlowStart, String> {
+    let client = reqwest::Client::new();
+    let response = client
+        .post(format!("{}/login/device/code", base_url))
+        .header("Accept", "application/json")
+        .header("User-Agent", "Laputa-App")
+        .form(&[("client_id", GITHUB_CLIENT_ID), ("scope", "repo")])
+        .send()
+        .await
+        .map_err(|e| format!("Device flow request failed: {}", e))?;
+
+    if !response.status().is_success() {
+        let status = response.status();
+        let body = response.text().await.unwrap_or_default();
+        if status.as_u16() == 404 {
+            return Err(
+                "GitHub device flow not available. Ensure a GitHub App is registered with \
+                 'Device authorization flow' enabled (Settings → Developer settings → GitHub Apps)."
+                    .to_string(),
+            );
+        }
+        return Err(format!("Device flow start failed ({}): {}", status, body));
+    }
+
+    response
+        .json::<DeviceFlowStart>()
+        .await
+        .map_err(|e| format!("Failed to parse device flow response: {}", e))
+}
+
+/// Polls GitHub for the device flow authorization result.
+pub async fn github_device_flow_poll(device_code: &str) -> Result<DeviceFlowPollResult, String> {
+    github_device_flow_poll_with_base(device_code, "https://github.com").await
+}
+
+async fn github_device_flow_poll_with_base(
+    device_code: &str,
+    base_url: &str,
+) -> Result<DeviceFlowPollResult, String> {
+    let client = reqwest::Client::new();
+    let response = client
+        .post(format!("{}/login/oauth/access_token", base_url))
+        .header("Accept", "application/json")
+        .header("User-Agent", "Laputa-App")
+        .form(&[
+            ("client_id", GITHUB_CLIENT_ID),
+            ("device_code", device_code),
+            ("grant_type", "urn:ietf:params:oauth:grant-type:device_code"),
+        ])
+        .send()
+        .await
+        .map_err(|e| format!("Device flow poll failed: {}", e))?;
+
+    if !response.status().is_success() {
+        let body = response.text().await.unwrap_or_default();
+        return Err(format!("Device flow poll HTTP error: {}", body));
+    }
+
+    #[derive(Deserialize)]
+    struct RawResponse {
+        access_token: Option<String>,
+        error: Option<String>,
+    }
+
+    let raw: RawResponse = response
+        .json()
+        .await
+        .map_err(|e| format!("Failed to parse poll response: {}", e))?;
+
+    if let Some(token) = raw.access_token {
+        Ok(DeviceFlowPollResult {
+            status: "complete".to_string(),
+            access_token: Some(token),
+            error: None,
+        })
+    } else {
+        let error = raw.error.unwrap_or_else(|| "unknown".to_string());
+        let status = match error.as_str() {
+            "authorization_pending" | "slow_down" => "pending",
+            "expired_token" => "expired",
+            _ => "error",
+        };
+        Ok(DeviceFlowPollResult {
+            status: status.to_string(),
+            access_token: None,
+            error: Some(error),
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    async fn mock_json(
+        method: &str,
+        path: &str,
+        status: usize,
+        body: &str,
+    ) -> (mockito::ServerGuard, mockito::Mock) {
+        let mut server = mockito::Server::new_async().await;
+        let mock = server
+            .mock(method, path)
+            .with_status(status)
+            .with_header("content-type", "application/json")
+            .with_body(body)
+            .create_async()
+            .await;
+        (server, mock)
+    }
+
+    async fn mock_device_start(status: usize, body: &str) -> Result<DeviceFlowStart, String> {
+        let (server, mock) = mock_json("POST", "/login/device/code", status, body).await;
+        let result = github_device_flow_start_with_base(&server.url()).await;
+        mock.assert_async().await;
+        result
+    }
+
+    async fn mock_poll(body: &str) -> DeviceFlowPollResult {
+        let (server, mock) = mock_json("POST", "/login/oauth/access_token", 200, body).await;
+        let result = github_device_flow_poll_with_base("dev_code_xyz", &server.url())
+            .await
+            .unwrap();
+        mock.assert_async().await;
+        result
+    }
+
+    #[tokio::test]
+    async fn test_github_device_flow_start_success() {
+        let start = mock_device_start(
+            200,
+            r#"{"device_code":"dev_abc","user_code":"ABCD-1234","verification_uri":"https://github.com/login/device","expires_in":900,"interval":5}"#,
+        )
+        .await
+        .unwrap();
+
+        assert_eq!(
+            start,
+            DeviceFlowStart {
+                device_code: "dev_abc".to_string(),
+                user_code: "ABCD-1234".to_string(),
+                verification_uri: "https://github.com/login/device".to_string(),
+                expires_in: 900,
+                interval: 5,
+            }
+        );
+    }
+
+    #[tokio::test]
+    async fn test_github_device_flow_start_error() {
+        let err = mock_device_start(400, "bad request").await.unwrap_err();
+        assert!(err.contains("Device flow start failed"));
+    }
+
+    #[tokio::test]
+    async fn test_github_device_flow_start_404_gives_clear_message() {
+        let err = mock_device_start(404, r#"{"error":"Not Found"}"#)
+            .await
+            .unwrap_err();
+        assert!(err.contains("device flow not available"));
+        assert!(err.contains("Device authorization flow"));
+    }
+
+    #[tokio::test]
+    async fn test_github_device_flow_poll_complete() {
+        let poll =
+            mock_poll(r#"{"access_token":"gho_secret123","token_type":"bearer","scope":"repo"}"#)
+                .await;
+        assert_eq!(
+            poll,
+            DeviceFlowPollResult {
+                status: "complete".to_string(),
+                access_token: Some("gho_secret123".to_string()),
+                error: None,
+            }
+        );
+    }
+
+    #[tokio::test]
+    async fn test_github_device_flow_poll_pending() {
+        let poll = mock_poll(
+            r#"{"error":"authorization_pending","error_description":"The authorization request is still pending."}"#,
+        )
+        .await;
+        assert_eq!(poll.status, "pending");
+        assert_eq!(poll.error, Some("authorization_pending".to_string()));
+    }
+
+    #[tokio::test]
+    async fn test_github_device_flow_poll_slow_down() {
+        let poll = mock_poll(r#"{"error":"slow_down"}"#).await;
+        assert_eq!(poll.status, "pending");
+        assert_eq!(poll.error, Some("slow_down".to_string()));
+    }
+
+    #[tokio::test]
+    async fn test_github_device_flow_poll_expired() {
+        let poll = mock_poll(r#"{"error":"expired_token"}"#).await;
+        assert_eq!(poll.status, "expired");
+        assert_eq!(poll.error, Some("expired_token".to_string()));
+    }
+
+    #[tokio::test]
+    async fn test_github_device_flow_poll_other_error() {
+        let poll = mock_poll(r#"{"error":"access_denied"}"#).await;
+        assert_eq!(poll.status, "error");
+        assert_eq!(poll.error, Some("access_denied".to_string()));
+    }
+
+    #[tokio::test]
+    async fn test_github_device_flow_poll_http_error() {
+        let mut server = mockito::Server::new_async().await;
+        let mock = server
+            .mock("POST", "/login/oauth/access_token")
+            .with_status(503)
+            .with_body("Service Unavailable")
+            .create_async()
+            .await;
+
+        let err = github_device_flow_poll_with_base("dev_code_xyz", &server.url())
+            .await
+            .unwrap_err();
+        mock.assert_async().await;
+        assert!(err.contains("Device flow poll HTTP error"));
+    }
+
+    #[tokio::test]
+    async fn test_github_device_flow_poll_unknown_error() {
+        let poll = mock_poll(r#"{}"#).await;
+        assert_eq!(poll.status, "error");
+        assert_eq!(poll.error, Some("unknown".to_string()));
+    }
+}

src-tauri/src/github/clone.rs

@@ -0,0 +1,203 @@
+use std::path::Path;
+use std::process::Command;
+
+/// Clones a GitHub repo to a local path using HTTPS + token auth.
+pub fn clone_repo(url: &str, token: &str, local_path: &str) -> Result<String, String> {
+    let dest = Path::new(local_path);
+
+    if dest.exists()
+        && dest
+            .read_dir()
+            .map(|mut d| d.next().is_some())
+            .unwrap_or(false)
+    {
+        return Err(format!(
+            "Destination '{}' already exists and is not empty",
+            local_path
+        ));
+    }
+
+    // Inject token into HTTPS URL: https://github.com/... → https://oauth2:TOKEN@github.com/...
+    let auth_url = inject_token_into_url(url, token)?;
+
+    let output = Command::new("git")
+        .args(["clone", "--progress", &auth_url, local_path])
+        .output()
+        .map_err(|e| format!("Failed to run git clone: {}", e))?;
+
+    if !output.status.success() {
+        // Clean up partial clone on failure
+        if dest.exists() {
+            let _ = std::fs::remove_dir_all(dest);
+        }
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        return Err(format!("git clone failed: {}", stderr));
+    }
+
+    // Configure the remote to use token auth for future pushes
+    configure_remote_auth(local_path, url, token)?;
+
+    Ok(format!("Cloned to {}", local_path))
+}
+
+/// Injects an OAuth token into an HTTPS GitHub URL.
+fn inject_token_into_url(url: &str, token: &str) -> Result<String, String> {
+    if let Some(rest) = url.strip_prefix("https://github.com/") {
+        Ok(format!("https://oauth2:{}@github.com/{}", token, rest))
+    } else if let Some(rest) = url.strip_prefix("https://") {
+        // Handle URLs that already have a host
+        Ok(format!("https://oauth2:{}@{}", token, rest))
+    } else {
+        Err(format!(
+            "Unsupported URL format: {}. Use an HTTPS URL.",
+            url
+        ))
+    }
+}
+
+/// Sets up the git remote to use token-based HTTPS auth.
+fn configure_remote_auth(local_path: &str, original_url: &str, token: &str) -> Result<(), String> {
+    let auth_url = inject_token_into_url(original_url, token)?;
+    let vault = Path::new(local_path);
+
+    let output = Command::new("git")
+        .args(["remote", "set-url", "origin", &auth_url])
+        .current_dir(vault)
+        .output()
+        .map_err(|e| format!("Failed to configure remote: {}", e))?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        return Err(format!("Failed to set remote URL: {}", stderr));
+    }
+
+    // Also configure git user if not set
+    let _ = Command::new("git")
+        .args(["config", "user.email", "laputa@app.local"])
+        .current_dir(vault)
+        .output();
+    let _ = Command::new("git")
+        .args(["config", "user.name", "Laputa App"])
+        .current_dir(vault)
+        .output();
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::process::Command as StdCommand;
+
+    fn clone_err_contains(url: &str, expected: &str) {
+        let dir = tempfile::TempDir::new().unwrap();
+        let dest = dir.path().join("dest");
+        let result = clone_repo(url, "token", dest.to_str().unwrap());
+        assert!(result.unwrap_err().contains(expected));
+    }
+
+    #[test]
+    fn test_inject_token_basic_github_url() {
+        let result = inject_token_into_url("https://github.com/user/repo.git", "gho_abc123");
+        assert_eq!(
+            result.unwrap(),
+            "https://oauth2:gho_abc123@github.com/user/repo.git"
+        );
+    }
+
+    #[test]
+    fn test_inject_token_generic_https_url() {
+        let result = inject_token_into_url("https://gitlab.com/user/repo.git", "glpat-abc");
+        assert_eq!(
+            result.unwrap(),
+            "https://oauth2:glpat-abc@gitlab.com/user/repo.git"
+        );
+    }
+
+    #[test]
+    fn test_inject_token_ssh_url_rejected() {
+        let err = inject_token_into_url("git@github.com:user/repo.git", "token").unwrap_err();
+        assert!(err.contains("Unsupported URL format"));
+    }
+
+    #[test]
+    fn test_inject_token_http_url_rejected() {
+        assert!(inject_token_into_url("http://github.com/user/repo.git", "token").is_err());
+    }
+
+    #[test]
+    fn test_inject_token_github_without_dot_git() {
+        let result = inject_token_into_url("https://github.com/user/repo", "tok");
+        assert_eq!(result.unwrap(), "https://oauth2:tok@github.com/user/repo");
+    }
+
+    #[test]
+    fn test_clone_repo_nonempty_dest() {
+        let dir = tempfile::TempDir::new().unwrap();
+        std::fs::write(dir.path().join("existing.txt"), "data").unwrap();
+
+        let result = clone_repo(
+            "https://github.com/test/repo.git",
+            "token",
+            dir.path().to_str().unwrap(),
+        );
+        assert!(result.unwrap_err().contains("not empty"));
+    }
+
+    #[test]
+    fn test_clone_repo_ssh_url_rejected() {
+        clone_err_contains("git@github.com:user/repo.git", "Unsupported URL format");
+    }
+
+    #[test]
+    fn test_clone_repo_empty_dest_allowed() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let dest = dir.path().join("empty-dir");
+        std::fs::create_dir(&dest).unwrap();
+
+        let result = clone_repo(
+            "https://github.com/nonexistent/repo.git",
+            "token",
+            dest.to_str().unwrap(),
+        );
+        // Should fail at git clone, not at directory check
+        assert!(result.unwrap_err().contains("git clone failed"));
+    }
+
+    #[test]
+    fn test_configure_remote_auth_on_git_repo() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let path = dir.path();
+
+        StdCommand::new("git")
+            .args(["init"])
+            .current_dir(path)
+            .output()
+            .unwrap();
+        StdCommand::new("git")
+            .args([
+                "remote",
+                "add",
+                "origin",
+                "https://github.com/user/repo.git",
+            ])
+            .current_dir(path)
+            .output()
+            .unwrap();
+
+        configure_remote_auth(
+            path.to_str().unwrap(),
+            "https://github.com/user/repo.git",
+            "gho_test123",
+        )
+        .unwrap();
+
+        let output = StdCommand::new("git")
+            .args(["remote", "get-url", "origin"])
+            .current_dir(path)
+            .output()
+            .unwrap();
+        let url = String::from_utf8_lossy(&output.stdout).trim().to_string();
+        assert_eq!(url, "https://oauth2:gho_test123@github.com/user/repo.git");
+    }
+}

src-tauri/src/github/mod.rs

@@ -0,0 +1,139 @@
+mod api;
+mod auth;
+mod clone;
+
+use serde::{Deserialize, Serialize};
+
+pub use api::{github_create_repo, github_get_user, github_list_repos};
+pub use auth::{github_device_flow_poll, github_device_flow_start};
+pub use clone::clone_repo;
+
+/// GitHub App client ID for OAuth device flow.
+/// To set up: GitHub Settings → Developer settings → GitHub Apps → New GitHub App.
+/// Enable "Device authorization flow" under Optional features. Webhook can be disabled.
+const GITHUB_CLIENT_ID: &str = "Ov23liwee215tDMs9u4L";
+
+#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
+pub struct GithubRepo {
+    pub name: String,
+    pub full_name: String,
+    pub description: Option<String>,
+    pub private: bool,
+    pub clone_url: String,
+    pub html_url: String,
+    pub updated_at: Option<String>,
+}
+
+#[derive(Debug, Serialize, Deserialize, PartialEq)]
+pub struct DeviceFlowStart {
+    pub device_code: String,
+    pub user_code: String,
+    pub verification_uri: String,
+    pub expires_in: u64,
+    pub interval: u64,
+}
+
+#[derive(Debug, Serialize, Deserialize, PartialEq)]
+pub struct DeviceFlowPollResult {
+    pub status: String,
+    pub access_token: Option<String>,
+    pub error: Option<String>,
+}
+
+#[derive(Debug, Serialize, Deserialize, PartialEq)]
+pub struct GitHubUser {
+    pub login: String,
+    pub name: Option<String>,
+    pub avatar_url: String,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_github_repo_serialization_roundtrip() {
+        let repo = GithubRepo {
+            name: "test-repo".to_string(),
+            full_name: "user/test-repo".to_string(),
+            description: Some("A test repo".to_string()),
+            private: true,
+            clone_url: "https://github.com/user/test-repo.git".to_string(),
+            html_url: "https://github.com/user/test-repo".to_string(),
+            updated_at: Some("2026-02-20T10:00:00Z".to_string()),
+        };
+        let json = serde_json::to_string(&repo).unwrap();
+        assert_eq!(serde_json::from_str::<GithubRepo>(&json).unwrap(), repo);
+    }
+
+    #[test]
+    fn test_github_repo_deserialization_null_fields() {
+        let json = r#"{"name":"r","full_name":"u/r","description":null,"private":false,"clone_url":"https://x","html_url":"https://y","updated_at":null}"#;
+        let repo: GithubRepo = serde_json::from_str(json).unwrap();
+        assert_eq!(repo.name, "r");
+        assert!(!repo.private);
+        assert!(repo.description.is_none());
+        assert!(repo.updated_at.is_none());
+    }
+
+    #[test]
+    fn test_device_flow_start_serialization_roundtrip() {
+        let start = DeviceFlowStart {
+            device_code: "dc_123".to_string(),
+            user_code: "ABCD-1234".to_string(),
+            verification_uri: "https://github.com/login/device".to_string(),
+            expires_in: 900,
+            interval: 5,
+        };
+        let json = serde_json::to_string(&start).unwrap();
+        assert_eq!(
+            serde_json::from_str::<DeviceFlowStart>(&json).unwrap(),
+            start
+        );
+    }
+
+    #[test]
+    fn test_device_flow_poll_result_roundtrip() {
+        let complete = DeviceFlowPollResult {
+            status: "complete".to_string(),
+            access_token: Some("gho_abc123".to_string()),
+            error: None,
+        };
+        let json = serde_json::to_string(&complete).unwrap();
+        assert_eq!(
+            serde_json::from_str::<DeviceFlowPollResult>(&json).unwrap(),
+            complete
+        );
+
+        let pending = DeviceFlowPollResult {
+            status: "pending".to_string(),
+            access_token: None,
+            error: Some("authorization_pending".to_string()),
+        };
+        let json = serde_json::to_string(&pending).unwrap();
+        assert_eq!(
+            serde_json::from_str::<DeviceFlowPollResult>(&json).unwrap(),
+            pending
+        );
+    }
+
+    #[test]
+    fn test_github_user_serialization_roundtrip() {
+        let user = GitHubUser {
+            login: "lucaong".to_string(),
+            name: Some("Luca Ongaro".to_string()),
+            avatar_url: "https://avatars.githubusercontent.com/u/123".to_string(),
+        };
+        let json = serde_json::to_string(&user).unwrap();
+        assert_eq!(serde_json::from_str::<GitHubUser>(&json).unwrap(), user);
+    }
+
+    #[test]
+    fn test_github_user_deserialization_null_name() {
+        let user: GitHubUser =
+            serde_json::from_str(r#"{"login":"bot","name":null,"avatar_url":"https://x"}"#)
+                .unwrap();
+        assert_eq!(user.login, "bot");
+        assert!(user.name.is_none());
+    }
+}

src-tauri/src/indexing.rs

@@ -1,14 +1,33 @@
-use serde::Serialize;
-use std::path::Path;
+use serde::{Deserialize, Serialize};
+use std::path::{Path, PathBuf};
 use std::process::Command;
 use std::sync::Mutex;
 
-static QMD_PATH_CACHE: Mutex<Option<String>> = Mutex::new(None);
+/// Resolved qmd binary location: path + optional working directory.
+/// The working dir is required for the bundled binary to find its node_modules.
+#[derive(Debug, Clone)]
+pub struct QmdBinary {
+    pub path: String,
+    pub work_dir: Option<PathBuf>,
+}
 
-/// Locate the qmd binary, checking known locations and PATH.
+impl QmdBinary {
+    /// Create a `Command` pre-configured with the correct working directory.
+    pub fn command(&self) -> Command {
+        let mut cmd = Command::new(&self.path);
+        if let Some(ref dir) = self.work_dir {
+            cmd.current_dir(dir);
+        }
+        cmd
+    }
+}
+
+static QMD_CACHE: Mutex<Option<QmdBinary>> = Mutex::new(None);
+
+/// Locate the qmd binary, checking bundled resource first, then known locations.
 /// Caches the result for subsequent calls.
-pub fn find_qmd_binary() -> Option<String> {
-    if let Ok(guard) = QMD_PATH_CACHE.lock() {
+pub fn find_qmd_binary() -> Option<QmdBinary> {
+    if let Ok(guard) = QMD_CACHE.lock() {
         if let Some(ref cached) = *guard {
             return Some(cached.clone());
         }
@@ -16,16 +35,22 @@ pub fn find_qmd_binary() -> Option<String> {
 
     let result = find_qmd_binary_uncached();
 
-    if let Some(ref path) = result {
-        if let Ok(mut guard) = QMD_PATH_CACHE.lock() {
-            *guard = Some(path.clone());
+    if let Some(ref bin) = result {
+        if let Ok(mut guard) = QMD_CACHE.lock() {
+            *guard = Some(bin.clone());
         }
     }
 
     result
 }
 
-fn find_qmd_binary_uncached() -> Option<String> {
+fn find_qmd_binary_uncached() -> Option<QmdBinary> {
+    // 1. Check bundled binary (Tauri resource)
+    if let Some(bin) = find_bundled_qmd() {
+        return Some(bin);
+    }
+
+    // 2. Check known system locations
     let candidates = [
         dirs::home_dir().map(|h| h.join(".bun/bin/qmd").to_string_lossy().to_string()),
         Some("/usr/local/bin/qmd".to_string()),
@@ -33,26 +58,159 @@ fn find_qmd_binary_uncached() -> Option<String> {
     ];
     for candidate in candidates.into_iter().flatten() {
         if Path::new(&candidate).exists() {
-            return Some(candidate);
+            return Some(QmdBinary {
+                path: candidate,
+                work_dir: None,
+            });
         }
     }
-    // Fallback: try PATH
+
+    // 3. Fallback: try PATH
     Command::new("which")
         .arg("qmd")
         .output()
         .ok()
         .and_then(|o| {
             if o.status.success() {
-                Some(String::from_utf8_lossy(&o.stdout).trim().to_string())
+                Some(QmdBinary {
+                    path: String::from_utf8_lossy(&o.stdout).trim().to_string(),
+                    work_dir: None,
+                })
             } else {
                 None
             }
         })
 }
 
-/// Clear the cached qmd path (e.g. after auto-install).
+/// Look for the bundled qmd binary inside the app bundle or dev resources.
+fn find_bundled_qmd() -> Option<QmdBinary> {
+    let exe = std::env::current_exe().ok()?;
+    let exe_dir = exe.parent()?;
+
+    // macOS app bundle: <app>/Contents/MacOS/laputa → <app>/Contents/Resources/qmd/qmd
+    let bundle_dir = exe_dir.parent()?.join("Resources").join("qmd");
+    if let Some(bin) = prepare_bundled_dir(&bundle_dir) {
+        return Some(bin);
+    }
+
+    // Dev mode: use compile-time CARGO_MANIFEST_DIR for reliable path resolution
+    let dev_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("resources")
+        .join("qmd");
+    if let Some(bin) = prepare_bundled_dir(&dev_dir) {
+        return Some(bin);
+    }
+
+    // Dev mode fallback: walk up from exe_dir to find the project root
+    let mut dir = exe_dir.to_path_buf();
+    for _ in 0..6 {
+        let qmd_dir = dir.join("resources").join("qmd");
+        if let Some(bin) = prepare_bundled_dir(&qmd_dir) {
+            return Some(bin);
+        }
+        if !dir.pop() {
+            break;
+        }
+    }
+
+    None
+}
+
+/// Validate a bundled qmd directory and prepare the binary for execution.
+/// Sets execute permissions and removes macOS quarantine attributes.
+fn prepare_bundled_dir(qmd_dir: &Path) -> Option<QmdBinary> {
+    let qmd_path = qmd_dir.join("qmd");
+    if !qmd_path.exists() {
+        return None;
+    }
+
+    ensure_executable(&qmd_path);
+
+    // Remove macOS quarantine attributes that block execution of bundled binaries
+    #[cfg(target_os = "macos")]
+    {
+        let _ = Command::new("xattr")
+            .args(["-rd", "com.apple.quarantine"])
+            .arg(qmd_dir)
+            .output();
+    }
+
+    Some(QmdBinary {
+        path: qmd_path.to_string_lossy().to_string(),
+        work_dir: Some(qmd_dir.to_path_buf()),
+    })
+}
+
+/// Ensure a file has execute permission.
+#[cfg(unix)]
+fn ensure_executable(path: &Path) {
+    use std::os::unix::fs::PermissionsExt;
+    if let Ok(metadata) = path.metadata() {
+        let mode = metadata.permissions().mode();
+        if mode & 0o111 == 0 {
+            let mut perms = metadata.permissions();
+            perms.set_mode(mode | 0o755);
+            let _ = std::fs::set_permissions(path, perms);
+        }
+    }
+}
+
+#[cfg(not(unix))]
+fn ensure_executable(_path: &Path) {}
+
+/// Try to install qmd globally using bun. Returns Ok if installation succeeded.
+pub fn try_auto_install_qmd() -> Result<(), String> {
+    let bun = find_bun().ok_or("bun not found — cannot auto-install qmd")?;
+
+    log::info!("Auto-installing qmd via bun...");
+    let output = Command::new(&bun)
+        .args(["install", "-g", "qmd"])
+        .output()
+        .map_err(|e| format!("Failed to run bun install: {e}"))?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        return Err(format!("bun install -g qmd failed: {stderr}"));
+    }
+
+    // Clear cache so the newly installed binary is discovered
+    clear_qmd_cache();
+    log::info!("qmd auto-install succeeded");
+    Ok(())
+}
+
+/// Locate bun binary for auto-installing qmd.
+fn find_bun() -> Option<PathBuf> {
+    let candidates = [
+        dirs::home_dir().map(|h| h.join(".bun/bin/bun")),
+        Some(PathBuf::from("/opt/homebrew/bin/bun")),
+        Some(PathBuf::from("/usr/local/bin/bun")),
+    ];
+    for candidate in candidates.into_iter().flatten() {
+        if candidate.exists() {
+            return Some(candidate);
+        }
+    }
+
+    // Fallback: try PATH
+    Command::new("which")
+        .arg("bun")
+        .output()
+        .ok()
+        .and_then(|o| {
+            if o.status.success() {
+                Some(PathBuf::from(
+                    String::from_utf8_lossy(&o.stdout).trim().to_string(),
+                ))
+            } else {
+                None
+            }
+        })
+}
+
+/// Clear the cached qmd binary (e.g. after path changes or installation).
 pub fn clear_qmd_cache() {
-    if let Ok(mut guard) = QMD_PATH_CACHE.lock() {
+    if let Ok(mut guard) = QMD_CACHE.lock() {
         *guard = None;
     }
 }
@@ -65,11 +223,73 @@ pub struct IndexStatus {
     pub indexed_count: usize,
     pub embedded_count: usize,
     pub pending_embed: usize,
+    pub last_indexed_commit: Option<String>,
+    pub last_indexed_at: Option<u64>,
+}
+
+// --- Index metadata persistence ---
+
+#[derive(Debug, Serialize, Deserialize, Default)]
+struct IndexMetadata {
+    #[serde(default)]
+    last_indexed_commit: Option<String>,
+    #[serde(default)]
+    last_indexed_at: Option<u64>,
+}
+
+fn index_metadata_path(vault_path: &str) -> PathBuf {
+    Path::new(vault_path).join(".laputa-index.json")
+}
+
+fn load_index_metadata(vault_path: &str) -> IndexMetadata {
+    let path = index_metadata_path(vault_path);
+    std::fs::read_to_string(&path)
+        .ok()
+        .and_then(|s| serde_json::from_str(&s).ok())
+        .unwrap_or_default()
+}
+
+fn save_index_metadata(vault_path: &str, meta: &IndexMetadata) -> Result<(), String> {
+    let path = index_metadata_path(vault_path);
+    let json =
+        serde_json::to_string_pretty(meta).map_err(|e| format!("Failed to serialize: {e}"))?;
+    std::fs::write(&path, json).map_err(|e| format!("Failed to write index metadata: {e}"))
+}
+
+/// Get the current HEAD commit hash for a vault.
+fn get_head_commit(vault_path: &str) -> Option<String> {
+    let output = Command::new("git")
+        .args(["rev-parse", "HEAD"])
+        .current_dir(vault_path)
+        .output()
+        .ok()?;
+    if output.status.success() {
+        Some(String::from_utf8_lossy(&output.stdout).trim().to_string())
+    } else {
+        None
+    }
+}
+
+/// Record the current HEAD as the last indexed commit.
+fn stamp_index_commit(vault_path: &str) {
+    if let Some(commit) = get_head_commit(vault_path) {
+        let now = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_secs())
+            .unwrap_or(0);
+        let meta = IndexMetadata {
+            last_indexed_commit: Some(commit),
+            last_indexed_at: Some(now),
+        };
+        let _ = save_index_metadata(vault_path, &meta);
+    }
 }
 
 /// Check whether the vault has a qmd index and its status.
 pub fn check_index_status(vault_path: &str) -> IndexStatus {
-    let qmd_bin = match find_qmd_binary() {
+    let meta = load_index_metadata(vault_path);
+
+    let qmd = match find_qmd_binary() {
         Some(b) => b,
         None => {
             return IndexStatus {
@@ -79,14 +299,16 @@ pub fn check_index_status(vault_path: &str) -> IndexStatus {
                 indexed_count: 0,
                 embedded_count: 0,
                 pending_embed: 0,
+                last_indexed_commit: meta.last_indexed_commit,
+                last_indexed_at: meta.last_indexed_at,
             }
         }
     };
 
     let vault_name = vault_dir_name(vault_path);
-    let output = Command::new(&qmd_bin).args(["status"]).output();
+    let output = qmd.command().args(["status"]).output();
 
-    match output {
+    let mut status = match output {
         Ok(o) if o.status.success() => {
             let stdout = String::from_utf8_lossy(&o.stdout);
             parse_status_for_vault(&stdout, &vault_name)
@@ -98,8 +320,14 @@ pub fn check_index_status(vault_path: &str) -> IndexStatus {
             indexed_count: 0,
             embedded_count: 0,
             pending_embed: 0,
+            last_indexed_commit: None,
+            last_indexed_at: None,
         },
-    }
+    };
+
+    status.last_indexed_commit = meta.last_indexed_commit;
+    status.last_indexed_at = meta.last_indexed_at;
+    status
 }
 
 fn vault_dir_name(vault_path: &str) -> String {
@@ -165,6 +393,8 @@ fn parse_status_for_vault(status_output: &str, vault_name: &str) -> IndexStatus
         indexed_count,
         embedded_count,
         pending_embed,
+        last_indexed_commit: None,
+        last_indexed_at: None,
     }
 }
 
@@ -182,11 +412,12 @@ fn extract_first_number(s: &str) -> Option<usize> {
 
 /// Ensure a qmd collection exists for this vault. Creates one if missing.
 pub fn ensure_collection(vault_path: &str) -> Result<(), String> {
-    let qmd_bin = find_qmd_binary().ok_or("qmd not installed")?;
+    let qmd = find_qmd_binary().ok_or("qmd not installed")?;
     let vault_name = vault_dir_name(vault_path);
 
     // Check if collection already exists
-    let output = Command::new(&qmd_bin)
+    let output = qmd
+        .command()
         .args(["collection", "list"])
         .output()
         .map_err(|e| format!("Failed to list collections: {e}"))?;
@@ -199,7 +430,7 @@ pub fn ensure_collection(vault_path: &str) -> Result<(), String> {
     }
 
     // Create collection
-    Command::new(&qmd_bin)
+    qmd.command()
         .args([
             "collection",
             "add",
@@ -229,11 +460,13 @@ pub fn run_full_index<F>(vault_path: &str, on_progress: F) -> Result<(), String>
 where
     F: Fn(IndexingProgress),
 {
-    let qmd_bin = find_qmd_binary().ok_or("qmd not installed")?;
+    let qmd = find_qmd_binary().ok_or("qmd not installed")?;
 
     ensure_collection(vault_path)?;
 
-    // Phase 1: update (scan files)
+    let vault_name = vault_dir_name(vault_path);
+
+    // Phase 1: update (scan files) — scoped to this vault's collection only
     on_progress(IndexingProgress {
         phase: "scanning".to_string(),
         current: 0,
@@ -242,8 +475,9 @@ where
         error: None,
     });
 
-    let update_output = Command::new(&qmd_bin)
-        .args(["update"])
+    let update_output = qmd
+        .command()
+        .args(["update", &vault_name])
         .output()
         .map_err(|e| format!("qmd update failed: {e}"))?;
 
@@ -272,7 +506,7 @@ where
         error: None,
     });
 
-    // Phase 2: embed (generate vectors)
+    // Phase 2: embed (generate vectors) — scoped to this vault's collection only
     on_progress(IndexingProgress {
         phase: "embedding".to_string(),
         current: 0,
@@ -281,8 +515,9 @@ where
         error: None,
     });
 
-    let embed_output = Command::new(&qmd_bin)
-        .args(["embed"])
+    let embed_output = qmd
+        .command()
+        .args(["embed", "-c", &vault_name])
         .output()
         .map_err(|e| format!("qmd embed failed: {e}"))?;
 
@@ -290,6 +525,7 @@ where
         let stderr = String::from_utf8_lossy(&embed_output.stderr);
         // Embedding failure is non-fatal — keyword search still works
         log::warn!("qmd embed failed (keyword search still works): {stderr}");
+        stamp_index_commit(vault_path);
         on_progress(IndexingProgress {
             phase: "complete".to_string(),
             current: total,
@@ -300,6 +536,8 @@ where
         return Ok(());
     }
 
+    stamp_index_commit(vault_path);
+
     on_progress(IndexingProgress {
         phase: "complete".to_string(),
         current: total,
@@ -323,11 +561,12 @@ fn parse_indexed_count(update_output: &str) -> usize {
 
 /// Run incremental update for a single file change.
 pub fn run_incremental_update(vault_path: &str) -> Result<(), String> {
-    let qmd_bin = find_qmd_binary().ok_or("qmd not installed")?;
+    let qmd = find_qmd_binary().ok_or("qmd not installed")?;
 
     // Verify collection exists
     let vault_name = vault_dir_name(vault_path);
-    let list_output = Command::new(&qmd_bin)
+    let list_output = qmd
+        .command()
         .args(["collection", "list"])
         .output()
         .map_err(|e| format!("Failed to list collections: {e}"))?;
@@ -340,8 +579,9 @@ pub fn run_incremental_update(vault_path: &str) -> Result<(), String> {
         }
     }
 
-    let output = Command::new(&qmd_bin)
-        .args(["update"])
+    let output = qmd
+        .command()
+        .args(["update", &vault_name])
         .output()
         .map_err(|e| format!("qmd incremental update failed: {e}"))?;
 
@@ -350,61 +590,48 @@ pub fn run_incremental_update(vault_path: &str) -> Result<(), String> {
         return Err(format!("qmd update failed: {stderr}"));
     }
 
+    stamp_index_commit(vault_path);
+
     Ok(())
 }
 
-/// Attempt to auto-install qmd via bun. Returns Ok if successful.
-pub fn auto_install_qmd() -> Result<String, String> {
-    // Find bun
-    let bun = find_bun().ok_or("bun not installed — cannot auto-install qmd")?;
-
-    let output = Command::new(&bun)
-        .args(["install", "-g", "qmd"])
-        .output()
-        .map_err(|e| format!("Failed to install qmd: {e}"))?;
-
-    if !output.status.success() {
-        let stderr = String::from_utf8_lossy(&output.stderr);
-        return Err(format!("qmd installation failed: {stderr}"));
+/// Check if HEAD has advanced past the last indexed commit.
+#[cfg(test)]
+fn needs_reindex_after_sync(vault_path: &str) -> bool {
+    let meta = load_index_metadata(vault_path);
+    let head = get_head_commit(vault_path);
+    match (meta.last_indexed_commit, head) {
+        (Some(last), Some(current)) => last != current,
+        (None, Some(_)) => true,
+        _ => false,
     }
-
-    // Clear cache so find_qmd_binary() re-discovers
-    clear_qmd_cache();
-
-    match find_qmd_binary() {
-        Some(path) => Ok(path),
-        None => Err("qmd installed but binary not found".to_string()),
-    }
-}
-
-fn find_bun() -> Option<String> {
-    let candidates = [
-        dirs::home_dir().map(|h| h.join(".bun/bin/bun").to_string_lossy().to_string()),
-        Some("/opt/homebrew/bin/bun".to_string()),
-        Some("/usr/local/bin/bun".to_string()),
-    ];
-    for candidate in candidates.into_iter().flatten() {
-        if Path::new(&candidate).exists() {
-            return Some(candidate);
-        }
-    }
-    Command::new("which")
-        .arg("bun")
-        .output()
-        .ok()
-        .and_then(|o| {
-            if o.status.success() {
-                Some(String::from_utf8_lossy(&o.stdout).trim().to_string())
-            } else {
-                None
-            }
-        })
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    #[test]
+    fn qmd_binary_command_sets_work_dir() {
+        let qmd = QmdBinary {
+            path: "/bin/echo".to_string(),
+            work_dir: Some(PathBuf::from("/tmp")),
+        };
+        let cmd = qmd.command();
+        let dbg = format!("{:?}", cmd);
+        assert!(dbg.contains("/bin/echo"));
+    }
+
+    #[test]
+    fn qmd_binary_command_no_work_dir() {
+        let qmd = QmdBinary {
+            path: "/bin/echo".to_string(),
+            work_dir: None,
+        };
+        let output = qmd.command().arg("hello").output().unwrap();
+        assert!(output.status.success());
+    }
+
     #[test]
     fn vault_dir_name_extracts_last_segment() {
         assert_eq!(vault_dir_name("/Users/luca/Laputa"), "laputa");
@@ -483,4 +710,205 @@ Collections
         assert_eq!(parse_indexed_count("Indexed 342 files in 1.2s"), 342);
         assert_eq!(parse_indexed_count("No output"), 0);
     }
+
+    #[test]
+    fn ensure_executable_sets_permission() {
+        use std::fs;
+        let dir = tempfile::tempdir().unwrap();
+        let file = dir.path().join("test-bin");
+        fs::write(&file, "#!/bin/sh\necho ok").unwrap();
+
+        // Start with no execute permission
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            fs::set_permissions(&file, fs::Permissions::from_mode(0o644)).unwrap();
+            assert_eq!(fs::metadata(&file).unwrap().permissions().mode() & 0o111, 0);
+
+            ensure_executable(&file);
+            assert_ne!(fs::metadata(&file).unwrap().permissions().mode() & 0o111, 0);
+        }
+    }
+
+    #[test]
+    fn ensure_executable_noop_when_already_executable() {
+        use std::fs;
+        let dir = tempfile::tempdir().unwrap();
+        let file = dir.path().join("test-bin");
+        fs::write(&file, "#!/bin/sh\necho ok").unwrap();
+
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            fs::set_permissions(&file, fs::Permissions::from_mode(0o755)).unwrap();
+            ensure_executable(&file);
+            let mode = fs::metadata(&file).unwrap().permissions().mode();
+            assert_ne!(mode & 0o111, 0);
+        }
+    }
+
+    #[test]
+    fn prepare_bundled_dir_returns_none_for_missing_binary() {
+        let dir = tempfile::tempdir().unwrap();
+        assert!(prepare_bundled_dir(dir.path()).is_none());
+    }
+
+    #[test]
+    fn prepare_bundled_dir_finds_and_prepares_binary() {
+        use std::fs;
+        let dir = tempfile::tempdir().unwrap();
+        let qmd_path = dir.path().join("qmd");
+        fs::write(&qmd_path, "#!/bin/sh\necho ok").unwrap();
+
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            fs::set_permissions(&qmd_path, fs::Permissions::from_mode(0o644)).unwrap();
+        }
+
+        let result = prepare_bundled_dir(dir.path());
+        assert!(result.is_some());
+        let bin = result.unwrap();
+        assert!(bin.path.ends_with("qmd"));
+        assert_eq!(bin.work_dir.unwrap(), dir.path());
+
+        // Verify execute permission was set
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            assert_ne!(
+                fs::metadata(&qmd_path).unwrap().permissions().mode() & 0o111,
+                0
+            );
+        }
+    }
+
+    #[test]
+    fn find_bun_returns_some_if_available() {
+        // This test may succeed or fail depending on the system.
+        // It verifies the function doesn't panic.
+        let _ = find_bun();
+    }
+
+    #[test]
+    fn index_metadata_roundtrip() {
+        let dir = tempfile::tempdir().unwrap();
+        let vault = dir.path().to_str().unwrap();
+
+        // Default when no file exists
+        let meta = load_index_metadata(vault);
+        assert!(meta.last_indexed_commit.is_none());
+        assert!(meta.last_indexed_at.is_none());
+
+        // Write and read back
+        let meta = IndexMetadata {
+            last_indexed_commit: Some("abc123def456".to_string()),
+            last_indexed_at: Some(1709000000),
+        };
+        save_index_metadata(vault, &meta).unwrap();
+
+        let loaded = load_index_metadata(vault);
+        assert_eq!(loaded.last_indexed_commit.as_deref(), Some("abc123def456"));
+        assert_eq!(loaded.last_indexed_at, Some(1709000000));
+    }
+
+    #[test]
+    fn index_metadata_survives_malformed_json() {
+        let dir = tempfile::tempdir().unwrap();
+        let vault = dir.path().to_str().unwrap();
+
+        // Write garbage
+        std::fs::write(dir.path().join(".laputa-index.json"), "not json").unwrap();
+
+        let meta = load_index_metadata(vault);
+        assert!(meta.last_indexed_commit.is_none());
+    }
+
+    #[test]
+    fn needs_reindex_after_sync_no_metadata() {
+        let dir = tempfile::tempdir().unwrap();
+        let vault = dir.path().to_str().unwrap();
+
+        // Init a git repo so get_head_commit works
+        Command::new("git")
+            .args(["init"])
+            .current_dir(dir.path())
+            .output()
+            .unwrap();
+        Command::new("git")
+            .args(["commit", "--allow-empty", "-m", "init"])
+            .current_dir(dir.path())
+            .output()
+            .unwrap();
+
+        // No metadata → needs reindex
+        assert!(needs_reindex_after_sync(vault));
+    }
+
+    #[test]
+    fn needs_reindex_after_sync_same_commit() {
+        let dir = tempfile::tempdir().unwrap();
+        let vault = dir.path().to_str().unwrap();
+
+        Command::new("git")
+            .args(["init"])
+            .current_dir(dir.path())
+            .output()
+            .unwrap();
+        Command::new("git")
+            .args(["commit", "--allow-empty", "-m", "init"])
+            .current_dir(dir.path())
+            .output()
+            .unwrap();
+
+        let head = get_head_commit(vault).unwrap();
+        let meta = IndexMetadata {
+            last_indexed_commit: Some(head),
+            last_indexed_at: Some(1709000000),
+        };
+        save_index_metadata(vault, &meta).unwrap();
+
+        assert!(!needs_reindex_after_sync(vault));
+    }
+
+    #[test]
+    fn needs_reindex_after_sync_different_commit() {
+        let dir = tempfile::tempdir().unwrap();
+        let vault = dir.path().to_str().unwrap();
+
+        Command::new("git")
+            .args(["init"])
+            .current_dir(dir.path())
+            .output()
+            .unwrap();
+        Command::new("git")
+            .args(["commit", "--allow-empty", "-m", "init"])
+            .current_dir(dir.path())
+            .output()
+            .unwrap();
+
+        let meta = IndexMetadata {
+            last_indexed_commit: Some("old_commit_hash".to_string()),
+            last_indexed_at: Some(1709000000),
+        };
+        save_index_metadata(vault, &meta).unwrap();
+
+        assert!(needs_reindex_after_sync(vault));
+    }
+
+    #[test]
+    fn check_index_status_includes_metadata() {
+        let dir = tempfile::tempdir().unwrap();
+        let vault = dir.path().to_str().unwrap();
+
+        let meta = IndexMetadata {
+            last_indexed_commit: Some("abc123".to_string()),
+            last_indexed_at: Some(1709000000),
+        };
+        save_index_metadata(vault, &meta).unwrap();
+
+        let status = check_index_status(vault);
+        assert_eq!(status.last_indexed_commit.as_deref(), Some("abc123"));
+        assert_eq!(status.last_indexed_at, Some(1709000000));
+    }
 }

src-tauri/src/lib.rs

@@ -1,5 +1,6 @@
 pub mod ai_chat;
 pub mod claude_cli;
+mod commands;
 pub mod frontmatter;
 pub mod git;
 pub mod github;
@@ -10,477 +11,14 @@ pub mod search;
 pub mod settings;
 pub mod theme;
 pub mod vault;
+pub mod vault_config;
 pub mod vault_list;
 
-use std::borrow::Cow;
-use std::path::Path;
 use std::process::Child;
 use std::sync::Mutex;
 
-use ai_chat::{AiChatRequest, AiChatResponse};
-use claude_cli::{AgentStreamRequest, ChatStreamRequest, ClaudeCliStatus, ClaudeStreamEvent};
-use frontmatter::FrontmatterValue;
-use git::{GitCommit, GitPullResult, LastCommitInfo, ModifiedFile};
-use github::{DeviceFlowPollResult, DeviceFlowStart, GitHubUser, GithubRepo};
-use indexing::{IndexStatus, IndexingProgress};
-use search::SearchResponse;
-use settings::Settings;
-use theme::{ThemeFile, VaultSettings};
-use vault::{RenameResult, VaultEntry};
-use vault_list::VaultList;
-
-/// Expand a leading `~` or `~/` in a path string to the user's home directory.
-/// Returns the original string unchanged if it doesn't start with `~` or if the
-/// home directory cannot be determined.
-fn expand_tilde(path: &str) -> Cow<'_, str> {
-    if path == "~" {
-        if let Some(home) = dirs::home_dir() {
-            return Cow::Owned(home.to_string_lossy().into_owned());
-        }
-    } else if let Some(rest) = path.strip_prefix("~/") {
-        if let Some(home) = dirs::home_dir() {
-            return Cow::Owned(format!("{}/{}", home.to_string_lossy(), rest));
-        }
-    }
-    Cow::Borrowed(path)
-}
-
-#[tauri::command]
-fn list_vault(path: String) -> Result<Vec<VaultEntry>, String> {
-    let path = expand_tilde(&path);
-    vault::scan_vault_cached(Path::new(path.as_ref()))
-}
-
-#[tauri::command]
-fn get_note_content(path: String) -> Result<String, String> {
-    let path = expand_tilde(&path);
-    vault::get_note_content(Path::new(path.as_ref()))
-}
-
-#[tauri::command]
-fn save_note_content(path: String, content: String) -> Result<(), String> {
-    let path = expand_tilde(&path);
-    vault::save_note_content(&path, &content)
-}
-
-#[tauri::command]
-fn update_frontmatter(
-    path: String,
-    key: String,
-    value: FrontmatterValue,
-) -> Result<String, String> {
-    let path = expand_tilde(&path);
-    frontmatter::update_frontmatter(&path, &key, value)
-}
-
-#[tauri::command]
-fn delete_frontmatter_property(path: String, key: String) -> Result<String, String> {
-    let path = expand_tilde(&path);
-    frontmatter::delete_frontmatter_property(&path, &key)
-}
-
-#[tauri::command]
-fn get_file_history(vault_path: String, path: String) -> Result<Vec<GitCommit>, String> {
-    let vault_path = expand_tilde(&vault_path);
-    let path = expand_tilde(&path);
-    git::get_file_history(&vault_path, &path)
-}
-
-#[tauri::command]
-fn get_modified_files(vault_path: String) -> Result<Vec<ModifiedFile>, String> {
-    let vault_path = expand_tilde(&vault_path);
-    git::get_modified_files(&vault_path)
-}
-
-#[tauri::command]
-fn get_file_diff(vault_path: String, path: String) -> Result<String, String> {
-    let vault_path = expand_tilde(&vault_path);
-    let path = expand_tilde(&path);
-    git::get_file_diff(&vault_path, &path)
-}
-
-#[tauri::command]
-fn get_file_diff_at_commit(
-    vault_path: String,
-    path: String,
-    commit_hash: String,
-) -> Result<String, String> {
-    let vault_path = expand_tilde(&vault_path);
-    let path = expand_tilde(&path);
-    git::get_file_diff_at_commit(&vault_path, &path, &commit_hash)
-}
-
-#[tauri::command]
-fn git_commit(vault_path: String, message: String) -> Result<String, String> {
-    let vault_path = expand_tilde(&vault_path);
-    git::git_commit(&vault_path, &message)
-}
-
-fn parse_build_label(version: &str) -> String {
-    let parts: Vec<&str> = version.split('.').collect();
-    match parts.as_slice() {
-        [_, minor, patch] if minor.len() >= 6 => format!("b{}", patch),
-        [_, _, _] => "dev".to_string(),
-        _ => "b?".to_string(),
-    }
-}
-
-#[tauri::command]
-fn get_build_number(app_handle: tauri::AppHandle) -> String {
-    let version = app_handle.package_info().version.to_string();
-    parse_build_label(&version)
-}
-
-#[tauri::command]
-fn get_last_commit_info(vault_path: String) -> Result<Option<LastCommitInfo>, String> {
-    let vault_path = expand_tilde(&vault_path);
-    git::get_last_commit_info(&vault_path)
-}
-
-#[tauri::command]
-fn git_pull(vault_path: String) -> Result<GitPullResult, String> {
-    let vault_path = expand_tilde(&vault_path);
-    git::git_pull(&vault_path)
-}
-
-#[tauri::command]
-fn git_resolve_conflict(vault_path: String, file: String, strategy: String) -> Result<(), String> {
-    let vault_path = expand_tilde(&vault_path);
-    git::git_resolve_conflict(&vault_path, &file, &strategy)
-}
-
-#[tauri::command]
-fn git_commit_conflict_resolution(vault_path: String) -> Result<String, String> {
-    let vault_path = expand_tilde(&vault_path);
-    git::git_commit_conflict_resolution(&vault_path)
-}
-
-#[tauri::command]
-fn git_push(vault_path: String) -> Result<String, String> {
-    let vault_path = expand_tilde(&vault_path);
-    git::git_push(&vault_path)
-}
-
-#[tauri::command]
-async fn ai_chat(request: AiChatRequest) -> Result<AiChatResponse, String> {
-    ai_chat::send_chat(request).await
-}
-
-#[tauri::command]
-fn check_claude_cli() -> ClaudeCliStatus {
-    claude_cli::check_cli()
-}
-
-#[tauri::command]
-async fn stream_claude_chat(
-    app_handle: tauri::AppHandle,
-    request: ChatStreamRequest,
-) -> Result<String, String> {
-    use tauri::Emitter;
-    tokio::task::spawn_blocking(move || {
-        claude_cli::run_chat_stream(request, |event: ClaudeStreamEvent| {
-            let _ = app_handle.emit("claude-stream", &event);
-        })
-    })
-    .await
-    .map_err(|e| format!("Task failed: {e}"))?
-}
-
-#[tauri::command]
-async fn stream_claude_agent(
-    app_handle: tauri::AppHandle,
-    request: AgentStreamRequest,
-) -> Result<String, String> {
-    use tauri::Emitter;
-    tokio::task::spawn_blocking(move || {
-        claude_cli::run_agent_stream(request, |event: ClaudeStreamEvent| {
-            let _ = app_handle.emit("claude-agent-stream", &event);
-        })
-    })
-    .await
-    .map_err(|e| format!("Task failed: {e}"))?
-}
-
-#[tauri::command]
-fn save_image(vault_path: String, filename: String, data: String) -> Result<String, String> {
-    let vault_path = expand_tilde(&vault_path);
-    vault::save_image(&vault_path, &filename, &data)
-}
-
-#[tauri::command]
-fn copy_image_to_vault(vault_path: String, source_path: String) -> Result<String, String> {
-    let vault_path = expand_tilde(&vault_path);
-    vault::copy_image_to_vault(&vault_path, &source_path)
-}
-
-#[tauri::command]
-fn rename_note(
-    vault_path: String,
-    old_path: String,
-    new_title: String,
-) -> Result<RenameResult, String> {
-    let vault_path = expand_tilde(&vault_path);
-    let old_path = expand_tilde(&old_path);
-    vault::rename_note(&vault_path, &old_path, &new_title)
-}
-
-#[tauri::command]
-fn purge_trash(vault_path: String) -> Result<Vec<String>, String> {
-    let vault_path = expand_tilde(&vault_path);
-    vault::purge_trash(&vault_path)
-}
-
-#[tauri::command]
-fn delete_note(path: String) -> Result<String, String> {
-    let path = expand_tilde(&path);
-    vault::delete_note(&path)
-}
-
-#[tauri::command]
-fn migrate_is_a_to_type(vault_path: String) -> Result<usize, String> {
-    let vault_path = expand_tilde(&vault_path);
-    vault::migrate_is_a_to_type(&vault_path)
-}
-
-#[tauri::command]
-fn create_getting_started_vault(target_path: Option<String>) -> Result<String, String> {
-    let path = match target_path {
-        Some(p) if !p.is_empty() => expand_tilde(&p).into_owned(),
-        _ => vault::default_vault_path()?.to_string_lossy().to_string(),
-    };
-    vault::create_getting_started_vault(&path)
-}
-
-#[tauri::command]
-fn check_vault_exists(path: String) -> bool {
-    let path = expand_tilde(&path);
-    vault::vault_exists(&path)
-}
-
-#[tauri::command]
-fn get_default_vault_path() -> Result<String, String> {
-    vault::default_vault_path().map(|p| p.to_string_lossy().to_string())
-}
-
-#[tauri::command]
-fn batch_archive_notes(paths: Vec<String>) -> Result<usize, String> {
-    let mut count = 0;
-    for path in &paths {
-        let path = expand_tilde(path);
-        frontmatter::update_frontmatter(&path, "Archived", FrontmatterValue::Bool(true))?;
-        count += 1;
-    }
-    Ok(count)
-}
-
-#[tauri::command]
-fn batch_trash_notes(paths: Vec<String>) -> Result<usize, String> {
-    let now = chrono::Utc::now().format("%Y-%m-%dT%H:%M:%SZ").to_string();
-    let mut count = 0;
-    for path in &paths {
-        let path = expand_tilde(path);
-        frontmatter::update_frontmatter(&path, "Trashed", FrontmatterValue::Bool(true))?;
-        frontmatter::update_frontmatter(
-            &path,
-            "Trashed at",
-            FrontmatterValue::String(now.clone()),
-        )?;
-        count += 1;
-    }
-    Ok(count)
-}
-
-#[tauri::command]
-fn update_menu_state(app_handle: tauri::AppHandle, has_active_note: bool) -> Result<(), String> {
-    menu::set_note_items_enabled(&app_handle, has_active_note);
-    Ok(())
-}
-
-#[tauri::command]
-fn get_settings() -> Result<Settings, String> {
-    settings::get_settings()
-}
-
-#[tauri::command]
-fn save_settings(settings: Settings) -> Result<(), String> {
-    settings::save_settings(settings)
-}
-
-#[tauri::command]
-fn load_vault_list() -> Result<VaultList, String> {
-    vault_list::load_vault_list()
-}
-
-#[tauri::command]
-fn save_vault_list(list: VaultList) -> Result<(), String> {
-    vault_list::save_vault_list(&list)
-}
-
-#[tauri::command]
-async fn github_list_repos(token: String) -> Result<Vec<GithubRepo>, String> {
-    github::github_list_repos(&token).await
-}
-
-#[tauri::command]
-async fn github_create_repo(
-    token: String,
-    name: String,
-    private: bool,
-) -> Result<GithubRepo, String> {
-    github::github_create_repo(&token, &name, private).await
-}
-
-#[tauri::command]
-fn clone_repo(url: String, token: String, local_path: String) -> Result<String, String> {
-    let local_path = expand_tilde(&local_path);
-    github::clone_repo(&url, &token, &local_path)
-}
-
-#[tauri::command]
-async fn github_device_flow_start() -> Result<DeviceFlowStart, String> {
-    github::github_device_flow_start().await
-}
-
-#[tauri::command]
-async fn github_device_flow_poll(device_code: String) -> Result<DeviceFlowPollResult, String> {
-    github::github_device_flow_poll(&device_code).await
-}
-
-#[tauri::command]
-async fn github_get_user(token: String) -> Result<GitHubUser, String> {
-    github::github_get_user(&token).await
-}
-
-#[tauri::command]
-async fn search_vault(
-    vault_path: String,
-    query: String,
-    mode: String,
-    limit: Option<usize>,
-) -> Result<SearchResponse, String> {
-    let vault_path = expand_tilde(&vault_path).into_owned();
-    let limit = limit.unwrap_or(20);
-    tokio::task::spawn_blocking(move || search::search_vault(&vault_path, &query, &mode, limit))
-        .await
-        .map_err(|e| format!("Search task failed: {}", e))?
-}
-
-#[tauri::command]
-fn get_index_status(vault_path: String) -> IndexStatus {
-    let vault_path = expand_tilde(&vault_path);
-    indexing::check_index_status(&vault_path)
-}
-
-#[tauri::command]
-async fn start_indexing(app_handle: tauri::AppHandle, vault_path: String) -> Result<(), String> {
-    use tauri::Emitter;
-    let vault_path = expand_tilde(&vault_path).into_owned();
-    tokio::task::spawn_blocking(move || {
-        // Auto-install qmd if not available
-        if indexing::find_qmd_binary().is_none() {
-            let _ = app_handle.emit(
-                "indexing-progress",
-                IndexingProgress {
-                    phase: "installing".to_string(),
-                    current: 0,
-                    total: 0,
-                    done: false,
-                    error: None,
-                },
-            );
-            match indexing::auto_install_qmd() {
-                Ok(_) => log::info!("qmd auto-installed successfully"),
-                Err(e) => {
-                    log::info!("qmd not available (search disabled): {e}");
-                    let _ = app_handle.emit(
-                        "indexing-progress",
-                        IndexingProgress {
-                            phase: "unavailable".to_string(),
-                            current: 0,
-                            total: 0,
-                            done: true,
-                            error: Some(format!("qmd not available: {e}")),
-                        },
-                    );
-                    return Err(e);
-                }
-            }
-        }
-
-        indexing::run_full_index(&vault_path, |progress| {
-            let _ = app_handle.emit("indexing-progress", &progress);
-        })
-    })
-    .await
-    .map_err(|e| format!("Indexing task failed: {e}"))?
-}
-
-#[tauri::command]
-async fn trigger_incremental_index(vault_path: String) -> Result<(), String> {
-    let vault_path = expand_tilde(&vault_path).into_owned();
-    tokio::task::spawn_blocking(move || indexing::run_incremental_update(&vault_path))
-        .await
-        .map_err(|e| format!("Incremental index failed: {e}"))?
-}
-
 struct WsBridgeChild(Mutex<Option<Child>>);
 
-#[tauri::command]
-async fn register_mcp_tools(vault_path: String) -> Result<String, String> {
-    let vault_path = expand_tilde(&vault_path).into_owned();
-    tokio::task::spawn_blocking(move || mcp::register_mcp(&vault_path))
-        .await
-        .map_err(|e| format!("Registration task failed: {e}"))?
-}
-
-#[tauri::command]
-fn list_themes(vault_path: String) -> Result<Vec<ThemeFile>, String> {
-    let vault_path = expand_tilde(&vault_path);
-    theme::list_themes(&vault_path)
-}
-
-#[tauri::command]
-fn get_theme(vault_path: String, theme_id: String) -> Result<ThemeFile, String> {
-    let vault_path = expand_tilde(&vault_path);
-    theme::get_theme(&vault_path, &theme_id)
-}
-
-#[tauri::command]
-fn get_vault_settings(vault_path: String) -> Result<VaultSettings, String> {
-    let vault_path = expand_tilde(&vault_path);
-    theme::get_vault_settings(&vault_path)
-}
-
-#[tauri::command]
-fn save_vault_settings(vault_path: String, settings: VaultSettings) -> Result<(), String> {
-    let vault_path = expand_tilde(&vault_path);
-    theme::save_vault_settings(&vault_path, settings)
-}
-
-#[tauri::command]
-fn set_active_theme(vault_path: String, theme_id: Option<String>) -> Result<(), String> {
-    let vault_path = expand_tilde(&vault_path);
-    theme::set_active_theme(&vault_path, theme_id.as_deref())
-}
-
-#[tauri::command]
-fn create_theme(vault_path: String, source_id: Option<String>) -> Result<String, String> {
-    let vault_path = expand_tilde(&vault_path);
-    theme::create_theme(&vault_path, source_id.as_deref())
-}
-
-#[tauri::command]
-fn create_vault_theme(vault_path: String, name: Option<String>) -> Result<String, String> {
-    let vault_path = expand_tilde(&vault_path);
-    theme::create_vault_theme(&vault_path, name.as_deref())
-}
-
-#[tauri::command]
-fn ensure_vault_themes(vault_path: String) -> Result<(), String> {
-    let vault_path = expand_tilde(&vault_path);
-    theme::ensure_vault_themes(&vault_path)
-}
-
 fn log_startup_result(label: &str, result: Result<usize, String>) {
     match result {
         Ok(n) if n > 0 => log::info!("{}: {} files", label, n),
@@ -506,11 +44,22 @@ fn run_startup_tasks() {
         "Migrated is_a to type on startup",
         vault::migrate_is_a_to_type(vp_str),
     );
+    log_startup_result(
+        "Migrated hidden_sections to visible property",
+        vault_config::migrate_hidden_sections_to_visible(vp_str),
+    );
 
     // Seed _themes/ with built-in JSON themes (legacy) if missing
     theme::seed_default_themes(vp_str);
     // Seed theme/ with built-in vault theme notes if missing
     theme::seed_vault_themes(vp_str);
+    // Seed type/theme.md so the Theme type has an icon in the sidebar
+    let _ = theme::ensure_theme_type_definition(vp_str);
+
+    // Migrate root AGENTS.md → config/agents.md (one-time, idempotent)
+    vault::migrate_agents_md(vp_str);
+    // Seed config/ with default config files if missing
+    vault::seed_config_files(vp_str);
 
     // Register Laputa MCP server in Claude Code and Cursor configs
     match mcp::register_mcp(vp_str) {
@@ -519,61 +68,6 @@ fn run_startup_tasks() {
     }
 }
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn expand_tilde_with_subpath() {
-        let home = dirs::home_dir().unwrap();
-        let result = expand_tilde("~/Documents/vault");
-        assert_eq!(result, format!("{}/Documents/vault", home.display()));
-    }
-
-    #[test]
-    fn expand_tilde_alone() {
-        let home = dirs::home_dir().unwrap();
-        let result = expand_tilde("~");
-        assert_eq!(result, home.to_string_lossy());
-    }
-
-    #[test]
-    fn expand_tilde_noop_for_absolute_path() {
-        let result = expand_tilde("/usr/local/bin");
-        assert_eq!(result, "/usr/local/bin");
-    }
-
-    #[test]
-    fn expand_tilde_noop_for_relative_path() {
-        let result = expand_tilde("some/relative/path");
-        assert_eq!(result, "some/relative/path");
-    }
-
-    #[test]
-    fn expand_tilde_noop_for_tilde_in_middle() {
-        let result = expand_tilde("/home/~user/path");
-        assert_eq!(result, "/home/~user/path");
-    }
-
-    #[test]
-    fn parse_build_label_release_version() {
-        assert_eq!(parse_build_label("0.20260303.281"), "b281");
-        assert_eq!(parse_build_label("0.20251215.42"), "b42");
-    }
-
-    #[test]
-    fn parse_build_label_dev_version() {
-        assert_eq!(parse_build_label("0.1.0"), "dev");
-        assert_eq!(parse_build_label("0.0.0"), "dev");
-    }
-
-    #[test]
-    fn parse_build_label_malformed() {
-        assert_eq!(parse_build_label("invalid"), "b?");
-        assert_eq!(parse_build_label(""), "b?");
-    }
-}
-
 fn spawn_ws_bridge(app: &mut tauri::App) {
     use tauri::Manager;
     let vault_path = dirs::home_dir()
@@ -600,11 +94,6 @@ pub fn run() {
                         .level(log::LevelFilter::Info)
                         .build(),
                 )?;
-                // Open devtools automatically in debug builds
-                // use tauri::Manager;
-                // if let Some(window) = app.get_webview_window("main") {
-                //     window.open_devtools();
-                // }
             }
 
             app.handle().plugin(tauri_plugin_dialog::init())?;
@@ -623,61 +112,69 @@ pub fn run() {
             Ok(())
         })
         .invoke_handler(tauri::generate_handler![
-            list_vault,
-            get_note_content,
-            save_note_content,
-            update_frontmatter,
-            delete_frontmatter_property,
-            rename_note,
-            get_file_history,
-            get_modified_files,
-            get_file_diff,
-            get_file_diff_at_commit,
-            git_commit,
-            get_build_number,
-            get_last_commit_info,
-            git_pull,
-            git_push,
-            git_resolve_conflict,
-            git_commit_conflict_resolution,
-            ai_chat,
-            check_claude_cli,
-            stream_claude_chat,
-            stream_claude_agent,
-            save_image,
-            copy_image_to_vault,
-            purge_trash,
-            delete_note,
-            migrate_is_a_to_type,
-            batch_archive_notes,
-            batch_trash_notes,
-            get_settings,
-            update_menu_state,
-            save_settings,
-            load_vault_list,
-            save_vault_list,
-            github_list_repos,
-            github_create_repo,
-            clone_repo,
-            github_device_flow_start,
-            github_device_flow_poll,
-            github_get_user,
-            search_vault,
-            get_index_status,
-            start_indexing,
-            trigger_incremental_index,
-            create_getting_started_vault,
-            check_vault_exists,
-            get_default_vault_path,
-            register_mcp_tools,
-            list_themes,
-            get_theme,
-            get_vault_settings,
-            save_vault_settings,
-            set_active_theme,
-            create_theme,
-            create_vault_theme,
-            ensure_vault_themes
+            commands::list_vault,
+            commands::get_note_content,
+            commands::save_note_content,
+            commands::update_frontmatter,
+            commands::delete_frontmatter_property,
+            commands::rename_note,
+            commands::get_file_history,
+            commands::get_modified_files,
+            commands::get_file_diff,
+            commands::get_file_diff_at_commit,
+            commands::get_vault_pulse,
+            commands::git_commit,
+            commands::get_build_number,
+            commands::get_last_commit_info,
+            commands::git_pull,
+            commands::git_push,
+            commands::get_conflict_files,
+            commands::get_conflict_mode,
+            commands::git_resolve_conflict,
+            commands::git_commit_conflict_resolution,
+            commands::ai_chat,
+            commands::check_claude_cli,
+            commands::stream_claude_chat,
+            commands::stream_claude_agent,
+            commands::save_image,
+            commands::copy_image_to_vault,
+            commands::purge_trash,
+            commands::delete_note,
+            commands::migrate_is_a_to_type,
+            commands::batch_archive_notes,
+            commands::batch_trash_notes,
+            commands::get_settings,
+            commands::update_menu_state,
+            commands::save_settings,
+            commands::load_vault_list,
+            commands::save_vault_list,
+            commands::github_list_repos,
+            commands::github_create_repo,
+            commands::clone_repo,
+            commands::github_device_flow_start,
+            commands::github_device_flow_poll,
+            commands::github_get_user,
+            commands::search_vault,
+            commands::get_index_status,
+            commands::start_indexing,
+            commands::trigger_incremental_index,
+            commands::create_getting_started_vault,
+            commands::check_vault_exists,
+            commands::get_default_vault_path,
+            commands::register_mcp_tools,
+            commands::check_mcp_status,
+            commands::list_themes,
+            commands::get_theme,
+            commands::get_vault_settings,
+            commands::save_vault_settings,
+            commands::set_active_theme,
+            commands::create_theme,
+            commands::create_vault_theme,
+            commands::ensure_vault_themes,
+            commands::restore_default_themes,
+            commands::repair_vault,
+            commands::get_vault_config,
+            commands::save_vault_config
         ])
         .build(tauri::generate_context!())
         .expect("error while building tauri application")

src-tauri/src/mcp.rs

@@ -1,6 +1,19 @@
+use serde::Serialize;
 use std::path::{Path, PathBuf};
 use std::process::{Child, Command};
 
+/// Status of the MCP server installation.
+#[derive(Debug, Serialize, Clone, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum McpStatus {
+    /// MCP is registered in Claude config and server files exist.
+    Installed,
+    /// MCP server files or config are missing but can be installed.
+    NotInstalled,
+    /// Claude CLI is not installed — must install that first.
+    NoClaudeCli,
+}
+
 /// Find the `node` binary path at runtime.
 pub(crate) fn find_node() -> Result<PathBuf, String> {
     let output = Command::new("which")
@@ -144,6 +157,57 @@ fn upsert_mcp_config(config_path: &Path, entry: &serde_json::Value) -> Result<bo
     Ok(was_update)
 }
 
+/// Check whether the MCP server is properly installed and registered.
+///
+/// Returns `Installed` when the laputa entry exists in `~/.claude/mcp.json`
+/// and the referenced index.js file is present. Returns `NoClaudeCli` when
+/// the Claude CLI binary cannot be found. Otherwise returns `NotInstalled`.
+pub fn check_mcp_status() -> McpStatus {
+    // Check Claude CLI first — no point installing MCP if Claude isn't available
+    if crate::claude_cli::find_claude_binary().is_err() {
+        return McpStatus::NoClaudeCli;
+    }
+
+    let config_path = match dirs::home_dir() {
+        Some(h) => h.join(".claude").join("mcp.json"),
+        None => return McpStatus::NotInstalled,
+    };
+
+    if !config_path.exists() {
+        return McpStatus::NotInstalled;
+    }
+
+    let raw = match std::fs::read_to_string(&config_path) {
+        Ok(r) => r,
+        Err(_) => return McpStatus::NotInstalled,
+    };
+
+    let config: serde_json::Value = match serde_json::from_str(&raw) {
+        Ok(c) => c,
+        Err(_) => return McpStatus::NotInstalled,
+    };
+
+    let entry = &config["mcpServers"]["laputa"];
+    if entry.is_null() {
+        return McpStatus::NotInstalled;
+    }
+
+    // Verify the referenced index.js actually exists on disk
+    if let Some(index_js) = entry["args"]
+        .as_array()
+        .and_then(|a| a.first())
+        .and_then(|v| v.as_str())
+    {
+        if !Path::new(index_js).exists() {
+            return McpStatus::NotInstalled;
+        }
+    } else {
+        return McpStatus::NotInstalled;
+    }
+
+    McpStatus::Installed
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -314,4 +378,29 @@ mod tests {
         // With empty config list, there were no updates, so status should be "registered"
         assert_eq!(status, "registered");
     }
+
+    #[test]
+    fn check_mcp_status_returns_valid_variant() {
+        // On a dev machine with Claude CLI and MCP registered, this should be Installed.
+        // On CI without Claude it might be NoClaudeCli. Either way it must not panic.
+        let status = check_mcp_status();
+        assert!(
+            matches!(
+                status,
+                McpStatus::Installed | McpStatus::NotInstalled | McpStatus::NoClaudeCli
+            ),
+            "unexpected status: {:?}",
+            status
+        );
+    }
+
+    #[test]
+    fn mcp_status_serializes_to_snake_case() {
+        let json = serde_json::to_string(&McpStatus::Installed).unwrap();
+        assert_eq!(json, r#""installed""#);
+        let json = serde_json::to_string(&McpStatus::NotInstalled).unwrap();
+        assert_eq!(json, r#""not_installed""#);
+        let json = serde_json::to_string(&McpStatus::NoClaudeCli).unwrap();
+        assert_eq!(json, r#""no_claude_cli""#);
+    }
 }

src-tauri/src/menu.rs

@@ -5,51 +5,111 @@ use tauri::{
 
 // Custom menu item IDs that emit events to the frontend.
 const APP_SETTINGS: &str = "app-settings";
+const APP_CHECK_FOR_UPDATES: &str = "app-check-for-updates";
+
 const FILE_NEW_NOTE: &str = "file-new-note";
+const FILE_NEW_TYPE: &str = "file-new-type";
 const FILE_DAILY_NOTE: &str = "file-daily-note";
 const FILE_QUICK_OPEN: &str = "file-quick-open";
 const FILE_SAVE: &str = "file-save";
 const FILE_CLOSE_TAB: &str = "file-close-tab";
+
+const EDIT_FIND_IN_VAULT: &str = "edit-find-in-vault";
+const EDIT_TOGGLE_RAW_EDITOR: &str = "edit-toggle-raw-editor";
+const EDIT_TOGGLE_DIFF: &str = "edit-toggle-diff";
+
 const VIEW_EDITOR_ONLY: &str = "view-editor-only";
 const VIEW_EDITOR_LIST: &str = "view-editor-list";
 const VIEW_ALL: &str = "view-all";
-const VIEW_TOGGLE_INSPECTOR: &str = "view-toggle-inspector";
+const VIEW_TOGGLE_PROPERTIES: &str = "view-toggle-properties";
+const VIEW_TOGGLE_AI_CHAT: &str = "view-toggle-ai-chat";
+const VIEW_TOGGLE_BACKLINKS: &str = "view-toggle-backlinks";
 const VIEW_COMMAND_PALETTE: &str = "view-command-palette";
 const VIEW_ZOOM_IN: &str = "view-zoom-in";
 const VIEW_ZOOM_OUT: &str = "view-zoom-out";
 const VIEW_ZOOM_RESET: &str = "view-zoom-reset";
-const NOTE_ARCHIVE: &str = "note-archive";
-const NOTE_TRASH: &str = "note-trash";
-const EDIT_FIND_IN_VAULT: &str = "edit-find-in-vault";
 const VIEW_GO_BACK: &str = "view-go-back";
 const VIEW_GO_FORWARD: &str = "view-go-forward";
-const APP_CHECK_FOR_UPDATES: &str = "app-check-for-updates";
+
+const GO_ALL_NOTES: &str = "go-all-notes";
+const GO_ARCHIVED: &str = "go-archived";
+const GO_TRASH: &str = "go-trash";
+const GO_CHANGES: &str = "go-changes";
+
+const NOTE_ARCHIVE: &str = "note-archive";
+const NOTE_TRASH: &str = "note-trash";
+
+const VAULT_OPEN: &str = "vault-open";
+const VAULT_REMOVE: &str = "vault-remove";
+const VAULT_RESTORE_GETTING_STARTED: &str = "vault-restore-getting-started";
+const VAULT_NEW_THEME: &str = "vault-new-theme";
+const VAULT_RESTORE_DEFAULT_THEMES: &str = "vault-restore-default-themes";
+const VAULT_COMMIT_PUSH: &str = "vault-commit-push";
+const VAULT_RESOLVE_CONFLICTS: &str = "vault-resolve-conflicts";
+const VAULT_VIEW_CHANGES: &str = "vault-view-changes";
+const VAULT_INSTALL_MCP: &str = "vault-install-mcp";
+const VAULT_REINDEX: &str = "vault-reindex";
+const VAULT_REPAIR: &str = "vault-repair";
 
 const CUSTOM_IDS: &[&str] = &[
     APP_SETTINGS,
+    APP_CHECK_FOR_UPDATES,
     FILE_NEW_NOTE,
+    FILE_NEW_TYPE,
     FILE_DAILY_NOTE,
     FILE_QUICK_OPEN,
     FILE_SAVE,
     FILE_CLOSE_TAB,
-    NOTE_ARCHIVE,
-    NOTE_TRASH,
     EDIT_FIND_IN_VAULT,
+    EDIT_TOGGLE_RAW_EDITOR,
+    EDIT_TOGGLE_DIFF,
     VIEW_EDITOR_ONLY,
     VIEW_EDITOR_LIST,
     VIEW_ALL,
-    VIEW_TOGGLE_INSPECTOR,
+    VIEW_TOGGLE_PROPERTIES,
+    VIEW_TOGGLE_AI_CHAT,
+    VIEW_TOGGLE_BACKLINKS,
     VIEW_COMMAND_PALETTE,
     VIEW_ZOOM_IN,
     VIEW_ZOOM_OUT,
     VIEW_ZOOM_RESET,
     VIEW_GO_BACK,
     VIEW_GO_FORWARD,
-    APP_CHECK_FOR_UPDATES,
+    GO_ALL_NOTES,
+    GO_ARCHIVED,
+    GO_TRASH,
+    GO_CHANGES,
+    NOTE_ARCHIVE,
+    NOTE_TRASH,
+    VAULT_OPEN,
+    VAULT_REMOVE,
+    VAULT_RESTORE_GETTING_STARTED,
+    VAULT_NEW_THEME,
+    VAULT_RESTORE_DEFAULT_THEMES,
+    VAULT_COMMIT_PUSH,
+    VAULT_RESOLVE_CONFLICTS,
+    VAULT_VIEW_CHANGES,
+    VAULT_INSTALL_MCP,
+    VAULT_REINDEX,
+    VAULT_REPAIR,
 ];
 
 /// IDs of menu items that should be disabled when no note tab is active.
-const NOTE_DEPENDENT_IDS: &[&str] = &[FILE_SAVE, FILE_CLOSE_TAB, NOTE_ARCHIVE, NOTE_TRASH];
+const NOTE_DEPENDENT_IDS: &[&str] = &[
+    FILE_SAVE,
+    FILE_CLOSE_TAB,
+    NOTE_ARCHIVE,
+    NOTE_TRASH,
+    EDIT_TOGGLE_RAW_EDITOR,
+    EDIT_TOGGLE_DIFF,
+    VIEW_TOGGLE_BACKLINKS,
+];
+
+/// IDs of menu items that depend on having uncommitted changes.
+const GIT_COMMIT_DEPENDENT_IDS: &[&str] = &[VAULT_COMMIT_PUSH];
+
+/// IDs of menu items that depend on having merge conflicts.
+const GIT_CONFLICT_DEPENDENT_IDS: &[&str] = &[VAULT_RESOLVE_CONFLICTS];
 
 type MenuResult = Result<Submenu<tauri::Wry>, Box<dyn std::error::Error>>;
 
@@ -84,6 +144,9 @@ fn build_file_menu(app: &App) -> MenuResult {
         .id(FILE_NEW_NOTE)
         .accelerator("CmdOrCtrl+N")
         .build(app)?;
+    let new_type = MenuItemBuilder::new("New Type")
+        .id(FILE_NEW_TYPE)
+        .build(app)?;
     let daily_note = MenuItemBuilder::new("Open Today's Note")
         .id(FILE_DAILY_NOTE)
         .accelerator("CmdOrCtrl+J")
@@ -100,25 +163,14 @@ fn build_file_menu(app: &App) -> MenuResult {
         .id(FILE_CLOSE_TAB)
         .accelerator("CmdOrCtrl+W")
         .build(app)?;
-    let archive_note = MenuItemBuilder::new("Archive Note")
-        .id(NOTE_ARCHIVE)
-        .accelerator("CmdOrCtrl+E")
-        .build(app)?;
-    let trash_note = MenuItemBuilder::new("Trash Note")
-        .id(NOTE_TRASH)
-        .accelerator("CmdOrCtrl+Backspace")
-        .build(app)?;
 
     Ok(SubmenuBuilder::new(app, "File")
         .item(&new_note)
+        .item(&new_type)
         .item(&daily_note)
         .item(&quick_open)
         .separator()
         .item(&save)
-        .separator()
-        .item(&archive_note)
-        .item(&trash_note)
-        .separator()
         .item(&close_tab)
         .build()?)
 }
@@ -128,6 +180,9 @@ fn build_edit_menu(app: &App) -> MenuResult {
         .id(EDIT_FIND_IN_VAULT)
         .accelerator("CmdOrCtrl+Shift+F")
         .build(app)?;
+    let toggle_diff = MenuItemBuilder::new("Toggle Diff Mode")
+        .id(EDIT_TOGGLE_DIFF)
+        .build(app)?;
 
     Ok(SubmenuBuilder::new(app, "Edit")
         .undo()
@@ -140,6 +195,7 @@ fn build_edit_menu(app: &App) -> MenuResult {
         .select_all()
         .separator()
         .item(&find_in_vault)
+        .item(&toggle_diff)
         .build()?)
 }
 
@@ -156,8 +212,8 @@ fn build_view_menu(app: &App) -> MenuResult {
         .id(VIEW_ALL)
         .accelerator("CmdOrCtrl+3")
         .build(app)?;
-    let toggle_inspector = MenuItemBuilder::new("Toggle Inspector")
-        .id(VIEW_TOGGLE_INSPECTOR)
+    let toggle_properties = MenuItemBuilder::new("Toggle Properties Panel")
+        .id(VIEW_TOGGLE_PROPERTIES)
         .build(app)?;
     let command_palette = MenuItemBuilder::new("Command Palette")
         .id(VIEW_COMMAND_PALETTE)
@@ -175,6 +231,31 @@ fn build_view_menu(app: &App) -> MenuResult {
         .id(VIEW_ZOOM_RESET)
         .accelerator("CmdOrCtrl+0")
         .build(app)?;
+
+    Ok(SubmenuBuilder::new(app, "View")
+        .item(&editor_only)
+        .item(&editor_list)
+        .item(&all_panels)
+        .separator()
+        .item(&toggle_properties)
+        .separator()
+        .item(&zoom_in)
+        .item(&zoom_out)
+        .item(&zoom_reset)
+        .separator()
+        .item(&command_palette)
+        .build()?)
+}
+
+fn build_go_menu(app: &App) -> MenuResult {
+    let all_notes = MenuItemBuilder::new("All Notes")
+        .id(GO_ALL_NOTES)
+        .build(app)?;
+    let archived = MenuItemBuilder::new("Archived")
+        .id(GO_ARCHIVED)
+        .build(app)?;
+    let trash = MenuItemBuilder::new("Trash").id(GO_TRASH).build(app)?;
+    let changes = MenuItemBuilder::new("Changes").id(GO_CHANGES).build(app)?;
     let go_back = MenuItemBuilder::new("Go Back")
         .id(VIEW_GO_BACK)
         .accelerator("CmdOrCtrl+[")
@@ -184,21 +265,99 @@ fn build_view_menu(app: &App) -> MenuResult {
         .accelerator("CmdOrCtrl+]")
         .build(app)?;
 
-    Ok(SubmenuBuilder::new(app, "View")
-        .item(&editor_only)
-        .item(&editor_list)
-        .item(&all_panels)
-        .separator()
-        .item(&toggle_inspector)
+    Ok(SubmenuBuilder::new(app, "Go")
+        .item(&all_notes)
+        .item(&archived)
+        .item(&trash)
+        .item(&changes)
         .separator()
         .item(&go_back)
         .item(&go_forward)
+        .build()?)
+}
+
+fn build_note_menu(app: &App) -> MenuResult {
+    let archive_note = MenuItemBuilder::new("Archive Note")
+        .id(NOTE_ARCHIVE)
+        .accelerator("CmdOrCtrl+E")
+        .build(app)?;
+    let trash_note = MenuItemBuilder::new("Trash Note")
+        .id(NOTE_TRASH)
+        .accelerator("CmdOrCtrl+Backspace")
+        .build(app)?;
+    let toggle_raw_editor = MenuItemBuilder::new("Toggle Raw Editor")
+        .id(EDIT_TOGGLE_RAW_EDITOR)
+        .accelerator("CmdOrCtrl+\\")
+        .build(app)?;
+    let toggle_ai_chat = MenuItemBuilder::new("Toggle AI Chat")
+        .id(VIEW_TOGGLE_AI_CHAT)
+        .accelerator("CmdOrCtrl+I")
+        .build(app)?;
+    let toggle_backlinks = MenuItemBuilder::new("Toggle Backlinks")
+        .id(VIEW_TOGGLE_BACKLINKS)
+        .build(app)?;
+
+    Ok(SubmenuBuilder::new(app, "Note")
+        .item(&archive_note)
+        .item(&trash_note)
         .separator()
-        .item(&zoom_in)
-        .item(&zoom_out)
-        .item(&zoom_reset)
+        .item(&toggle_raw_editor)
+        .item(&toggle_ai_chat)
+        .item(&toggle_backlinks)
+        .build()?)
+}
+
+fn build_vault_menu(app: &App) -> MenuResult {
+    let open_vault = MenuItemBuilder::new("Open Vault…")
+        .id(VAULT_OPEN)
+        .build(app)?;
+    let remove_vault = MenuItemBuilder::new("Remove Vault from List")
+        .id(VAULT_REMOVE)
+        .build(app)?;
+    let restore_getting_started = MenuItemBuilder::new("Restore Getting Started")
+        .id(VAULT_RESTORE_GETTING_STARTED)
+        .build(app)?;
+    let new_theme = MenuItemBuilder::new("New Theme")
+        .id(VAULT_NEW_THEME)
+        .build(app)?;
+    let restore_default_themes = MenuItemBuilder::new("Restore Default Themes")
+        .id(VAULT_RESTORE_DEFAULT_THEMES)
+        .build(app)?;
+    let commit_push = MenuItemBuilder::new("Commit & Push")
+        .id(VAULT_COMMIT_PUSH)
+        .build(app)?;
+    let resolve_conflicts = MenuItemBuilder::new("Resolve Conflicts")
+        .id(VAULT_RESOLVE_CONFLICTS)
+        .enabled(false)
+        .build(app)?;
+    let view_changes = MenuItemBuilder::new("View Pending Changes")
+        .id(VAULT_VIEW_CHANGES)
+        .build(app)?;
+    let install_mcp = MenuItemBuilder::new("Restore MCP Server")
+        .id(VAULT_INSTALL_MCP)
+        .build(app)?;
+    let reindex = MenuItemBuilder::new("Reindex Vault")
+        .id(VAULT_REINDEX)
+        .build(app)?;
+    let repair = MenuItemBuilder::new("Repair Vault")
+        .id(VAULT_REPAIR)
+        .build(app)?;
+
+    Ok(SubmenuBuilder::new(app, "Vault")
+        .item(&open_vault)
+        .item(&remove_vault)
+        .item(&restore_getting_started)
         .separator()
-        .item(&command_palette)
+        .item(&new_theme)
+        .item(&restore_default_themes)
+        .separator()
+        .item(&commit_push)
+        .item(&resolve_conflicts)
+        .item(&view_changes)
+        .separator()
+        .item(&reindex)
+        .item(&repair)
+        .item(&install_mcp)
         .build()?)
 }
 
@@ -216,6 +375,9 @@ pub fn setup_menu(app: &App) -> Result<(), Box<dyn std::error::Error>> {
     let file_menu = build_file_menu(app)?;
     let edit_menu = build_edit_menu(app)?;
     let view_menu = build_view_menu(app)?;
+    let go_menu = build_go_menu(app)?;
+    let note_menu = build_note_menu(app)?;
+    let vault_menu = build_vault_menu(app)?;
     let window_menu = build_window_menu(app)?;
 
     let menu = MenuBuilder::new(app)
@@ -223,6 +385,9 @@ pub fn setup_menu(app: &App) -> Result<(), Box<dyn std::error::Error>> {
         .item(&file_menu)
         .item(&edit_menu)
         .item(&view_menu)
+        .item(&go_menu)
+        .item(&note_menu)
+        .item(&vault_menu)
         .item(&window_menu)
         .build()?;
 
@@ -238,45 +403,78 @@ pub fn setup_menu(app: &App) -> Result<(), Box<dyn std::error::Error>> {
     Ok(())
 }
 
-/// Enable or disable menu items that depend on having an active note tab.
-pub fn set_note_items_enabled(app_handle: &AppHandle, enabled: bool) {
+fn set_items_enabled(app_handle: &AppHandle, ids: &[&str], enabled: bool) {
     let Some(menu) = app_handle.menu() else {
         return;
     };
-    for id in NOTE_DEPENDENT_IDS {
+    for id in ids {
         if let Some(MenuItemKind::MenuItem(mi)) = menu.get(*id) {
             let _ = mi.set_enabled(enabled);
         }
     }
 }
 
+/// Enable or disable menu items that depend on having an active note tab.
+pub fn set_note_items_enabled(app_handle: &AppHandle, enabled: bool) {
+    set_items_enabled(app_handle, NOTE_DEPENDENT_IDS, enabled);
+}
+
+/// Enable or disable menu items that depend on having uncommitted changes.
+pub fn set_git_commit_items_enabled(app_handle: &AppHandle, enabled: bool) {
+    set_items_enabled(app_handle, GIT_COMMIT_DEPENDENT_IDS, enabled);
+}
+
+/// Enable or disable menu items that depend on having merge conflicts.
+pub fn set_git_conflict_items_enabled(app_handle: &AppHandle, enabled: bool) {
+    set_items_enabled(app_handle, GIT_CONFLICT_DEPENDENT_IDS, enabled);
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
     #[test]
-    fn custom_ids_include_all_expected_items() {
+    fn custom_ids_include_all_constants() {
         let expected = [
-            "app-settings",
-            "file-new-note",
-            "file-daily-note",
-            "file-quick-open",
-            "file-save",
-            "file-close-tab",
-            "note-archive",
-            "note-trash",
-            "edit-find-in-vault",
-            "view-editor-only",
-            "view-editor-list",
-            "view-all",
-            "view-toggle-inspector",
-            "view-command-palette",
-            "view-zoom-in",
-            "view-zoom-out",
-            "view-zoom-reset",
-            "view-go-back",
-            "view-go-forward",
-            "app-check-for-updates",
+            APP_SETTINGS,
+            APP_CHECK_FOR_UPDATES,
+            FILE_NEW_NOTE,
+            FILE_NEW_TYPE,
+            FILE_DAILY_NOTE,
+            FILE_QUICK_OPEN,
+            FILE_SAVE,
+            FILE_CLOSE_TAB,
+            EDIT_FIND_IN_VAULT,
+            EDIT_TOGGLE_RAW_EDITOR,
+            EDIT_TOGGLE_DIFF,
+            VIEW_EDITOR_ONLY,
+            VIEW_EDITOR_LIST,
+            VIEW_ALL,
+            VIEW_TOGGLE_PROPERTIES,
+            VIEW_TOGGLE_AI_CHAT,
+            VIEW_TOGGLE_BACKLINKS,
+            VIEW_COMMAND_PALETTE,
+            VIEW_ZOOM_IN,
+            VIEW_ZOOM_OUT,
+            VIEW_ZOOM_RESET,
+            VIEW_GO_BACK,
+            VIEW_GO_FORWARD,
+            GO_ALL_NOTES,
+            GO_ARCHIVED,
+            GO_TRASH,
+            GO_CHANGES,
+            NOTE_ARCHIVE,
+            NOTE_TRASH,
+            VAULT_OPEN,
+            VAULT_REMOVE,
+            VAULT_RESTORE_GETTING_STARTED,
+            VAULT_NEW_THEME,
+            VAULT_RESTORE_DEFAULT_THEMES,
+            VAULT_COMMIT_PUSH,
+            VAULT_RESOLVE_CONFLICTS,
+            VAULT_VIEW_CHANGES,
+            VAULT_INSTALL_MCP,
+            VAULT_REINDEX,
         ];
         for id in &expected {
             assert!(CUSTOM_IDS.contains(id), "missing custom ID: {id}");
@@ -292,4 +490,28 @@ mod tests {
             );
         }
     }
+
+    #[test]
+    fn git_dependent_ids_are_subset_of_custom_ids() {
+        for id in GIT_COMMIT_DEPENDENT_IDS {
+            assert!(
+                CUSTOM_IDS.contains(id),
+                "git-commit-dependent ID {id} not in CUSTOM_IDS"
+            );
+        }
+        for id in GIT_CONFLICT_DEPENDENT_IDS {
+            assert!(
+                CUSTOM_IDS.contains(id),
+                "git-conflict-dependent ID {id} not in CUSTOM_IDS"
+            );
+        }
+    }
+
+    #[test]
+    fn no_duplicate_custom_ids() {
+        let mut seen = std::collections::HashSet::new();
+        for id in CUSTOM_IDS {
+            assert!(seen.insert(id), "duplicate custom ID: {id}");
+        }
+    }
 }

src-tauri/src/search.rs

@@ -2,7 +2,6 @@ use crate::indexing;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::path::Path;
-use std::process::Command;
 use std::sync::Mutex;
 use std::time::Instant;
 
@@ -84,12 +83,12 @@ fn detect_collection_name(vault_path: &str) -> String {
 }
 
 fn detect_collection_name_uncached(vault_path: &str) -> String {
-    let qmd_bin = match indexing::find_qmd_binary() {
+    let qmd = match indexing::find_qmd_binary() {
         Some(b) => b,
         None => return "laputa".to_string(),
     };
 
-    let output = Command::new(&qmd_bin).args(["collection", "list"]).output();
+    let output = qmd.command().args(["collection", "list"]).output();
 
     match output {
         Ok(o) if o.status.success() => {
@@ -125,8 +124,7 @@ pub fn search_vault(
 ) -> Result<SearchResponse, String> {
     let start = Instant::now();
 
-    let qmd_bin = indexing::find_qmd_binary()
-        .ok_or_else(|| "qmd binary not found. Install qmd first.".to_string())?;
+    let qmd = indexing::find_qmd_binary().ok_or_else(|| "qmd binary not found".to_string())?;
 
     let collection = detect_collection_name(vault_path);
 
@@ -137,7 +135,8 @@ pub fn search_vault(
     };
 
     let limit_str = limit.to_string();
-    let output = Command::new(&qmd_bin)
+    let output = qmd
+        .command()
         .args([
             search_cmd,
             query,

src-tauri/src/theme.rs

@@ -1,982 +0,0 @@
-use serde::{Deserialize, Serialize};
-use std::collections::HashMap;
-use std::fs;
-use std::path::Path;
-
-/// A theme file parsed from _themes/*.json in the vault.
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct ThemeFile {
-    /// Filename stem (e.g. "default" for _themes/default.json)
-    #[serde(default)]
-    pub id: String,
-    pub name: String,
-    #[serde(default)]
-    pub description: String,
-    #[serde(default)]
-    pub colors: HashMap<String, String>,
-    #[serde(default)]
-    pub typography: HashMap<String, String>,
-    #[serde(default)]
-    pub spacing: HashMap<String, String>,
-}
-
-/// Vault-level settings stored in .laputa/settings.json (git-tracked).
-#[derive(Debug, Clone, Serialize, Deserialize, Default)]
-pub struct VaultSettings {
-    #[serde(default)]
-    pub theme: Option<String>,
-}
-
-/// List all theme files in _themes/ directory of the vault.
-/// Seeds built-in themes if the directory is missing.
-pub fn list_themes(vault_path: &str) -> Result<Vec<ThemeFile>, String> {
-    let themes_dir = Path::new(vault_path).join("_themes");
-    if !themes_dir.is_dir() {
-        seed_default_themes(vault_path);
-    }
-    if !themes_dir.is_dir() {
-        return Ok(Vec::new());
-    }
-
-    let mut themes = Vec::new();
-    let entries =
-        fs::read_dir(&themes_dir).map_err(|e| format!("Failed to read _themes directory: {e}"))?;
-
-    for entry in entries.flatten() {
-        let path = entry.path();
-        if path.extension().and_then(|e| e.to_str()) != Some("json") {
-            continue;
-        }
-        match parse_theme_file(&path) {
-            Ok(theme) => themes.push(theme),
-            Err(e) => log::warn!("Skipping theme file {}: {e}", path.display()),
-        }
-    }
-
-    themes.sort_by(|a, b| a.name.cmp(&b.name));
-    Ok(themes)
-}
-
-/// Parse a single theme JSON file.
-fn parse_theme_file(path: &Path) -> Result<ThemeFile, String> {
-    let id = path
-        .file_stem()
-        .and_then(|s| s.to_str())
-        .map(|s| s.to_string())
-        .ok_or_else(|| "Invalid theme filename".to_string())?;
-
-    let content =
-        fs::read_to_string(path).map_err(|e| format!("Failed to read {}: {e}", path.display()))?;
-
-    let mut theme: ThemeFile = serde_json::from_str(&content)
-        .map_err(|e| format!("Failed to parse {}: {e}", path.display()))?;
-
-    theme.id = id;
-    Ok(theme)
-}
-
-/// Read vault-level settings from .laputa/settings.json.
-pub fn get_vault_settings(vault_path: &str) -> Result<VaultSettings, String> {
-    let settings_path = Path::new(vault_path).join(".laputa").join("settings.json");
-    if !settings_path.exists() {
-        return Ok(VaultSettings::default());
-    }
-    let content = fs::read_to_string(&settings_path)
-        .map_err(|e| format!("Failed to read vault settings: {e}"))?;
-    serde_json::from_str(&content).map_err(|e| format!("Failed to parse vault settings: {e}"))
-}
-
-/// Save vault-level settings to .laputa/settings.json.
-pub fn save_vault_settings(vault_path: &str, settings: VaultSettings) -> Result<(), String> {
-    let laputa_dir = Path::new(vault_path).join(".laputa");
-    fs::create_dir_all(&laputa_dir)
-        .map_err(|e| format!("Failed to create .laputa directory: {e}"))?;
-
-    let json = serde_json::to_string_pretty(&settings)
-        .map_err(|e| format!("Failed to serialize vault settings: {e}"))?;
-    fs::write(laputa_dir.join("settings.json"), json)
-        .map_err(|e| format!("Failed to write vault settings: {e}"))
-}
-
-/// Set the active theme in vault settings. Pass `None` to clear.
-pub fn set_active_theme(vault_path: &str, theme_id: Option<&str>) -> Result<(), String> {
-    let mut settings = get_vault_settings(vault_path)?;
-    settings.theme = theme_id.map(|s| s.to_string());
-    save_vault_settings(vault_path, settings)
-}
-
-/// Read a single theme file by ID from the vault's _themes/ directory.
-pub fn get_theme(vault_path: &str, theme_id: &str) -> Result<ThemeFile, String> {
-    let path = Path::new(vault_path)
-        .join("_themes")
-        .join(format!("{theme_id}.json"));
-    if !path.exists() {
-        return Err(format!("Theme not found: {theme_id}"));
-    }
-    parse_theme_file(&path)
-}
-
-/// Create `dir` and write each `(filename, content)` pair if the directory doesn't exist yet.
-fn seed_dir_with_files(dir: &Path, files: &[(&str, &str)], log_msg: &str) {
-    if dir.is_dir() {
-        return;
-    }
-    if fs::create_dir_all(dir).is_err() {
-        return;
-    }
-    for (name, content) in files {
-        let _ = fs::write(dir.join(name), content);
-    }
-    log::info!("{log_msg}");
-}
-
-/// Seed the `_themes/` directory with built-in themes if it doesn't exist yet.
-/// Safe to call multiple times — only writes files that are missing.
-pub fn seed_default_themes(vault_path: &str) {
-    seed_dir_with_files(
-        &Path::new(vault_path).join("_themes"),
-        &[
-            ("default.json", DEFAULT_THEME),
-            ("dark.json", DARK_THEME),
-            ("minimal.json", MINIMAL_THEME),
-        ],
-        "Seeded _themes/ with built-in themes",
-    );
-}
-
-/// Seed the vault `theme/` directory with built-in vault-based theme notes.
-/// Per-file idempotent: creates the directory if missing, writes each default
-/// file only when it doesn't exist or is empty (corrupt). Never overwrites
-/// existing files that have content.
-pub fn seed_vault_themes(vault_path: &str) {
-    let theme_dir = Path::new(vault_path).join("theme");
-    if fs::create_dir_all(&theme_dir).is_err() {
-        return;
-    }
-    let defaults: &[(&str, &str)] = &[
-        ("default.md", DEFAULT_VAULT_THEME),
-        ("dark.md", DARK_VAULT_THEME),
-        ("minimal.md", MINIMAL_VAULT_THEME),
-    ];
-    let mut seeded = false;
-    for (name, content) in defaults {
-        let path = theme_dir.join(name);
-        let needs_write = !path.exists() || fs::metadata(&path).map_or(true, |m| m.len() == 0);
-        if needs_write {
-            let _ = fs::write(&path, content);
-            seeded = true;
-        }
-    }
-    if seeded {
-        log::info!("Seeded theme/ with built-in vault themes");
-    }
-}
-
-/// Ensure vault theme files exist. Returns an error if the theme directory
-/// cannot be created (e.g. read-only filesystem).
-pub fn ensure_vault_themes(vault_path: &str) -> Result<(), String> {
-    let theme_dir = Path::new(vault_path).join("theme");
-    fs::create_dir_all(&theme_dir).map_err(|e| format!("Failed to create theme directory: {e}"))?;
-    let defaults: &[(&str, &str)] = &[
-        ("default.md", DEFAULT_VAULT_THEME),
-        ("dark.md", DARK_VAULT_THEME),
-    ];
-    for (name, content) in defaults {
-        let path = theme_dir.join(name);
-        let needs_write = !path.exists() || fs::metadata(&path).map_or(true, |m| m.len() == 0);
-        if needs_write {
-            fs::write(&path, content).map_err(|e| format!("Failed to write theme/{name}: {e}"))?;
-        }
-    }
-    Ok(())
-}
-
-/// Create a new vault theme note in `theme/` directory.
-/// Returns the absolute path to the newly created theme note.
-pub fn create_vault_theme(vault_path: &str, name: Option<&str>) -> Result<String, String> {
-    let theme_dir = Path::new(vault_path).join("theme");
-    fs::create_dir_all(&theme_dir).map_err(|e| format!("Failed to create theme directory: {e}"))?;
-
-    let display_name = name.unwrap_or("Untitled Theme");
-    let slug = slugify(display_name);
-    let filename = format!("{}.md", find_available_stem(&theme_dir, &slug, "md"));
-    let path = theme_dir.join(&filename);
-
-    let content = vault_theme_note_content(display_name, &DEFAULT_VAULT_THEME_VARS);
-    fs::write(&path, content).map_err(|e| format!("Failed to write theme note: {e}"))?;
-
-    Ok(path.to_string_lossy().to_string())
-}
-
-/// Convert a display name to a URL-safe slug.
-fn slugify(name: &str) -> String {
-    name.chars()
-        .map(|c| {
-            if c.is_ascii_alphanumeric() {
-                c.to_ascii_lowercase()
-            } else {
-                '-'
-            }
-        })
-        .collect::<String>()
-        .split('-')
-        .filter(|s| !s.is_empty())
-        .collect::<Vec<_>>()
-        .join("-")
-}
-
-/// Find an available filename stem (base, base-2, base-3, …) that doesn't conflict when `ext` is appended.
-fn find_available_stem(dir: &Path, base: &str, ext: &str) -> String {
-    if !dir.join(format!("{base}.{ext}")).exists() {
-        return base.to_string();
-    }
-    for i in 2.. {
-        let candidate = format!("{base}-{i}");
-        if !dir.join(format!("{candidate}.{ext}")).exists() {
-            return candidate;
-        }
-    }
-    unreachable!()
-}
-
-/// Build a vault theme note markdown string from a name and CSS variable map.
-fn vault_theme_note_content(name: &str, vars: &[(&str, &str)]) -> String {
-    let mut fm = format!("---\nIs A: Theme\nDescription: {name} theme\n");
-    for (key, value) in vars {
-        // Values with '#' or spaces need quoting; others can be bare strings.
-        if value.contains('#') || value.contains('\'') || value.contains(',') {
-            fm.push_str(&format!("{key}: \"{value}\"\n"));
-        } else {
-            fm.push_str(&format!("{key}: {value}\n"));
-        }
-    }
-    fm.push_str("---\n\n");
-    fm.push_str(&format!(
-        "# {name} Theme\n\nA custom {name} theme for Laputa.\n"
-    ));
-    fm
-}
-
-/// Create a new theme file by copying the active theme (or default).
-/// Returns the ID of the new theme.
-pub fn create_theme(vault_path: &str, source_id: Option<&str>) -> Result<String, String> {
-    let themes_dir = Path::new(vault_path).join("_themes");
-    fs::create_dir_all(&themes_dir)
-        .map_err(|e| format!("Failed to create _themes directory: {e}"))?;
-
-    let new_id = find_available_stem(&themes_dir, "untitled", "json");
-
-    let source = source_id.unwrap_or("default");
-    let source_path = themes_dir.join(format!("{source}.json"));
-
-    let content = if source_path.exists() {
-        let mut theme: serde_json::Value = serde_json::from_str(
-            &fs::read_to_string(&source_path)
-                .map_err(|e| format!("Failed to read source theme: {e}"))?,
-        )
-        .map_err(|e| format!("Failed to parse source theme: {e}"))?;
-
-        if let Some(obj) = theme.as_object_mut() {
-            obj.insert(
-                "name".to_string(),
-                serde_json::Value::String("Untitled Theme".to_string()),
-            );
-        }
-        serde_json::to_string_pretty(&theme)
-            .map_err(|e| format!("Failed to serialize new theme: {e}"))?
-    } else {
-        default_theme_json("Untitled Theme")
-    };
-
-    fs::write(themes_dir.join(format!("{new_id}.json")), content)
-        .map_err(|e| format!("Failed to write new theme: {e}"))?;
-
-    Ok(new_id)
-}
-
-/// Generate the default light theme JSON.
-fn default_theme_json(name: &str) -> String {
-    serde_json::to_string_pretty(&serde_json::json!({
-        "name": name,
-        "description": "Custom theme",
-        "colors": {
-            "background": "#FFFFFF",
-            "foreground": "#37352F",
-            "sidebar-background": "#F7F6F3",
-            "accent": "#155DFF",
-            "muted": "#787774",
-            "border": "#E9E9E7"
-        },
-        "typography": {
-            "font-family": "system-ui",
-            "font-size-base": "14px"
-        },
-        "spacing": {
-            "sidebar-width": "240px"
-        }
-    }))
-    .unwrap()
-}
-
-/// Content for the built-in default (light) theme.
-pub const DEFAULT_THEME: &str = r##"{
-  "name": "Default",
-  "description": "Light theme with warm, paper-like tones",
-  "colors": {
-    "background": "#FFFFFF",
-    "foreground": "#37352F",
-    "card": "#FFFFFF",
-    "popover": "#FFFFFF",
-    "primary": "#155DFF",
-    "primary-foreground": "#FFFFFF",
-    "secondary": "#EBEBEA",
-    "secondary-foreground": "#37352F",
-    "muted": "#F0F0EF",
-    "muted-foreground": "#787774",
-    "accent": "#EBEBEA",
-    "accent-foreground": "#37352F",
-    "destructive": "#E03E3E",
-    "border": "#E9E9E7",
-    "input": "#E9E9E7",
-    "ring": "#155DFF",
-    "sidebar-background": "#F7F6F3",
-    "sidebar-foreground": "#37352F",
-    "sidebar-border": "#E9E9E7",
-    "sidebar-accent": "#EBEBEA"
-  },
-  "typography": {
-    "font-family": "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
-    "font-size-base": "14px"
-  },
-  "spacing": {
-    "sidebar-width": "250px"
-  }
-}"##;
-
-/// Content for the built-in dark theme.
-pub const DARK_THEME: &str = r##"{
-  "name": "Dark",
-  "description": "Dark variant with deep navy tones",
-  "colors": {
-    "background": "#0f0f1a",
-    "foreground": "#e0e0e0",
-    "card": "#16162a",
-    "popover": "#1e1e3a",
-    "primary": "#155DFF",
-    "primary-foreground": "#FFFFFF",
-    "secondary": "#2a2a4a",
-    "secondary-foreground": "#e0e0e0",
-    "muted": "#1e1e3a",
-    "muted-foreground": "#888888",
-    "accent": "#2a2a4a",
-    "accent-foreground": "#e0e0e0",
-    "destructive": "#f44336",
-    "border": "#2a2a4a",
-    "input": "#2a2a4a",
-    "ring": "#155DFF",
-    "sidebar-background": "#1a1a2e",
-    "sidebar-foreground": "#e0e0e0",
-    "sidebar-border": "#2a2a4a",
-    "sidebar-accent": "#2a2a4a"
-  },
-  "typography": {
-    "font-family": "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
-    "font-size-base": "14px"
-  },
-  "spacing": {
-    "sidebar-width": "250px"
-  }
-}"##;
-
-/// Content for the built-in minimal theme.
-pub const MINIMAL_THEME: &str = r##"{
-  "name": "Minimal",
-  "description": "High contrast, minimal chrome",
-  "colors": {
-    "background": "#FAFAFA",
-    "foreground": "#111111",
-    "card": "#FFFFFF",
-    "popover": "#FFFFFF",
-    "primary": "#000000",
-    "primary-foreground": "#FFFFFF",
-    "secondary": "#F0F0F0",
-    "secondary-foreground": "#111111",
-    "muted": "#F5F5F5",
-    "muted-foreground": "#666666",
-    "accent": "#F0F0F0",
-    "accent-foreground": "#111111",
-    "destructive": "#CC0000",
-    "border": "#E0E0E0",
-    "input": "#E0E0E0",
-    "ring": "#000000",
-    "sidebar-background": "#F5F5F5",
-    "sidebar-foreground": "#111111",
-    "sidebar-border": "#E0E0E0",
-    "sidebar-accent": "#E8E8E8"
-  },
-  "typography": {
-    "font-family": "'SF Mono', 'Menlo', monospace",
-    "font-size-base": "13px"
-  },
-  "spacing": {
-    "sidebar-width": "220px"
-  }
-}"##;
-
-/// CSS variable key-value pairs for the default light vault theme.
-pub const DEFAULT_VAULT_THEME_VARS: [(&str, &str); 46] = [
-    // shadcn/ui base
-    ("background", "#FFFFFF"),
-    ("foreground", "#37352F"),
-    ("card", "#FFFFFF"),
-    ("popover", "#FFFFFF"),
-    ("primary", "#155DFF"),
-    ("primary-foreground", "#FFFFFF"),
-    ("secondary", "#EBEBEA"),
-    ("secondary-foreground", "#37352F"),
-    ("muted", "#F0F0EF"),
-    ("muted-foreground", "#787774"),
-    ("accent", "#EBEBEA"),
-    ("accent-foreground", "#37352F"),
-    ("destructive", "#E03E3E"),
-    ("border", "#E9E9E7"),
-    ("input", "#E9E9E7"),
-    ("ring", "#155DFF"),
-    ("sidebar", "#F7F6F3"),
-    ("sidebar-foreground", "#37352F"),
-    ("sidebar-border", "#E9E9E7"),
-    ("sidebar-accent", "#EBEBEA"),
-    // Text hierarchy
-    ("text-primary", "#37352F"),
-    ("text-secondary", "#787774"),
-    ("text-muted", "#B4B4B4"),
-    ("text-heading", "#37352F"),
-    // Backgrounds
-    ("bg-primary", "#FFFFFF"),
-    ("bg-sidebar", "#F7F6F3"),
-    ("bg-hover", "#EBEBEA"),
-    ("bg-hover-subtle", "#F0F0EF"),
-    ("bg-selected", "#E8F4FE"),
-    ("border-primary", "#E9E9E7"),
-    // Accent colours
-    ("accent-blue", "#155DFF"),
-    ("accent-green", "#00B38B"),
-    ("accent-orange", "#D9730D"),
-    ("accent-red", "#E03E3E"),
-    ("accent-purple", "#A932FF"),
-    ("accent-yellow", "#F0B100"),
-    ("accent-blue-light", "#155DFF14"),
-    ("accent-green-light", "#00B38B14"),
-    ("accent-purple-light", "#A932FF14"),
-    ("accent-red-light", "#E03E3E14"),
-    ("accent-yellow-light", "#F0B10014"),
-    // Typography
-    (
-        "font-family",
-        "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
-    ),
-    ("font-size-base", "14px"),
-    // Editor
-    ("editor-font-size", "16"),
-    ("editor-line-height", "1.5"),
-    ("editor-max-width", "720"),
-];
-
-/// Vault-based theme note for the built-in Default theme.
-pub const DEFAULT_VAULT_THEME: &str = "---\n\
-Is A: Theme\n\
-Description: Light theme with warm, paper-like tones\n\
-background: \"#FFFFFF\"\n\
-foreground: \"#37352F\"\n\
-card: \"#FFFFFF\"\n\
-popover: \"#FFFFFF\"\n\
-primary: \"#155DFF\"\n\
-primary-foreground: \"#FFFFFF\"\n\
-secondary: \"#EBEBEA\"\n\
-secondary-foreground: \"#37352F\"\n\
-muted: \"#F0F0EF\"\n\
-muted-foreground: \"#787774\"\n\
-accent: \"#EBEBEA\"\n\
-accent-foreground: \"#37352F\"\n\
-destructive: \"#E03E3E\"\n\
-border: \"#E9E9E7\"\n\
-input: \"#E9E9E7\"\n\
-ring: \"#155DFF\"\n\
-sidebar: \"#F7F6F3\"\n\
-sidebar-foreground: \"#37352F\"\n\
-sidebar-border: \"#E9E9E7\"\n\
-sidebar-accent: \"#EBEBEA\"\n\
-text-primary: \"#37352F\"\n\
-text-secondary: \"#787774\"\n\
-text-muted: \"#B4B4B4\"\n\
-text-heading: \"#37352F\"\n\
-bg-primary: \"#FFFFFF\"\n\
-bg-sidebar: \"#F7F6F3\"\n\
-bg-hover: \"#EBEBEA\"\n\
-bg-hover-subtle: \"#F0F0EF\"\n\
-bg-selected: \"#E8F4FE\"\n\
-border-primary: \"#E9E9E7\"\n\
-accent-blue: \"#155DFF\"\n\
-accent-green: \"#00B38B\"\n\
-accent-orange: \"#D9730D\"\n\
-accent-red: \"#E03E3E\"\n\
-accent-purple: \"#A932FF\"\n\
-accent-yellow: \"#F0B100\"\n\
-accent-blue-light: \"#155DFF14\"\n\
-accent-green-light: \"#00B38B14\"\n\
-accent-purple-light: \"#A932FF14\"\n\
-accent-red-light: \"#E03E3E14\"\n\
-accent-yellow-light: \"#F0B10014\"\n\
-font-family: \"'Inter', -apple-system, BlinkMacSystemFont, sans-serif\"\n\
-font-size-base: 14px\n\
-editor-font-size: 16\n\
-editor-line-height: 1.5\n\
-editor-max-width: 720\n\
----\n\
-\n\
-# Default Theme\n\
-\n\
-The default light theme for Laputa. Clean and warm, inspired by Notion.\n";
-
-/// Vault-based theme note for the built-in Dark theme.
-pub const DARK_VAULT_THEME: &str = "---\n\
-Is A: Theme\n\
-Description: Dark variant with deep navy tones\n\
-background: \"#0f0f1a\"\n\
-foreground: \"#e0e0e0\"\n\
-card: \"#16162a\"\n\
-popover: \"#1e1e3a\"\n\
-primary: \"#155DFF\"\n\
-primary-foreground: \"#FFFFFF\"\n\
-secondary: \"#2a2a4a\"\n\
-secondary-foreground: \"#e0e0e0\"\n\
-muted: \"#1e1e3a\"\n\
-muted-foreground: \"#888888\"\n\
-accent: \"#2a2a4a\"\n\
-accent-foreground: \"#e0e0e0\"\n\
-destructive: \"#f44336\"\n\
-border: \"#2a2a4a\"\n\
-input: \"#2a2a4a\"\n\
-ring: \"#155DFF\"\n\
-sidebar: \"#1a1a2e\"\n\
-sidebar-foreground: \"#e0e0e0\"\n\
-sidebar-border: \"#2a2a4a\"\n\
-sidebar-accent: \"#2a2a4a\"\n\
-text-primary: \"#e0e0e0\"\n\
-text-secondary: \"#888888\"\n\
-text-muted: \"#666666\"\n\
-text-heading: \"#e0e0e0\"\n\
-bg-primary: \"#0f0f1a\"\n\
-bg-sidebar: \"#1a1a2e\"\n\
-bg-hover: \"#2a2a4a\"\n\
-bg-hover-subtle: \"#1e1e3a\"\n\
-bg-selected: \"#155DFF22\"\n\
-border-primary: \"#2a2a4a\"\n\
-accent-blue: \"#155DFF\"\n\
-accent-green: \"#00B38B\"\n\
-accent-orange: \"#D9730D\"\n\
-accent-red: \"#f44336\"\n\
-accent-purple: \"#A932FF\"\n\
-accent-yellow: \"#F0B100\"\n\
-accent-blue-light: \"#155DFF33\"\n\
-accent-green-light: \"#00B38B33\"\n\
-accent-purple-light: \"#A932FF33\"\n\
-accent-red-light: \"#f4433633\"\n\
-accent-yellow-light: \"#F0B10033\"\n\
-font-family: \"'Inter', -apple-system, BlinkMacSystemFont, sans-serif\"\n\
-font-size-base: 14px\n\
-editor-font-size: 16\n\
-editor-line-height: 1.5\n\
-editor-max-width: 720\n\
----\n\
-\n\
-# Dark Theme\n\
-\n\
-A dark theme with deep navy tones for comfortable night-time reading.\n";
-
-/// Vault-based theme note for the built-in Minimal theme.
-pub const MINIMAL_VAULT_THEME: &str = "---\n\
-Is A: Theme\n\
-Description: High contrast, minimal chrome\n\
-background: \"#FAFAFA\"\n\
-foreground: \"#111111\"\n\
-card: \"#FFFFFF\"\n\
-popover: \"#FFFFFF\"\n\
-primary: \"#000000\"\n\
-primary-foreground: \"#FFFFFF\"\n\
-secondary: \"#F0F0F0\"\n\
-secondary-foreground: \"#111111\"\n\
-muted: \"#F5F5F5\"\n\
-muted-foreground: \"#666666\"\n\
-accent: \"#F0F0F0\"\n\
-accent-foreground: \"#111111\"\n\
-destructive: \"#CC0000\"\n\
-border: \"#E0E0E0\"\n\
-input: \"#E0E0E0\"\n\
-ring: \"#000000\"\n\
-sidebar: \"#F5F5F5\"\n\
-sidebar-foreground: \"#111111\"\n\
-sidebar-border: \"#E0E0E0\"\n\
-sidebar-accent: \"#E8E8E8\"\n\
-text-primary: \"#111111\"\n\
-text-secondary: \"#666666\"\n\
-text-muted: \"#999999\"\n\
-text-heading: \"#111111\"\n\
-bg-primary: \"#FAFAFA\"\n\
-bg-sidebar: \"#F5F5F5\"\n\
-bg-hover: \"#EBEBEB\"\n\
-bg-hover-subtle: \"#F5F5F5\"\n\
-bg-selected: \"#00000014\"\n\
-border-primary: \"#E0E0E0\"\n\
-accent-blue: \"#000000\"\n\
-accent-green: \"#006600\"\n\
-accent-orange: \"#996600\"\n\
-accent-red: \"#CC0000\"\n\
-accent-purple: \"#660099\"\n\
-accent-yellow: \"#996600\"\n\
-accent-blue-light: \"#00000014\"\n\
-accent-green-light: \"#00660014\"\n\
-accent-purple-light: \"#66009914\"\n\
-accent-red-light: \"#CC000014\"\n\
-accent-yellow-light: \"#99660014\"\n\
-font-family: \"'SF Mono', 'Menlo', monospace\"\n\
-font-size-base: 13px\n\
-editor-font-size: 15\n\
-editor-line-height: 1.6\n\
-editor-max-width: 680\n\
----\n\
-\n\
-# Minimal Theme\n\
-\n\
-High contrast, minimal chrome. Monospace typography throughout.\n";
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use std::fs;
-    use tempfile::TempDir;
-
-    fn setup_vault_with_themes(dir: &TempDir) -> String {
-        let vault = dir.path().join("vault");
-        let themes_dir = vault.join("_themes");
-        fs::create_dir_all(&themes_dir).unwrap();
-        fs::write(themes_dir.join("default.json"), DEFAULT_THEME).unwrap();
-        fs::write(themes_dir.join("dark.json"), DARK_THEME).unwrap();
-        vault.to_string_lossy().to_string()
-    }
-
-    #[test]
-    fn test_list_themes_returns_sorted_list() {
-        let dir = TempDir::new().unwrap();
-        let vault = setup_vault_with_themes(&dir);
-        let themes = list_themes(&vault).unwrap();
-        assert_eq!(themes.len(), 2);
-        assert_eq!(themes[0].id, "dark");
-        assert_eq!(themes[1].id, "default");
-    }
-
-    #[test]
-    fn test_list_themes_seeds_defaults_when_no_dir() {
-        let dir = TempDir::new().unwrap();
-        let vault = dir.path().join("empty-vault");
-        fs::create_dir_all(&vault).unwrap();
-        let themes = list_themes(vault.to_str().unwrap()).unwrap();
-        assert_eq!(themes.len(), 3);
-        let names: Vec<&str> = themes.iter().map(|t| t.name.as_str()).collect();
-        assert!(names.contains(&"Default"));
-        assert!(names.contains(&"Dark"));
-        assert!(names.contains(&"Minimal"));
-    }
-
-    #[test]
-    fn test_get_theme_by_id() {
-        let dir = TempDir::new().unwrap();
-        let vault = setup_vault_with_themes(&dir);
-        let theme = get_theme(&vault, "default").unwrap();
-        assert_eq!(theme.name, "Default");
-        assert!(!theme.colors.is_empty());
-    }
-
-    #[test]
-    fn test_get_theme_not_found() {
-        let dir = TempDir::new().unwrap();
-        let vault = setup_vault_with_themes(&dir);
-        let result = get_theme(&vault, "nonexistent");
-        assert!(result.is_err());
-    }
-
-    #[test]
-    fn test_vault_settings_roundtrip() {
-        let dir = TempDir::new().unwrap();
-        let vault = dir.path().join("vault");
-        fs::create_dir_all(&vault).unwrap();
-        let vp = vault.to_str().unwrap();
-
-        // Default settings have no theme
-        let settings = get_vault_settings(vp).unwrap();
-        assert!(settings.theme.is_none());
-
-        // Set and read back
-        set_active_theme(vp, Some("dark")).unwrap();
-        let settings = get_vault_settings(vp).unwrap();
-        assert_eq!(settings.theme.as_deref(), Some("dark"));
-
-        // Clear theme
-        set_active_theme(vp, None).unwrap();
-        let settings = get_vault_settings(vp).unwrap();
-        assert_eq!(settings.theme, None);
-    }
-
-    #[test]
-    fn test_vault_settings_creates_laputa_dir() {
-        let dir = TempDir::new().unwrap();
-        let vault = dir.path().join("vault");
-        fs::create_dir_all(&vault).unwrap();
-        let vp = vault.to_str().unwrap();
-
-        assert!(!vault.join(".laputa").exists());
-        save_vault_settings(
-            vp,
-            VaultSettings {
-                theme: Some("light".into()),
-            },
-        )
-        .unwrap();
-        assert!(vault.join(".laputa").join("settings.json").exists());
-    }
-
-    #[test]
-    fn test_create_theme_copies_source() {
-        let dir = TempDir::new().unwrap();
-        let vault = setup_vault_with_themes(&dir);
-        let new_id = create_theme(&vault, Some("default")).unwrap();
-        assert_eq!(new_id, "untitled");
-
-        let theme = get_theme(&vault, &new_id).unwrap();
-        assert_eq!(theme.name, "Untitled Theme");
-        assert!(!theme.colors.is_empty());
-    }
-
-    #[test]
-    fn test_create_theme_increments_id() {
-        let dir = TempDir::new().unwrap();
-        let vault = setup_vault_with_themes(&dir);
-
-        let id1 = create_theme(&vault, None).unwrap();
-        assert_eq!(id1, "untitled");
-
-        let id2 = create_theme(&vault, None).unwrap();
-        assert_eq!(id2, "untitled-2");
-    }
-
-    #[test]
-    fn test_parse_all_builtin_themes() {
-        for (name, content) in [
-            ("default", DEFAULT_THEME),
-            ("dark", DARK_THEME),
-            ("minimal", MINIMAL_THEME),
-        ] {
-            let theme: ThemeFile = serde_json::from_str(content)
-                .unwrap_or_else(|e| panic!("Failed to parse {name} theme: {e}"));
-            assert!(!theme.name.is_empty(), "{name} theme should have a name");
-            assert!(!theme.colors.is_empty(), "{name} theme should have colors");
-        }
-    }
-
-    #[test]
-    fn test_list_themes_ignores_non_json_files() {
-        let dir = TempDir::new().unwrap();
-        let vault = setup_vault_with_themes(&dir);
-        let themes_dir = Path::new(&vault).join("_themes");
-        fs::write(themes_dir.join("readme.txt"), "not a theme").unwrap();
-        fs::write(themes_dir.join(".DS_Store"), "").unwrap();
-
-        let themes = list_themes(&vault).unwrap();
-        assert_eq!(themes.len(), 2); // only default and dark
-    }
-
-    #[test]
-    fn test_list_themes_skips_malformed_json() {
-        let dir = TempDir::new().unwrap();
-        let vault = setup_vault_with_themes(&dir);
-        let themes_dir = Path::new(&vault).join("_themes");
-        fs::write(themes_dir.join("broken.json"), "not valid json{{{").unwrap();
-
-        let themes = list_themes(&vault).unwrap();
-        assert_eq!(themes.len(), 2); // broken.json is skipped
-    }
-
-    #[test]
-    fn test_seed_vault_themes_creates_theme_dir() {
-        let dir = TempDir::new().unwrap();
-        let vault = dir.path().join("vault");
-        fs::create_dir_all(&vault).unwrap();
-        let vp = vault.to_str().unwrap();
-
-        assert!(!vault.join("theme").exists());
-        seed_vault_themes(vp);
-        assert!(vault.join("theme").is_dir());
-        assert!(vault.join("theme").join("default.md").exists());
-        assert!(vault.join("theme").join("dark.md").exists());
-        assert!(vault.join("theme").join("minimal.md").exists());
-    }
-
-    #[test]
-    fn test_seed_vault_themes_is_idempotent() {
-        let dir = TempDir::new().unwrap();
-        let vault = dir.path().join("vault");
-        fs::create_dir_all(&vault).unwrap();
-        let vp = vault.to_str().unwrap();
-
-        seed_vault_themes(vp);
-        seed_vault_themes(vp); // second call should be a no-op
-        assert!(vault.join("theme").join("default.md").exists());
-    }
-
-    #[test]
-    fn test_create_vault_theme_creates_md_file() {
-        let dir = TempDir::new().unwrap();
-        let vault = dir.path().join("vault");
-        fs::create_dir_all(&vault).unwrap();
-        let vp = vault.to_str().unwrap();
-
-        let path = create_vault_theme(vp, Some("My Theme")).unwrap();
-        assert!(std::path::Path::new(&path).exists());
-        let content = fs::read_to_string(&path).unwrap();
-        assert!(content.contains("Is A: Theme"));
-        assert!(content.contains("# My Theme"));
-        assert!(content.contains("background:"));
-    }
-
-    #[test]
-    fn test_create_vault_theme_default_name() {
-        let dir = TempDir::new().unwrap();
-        let vault = dir.path().join("vault");
-        fs::create_dir_all(&vault).unwrap();
-        let vp = vault.to_str().unwrap();
-
-        let path = create_vault_theme(vp, None).unwrap();
-        let content = fs::read_to_string(&path).unwrap();
-        assert!(content.contains("# Untitled Theme"));
-    }
-
-    #[test]
-    fn test_create_vault_theme_avoids_conflicts() {
-        let dir = TempDir::new().unwrap();
-        let vault = dir.path().join("vault");
-        fs::create_dir_all(&vault).unwrap();
-        let vp = vault.to_str().unwrap();
-
-        let p1 = create_vault_theme(vp, Some("Custom")).unwrap();
-        let p2 = create_vault_theme(vp, Some("Custom")).unwrap();
-        assert_ne!(p1, p2);
-    }
-
-    #[test]
-    fn test_slugify() {
-        assert_eq!(slugify("My Cool Theme"), "my-cool-theme");
-        assert_eq!(slugify("default"), "default");
-        assert_eq!(slugify("Dark Mode!"), "dark-mode");
-    }
-
-    #[test]
-    fn test_vault_theme_content_contains_all_vars() {
-        let content = DEFAULT_VAULT_THEME;
-        assert!(content.contains("background:"));
-        assert!(content.contains("primary:"));
-        assert!(content.contains("sidebar:"));
-        assert!(content.contains("text-primary:"));
-        assert!(content.contains("accent-blue:"));
-        assert!(content.contains("editor-font-size:"));
-    }
-
-    #[test]
-    fn test_seed_vault_themes_writes_missing_files_in_existing_dir() {
-        let dir = TempDir::new().unwrap();
-        let vault = dir.path().join("vault");
-        let theme_dir = vault.join("theme");
-        fs::create_dir_all(&theme_dir).unwrap();
-        // Only default exists — dark and minimal should be seeded
-        fs::write(theme_dir.join("default.md"), DEFAULT_VAULT_THEME).unwrap();
-        let vp = vault.to_str().unwrap();
-
-        seed_vault_themes(vp);
-        assert!(theme_dir.join("dark.md").exists());
-        assert!(theme_dir.join("minimal.md").exists());
-    }
-
-    #[test]
-    fn test_seed_vault_themes_reseeds_empty_files() {
-        let dir = TempDir::new().unwrap();
-        let vault = dir.path().join("vault");
-        let theme_dir = vault.join("theme");
-        fs::create_dir_all(&theme_dir).unwrap();
-        // Create empty file — should be re-seeded
-        fs::write(theme_dir.join("default.md"), "").unwrap();
-        let vp = vault.to_str().unwrap();
-
-        seed_vault_themes(vp);
-        let content = fs::read_to_string(theme_dir.join("default.md")).unwrap();
-        assert!(content.contains("Is A: Theme"));
-    }
-
-    #[test]
-    fn test_seed_vault_themes_preserves_existing_content() {
-        let dir = TempDir::new().unwrap();
-        let vault = dir.path().join("vault");
-        let theme_dir = vault.join("theme");
-        fs::create_dir_all(&theme_dir).unwrap();
-        let custom = "---\nIs A: Theme\nbackground: \"#FF0000\"\n---\n# Custom\n";
-        fs::write(theme_dir.join("default.md"), custom).unwrap();
-        let vp = vault.to_str().unwrap();
-
-        seed_vault_themes(vp);
-        let content = fs::read_to_string(theme_dir.join("default.md")).unwrap();
-        assert!(
-            content.contains("#FF0000"),
-            "existing content must be preserved"
-        );
-    }
-
-    #[test]
-    fn test_ensure_vault_themes_creates_dir_and_defaults() {
-        let dir = TempDir::new().unwrap();
-        let vault = dir.path().join("vault");
-        fs::create_dir_all(&vault).unwrap();
-        let vp = vault.to_str().unwrap();
-
-        ensure_vault_themes(vp).unwrap();
-        assert!(vault.join("theme").is_dir());
-        assert!(vault.join("theme").join("default.md").exists());
-        assert!(vault.join("theme").join("dark.md").exists());
-    }
-
-    #[test]
-    fn test_ensure_vault_themes_reseeds_empty_files() {
-        let dir = TempDir::new().unwrap();
-        let vault = dir.path().join("vault");
-        let theme_dir = vault.join("theme");
-        fs::create_dir_all(&theme_dir).unwrap();
-        fs::write(theme_dir.join("default.md"), "").unwrap();
-        let vp = vault.to_str().unwrap();
-
-        ensure_vault_themes(vp).unwrap();
-        let content = fs::read_to_string(theme_dir.join("default.md")).unwrap();
-        assert!(content.contains("Is A: Theme"));
-    }
-
-    #[test]
-    fn test_ensure_vault_themes_preserves_custom_themes() {
-        let dir = TempDir::new().unwrap();
-        let vault = dir.path().join("vault");
-        let theme_dir = vault.join("theme");
-        fs::create_dir_all(&theme_dir).unwrap();
-        let custom = "---\nIs A: Theme\nbackground: \"#123456\"\n---\n";
-        fs::write(theme_dir.join("default.md"), custom).unwrap();
-        let vp = vault.to_str().unwrap();
-
-        ensure_vault_themes(vp).unwrap();
-        let content = fs::read_to_string(theme_dir.join("default.md")).unwrap();
-        assert!(content.contains("#123456"));
-    }
-}

src-tauri/src/theme/create.rs

@@ -0,0 +1,219 @@
+use std::fs;
+use std::path::Path;
+
+use super::defaults::DEFAULT_VAULT_THEME_VARS;
+
+/// Create a new vault theme note in `theme/` directory.
+/// Returns the absolute path to the newly created theme note.
+pub fn create_vault_theme(vault_path: &str, name: Option<&str>) -> Result<String, String> {
+    let theme_dir = Path::new(vault_path).join("theme");
+    fs::create_dir_all(&theme_dir).map_err(|e| format!("Failed to create theme directory: {e}"))?;
+
+    let display_name = name.unwrap_or("Untitled Theme");
+    let slug = slugify(display_name);
+    let filename = format!("{}.md", find_available_stem(&theme_dir, &slug, "md"));
+    let path = theme_dir.join(&filename);
+
+    let content = vault_theme_note_content(display_name, &DEFAULT_VAULT_THEME_VARS);
+    fs::write(&path, content).map_err(|e| format!("Failed to write theme note: {e}"))?;
+
+    Ok(path.to_string_lossy().to_string())
+}
+
+/// Create a new theme file by copying the active theme (or default).
+/// Returns the ID of the new theme.
+pub fn create_theme(vault_path: &str, source_id: Option<&str>) -> Result<String, String> {
+    let themes_dir = Path::new(vault_path).join("_themes");
+    fs::create_dir_all(&themes_dir)
+        .map_err(|e| format!("Failed to create _themes directory: {e}"))?;
+
+    let new_id = find_available_stem(&themes_dir, "untitled", "json");
+
+    let source = source_id.unwrap_or("default");
+    let source_path = themes_dir.join(format!("{source}.json"));
+
+    let content = if source_path.exists() {
+        let mut theme: serde_json::Value = serde_json::from_str(
+            &fs::read_to_string(&source_path)
+                .map_err(|e| format!("Failed to read source theme: {e}"))?,
+        )
+        .map_err(|e| format!("Failed to parse source theme: {e}"))?;
+
+        if let Some(obj) = theme.as_object_mut() {
+            obj.insert(
+                "name".to_string(),
+                serde_json::Value::String("Untitled Theme".to_string()),
+            );
+        }
+        serde_json::to_string_pretty(&theme)
+            .map_err(|e| format!("Failed to serialize new theme: {e}"))?
+    } else {
+        default_theme_json("Untitled Theme")
+    };
+
+    fs::write(themes_dir.join(format!("{new_id}.json")), content)
+        .map_err(|e| format!("Failed to write new theme: {e}"))?;
+
+    Ok(new_id)
+}
+
+/// Convert a display name to a URL-safe slug.
+fn slugify(name: &str) -> String {
+    name.chars()
+        .map(|c| {
+            if c.is_ascii_alphanumeric() {
+                c.to_ascii_lowercase()
+            } else {
+                '-'
+            }
+        })
+        .collect::<String>()
+        .split('-')
+        .filter(|s| !s.is_empty())
+        .collect::<Vec<_>>()
+        .join("-")
+}
+
+/// Find an available filename stem (base, base-2, base-3, …) that doesn't
+/// conflict when `ext` is appended.
+fn find_available_stem(dir: &Path, base: &str, ext: &str) -> String {
+    if !dir.join(format!("{base}.{ext}")).exists() {
+        return base.to_string();
+    }
+    for i in 2.. {
+        let candidate = format!("{base}-{i}");
+        if !dir.join(format!("{candidate}.{ext}")).exists() {
+            return candidate;
+        }
+    }
+    unreachable!()
+}
+
+/// Build a vault theme note markdown string from a name and CSS variable map.
+fn vault_theme_note_content(name: &str, vars: &[(&str, &str)]) -> String {
+    let mut fm = format!("---\nIs A: Theme\nDescription: {name} theme\n");
+    for (key, value) in vars {
+        if value.contains('#') || value.contains('\'') || value.contains(',') {
+            fm.push_str(&format!("{key}: \"{value}\"\n"));
+        } else {
+            fm.push_str(&format!("{key}: {value}\n"));
+        }
+    }
+    fm.push_str("---\n\n");
+    fm.push_str(&format!(
+        "# {name} Theme\n\nA custom {name} theme for Laputa.\n"
+    ));
+    fm
+}
+
+/// Generate the default light theme JSON.
+fn default_theme_json(name: &str) -> String {
+    serde_json::to_string_pretty(&serde_json::json!({
+        "name": name,
+        "description": "Custom theme",
+        "colors": {
+            "background": "#FFFFFF",
+            "foreground": "#37352F",
+            "sidebar-background": "#F7F6F3",
+            "accent": "#155DFF",
+            "muted": "#787774",
+            "border": "#E9E9E7"
+        },
+        "typography": {
+            "font-family": "system-ui",
+            "font-size-base": "14px"
+        },
+        "spacing": {
+            "sidebar-width": "240px"
+        }
+    }))
+    .unwrap()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::theme::defaults::*;
+    use crate::theme::get_theme;
+    use std::fs;
+    use tempfile::TempDir;
+
+    fn setup_vault_with_themes(dir: &TempDir) -> String {
+        let vault = dir.path().join("vault");
+        let themes_dir = vault.join("_themes");
+        fs::create_dir_all(&themes_dir).unwrap();
+        fs::write(themes_dir.join("default.json"), DEFAULT_THEME).unwrap();
+        fs::write(themes_dir.join("dark.json"), DARK_THEME).unwrap();
+        vault.to_string_lossy().to_string()
+    }
+
+    #[test]
+    fn test_create_theme_copies_source() {
+        let dir = TempDir::new().unwrap();
+        let vault = setup_vault_with_themes(&dir);
+        let new_id = create_theme(&vault, Some("default")).unwrap();
+        assert_eq!(new_id, "untitled");
+
+        let theme = get_theme(&vault, &new_id).unwrap();
+        assert_eq!(theme.name, "Untitled Theme");
+        assert!(!theme.colors.is_empty());
+    }
+
+    #[test]
+    fn test_create_theme_increments_id() {
+        let dir = TempDir::new().unwrap();
+        let vault = setup_vault_with_themes(&dir);
+
+        let id1 = create_theme(&vault, None).unwrap();
+        assert_eq!(id1, "untitled");
+
+        let id2 = create_theme(&vault, None).unwrap();
+        assert_eq!(id2, "untitled-2");
+    }
+
+    #[test]
+    fn test_create_vault_theme_creates_md_file() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        let path = create_vault_theme(vp, Some("My Theme")).unwrap();
+        assert!(std::path::Path::new(&path).exists());
+        let content = fs::read_to_string(&path).unwrap();
+        assert!(content.contains("Is A: Theme"));
+        assert!(content.contains("# My Theme"));
+        assert!(content.contains("background:"));
+    }
+
+    #[test]
+    fn test_create_vault_theme_default_name() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        let path = create_vault_theme(vp, None).unwrap();
+        let content = fs::read_to_string(&path).unwrap();
+        assert!(content.contains("# Untitled Theme"));
+    }
+
+    #[test]
+    fn test_create_vault_theme_avoids_conflicts() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        let p1 = create_vault_theme(vp, Some("Custom")).unwrap();
+        let p2 = create_vault_theme(vp, Some("Custom")).unwrap();
+        assert_ne!(p1, p2);
+    }
+
+    #[test]
+    fn test_slugify() {
+        assert_eq!(slugify("My Cool Theme"), "my-cool-theme");
+        assert_eq!(slugify("default"), "default");
+        assert_eq!(slugify("Dark Mode!"), "dark-mode");
+    }
+}

src-tauri/src/theme/defaults.rs

@@ -0,0 +1,343 @@
+/// Content for the built-in default (light) theme.
+pub const DEFAULT_THEME: &str = r##"{
+  "name": "Default",
+  "description": "Light theme with warm, paper-like tones",
+  "colors": {
+    "background": "#FFFFFF",
+    "foreground": "#37352F",
+    "card": "#FFFFFF",
+    "popover": "#FFFFFF",
+    "primary": "#155DFF",
+    "primary-foreground": "#FFFFFF",
+    "secondary": "#EBEBEA",
+    "secondary-foreground": "#37352F",
+    "muted": "#F0F0EF",
+    "muted-foreground": "#787774",
+    "accent": "#EBEBEA",
+    "accent-foreground": "#37352F",
+    "destructive": "#E03E3E",
+    "border": "#E9E9E7",
+    "input": "#E9E9E7",
+    "ring": "#155DFF",
+    "sidebar-background": "#F7F6F3",
+    "sidebar-foreground": "#37352F",
+    "sidebar-border": "#E9E9E7",
+    "sidebar-accent": "#EBEBEA"
+  },
+  "typography": {
+    "font-family": "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
+    "font-size-base": "14px"
+  },
+  "spacing": {
+    "sidebar-width": "250px"
+  }
+}"##;
+
+/// Content for the built-in dark theme.
+pub const DARK_THEME: &str = r##"{
+  "name": "Dark",
+  "description": "Dark variant with deep navy tones",
+  "colors": {
+    "background": "#0f0f1a",
+    "foreground": "#e0e0e0",
+    "card": "#16162a",
+    "popover": "#1e1e3a",
+    "primary": "#155DFF",
+    "primary-foreground": "#FFFFFF",
+    "secondary": "#2a2a4a",
+    "secondary-foreground": "#e0e0e0",
+    "muted": "#1e1e3a",
+    "muted-foreground": "#888888",
+    "accent": "#2a2a4a",
+    "accent-foreground": "#e0e0e0",
+    "destructive": "#f44336",
+    "border": "#2a2a4a",
+    "input": "#2a2a4a",
+    "ring": "#155DFF",
+    "sidebar-background": "#1a1a2e",
+    "sidebar-foreground": "#e0e0e0",
+    "sidebar-border": "#2a2a4a",
+    "sidebar-accent": "#2a2a4a"
+  },
+  "typography": {
+    "font-family": "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
+    "font-size-base": "14px"
+  },
+  "spacing": {
+    "sidebar-width": "250px"
+  }
+}"##;
+
+/// Content for the built-in minimal theme.
+pub const MINIMAL_THEME: &str = r##"{
+  "name": "Minimal",
+  "description": "High contrast, minimal chrome",
+  "colors": {
+    "background": "#FAFAFA",
+    "foreground": "#111111",
+    "card": "#FFFFFF",
+    "popover": "#FFFFFF",
+    "primary": "#000000",
+    "primary-foreground": "#FFFFFF",
+    "secondary": "#F0F0F0",
+    "secondary-foreground": "#111111",
+    "muted": "#F5F5F5",
+    "muted-foreground": "#666666",
+    "accent": "#F0F0F0",
+    "accent-foreground": "#111111",
+    "destructive": "#CC0000",
+    "border": "#E0E0E0",
+    "input": "#E0E0E0",
+    "ring": "#000000",
+    "sidebar-background": "#F5F5F5",
+    "sidebar-foreground": "#111111",
+    "sidebar-border": "#E0E0E0",
+    "sidebar-accent": "#E8E8E8"
+  },
+  "typography": {
+    "font-family": "'SF Mono', 'Menlo', monospace",
+    "font-size-base": "13px"
+  },
+  "spacing": {
+    "sidebar-width": "220px"
+  }
+}"##;
+
+/// CSS variable key-value pairs for the default light vault theme.
+pub const DEFAULT_VAULT_THEME_VARS: [(&str, &str); 46] = [
+    // shadcn/ui base
+    ("background", "#FFFFFF"),
+    ("foreground", "#37352F"),
+    ("card", "#FFFFFF"),
+    ("popover", "#FFFFFF"),
+    ("primary", "#155DFF"),
+    ("primary-foreground", "#FFFFFF"),
+    ("secondary", "#EBEBEA"),
+    ("secondary-foreground", "#37352F"),
+    ("muted", "#F0F0EF"),
+    ("muted-foreground", "#787774"),
+    ("accent", "#EBEBEA"),
+    ("accent-foreground", "#37352F"),
+    ("destructive", "#E03E3E"),
+    ("border", "#E9E9E7"),
+    ("input", "#E9E9E7"),
+    ("ring", "#155DFF"),
+    ("sidebar", "#F7F6F3"),
+    ("sidebar-foreground", "#37352F"),
+    ("sidebar-border", "#E9E9E7"),
+    ("sidebar-accent", "#EBEBEA"),
+    // Text hierarchy
+    ("text-primary", "#37352F"),
+    ("text-secondary", "#787774"),
+    ("text-muted", "#B4B4B4"),
+    ("text-heading", "#37352F"),
+    // Backgrounds
+    ("bg-primary", "#FFFFFF"),
+    ("bg-sidebar", "#F7F6F3"),
+    ("bg-hover", "#EBEBEA"),
+    ("bg-hover-subtle", "#F0F0EF"),
+    ("bg-selected", "#E8F4FE"),
+    ("border-primary", "#E9E9E7"),
+    // Accent colours
+    ("accent-blue", "#155DFF"),
+    ("accent-green", "#00B38B"),
+    ("accent-orange", "#D9730D"),
+    ("accent-red", "#E03E3E"),
+    ("accent-purple", "#A932FF"),
+    ("accent-yellow", "#F0B100"),
+    ("accent-blue-light", "#155DFF14"),
+    ("accent-green-light", "#00B38B14"),
+    ("accent-purple-light", "#A932FF14"),
+    ("accent-red-light", "#E03E3E14"),
+    ("accent-yellow-light", "#F0B10014"),
+    // Typography
+    (
+        "font-family",
+        "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
+    ),
+    ("font-size-base", "14px"),
+    // Editor
+    ("editor-font-size", "16"),
+    ("editor-line-height", "1.5"),
+    ("editor-max-width", "720"),
+];
+
+/// Vault-based theme note for the built-in Default theme.
+pub const DEFAULT_VAULT_THEME: &str = "---\n\
+Is A: Theme\n\
+Description: Light theme with warm, paper-like tones\n\
+background: \"#FFFFFF\"\n\
+foreground: \"#37352F\"\n\
+card: \"#FFFFFF\"\n\
+popover: \"#FFFFFF\"\n\
+primary: \"#155DFF\"\n\
+primary-foreground: \"#FFFFFF\"\n\
+secondary: \"#EBEBEA\"\n\
+secondary-foreground: \"#37352F\"\n\
+muted: \"#F0F0EF\"\n\
+muted-foreground: \"#787774\"\n\
+accent: \"#EBEBEA\"\n\
+accent-foreground: \"#37352F\"\n\
+destructive: \"#E03E3E\"\n\
+border: \"#E9E9E7\"\n\
+input: \"#E9E9E7\"\n\
+ring: \"#155DFF\"\n\
+sidebar: \"#F7F6F3\"\n\
+sidebar-foreground: \"#37352F\"\n\
+sidebar-border: \"#E9E9E7\"\n\
+sidebar-accent: \"#EBEBEA\"\n\
+text-primary: \"#37352F\"\n\
+text-secondary: \"#787774\"\n\
+text-muted: \"#B4B4B4\"\n\
+text-heading: \"#37352F\"\n\
+bg-primary: \"#FFFFFF\"\n\
+bg-sidebar: \"#F7F6F3\"\n\
+bg-hover: \"#EBEBEA\"\n\
+bg-hover-subtle: \"#F0F0EF\"\n\
+bg-selected: \"#E8F4FE\"\n\
+border-primary: \"#E9E9E7\"\n\
+accent-blue: \"#155DFF\"\n\
+accent-green: \"#00B38B\"\n\
+accent-orange: \"#D9730D\"\n\
+accent-red: \"#E03E3E\"\n\
+accent-purple: \"#A932FF\"\n\
+accent-yellow: \"#F0B100\"\n\
+accent-blue-light: \"#155DFF14\"\n\
+accent-green-light: \"#00B38B14\"\n\
+accent-purple-light: \"#A932FF14\"\n\
+accent-red-light: \"#E03E3E14\"\n\
+accent-yellow-light: \"#F0B10014\"\n\
+font-family: \"'Inter', -apple-system, BlinkMacSystemFont, sans-serif\"\n\
+font-size-base: 14px\n\
+editor-font-size: 16\n\
+editor-line-height: 1.5\n\
+editor-max-width: 720\n\
+---\n\
+\n\
+# Default Theme\n\
+\n\
+The default light theme for Laputa. Clean and warm, inspired by Notion.\n";
+
+/// Vault-based theme note for the built-in Dark theme.
+pub const DARK_VAULT_THEME: &str = "---\n\
+Is A: Theme\n\
+Description: Dark variant with deep navy tones\n\
+background: \"#0f0f1a\"\n\
+foreground: \"#e0e0e0\"\n\
+card: \"#16162a\"\n\
+popover: \"#1e1e3a\"\n\
+primary: \"#155DFF\"\n\
+primary-foreground: \"#FFFFFF\"\n\
+secondary: \"#2a2a4a\"\n\
+secondary-foreground: \"#e0e0e0\"\n\
+muted: \"#1e1e3a\"\n\
+muted-foreground: \"#888888\"\n\
+accent: \"#2a2a4a\"\n\
+accent-foreground: \"#e0e0e0\"\n\
+destructive: \"#f44336\"\n\
+border: \"#2a2a4a\"\n\
+input: \"#2a2a4a\"\n\
+ring: \"#155DFF\"\n\
+sidebar: \"#1a1a2e\"\n\
+sidebar-foreground: \"#e0e0e0\"\n\
+sidebar-border: \"#2a2a4a\"\n\
+sidebar-accent: \"#2a2a4a\"\n\
+text-primary: \"#e0e0e0\"\n\
+text-secondary: \"#888888\"\n\
+text-muted: \"#666666\"\n\
+text-heading: \"#e0e0e0\"\n\
+bg-primary: \"#0f0f1a\"\n\
+bg-sidebar: \"#1a1a2e\"\n\
+bg-hover: \"#2a2a4a\"\n\
+bg-hover-subtle: \"#1e1e3a\"\n\
+bg-selected: \"#155DFF22\"\n\
+border-primary: \"#2a2a4a\"\n\
+accent-blue: \"#155DFF\"\n\
+accent-green: \"#00B38B\"\n\
+accent-orange: \"#D9730D\"\n\
+accent-red: \"#f44336\"\n\
+accent-purple: \"#A932FF\"\n\
+accent-yellow: \"#F0B100\"\n\
+accent-blue-light: \"#155DFF33\"\n\
+accent-green-light: \"#00B38B33\"\n\
+accent-purple-light: \"#A932FF33\"\n\
+accent-red-light: \"#f4433633\"\n\
+accent-yellow-light: \"#F0B10033\"\n\
+font-family: \"'Inter', -apple-system, BlinkMacSystemFont, sans-serif\"\n\
+font-size-base: 14px\n\
+editor-font-size: 16\n\
+editor-line-height: 1.5\n\
+editor-max-width: 720\n\
+---\n\
+\n\
+# Dark Theme\n\
+\n\
+A dark theme with deep navy tones for comfortable night-time reading.\n";
+
+/// Vault-based theme note for the built-in Minimal theme.
+pub const MINIMAL_VAULT_THEME: &str = "---\n\
+Is A: Theme\n\
+Description: High contrast, minimal chrome\n\
+background: \"#FAFAFA\"\n\
+foreground: \"#111111\"\n\
+card: \"#FFFFFF\"\n\
+popover: \"#FFFFFF\"\n\
+primary: \"#000000\"\n\
+primary-foreground: \"#FFFFFF\"\n\
+secondary: \"#F0F0F0\"\n\
+secondary-foreground: \"#111111\"\n\
+muted: \"#F5F5F5\"\n\
+muted-foreground: \"#666666\"\n\
+accent: \"#F0F0F0\"\n\
+accent-foreground: \"#111111\"\n\
+destructive: \"#CC0000\"\n\
+border: \"#E0E0E0\"\n\
+input: \"#E0E0E0\"\n\
+ring: \"#000000\"\n\
+sidebar: \"#F5F5F5\"\n\
+sidebar-foreground: \"#111111\"\n\
+sidebar-border: \"#E0E0E0\"\n\
+sidebar-accent: \"#E8E8E8\"\n\
+text-primary: \"#111111\"\n\
+text-secondary: \"#666666\"\n\
+text-muted: \"#999999\"\n\
+text-heading: \"#111111\"\n\
+bg-primary: \"#FAFAFA\"\n\
+bg-sidebar: \"#F5F5F5\"\n\
+bg-hover: \"#EBEBEB\"\n\
+bg-hover-subtle: \"#F5F5F5\"\n\
+bg-selected: \"#00000014\"\n\
+border-primary: \"#E0E0E0\"\n\
+accent-blue: \"#000000\"\n\
+accent-green: \"#006600\"\n\
+accent-orange: \"#996600\"\n\
+accent-red: \"#CC0000\"\n\
+accent-purple: \"#660099\"\n\
+accent-yellow: \"#996600\"\n\
+accent-blue-light: \"#00000014\"\n\
+accent-green-light: \"#00660014\"\n\
+accent-purple-light: \"#66009914\"\n\
+accent-red-light: \"#CC000014\"\n\
+accent-yellow-light: \"#99660014\"\n\
+font-family: \"'SF Mono', 'Menlo', monospace\"\n\
+font-size-base: 13px\n\
+editor-font-size: 15\n\
+editor-line-height: 1.6\n\
+editor-max-width: 680\n\
+---\n\
+\n\
+# Minimal Theme\n\
+\n\
+High contrast, minimal chrome. Monospace typography throughout.\n";
+
+/// Type definition for the Theme note type.
+pub const THEME_TYPE_DEFINITION: &str = "---\n\
+Is A: Type\n\
+icon: palette\n\
+color: purple\n\
+order: 50\n\
+---\n\
+\n\
+# Theme\n\
+\n\
+A visual theme for Laputa. Each theme defines CSS custom properties that control colors, typography, and spacing.\n";

src-tauri/src/theme/mod.rs

@@ -0,0 +1,269 @@
+mod create;
+pub mod defaults;
+mod seed;
+
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::fs;
+use std::path::Path;
+
+pub use create::{create_theme, create_vault_theme};
+pub use defaults::*;
+pub use seed::{
+    ensure_theme_type_definition, ensure_vault_themes, restore_default_themes, seed_default_themes,
+    seed_vault_themes,
+};
+
+/// A theme file parsed from _themes/*.json in the vault.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ThemeFile {
+    /// Filename stem (e.g. "default" for _themes/default.json)
+    #[serde(default)]
+    pub id: String,
+    pub name: String,
+    #[serde(default)]
+    pub description: String,
+    #[serde(default)]
+    pub colors: HashMap<String, String>,
+    #[serde(default)]
+    pub typography: HashMap<String, String>,
+    #[serde(default)]
+    pub spacing: HashMap<String, String>,
+}
+
+/// Vault-level settings stored in .laputa/settings.json (git-tracked).
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct VaultSettings {
+    #[serde(default)]
+    pub theme: Option<String>,
+}
+
+/// List all theme files in _themes/ directory of the vault.
+/// Seeds built-in themes if the directory is missing.
+pub fn list_themes(vault_path: &str) -> Result<Vec<ThemeFile>, String> {
+    let themes_dir = Path::new(vault_path).join("_themes");
+    if !themes_dir.is_dir() {
+        seed_default_themes(vault_path);
+    }
+    if !themes_dir.is_dir() {
+        return Ok(Vec::new());
+    }
+
+    let mut themes = Vec::new();
+    let entries =
+        fs::read_dir(&themes_dir).map_err(|e| format!("Failed to read _themes directory: {e}"))?;
+
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if path.extension().and_then(|e| e.to_str()) != Some("json") {
+            continue;
+        }
+        match parse_theme_file(&path) {
+            Ok(theme) => themes.push(theme),
+            Err(e) => log::warn!("Skipping theme file {}: {e}", path.display()),
+        }
+    }
+
+    themes.sort_by(|a, b| a.name.cmp(&b.name));
+    Ok(themes)
+}
+
+/// Parse a single theme JSON file.
+fn parse_theme_file(path: &Path) -> Result<ThemeFile, String> {
+    let id = path
+        .file_stem()
+        .and_then(|s| s.to_str())
+        .map(|s| s.to_string())
+        .ok_or_else(|| "Invalid theme filename".to_string())?;
+
+    let content =
+        fs::read_to_string(path).map_err(|e| format!("Failed to read {}: {e}", path.display()))?;
+
+    let mut theme: ThemeFile = serde_json::from_str(&content)
+        .map_err(|e| format!("Failed to parse {}: {e}", path.display()))?;
+
+    theme.id = id;
+    Ok(theme)
+}
+
+/// Read vault-level settings from .laputa/settings.json.
+pub fn get_vault_settings(vault_path: &str) -> Result<VaultSettings, String> {
+    let settings_path = Path::new(vault_path).join(".laputa").join("settings.json");
+    if !settings_path.exists() {
+        return Ok(VaultSettings::default());
+    }
+    let content = fs::read_to_string(&settings_path)
+        .map_err(|e| format!("Failed to read vault settings: {e}"))?;
+    serde_json::from_str(&content).map_err(|e| format!("Failed to parse vault settings: {e}"))
+}
+
+/// Save vault-level settings to .laputa/settings.json.
+pub fn save_vault_settings(vault_path: &str, settings: VaultSettings) -> Result<(), String> {
+    let laputa_dir = Path::new(vault_path).join(".laputa");
+    fs::create_dir_all(&laputa_dir)
+        .map_err(|e| format!("Failed to create .laputa directory: {e}"))?;
+
+    let json = serde_json::to_string_pretty(&settings)
+        .map_err(|e| format!("Failed to serialize vault settings: {e}"))?;
+    fs::write(laputa_dir.join("settings.json"), json)
+        .map_err(|e| format!("Failed to write vault settings: {e}"))
+}
+
+/// Set the active theme in vault settings. Pass `None` to clear.
+pub fn set_active_theme(vault_path: &str, theme_id: Option<&str>) -> Result<(), String> {
+    let mut settings = get_vault_settings(vault_path)?;
+    settings.theme = theme_id.map(|s| s.to_string());
+    save_vault_settings(vault_path, settings)
+}
+
+/// Read a single theme file by ID from the vault's _themes/ directory.
+pub fn get_theme(vault_path: &str, theme_id: &str) -> Result<ThemeFile, String> {
+    let path = Path::new(vault_path)
+        .join("_themes")
+        .join(format!("{theme_id}.json"));
+    if !path.exists() {
+        return Err(format!("Theme not found: {theme_id}"));
+    }
+    parse_theme_file(&path)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+    use tempfile::TempDir;
+
+    fn setup_vault_with_themes(dir: &TempDir) -> String {
+        let vault = dir.path().join("vault");
+        let themes_dir = vault.join("_themes");
+        fs::create_dir_all(&themes_dir).unwrap();
+        fs::write(themes_dir.join("default.json"), DEFAULT_THEME).unwrap();
+        fs::write(themes_dir.join("dark.json"), DARK_THEME).unwrap();
+        vault.to_string_lossy().to_string()
+    }
+
+    #[test]
+    fn test_list_themes_returns_sorted_list() {
+        let dir = TempDir::new().unwrap();
+        let vault = setup_vault_with_themes(&dir);
+        let themes = list_themes(&vault).unwrap();
+        assert_eq!(themes.len(), 2);
+        assert_eq!(themes[0].id, "dark");
+        assert_eq!(themes[1].id, "default");
+    }
+
+    #[test]
+    fn test_list_themes_seeds_defaults_when_no_dir() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("empty-vault");
+        fs::create_dir_all(&vault).unwrap();
+        let themes = list_themes(vault.to_str().unwrap()).unwrap();
+        assert_eq!(themes.len(), 3);
+        let names: Vec<&str> = themes.iter().map(|t| t.name.as_str()).collect();
+        assert!(names.contains(&"Default"));
+        assert!(names.contains(&"Dark"));
+        assert!(names.contains(&"Minimal"));
+    }
+
+    #[test]
+    fn test_get_theme_by_id() {
+        let dir = TempDir::new().unwrap();
+        let vault = setup_vault_with_themes(&dir);
+        let theme = get_theme(&vault, "default").unwrap();
+        assert_eq!(theme.name, "Default");
+        assert!(!theme.colors.is_empty());
+    }
+
+    #[test]
+    fn test_get_theme_not_found() {
+        let dir = TempDir::new().unwrap();
+        let vault = setup_vault_with_themes(&dir);
+        let result = get_theme(&vault, "nonexistent");
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_vault_settings_roundtrip() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        let settings = get_vault_settings(vp).unwrap();
+        assert!(settings.theme.is_none());
+
+        set_active_theme(vp, Some("dark")).unwrap();
+        let settings = get_vault_settings(vp).unwrap();
+        assert_eq!(settings.theme.as_deref(), Some("dark"));
+
+        set_active_theme(vp, None).unwrap();
+        let settings = get_vault_settings(vp).unwrap();
+        assert_eq!(settings.theme, None);
+    }
+
+    #[test]
+    fn test_vault_settings_creates_laputa_dir() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        assert!(!vault.join(".laputa").exists());
+        save_vault_settings(
+            vp,
+            VaultSettings {
+                theme: Some("light".into()),
+            },
+        )
+        .unwrap();
+        assert!(vault.join(".laputa").join("settings.json").exists());
+    }
+
+    #[test]
+    fn test_parse_all_builtin_themes() {
+        for (name, content) in [
+            ("default", DEFAULT_THEME),
+            ("dark", DARK_THEME),
+            ("minimal", MINIMAL_THEME),
+        ] {
+            let theme: ThemeFile = serde_json::from_str(content)
+                .unwrap_or_else(|e| panic!("Failed to parse {name} theme: {e}"));
+            assert!(!theme.name.is_empty(), "{name} theme should have a name");
+            assert!(!theme.colors.is_empty(), "{name} theme should have colors");
+        }
+    }
+
+    #[test]
+    fn test_list_themes_ignores_non_json_files() {
+        let dir = TempDir::new().unwrap();
+        let vault = setup_vault_with_themes(&dir);
+        let themes_dir = Path::new(&vault).join("_themes");
+        fs::write(themes_dir.join("readme.txt"), "not a theme").unwrap();
+        fs::write(themes_dir.join(".DS_Store"), "").unwrap();
+
+        let themes = list_themes(&vault).unwrap();
+        assert_eq!(themes.len(), 2);
+    }
+
+    #[test]
+    fn test_list_themes_skips_malformed_json() {
+        let dir = TempDir::new().unwrap();
+        let vault = setup_vault_with_themes(&dir);
+        let themes_dir = Path::new(&vault).join("_themes");
+        fs::write(themes_dir.join("broken.json"), "not valid json{{{").unwrap();
+
+        let themes = list_themes(&vault).unwrap();
+        assert_eq!(themes.len(), 2);
+    }
+
+    #[test]
+    fn test_vault_theme_content_contains_all_vars() {
+        let content = DEFAULT_VAULT_THEME;
+        assert!(content.contains("background:"));
+        assert!(content.contains("primary:"));
+        assert!(content.contains("sidebar:"));
+        assert!(content.contains("text-primary:"));
+        assert!(content.contains("accent-blue:"));
+        assert!(content.contains("editor-font-size:"));
+    }
+}

src-tauri/src/theme/seed.rs

@@ -0,0 +1,344 @@
+use std::fs;
+use std::path::Path;
+
+use super::defaults::*;
+
+/// Create `dir` and write each `(filename, content)` pair if the directory doesn't exist yet.
+fn seed_dir_with_files(dir: &Path, files: &[(&str, &str)], log_msg: &str) {
+    if dir.is_dir() {
+        return;
+    }
+    if fs::create_dir_all(dir).is_err() {
+        return;
+    }
+    for (name, content) in files {
+        let _ = fs::write(dir.join(name), content);
+    }
+    log::info!("{log_msg}");
+}
+
+/// Seed the `_themes/` directory with built-in themes if it doesn't exist yet.
+/// Safe to call multiple times — only writes files that are missing.
+pub fn seed_default_themes(vault_path: &str) {
+    seed_dir_with_files(
+        &Path::new(vault_path).join("_themes"),
+        &[
+            ("default.json", DEFAULT_THEME),
+            ("dark.json", DARK_THEME),
+            ("minimal.json", MINIMAL_THEME),
+        ],
+        "Seeded _themes/ with built-in themes",
+    );
+}
+
+/// Seed the vault `theme/` directory with built-in vault-based theme notes.
+/// Per-file idempotent: creates the directory if missing, writes each default
+/// file only when it doesn't exist or is empty (corrupt). Never overwrites
+/// existing files that have content.
+pub fn seed_vault_themes(vault_path: &str) {
+    let theme_dir = Path::new(vault_path).join("theme");
+    if fs::create_dir_all(&theme_dir).is_err() {
+        return;
+    }
+    let defaults: &[(&str, &str)] = &[
+        ("default.md", DEFAULT_VAULT_THEME),
+        ("dark.md", DARK_VAULT_THEME),
+        ("minimal.md", MINIMAL_VAULT_THEME),
+    ];
+    let mut seeded = false;
+    for (name, content) in defaults {
+        let path = theme_dir.join(name);
+        let needs_write = !path.exists() || fs::metadata(&path).map_or(true, |m| m.len() == 0);
+        if needs_write {
+            let _ = fs::write(&path, content);
+            seeded = true;
+        }
+    }
+    if seeded {
+        log::info!("Seeded theme/ with built-in vault themes");
+    }
+}
+
+/// Ensure vault theme files exist. Returns an error if the theme directory
+/// cannot be created (e.g. read-only filesystem).
+pub fn ensure_vault_themes(vault_path: &str) -> Result<(), String> {
+    let theme_dir = Path::new(vault_path).join("theme");
+    fs::create_dir_all(&theme_dir).map_err(|e| format!("Failed to create theme directory: {e}"))?;
+    let defaults: &[(&str, &str)] = &[
+        ("default.md", DEFAULT_VAULT_THEME),
+        ("dark.md", DARK_VAULT_THEME),
+        ("minimal.md", MINIMAL_VAULT_THEME),
+    ];
+    for (name, content) in defaults {
+        let path = theme_dir.join(name);
+        let needs_write = !path.exists() || fs::metadata(&path).map_or(true, |m| m.len() == 0);
+        if needs_write {
+            fs::write(&path, content).map_err(|e| format!("Failed to write theme/{name}: {e}"))?;
+        }
+    }
+    Ok(())
+}
+
+/// Restore default themes for a vault: seeds both `_themes/` (JSON) and
+/// `theme/` (markdown notes). Per-file idempotent — never overwrites files
+/// that already have content. Returns an error on read-only filesystems.
+pub fn restore_default_themes(vault_path: &str) -> Result<String, String> {
+    // Seed _themes/ JSON files (per-file idempotent)
+    let themes_dir = Path::new(vault_path).join("_themes");
+    fs::create_dir_all(&themes_dir)
+        .map_err(|e| format!("Failed to create _themes directory: {e}"))?;
+    let json_defaults: &[(&str, &str)] = &[
+        ("default.json", DEFAULT_THEME),
+        ("dark.json", DARK_THEME),
+        ("minimal.json", MINIMAL_THEME),
+    ];
+    for (name, content) in json_defaults {
+        let path = themes_dir.join(name);
+        let needs_write = !path.exists() || fs::metadata(&path).map_or(true, |m| m.len() == 0);
+        if needs_write {
+            fs::write(&path, content)
+                .map_err(|e| format!("Failed to write _themes/{name}: {e}"))?;
+        }
+    }
+
+    // Seed theme/ markdown notes (reuses ensure_vault_themes for consistency)
+    ensure_vault_themes(vault_path)?;
+
+    // Seed type/theme.md so the Theme type has an icon and label in the sidebar
+    ensure_theme_type_definition(vault_path)?;
+
+    Ok("Default themes restored".to_string())
+}
+
+/// Create `type/theme.md` if it doesn't exist (gives the Theme type a sidebar icon/color).
+pub fn ensure_theme_type_definition(vault_path: &str) -> Result<(), String> {
+    let type_dir = Path::new(vault_path).join("type");
+    fs::create_dir_all(&type_dir).map_err(|e| format!("Failed to create type directory: {e}"))?;
+    let path = type_dir.join("theme.md");
+    let needs_write = !path.exists() || fs::metadata(&path).map_or(true, |m| m.len() == 0);
+    if needs_write {
+        fs::write(&path, THEME_TYPE_DEFINITION)
+            .map_err(|e| format!("Failed to write type/theme.md: {e}"))?;
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+    use tempfile::TempDir;
+
+    #[test]
+    fn test_seed_vault_themes_creates_theme_dir() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        assert!(!vault.join("theme").exists());
+        seed_vault_themes(vp);
+        assert!(vault.join("theme").is_dir());
+        assert!(vault.join("theme").join("default.md").exists());
+        assert!(vault.join("theme").join("dark.md").exists());
+        assert!(vault.join("theme").join("minimal.md").exists());
+    }
+
+    #[test]
+    fn test_seed_vault_themes_is_idempotent() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        seed_vault_themes(vp);
+        seed_vault_themes(vp); // second call should be a no-op
+        assert!(vault.join("theme").join("default.md").exists());
+    }
+
+    #[test]
+    fn test_seed_vault_themes_writes_missing_files_in_existing_dir() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        let theme_dir = vault.join("theme");
+        fs::create_dir_all(&theme_dir).unwrap();
+        fs::write(theme_dir.join("default.md"), DEFAULT_VAULT_THEME).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        seed_vault_themes(vp);
+        assert!(theme_dir.join("dark.md").exists());
+        assert!(theme_dir.join("minimal.md").exists());
+    }
+
+    #[test]
+    fn test_seed_vault_themes_reseeds_empty_files() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        let theme_dir = vault.join("theme");
+        fs::create_dir_all(&theme_dir).unwrap();
+        fs::write(theme_dir.join("default.md"), "").unwrap();
+        let vp = vault.to_str().unwrap();
+
+        seed_vault_themes(vp);
+        let content = fs::read_to_string(theme_dir.join("default.md")).unwrap();
+        assert!(content.contains("Is A: Theme"));
+    }
+
+    #[test]
+    fn test_seed_vault_themes_preserves_existing_content() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        let theme_dir = vault.join("theme");
+        fs::create_dir_all(&theme_dir).unwrap();
+        let custom = "---\nIs A: Theme\nbackground: \"#FF0000\"\n---\n# Custom\n";
+        fs::write(theme_dir.join("default.md"), custom).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        seed_vault_themes(vp);
+        let content = fs::read_to_string(theme_dir.join("default.md")).unwrap();
+        assert!(
+            content.contains("#FF0000"),
+            "existing content must be preserved"
+        );
+    }
+
+    #[test]
+    fn test_ensure_vault_themes_creates_dir_and_defaults() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        ensure_vault_themes(vp).unwrap();
+        assert!(vault.join("theme").is_dir());
+        assert!(vault.join("theme").join("default.md").exists());
+        assert!(vault.join("theme").join("dark.md").exists());
+        assert!(vault.join("theme").join("minimal.md").exists());
+    }
+
+    #[test]
+    fn test_ensure_vault_themes_reseeds_empty_files() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        let theme_dir = vault.join("theme");
+        fs::create_dir_all(&theme_dir).unwrap();
+        fs::write(theme_dir.join("default.md"), "").unwrap();
+        let vp = vault.to_str().unwrap();
+
+        ensure_vault_themes(vp).unwrap();
+        let content = fs::read_to_string(theme_dir.join("default.md")).unwrap();
+        assert!(content.contains("Is A: Theme"));
+    }
+
+    #[test]
+    fn test_ensure_vault_themes_preserves_custom_themes() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        let theme_dir = vault.join("theme");
+        fs::create_dir_all(&theme_dir).unwrap();
+        let custom = "---\nIs A: Theme\nbackground: \"#123456\"\n---\n";
+        fs::write(theme_dir.join("default.md"), custom).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        ensure_vault_themes(vp).unwrap();
+        let content = fs::read_to_string(theme_dir.join("default.md")).unwrap();
+        assert!(content.contains("#123456"));
+    }
+
+    #[test]
+    fn test_restore_default_themes_creates_both_dirs() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        let msg = restore_default_themes(vp).unwrap();
+        assert_eq!(msg, "Default themes restored");
+        assert!(vault.join("_themes").join("default.json").exists());
+        assert!(vault.join("_themes").join("dark.json").exists());
+        assert!(vault.join("_themes").join("minimal.json").exists());
+        assert!(vault.join("theme").join("default.md").exists());
+        assert!(vault.join("theme").join("dark.md").exists());
+        assert!(vault.join("theme").join("minimal.md").exists());
+        assert!(
+            vault.join("type").join("theme.md").exists(),
+            "restore must create type/theme.md"
+        );
+        let type_content = fs::read_to_string(vault.join("type").join("theme.md")).unwrap();
+        assert!(type_content.contains("Is A: Type"));
+        assert!(type_content.contains("icon: palette"));
+    }
+
+    #[test]
+    fn test_ensure_theme_type_definition_creates_file() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        ensure_theme_type_definition(vp).unwrap();
+        let path = vault.join("type").join("theme.md");
+        assert!(path.exists());
+        let content = fs::read_to_string(&path).unwrap();
+        assert!(content.contains("Is A: Type"));
+        assert!(content.contains("icon: palette"));
+    }
+
+    #[test]
+    fn test_ensure_theme_type_definition_is_idempotent() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        let type_dir = vault.join("type");
+        fs::create_dir_all(&type_dir).unwrap();
+        let custom = "---\nIs A: Type\nicon: swatches\ncolor: green\n---\n# Theme\n";
+        fs::write(type_dir.join("theme.md"), custom).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        ensure_theme_type_definition(vp).unwrap();
+        let content = fs::read_to_string(type_dir.join("theme.md")).unwrap();
+        assert!(
+            content.contains("swatches"),
+            "existing content must be preserved"
+        );
+    }
+
+    #[test]
+    fn test_restore_default_themes_is_idempotent() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        restore_default_themes(vp).unwrap();
+        let custom = "---\nIs A: Theme\nbackground: \"#CUSTOM\"\n---\n";
+        fs::write(vault.join("theme").join("default.md"), custom).unwrap();
+
+        restore_default_themes(vp).unwrap();
+        let content = fs::read_to_string(vault.join("theme").join("default.md")).unwrap();
+        assert!(
+            content.contains("#CUSTOM"),
+            "must not overwrite existing content"
+        );
+    }
+
+    #[test]
+    fn test_restore_default_themes_fills_partial_state() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        let themes_dir = vault.join("_themes");
+        let theme_dir = vault.join("theme");
+        fs::create_dir_all(&themes_dir).unwrap();
+        fs::create_dir_all(&theme_dir).unwrap();
+        fs::write(themes_dir.join("default.json"), DEFAULT_THEME).unwrap();
+        fs::write(theme_dir.join("default.md"), DEFAULT_VAULT_THEME).unwrap();
+        let vp = vault.to_str().unwrap();
+
+        restore_default_themes(vp).unwrap();
+        assert!(themes_dir.join("dark.json").exists());
+        assert!(themes_dir.join("minimal.json").exists());
+        assert!(theme_dir.join("dark.md").exists());
+        assert!(theme_dir.join("minimal.md").exists());
+        let content = fs::read_to_string(theme_dir.join("default.md")).unwrap();
+        assert!(content.contains("Light theme with warm"));
+    }
+}

src-tauri/src/vault/cache.rs

@@ -7,7 +7,7 @@ use super::{parse_md_file, scan_vault, VaultEntry};
 // --- Vault Cache ---
 
 /// Bump this when VaultEntry fields change to force a full rescan.
-const CACHE_VERSION: u32 = 4;
+const CACHE_VERSION: u32 = 5;
 
 #[derive(Debug, Serialize, Deserialize)]
 struct VaultCache {
@@ -79,15 +79,10 @@ fn git_changed_files(vault: &Path, from_hash: &str, to_hash: &str) -> Vec<String
         .map(|s| collect_md_paths_from_diff(&s))
         .unwrap_or_default();
 
-    // Use ls-files for untracked files so that newly-seeded directories are picked up
-    // as individual files rather than as a single "?? dirname/" entry.
+    // Include uncommitted changes (modified, staged, and untracked files).
     let uncommitted = git_uncommitted_files(vault);
-    // Also include modified-but-unstaged files via status --porcelain.
-    let modified = run_git(vault, &["status", "--porcelain"])
-        .map(|s| collect_md_paths_from_porcelain(&s))
-        .unwrap_or_default();
 
-    for path in uncommitted.into_iter().chain(modified) {
+    for path in uncommitted.into_iter() {
         if !files.contains(&path) {
             files.push(path);
         }
@@ -97,9 +92,30 @@ fn git_changed_files(vault: &Path, from_hash: &str, to_hash: &str) -> Vec<String
 }
 
 fn git_uncommitted_files(vault: &Path) -> Vec<String> {
-    run_git(vault, &["status", "--porcelain"])
+    // Modified/staged tracked files from git status --porcelain
+    let mut files: Vec<String> = run_git(vault, &["status", "--porcelain"])
         .map(|s| collect_md_paths_from_porcelain(&s))
-        .unwrap_or_default()
+        .unwrap_or_default();
+
+    // Untracked files via ls-files (lists individual files, not just directories).
+    // git status --porcelain shows `?? dir/` for new directories, hiding individual
+    // files inside — ls-files resolves them so the cache picks up all new .md files.
+    let untracked = run_git(vault, &["ls-files", "--others", "--exclude-standard"])
+        .map(|s| {
+            s.lines()
+                .filter(|l| !l.is_empty() && l.ends_with(".md"))
+                .map(|l| l.to_string())
+                .collect::<Vec<_>>()
+        })
+        .unwrap_or_default();
+
+    for path in untracked {
+        if !files.contains(&path) {
+            files.push(path);
+        }
+    }
+
+    files
 }
 
 fn load_cache(vault: &Path) -> Option<VaultCache> {
@@ -140,21 +156,48 @@ fn parse_files_at(vault: &Path, rel_paths: &[String]) -> Vec<VaultEntry> {
         .collect()
 }
 
-/// Ensure `.laputa-cache.json` is excluded from git via `.git/info/exclude`.
-/// This prevents the cache (which contains machine-specific absolute paths)
-/// from being committed and causing stale-path bugs on cloned vaults.
+/// Machine-local files that should never be git-tracked in any vault.
+/// These are either caches with absolute paths or per-machine settings.
+const UNTRACKED_FILES: &[&str] = &[".laputa-cache.json", ".laputa/settings.json"];
+
+/// Ensure machine-local files are excluded from git via `.git/info/exclude`
+/// and un-tracked if they were previously committed (git rm --cached).
+/// Called on every cache write so existing vaults self-heal automatically.
 fn ensure_cache_excluded(vault: &Path) {
-    let exclude_path = vault.join(".git/info/exclude");
-    let entry = ".laputa-cache.json";
-    if let Ok(content) = fs::read_to_string(&exclude_path) {
-        if content.lines().any(|line| line.trim() == entry) {
-            return;
-        }
-        let separator = if content.ends_with('\n') { "" } else { "\n" };
-        let _ = fs::write(&exclude_path, format!("{content}{separator}{entry}\n"));
-    } else if exclude_path.parent().map(|p| p.is_dir()).unwrap_or(false) {
-        let _ = fs::write(&exclude_path, format!("{entry}\n"));
+    let git_dir = vault.join(".git");
+    if !git_dir.is_dir() {
+        return;
     }
+
+    let exclude_path = git_dir.join("info").join("exclude");
+
+    // 1. Add each entry to .git/info/exclude so git ignores it going forward.
+    let existing = fs::read_to_string(&exclude_path).unwrap_or_default();
+    let mut to_add: Vec<&str> = UNTRACKED_FILES
+        .iter()
+        .filter(|e| !existing.lines().any(|line| line.trim() == **e))
+        .copied()
+        .collect();
+
+    if !to_add.is_empty() {
+        to_add.sort();
+        let separator = if existing.ends_with('\n') || existing.is_empty() {
+            ""
+        } else {
+            "\n"
+        };
+        let additions = to_add.join("\n");
+        let _ = fs::write(&exclude_path, format!("{existing}{separator}{additions}\n"));
+    }
+
+    // 2. Un-track each file if git currently tracks it.
+    //    `git rm --cached --quiet --ignore-unmatch` exits 0 even if the file isn't tracked.
+    //    This fixes existing vaults where these files were committed before this guard.
+    let _ = std::process::Command::new("git")
+        .args(["rm", "--cached", "--quiet", "--ignore-unmatch", "--"])
+        .args(UNTRACKED_FILES)
+        .current_dir(vault)
+        .output();
 }
 
 /// Sort entries by modified_at descending and write the cache.
@@ -541,4 +584,125 @@ mod tests {
         assert!(titles.contains(&"Existing"));
         assert!(titles.contains(&"New Note"));
     }
+
+    #[test]
+    fn test_update_same_commit_new_files_in_new_subdirectory() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+
+        std::process::Command::new("git")
+            .args(["init"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        std::process::Command::new("git")
+            .args(["config", "user.email", "test@test.com"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        std::process::Command::new("git")
+            .args(["config", "user.name", "Test"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        create_test_file(vault, "existing.md", "# Existing\n");
+        std::process::Command::new("git")
+            .args(["add", "."])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        std::process::Command::new("git")
+            .args(["commit", "-m", "init"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        // Prime cache
+        let entries = scan_vault_cached(vault).unwrap();
+        assert_eq!(entries.len(), 1);
+
+        // Create files in a new subdirectory (simulates restore_default_themes)
+        create_test_file(
+            vault,
+            "theme/default.md",
+            "---\nIs A: Theme\n---\n# Default Theme\n",
+        );
+        create_test_file(
+            vault,
+            "theme/dark.md",
+            "---\nIs A: Theme\n---\n# Dark Theme\n",
+        );
+
+        // Cache same commit — files in new subdirectory must appear
+        let entries2 = scan_vault_cached(vault).unwrap();
+        assert_eq!(
+            entries2.len(),
+            3,
+            "must pick up files in new untracked subdirectory"
+        );
+        let titles: Vec<&str> = entries2.iter().map(|e| e.title.as_str()).collect();
+        assert!(titles.contains(&"Existing"));
+        assert!(titles.contains(&"Default Theme"));
+        assert!(titles.contains(&"Dark Theme"));
+    }
+
+    #[test]
+    fn test_update_same_commit_visible_removed_from_type_note() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+
+        std::process::Command::new("git")
+            .args(["init"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        std::process::Command::new("git")
+            .args(["config", "user.email", "test@test.com"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        std::process::Command::new("git")
+            .args(["config", "user.name", "Test"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        // Commit a type note with visible: false
+        create_test_file(
+            vault,
+            "type/topic.md",
+            "---\ntype: Type\nvisible: false\n---\n# Topic\n",
+        );
+        std::process::Command::new("git")
+            .args(["add", "."])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        std::process::Command::new("git")
+            .args(["commit", "-m", "init"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        // Prime the cache
+        let entries = scan_vault_cached(vault).unwrap();
+        assert_eq!(entries.len(), 1);
+        assert_eq!(
+            entries[0].visible,
+            Some(false),
+            "visible must be false initially"
+        );
+
+        // User removes visible field (uncommitted edit)
+        create_test_file(vault, "type/topic.md", "---\ntype: Type\n---\n# Topic\n");
+
+        // Reload — must reflect the removal (visible defaults to None)
+        let entries2 = scan_vault_cached(vault).unwrap();
+        assert_eq!(entries2.len(), 1);
+        assert_eq!(
+            entries2[0].visible, None,
+            "visible must be None after removing the field"
+        );
+    }
 }

src-tauri/src/vault/config_seed.rs

@@ -0,0 +1,355 @@
+use std::fs;
+use std::path::Path;
+
+use super::getting_started::AGENTS_MD;
+
+/// Content for `type/config.md` — gives the Config type a sidebar icon and label.
+const CONFIG_TYPE_DEFINITION: &str = "\
+---
+Is A: Type
+icon: gear-six
+color: gray
+order: 90
+sidebar label: Config
+---
+
+# Config
+
+Vault configuration files. These control how AI agents, tools, and other integrations interact with this vault.
+";
+
+/// Minimal root `AGENTS.md` stub that redirects to `config/agents.md`.
+const AGENTS_MD_STUB: &str = "\
+# Agent Instructions
+
+See config/agents.md for vault instructions.
+";
+
+/// Seed `config/agents.md` if missing or empty (idempotent, per-file).
+/// Also seeds `type/config.md` for sidebar visibility.
+pub fn seed_config_files(vault_path: &str) {
+    let vault = Path::new(vault_path);
+    let config_dir = vault.join("config");
+    if fs::create_dir_all(&config_dir).is_err() {
+        return;
+    }
+
+    let agents_path = config_dir.join("agents.md");
+    let needs_write =
+        !agents_path.exists() || fs::metadata(&agents_path).map_or(true, |m| m.len() == 0);
+    if needs_write {
+        let _ = fs::write(&agents_path, AGENTS_MD);
+        log::info!("Seeded config/agents.md");
+    }
+
+    ensure_config_type_definition(vault_path);
+}
+
+/// Ensure `type/config.md` exists (gives Config type a sidebar icon/color).
+fn ensure_config_type_definition(vault_path: &str) {
+    let type_dir = Path::new(vault_path).join("type");
+    if fs::create_dir_all(&type_dir).is_err() {
+        return;
+    }
+    let path = type_dir.join("config.md");
+    let needs_write = !path.exists() || fs::metadata(&path).map_or(true, |m| m.len() == 0);
+    if needs_write {
+        let _ = fs::write(&path, CONFIG_TYPE_DEFINITION);
+    }
+}
+
+/// Migrate root `AGENTS.md` → `config/agents.md` for existing vaults.
+///
+/// - If root `AGENTS.md` exists and `config/agents.md` does not: move content, write stub.
+/// - If root `AGENTS.md` exists and `config/agents.md` also exists: just replace root with stub.
+/// - If root `AGENTS.md` doesn't exist: write the stub anyway (for Codex discoverability).
+///
+/// Always idempotent and silent.
+pub fn migrate_agents_md(vault_path: &str) {
+    let vault = Path::new(vault_path);
+    let root_agents = vault.join("AGENTS.md");
+    let config_dir = vault.join("config");
+    let config_agents = config_dir.join("agents.md");
+
+    // Ensure config/ directory exists
+    if fs::create_dir_all(&config_dir).is_err() {
+        return;
+    }
+
+    // If root AGENTS.md has real content (not already a stub), migrate it
+    if root_agents.exists() {
+        let content = fs::read_to_string(&root_agents).unwrap_or_default();
+        let is_stub = content.contains("See config/agents.md");
+
+        if !is_stub {
+            // Only move content if config/agents.md doesn't exist yet
+            let config_needs_write = !config_agents.exists()
+                || fs::metadata(&config_agents).map_or(true, |m| m.len() == 0);
+            if config_needs_write {
+                let _ = fs::write(&config_agents, &content);
+                log::info!("Migrated AGENTS.md content to config/agents.md");
+            }
+            // Replace root with stub
+            let _ = fs::write(&root_agents, AGENTS_MD_STUB);
+            log::info!("Replaced root AGENTS.md with stub pointing to config/agents.md");
+        }
+    } else {
+        // No root AGENTS.md — write stub for Codex discoverability
+        let _ = fs::write(&root_agents, AGENTS_MD_STUB);
+    }
+}
+
+/// Repair config files: re-create missing `config/agents.md` and `type/config.md`.
+/// Called by the "Repair Vault" command. Returns a status message.
+pub fn repair_config_files(vault_path: &str) -> Result<String, String> {
+    let vault = Path::new(vault_path);
+
+    // Ensure config/ directory
+    let config_dir = vault.join("config");
+    fs::create_dir_all(&config_dir)
+        .map_err(|e| format!("Failed to create config directory: {e}"))?;
+
+    let agents_path = config_dir.join("agents.md");
+    let root_agents = vault.join("AGENTS.md");
+
+    // Step 1: Migrate root AGENTS.md content → config/agents.md if needed
+    if root_agents.exists() {
+        let root_content = fs::read_to_string(&root_agents).unwrap_or_default();
+        let is_stub = root_content.contains("See config/agents.md");
+        if !is_stub && !root_content.is_empty() {
+            let config_needs_write =
+                !agents_path.exists() || fs::metadata(&agents_path).map_or(true, |m| m.len() == 0);
+            if config_needs_write {
+                fs::write(&agents_path, &root_content)
+                    .map_err(|e| format!("Failed to migrate AGENTS.md: {e}"))?;
+            }
+            fs::write(&root_agents, AGENTS_MD_STUB)
+                .map_err(|e| format!("Failed to write AGENTS.md stub: {e}"))?;
+        }
+    }
+
+    // Step 2: Seed config/agents.md with defaults if still missing or empty
+    let needs_write =
+        !agents_path.exists() || fs::metadata(&agents_path).map_or(true, |m| m.len() == 0);
+    if needs_write {
+        fs::write(&agents_path, AGENTS_MD)
+            .map_err(|e| format!("Failed to write config/agents.md: {e}"))?;
+    }
+
+    // Step 3: Ensure type/config.md
+    let type_dir = vault.join("type");
+    fs::create_dir_all(&type_dir).map_err(|e| format!("Failed to create type directory: {e}"))?;
+    let config_type_path = type_dir.join("config.md");
+    let type_needs_write = !config_type_path.exists()
+        || fs::metadata(&config_type_path).map_or(true, |m| m.len() == 0);
+    if type_needs_write {
+        fs::write(&config_type_path, CONFIG_TYPE_DEFINITION)
+            .map_err(|e| format!("Failed to write type/config.md: {e}"))?;
+    }
+
+    // Step 4: Ensure root AGENTS.md stub exists
+    let stub_needs_write = !root_agents.exists()
+        || fs::read_to_string(&root_agents).map_or(true, |c| !c.contains("See config/agents.md"));
+    if stub_needs_write {
+        fs::write(&root_agents, AGENTS_MD_STUB)
+            .map_err(|e| format!("Failed to write AGENTS.md stub: {e}"))?;
+    }
+
+    Ok("Config files repaired".to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+    use tempfile::TempDir;
+
+    #[test]
+    fn test_seed_config_files_creates_dir_and_agents() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+
+        seed_config_files(vault.to_str().unwrap());
+
+        assert!(vault.join("config").is_dir());
+        assert!(vault.join("config/agents.md").exists());
+        let content = fs::read_to_string(vault.join("config/agents.md")).unwrap();
+        assert!(content.contains("Vault Instructions for AI Agents"));
+    }
+
+    #[test]
+    fn test_seed_config_files_creates_type_definition() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+
+        seed_config_files(vault.to_str().unwrap());
+
+        assert!(vault.join("type/config.md").exists());
+        let content = fs::read_to_string(vault.join("type/config.md")).unwrap();
+        assert!(content.contains("Is A: Type"));
+        assert!(content.contains("icon: gear-six"));
+    }
+
+    #[test]
+    fn test_seed_config_files_is_idempotent() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+
+        seed_config_files(vault.to_str().unwrap());
+        // Customize the file
+        let custom = "---\nIs A: Config\n---\n# Custom Agents\nMy custom instructions\n";
+        fs::write(vault.join("config/agents.md"), custom).unwrap();
+
+        seed_config_files(vault.to_str().unwrap());
+        let content = fs::read_to_string(vault.join("config/agents.md")).unwrap();
+        assert!(
+            content.contains("Custom Agents"),
+            "must preserve existing content"
+        );
+    }
+
+    #[test]
+    fn test_seed_config_files_reseeds_empty() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        let config_dir = vault.join("config");
+        fs::create_dir_all(&config_dir).unwrap();
+        fs::write(config_dir.join("agents.md"), "").unwrap();
+
+        seed_config_files(vault.to_str().unwrap());
+        let content = fs::read_to_string(config_dir.join("agents.md")).unwrap();
+        assert!(content.contains("Vault Instructions for AI Agents"));
+    }
+
+    #[test]
+    fn test_migrate_agents_md_moves_content() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+        fs::write(vault.join("AGENTS.md"), AGENTS_MD).unwrap();
+
+        migrate_agents_md(vault.to_str().unwrap());
+
+        // config/agents.md should have the original content
+        let config_content = fs::read_to_string(vault.join("config/agents.md")).unwrap();
+        assert!(config_content.contains("Vault Instructions for AI Agents"));
+
+        // Root AGENTS.md should be a stub
+        let root_content = fs::read_to_string(vault.join("AGENTS.md")).unwrap();
+        assert!(root_content.contains("See config/agents.md"));
+        assert!(!root_content.contains("## Structure"));
+    }
+
+    #[test]
+    fn test_migrate_agents_md_preserves_existing_config() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        let config_dir = vault.join("config");
+        fs::create_dir_all(&config_dir).unwrap();
+        let custom = "# Custom agent instructions\n";
+        fs::write(config_dir.join("agents.md"), custom).unwrap();
+        fs::write(vault.join("AGENTS.md"), AGENTS_MD).unwrap();
+
+        migrate_agents_md(vault.to_str().unwrap());
+
+        // config/agents.md should preserve custom content
+        let content = fs::read_to_string(config_dir.join("agents.md")).unwrap();
+        assert!(content.contains("Custom agent instructions"));
+
+        // Root should be a stub
+        let root = fs::read_to_string(vault.join("AGENTS.md")).unwrap();
+        assert!(root.contains("See config/agents.md"));
+    }
+
+    #[test]
+    fn test_migrate_agents_md_idempotent_on_stub() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+        fs::write(vault.join("AGENTS.md"), AGENTS_MD_STUB).unwrap();
+
+        migrate_agents_md(vault.to_str().unwrap());
+
+        // Stub should remain unchanged
+        let root = fs::read_to_string(vault.join("AGENTS.md")).unwrap();
+        assert!(root.contains("See config/agents.md"));
+    }
+
+    #[test]
+    fn test_migrate_agents_md_writes_stub_when_no_root() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+
+        migrate_agents_md(vault.to_str().unwrap());
+
+        assert!(vault.join("AGENTS.md").exists());
+        let root = fs::read_to_string(vault.join("AGENTS.md")).unwrap();
+        assert!(root.contains("See config/agents.md"));
+    }
+
+    #[test]
+    fn test_repair_config_files_creates_all() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+
+        let msg = repair_config_files(vault.to_str().unwrap()).unwrap();
+        assert_eq!(msg, "Config files repaired");
+
+        assert!(vault.join("config/agents.md").exists());
+        assert!(vault.join("type/config.md").exists());
+        assert!(vault.join("AGENTS.md").exists());
+
+        let agents = fs::read_to_string(vault.join("config/agents.md")).unwrap();
+        assert!(agents.contains("Vault Instructions for AI Agents"));
+
+        let stub = fs::read_to_string(vault.join("AGENTS.md")).unwrap();
+        assert!(stub.contains("See config/agents.md"));
+    }
+
+    #[test]
+    fn test_repair_config_files_preserves_custom_content() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        let config_dir = vault.join("config");
+        fs::create_dir_all(&config_dir).unwrap();
+        let custom = "# My custom agent config\nDo not overwrite me\n";
+        fs::write(config_dir.join("agents.md"), custom).unwrap();
+        fs::write(
+            vault.join("AGENTS.md"),
+            "# Agent Instructions\nSee config/agents.md for vault instructions.\n",
+        )
+        .unwrap();
+
+        repair_config_files(vault.to_str().unwrap()).unwrap();
+
+        let content = fs::read_to_string(config_dir.join("agents.md")).unwrap();
+        assert!(
+            content.contains("My custom agent config"),
+            "must preserve existing content"
+        );
+    }
+
+    #[test]
+    fn test_repair_config_files_migrates_root_agents() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path().join("vault");
+        fs::create_dir_all(&vault).unwrap();
+        let original = "# My vault agents instructions\nCustom content here\n";
+        fs::write(vault.join("AGENTS.md"), original).unwrap();
+
+        repair_config_files(vault.to_str().unwrap()).unwrap();
+
+        // Root should be a stub
+        let root = fs::read_to_string(vault.join("AGENTS.md")).unwrap();
+        assert!(root.contains("See config/agents.md"));
+
+        // config/agents.md should have the original content
+        let config = fs::read_to_string(vault.join("config/agents.md")).unwrap();
+        assert!(config.contains("My vault agents instructions"));
+    }
+}

src-tauri/src/vault/getting_started.rs

@@ -18,10 +18,10 @@ struct SampleFile {
     content: &'static str,
 }
 
-/// Content for the AGENTS.md file written to the vault root.
+/// Content for config/agents.md — vault instructions for AI agents.
 /// This file has no YAML frontmatter — it is a convention file for AI agents,
 /// not a vault note. The vault scanner will still pick it up as a regular entry.
-const AGENTS_MD: &str = r#"# AGENTS.md — Vault Instructions for AI Agents
+pub(super) const AGENTS_MD: &str = r#"# AGENTS.md — Vault Instructions for AI Agents
 
 This is a [Laputa](https://github.com/refactoring-ai/laputa) vault — a folder of markdown files with YAML frontmatter that form a personal knowledge graph.
 
@@ -133,6 +133,14 @@ const SAMPLE_FILES: &[SampleFile] = &[
         rel_path: "type/topic.md",
         content: "---\nIs A: Type\nicon: tag\ncolor: yellow\norder: 4\n---\n\n# Topic\n\nA Topic is a subject area or interest category that groups related notes, projects, and people.\n",
     },
+    SampleFile {
+        rel_path: "type/theme.md",
+        content: "---\nIs A: Type\nicon: palette\ncolor: purple\norder: 50\n---\n\n# Theme\n\nA visual theme for Laputa. Each theme defines CSS custom properties that control colors, typography, and spacing.\n",
+    },
+    SampleFile {
+        rel_path: "type/config.md",
+        content: "---\nIs A: Type\nicon: gear-six\ncolor: gray\norder: 90\nsidebar label: Config\n---\n\n# Config\n\nVault configuration files. These control how AI agents, tools, and other integrations interact with this vault.\n",
+    },
     SampleFile {
         rel_path: "note/welcome-to-laputa.md",
         content: r#"---
@@ -380,9 +388,19 @@ pub fn create_getting_started_vault(target_path: &str) -> Result<String, String>
     fs::create_dir_all(vault_dir)
         .map_err(|e| format!("Failed to create vault directory: {}", e))?;
 
-    // Write AGENTS.md at the vault root
-    fs::write(vault_dir.join("AGENTS.md"), AGENTS_MD)
-        .map_err(|e| format!("Failed to write AGENTS.md: {}", e))?;
+    // Write config/agents.md with vault instructions for AI agents
+    let config_dir = vault_dir.join("config");
+    fs::create_dir_all(&config_dir)
+        .map_err(|e| format!("Failed to create config directory: {}", e))?;
+    fs::write(config_dir.join("agents.md"), AGENTS_MD)
+        .map_err(|e| format!("Failed to write config/agents.md: {}", e))?;
+
+    // Write root AGENTS.md stub for Codex discoverability
+    fs::write(
+        vault_dir.join("AGENTS.md"),
+        "# Agent Instructions\n\nSee config/agents.md for vault instructions.\n",
+    )
+    .map_err(|e| format!("Failed to write AGENTS.md stub: {}", e))?;
 
     for sample in SAMPLE_FILES {
         let file_path = vault_dir.join(sample.rel_path);
@@ -394,7 +412,7 @@ pub fn create_getting_started_vault(target_path: &str) -> Result<String, String>
             .map_err(|e| format!("Failed to write {}: {}", sample.rel_path, e))?;
     }
 
-    // Seed built-in themes
+    // Seed built-in themes (both JSON legacy and vault-based markdown notes)
     let themes_dir = vault_dir.join("_themes");
     fs::create_dir_all(&themes_dir)
         .map_err(|e| format!("Failed to create _themes directory: {e}"))?;
@@ -405,6 +423,25 @@ pub fn create_getting_started_vault(target_path: &str) -> Result<String, String>
     fs::write(themes_dir.join("minimal.json"), crate::theme::MINIMAL_THEME)
         .map_err(|e| format!("Failed to write minimal theme: {e}"))?;
 
+    let theme_notes_dir = vault_dir.join("theme");
+    fs::create_dir_all(&theme_notes_dir)
+        .map_err(|e| format!("Failed to create theme directory: {e}"))?;
+    fs::write(
+        theme_notes_dir.join("default.md"),
+        crate::theme::DEFAULT_VAULT_THEME,
+    )
+    .map_err(|e| format!("Failed to write default vault theme: {e}"))?;
+    fs::write(
+        theme_notes_dir.join("dark.md"),
+        crate::theme::DARK_VAULT_THEME,
+    )
+    .map_err(|e| format!("Failed to write dark vault theme: {e}"))?;
+    fs::write(
+        theme_notes_dir.join("minimal.md"),
+        crate::theme::MINIMAL_VAULT_THEME,
+    )
+    .map_err(|e| format!("Failed to write minimal vault theme: {e}"))?;
+
     crate::git::init_repo(target_path)?;
 
     Ok(vault_dir
@@ -439,6 +476,7 @@ mod tests {
         assert!(result.is_ok());
 
         // Verify key files exist
+        assert!(vault_path.join("config/agents.md").exists());
         assert!(vault_path.join("AGENTS.md").exists());
         assert!(vault_path.join("note/welcome-to-laputa.md").exists());
         assert!(vault_path.join("note/editor-basics.md").exists());
@@ -453,6 +491,7 @@ mod tests {
         assert!(vault_path.join("type/note.md").exists());
         assert!(vault_path.join("type/person.md").exists());
         assert!(vault_path.join("type/topic.md").exists());
+        assert!(vault_path.join("type/config.md").exists());
     }
 
     #[test]
@@ -507,57 +546,63 @@ mod tests {
         create_getting_started_vault(vault_path.to_str().unwrap()).unwrap();
 
         let entries = crate::vault::scan_vault(&vault_path).unwrap();
-        // SAMPLE_FILES + AGENTS.md
-        assert_eq!(entries.len(), SAMPLE_FILES.len() + 1);
+        // SAMPLE_FILES + config/agents.md + AGENTS.md stub + 3 vault theme notes
+        assert_eq!(entries.len(), SAMPLE_FILES.len() + 2 + 3);
     }
 
     #[test]
-    fn test_agents_md_present_after_vault_creation() {
+    fn test_config_agents_md_present_after_vault_creation() {
         let dir = tempfile::TempDir::new().unwrap();
         let vault_path = dir.path().join("agents-vault");
         create_getting_started_vault(vault_path.to_str().unwrap()).unwrap();
 
-        let agents_path = vault_path.join("AGENTS.md");
-        assert!(agents_path.exists(), "AGENTS.md should exist at vault root");
+        let agents_path = vault_path.join("config/agents.md");
+        assert!(
+            agents_path.exists(),
+            "config/agents.md should exist in vault"
+        );
 
         let content = fs::read_to_string(&agents_path).unwrap();
+        assert!(content.contains("Vault Instructions for AI Agents"));
+        assert!(content.contains("## Structure"));
+        assert!(content.contains("## Frontmatter"));
+        assert!(content.contains("## Wikilinks"));
+        assert!(content.contains("## Type definitions"));
+        assert!(content.contains("## Conventions"));
+    }
+
+    #[test]
+    fn test_root_agents_md_is_stub_after_vault_creation() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let vault_path = dir.path().join("stub-vault");
+        create_getting_started_vault(vault_path.to_str().unwrap()).unwrap();
+
+        let root_path = vault_path.join("AGENTS.md");
+        assert!(root_path.exists(), "Root AGENTS.md stub should exist");
+
+        let content = fs::read_to_string(&root_path).unwrap();
         assert!(
-            content.contains("Vault Instructions for AI Agents"),
-            "AGENTS.md should contain instructions header"
+            content.contains("See config/agents.md"),
+            "Root AGENTS.md should redirect to config/agents.md"
         );
         assert!(
-            content.contains("## Structure"),
-            "AGENTS.md should describe vault structure"
-        );
-        assert!(
-            content.contains("## Frontmatter"),
-            "AGENTS.md should describe frontmatter"
-        );
-        assert!(
-            content.contains("## Wikilinks"),
-            "AGENTS.md should describe wikilinks"
-        );
-        assert!(
-            content.contains("## Type definitions"),
-            "AGENTS.md should describe type definitions"
-        );
-        assert!(
-            content.contains("## Conventions"),
-            "AGENTS.md should describe conventions"
+            !content.contains("## Structure"),
+            "Root AGENTS.md should not contain full instructions"
         );
     }
 
     #[test]
-    fn test_agents_md_parseable_as_vault_entry() {
+    fn test_config_agents_md_parseable_as_vault_entry() {
         let dir = tempfile::TempDir::new().unwrap();
         let vault_path = dir.path().join("agents-parse-vault");
         create_getting_started_vault(vault_path.to_str().unwrap()).unwrap();
 
-        let entry = crate::vault::parse_md_file(&vault_path.join("AGENTS.md")).unwrap();
+        let entry = crate::vault::parse_md_file(&vault_path.join("config/agents.md")).unwrap();
         assert_eq!(
             entry.title,
             "AGENTS.md \u{2014} Vault Instructions for AI Agents"
         );
+        assert_eq!(entry.is_a.as_deref(), Some("Config"));
     }
 
     #[test]
@@ -583,12 +628,21 @@ mod tests {
         let vault_path = dir.path().join("theme-vault");
         create_getting_started_vault(vault_path.to_str().unwrap()).unwrap();
 
+        // JSON legacy themes
         assert!(vault_path.join("_themes/default.json").exists());
         assert!(vault_path.join("_themes/dark.json").exists());
         assert!(vault_path.join("_themes/minimal.json").exists());
 
         let themes = crate::theme::list_themes(vault_path.to_str().unwrap()).unwrap();
         assert_eq!(themes.len(), 3);
+
+        // Vault-based theme notes
+        assert!(vault_path.join("theme/default.md").exists());
+        assert!(vault_path.join("theme/dark.md").exists());
+        assert!(vault_path.join("theme/minimal.md").exists());
+
+        // Theme type definition
+        assert!(vault_path.join("type/theme.md").exists());
     }
 
     #[test]

src-tauri/src/vault/mod.rs

@@ -1,4 +1,5 @@
 mod cache;
+mod config_seed;
 mod getting_started;
 mod image;
 mod migration;
@@ -7,6 +8,7 @@ mod rename;
 mod trash;
 
 pub use cache::scan_vault_cached;
+pub use config_seed::{migrate_agents_md, repair_config_files, seed_config_files};
 pub use getting_started::{create_getting_started_vault, default_vault_path, vault_exists};
 pub use image::{copy_image_to_vault, save_image};
 pub use migration::migrate_is_a_to_type;
@@ -14,8 +16,8 @@ pub use rename::{rename_note, RenameResult};
 pub use trash::{delete_note, purge_trash};
 
 use parsing::{
-    capitalize_first, contains_wikilink, count_body_words, extract_outgoing_links, extract_snippet,
-    extract_title, parse_iso_date,
+    contains_wikilink, count_body_words, extract_outgoing_links, extract_snippet, extract_title,
+    parse_iso_date, title_case_folder,
 };
 
 use gray_matter::engine::YAML;
@@ -71,6 +73,11 @@ pub struct VaultEntry {
     /// Default sort preference for the note list when viewing instances of this Type.
     /// Stored as "option:direction" (e.g. "modified:desc", "title:asc", "property:Priority:asc").
     pub sort: Option<String>,
+    /// Default view mode for the note list when viewing instances of this Type.
+    /// Stored as a string: "all", "editor-list", or "editor-only".
+    pub view: Option<String>,
+    /// Whether this Type is visible in the sidebar. Defaults to true when absent.
+    pub visible: Option<bool>,
     /// Word count of the note body (excludes frontmatter and H1 title).
     #[serde(rename = "wordCount")]
     pub word_count: u32,
@@ -103,9 +110,9 @@ struct Frontmatter {
     cadence: Option<String>,
     #[serde(rename = "Archived")]
     archived: Option<bool>,
-    #[serde(rename = "Trashed")]
+    #[serde(rename = "Trashed", alias = "trashed")]
     trashed: Option<bool>,
-    #[serde(rename = "Trashed at")]
+    #[serde(rename = "Trashed at", alias = "trashed_at")]
     trashed_at: Option<String>,
     #[serde(rename = "Created at")]
     created_at: Option<String>,
@@ -123,6 +130,10 @@ struct Frontmatter {
     template: Option<String>,
     #[serde(default)]
     sort: Option<String>,
+    #[serde(default)]
+    view: Option<String>,
+    #[serde(default)]
+    visible: Option<bool>,
 }
 
 /// Handles YAML fields that can be either a single string or a list of strings.
@@ -169,6 +180,8 @@ const SKIP_KEYS: &[&str] = &[
     "sidebar label",
     "template",
     "sort",
+    "view",
+    "visible",
 ];
 
 /// Extract all wikilink-containing fields from raw YAML frontmatter.
@@ -266,9 +279,10 @@ fn infer_type_from_folder(folder: &str) -> String {
         "target" => "Target",
         "journal" => "Journal",
         "month" => "Month",
+        "config" => "Config",
         "essay" => "Essay",
         "evergreen" => "Evergreen",
-        _ => return capitalize_first(folder),
+        _ => return title_case_folder(folder),
     }
     .to_string()
 }
@@ -394,6 +408,8 @@ pub fn parse_md_file(path: &Path) -> Result<VaultEntry, String> {
         sidebar_label: frontmatter.sidebar_label,
         template: frontmatter.template,
         sort: frontmatter.sort,
+        view: frontmatter.view,
+        visible: frontmatter.visible,
         word_count,
         outgoing_links,
         properties,
@@ -953,6 +969,28 @@ References:
         assert_eq!(entry.is_a, Some("Recipe".to_string()));
     }
 
+    #[test]
+    fn test_infer_type_from_hyphenated_folder_title_cases() {
+        let dir = TempDir::new().unwrap();
+        let cases = vec![
+            ("monday-ideas", "Monday Ideas"),
+            ("key-result", "Key Result"),
+            ("my_custom_type", "My Custom Type"),
+            ("mix-and_match", "Mix And Match"),
+        ];
+        for (folder, expected) in cases {
+            create_test_file(dir.path(), &format!("{}/test.md", folder), "# Test\n");
+            let entry = parse_md_file(&dir.path().join(folder).join("test.md")).unwrap();
+            assert_eq!(
+                entry.is_a,
+                Some(expected.to_string()),
+                "folder '{}' should infer type '{}'",
+                folder,
+                expected
+            );
+        }
+    }
+
     #[test]
     fn test_infer_type_frontmatter_overrides_folder() {
         let dir = TempDir::new().unwrap();
@@ -1312,6 +1350,81 @@ Company: Acme Corp
         );
     }
 
+    #[test]
+    fn test_parse_trashed_title_case() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\nTrashed: true\nTrashed at: \"2025-02-01\"\n---\n# Gone\n";
+        let entry = parse_test_entry(&dir, "gone.md", content);
+        assert!(entry.trashed);
+        assert!(entry.trashed_at.is_some());
+    }
+
+    #[test]
+    fn test_parse_trashed_lowercase_alias() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\ntrashed: true\ntrashed_at: \"2025-02-01\"\n---\n# Gone\n";
+        let entry = parse_test_entry(&dir, "gone.md", content);
+        assert!(
+            entry.trashed,
+            "lowercase 'trashed' must be parsed via alias"
+        );
+        assert!(
+            entry.trashed_at.is_some(),
+            "lowercase 'trashed_at' must be parsed via alias"
+        );
+    }
+
+    #[test]
+    fn test_trashed_false_when_absent() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\nIs A: Note\n---\n# Active\n";
+        let entry = parse_test_entry(&dir, "active.md", content);
+        assert!(!entry.trashed);
+        assert!(entry.trashed_at.is_none());
+    }
+
+    // --- visible field tests ---
+
+    #[test]
+    fn test_parse_visible_false_from_type_entry() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\ntype: Type\nvisible: false\n---\n# Journal\n";
+        let entry = parse_test_entry(&dir, "type/journal.md", content);
+        assert_eq!(entry.visible, Some(false));
+    }
+
+    #[test]
+    fn test_parse_visible_true_from_type_entry() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\ntype: Type\nvisible: true\n---\n# Project\n";
+        let entry = parse_test_entry(&dir, "type/project.md", content);
+        assert_eq!(entry.visible, Some(true));
+    }
+
+    #[test]
+    fn test_parse_visible_missing_defaults_to_none() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\ntype: Type\n---\n# Project\n";
+        let entry = parse_test_entry(&dir, "type/project.md", content);
+        assert_eq!(entry.visible, None);
+    }
+
+    #[test]
+    fn test_visible_not_in_relationships() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\ntype: Type\nvisible: false\n---\n# Journal\n";
+        let entry = parse_test_entry(&dir, "type/journal.md", content);
+        assert!(entry.relationships.get("visible").is_none());
+    }
+
+    #[test]
+    fn test_visible_not_in_properties() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\ntype: Type\nvisible: false\n---\n# Journal\n";
+        let entry = parse_test_entry(&dir, "type/journal.md", content);
+        assert!(entry.properties.get("visible").is_none());
+    }
+
     // Frontmatter update/delete tests are in frontmatter.rs
     // save_image tests are in vault/image.rs
     // purge_trash tests are in vault/trash.rs

src-tauri/src/vault/parsing.rs

@@ -116,6 +116,14 @@ fn strip_markdown_chars(s: &str) -> String {
     let mut chars = s.chars().peekable();
     while let Some(ch) = chars.next() {
         match ch {
+            '[' if chars.peek() == Some(&'[') => {
+                chars.next(); // consume second '['
+                let inner = collect_wikilink_inner(&mut chars);
+                match inner.find('|') {
+                    Some(idx) => result.push_str(&inner[idx + 1..]),
+                    None => result.push_str(&inner),
+                }
+            }
             '[' => {
                 let inner = collect_until(&mut chars, ']');
                 if chars.peek() == Some(&'(') {
@@ -131,6 +139,19 @@ fn strip_markdown_chars(s: &str) -> String {
     result
 }
 
+/// Collect chars inside a wikilink until `]]`, consuming both closing brackets.
+fn collect_wikilink_inner(chars: &mut std::iter::Peekable<impl Iterator<Item = char>>) -> String {
+    let mut buf = String::new();
+    while let Some(c) = chars.next() {
+        if c == ']' && chars.peek() == Some(&']') {
+            chars.next();
+            break;
+        }
+        buf.push(c);
+    }
+    buf
+}
+
 /// Check if a string contains a wikilink pattern `[[...]]`.
 pub(super) fn contains_wikilink(s: &str) -> bool {
     s.contains("[[") && s.contains("]]")
@@ -174,6 +195,16 @@ pub(super) fn capitalize_first(s: &str) -> String {
     }
 }
 
+/// Title-case a folder name: split on hyphens and underscores, capitalize each word, join with spaces.
+/// Example: "monday-ideas" → "Monday Ideas", "key_result" → "Key Result"
+pub(super) fn title_case_folder(s: &str) -> String {
+    s.split(['-', '_'])
+        .filter(|w| !w.is_empty())
+        .map(capitalize_first)
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
 /// Parse an ISO 8601 date string to Unix timestamp (seconds since epoch).
 /// Handles "2025-05-23T14:35:00.000Z" and "2025-05-23" formats.
 pub(super) fn parse_iso_date(date_str: &str) -> Option<u64> {
@@ -250,6 +281,16 @@ mod tests {
         let snippet = extract_snippet(content);
         assert!(snippet.contains("this link"));
         assert!(!snippet.contains("https://example.com"));
+        assert!(snippet.contains("wiki link"));
+        assert!(!snippet.contains("[["));
+        assert!(!snippet.contains("]]"));
+    }
+
+    #[test]
+    fn test_extract_snippet_wikilink_alias() {
+        let content = "# Title\n\nDiscussed in [[meetings/standup|standup]] today.";
+        let snippet = extract_snippet(content);
+        assert_eq!(snippet, "Discussed in standup today.");
     }
 
     #[test]
@@ -378,7 +419,20 @@ mod tests {
 
     #[test]
     fn test_strip_markdown_chars_wikilink() {
-        assert_eq!(strip_markdown_chars("see [[my note]]"), "see [my note]");
+        assert_eq!(strip_markdown_chars("see [[my note]]"), "see my note");
+    }
+
+    #[test]
+    fn test_strip_markdown_chars_wikilink_alias() {
+        assert_eq!(
+            strip_markdown_chars("visit [[project/alpha|Alpha Project]]"),
+            "visit Alpha Project"
+        );
+    }
+
+    #[test]
+    fn test_strip_markdown_chars_wikilink_unclosed() {
+        assert_eq!(strip_markdown_chars("see [[broken link"), "see broken link");
     }
 
     #[test]
@@ -413,6 +467,29 @@ mod tests {
         assert_eq!(capitalize_first("a"), "A");
     }
 
+    // --- title_case_folder tests ---
+
+    #[test]
+    fn test_title_case_folder_hyphenated() {
+        assert_eq!(title_case_folder("monday-ideas"), "Monday Ideas");
+        assert_eq!(title_case_folder("key-result"), "Key Result");
+    }
+
+    #[test]
+    fn test_title_case_folder_underscored() {
+        assert_eq!(title_case_folder("my_custom_type"), "My Custom Type");
+    }
+
+    #[test]
+    fn test_title_case_folder_single_word() {
+        assert_eq!(title_case_folder("recipe"), "Recipe");
+    }
+
+    #[test]
+    fn test_title_case_folder_empty() {
+        assert_eq!(title_case_folder(""), "");
+    }
+
     // --- without_h1_line tests ---
 
     #[test]

src-tauri/src/vault_config.rs

@@ -0,0 +1,481 @@
+use gray_matter::engine::YAML;
+use gray_matter::Matter;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::path::Path;
+
+/// Vault-wide UI configuration stored in `config/ui.config.md`.
+///
+/// This file is a regular vault note with YAML frontmatter, visible in the
+/// sidebar under the "Config" section and editable like any note.
+#[derive(Debug, Serialize, Deserialize, Default, Clone)]
+pub struct VaultConfig {
+    pub zoom: Option<f64>,
+    pub view_mode: Option<String>,
+    #[serde(default)]
+    pub tag_colors: Option<HashMap<String, String>>,
+    #[serde(default)]
+    pub status_colors: Option<HashMap<String, String>>,
+    #[serde(default)]
+    pub property_display_modes: Option<HashMap<String, String>>,
+}
+
+const CONFIG_DIR: &str = "config";
+const CONFIG_FILENAME: &str = "ui.config.md";
+
+fn config_path(vault_path: &str) -> std::path::PathBuf {
+    Path::new(vault_path).join(CONFIG_DIR).join(CONFIG_FILENAME)
+}
+
+/// Read the vault-wide UI config from `config/ui.config.md`.
+/// Returns default values if the file doesn't exist.
+pub fn get_vault_config(vault_path: &str) -> Result<VaultConfig, String> {
+    let path = config_path(vault_path);
+    if !path.exists() {
+        return Ok(VaultConfig::default());
+    }
+
+    let content =
+        std::fs::read_to_string(&path).map_err(|e| format!("Failed to read config: {e}"))?;
+
+    parse_vault_config(&content)
+}
+
+/// Parse VaultConfig from markdown content with YAML frontmatter.
+fn parse_vault_config(content: &str) -> Result<VaultConfig, String> {
+    let matter = Matter::<YAML>::new();
+    let parsed = matter.parse(content);
+
+    let hash = match parsed.data {
+        Some(gray_matter::Pod::Hash(map)) => map,
+        _ => return Ok(VaultConfig::default()),
+    };
+
+    let json_map: serde_json::Map<String, serde_json::Value> =
+        hash.into_iter().map(|(k, v)| (k, pod_to_json(v))).collect();
+    let json = serde_json::Value::Object(json_map);
+
+    serde_json::from_value(json.clone())
+        .or_else(|_| {
+            // If direct deserialization fails, strip the `type` field and retry
+            let mut map = match json {
+                serde_json::Value::Object(m) => m,
+                _ => return Ok(VaultConfig::default()),
+            };
+            map.remove("type");
+            serde_json::from_value(serde_json::Value::Object(map))
+        })
+        .map_err(|e| format!("Failed to parse config: {e}"))
+}
+
+/// Save the vault-wide UI config to `config/ui.config.md`.
+/// Creates the directory and file if they don't exist.
+pub fn save_vault_config(vault_path: &str, config: VaultConfig) -> Result<(), String> {
+    let path = config_path(vault_path);
+    let dir = Path::new(vault_path).join(CONFIG_DIR);
+    if !dir.exists() {
+        std::fs::create_dir_all(&dir).map_err(|e| format!("Failed to create config dir: {e}"))?;
+    }
+
+    let content = serialize_config(&config);
+    std::fs::write(&path, content).map_err(|e| format!("Failed to write config: {e}"))
+}
+
+/// Serialize VaultConfig to a markdown file with YAML frontmatter.
+fn serialize_config(config: &VaultConfig) -> String {
+    let mut lines = vec!["---".to_string(), "type: config".to_string()];
+
+    if let Some(zoom) = config.zoom {
+        lines.push(format!("zoom: {zoom}"));
+    }
+    if let Some(ref mode) = config.view_mode {
+        lines.push(format!("view_mode: {mode}"));
+    }
+    append_string_map(&mut lines, "tag_colors", config.tag_colors.as_ref());
+    append_string_map(&mut lines, "status_colors", config.status_colors.as_ref());
+    append_string_map(
+        &mut lines,
+        "property_display_modes",
+        config.property_display_modes.as_ref(),
+    );
+    lines.push("---".to_string());
+    lines.join("\n") + "\n"
+}
+
+/// Append a YAML map section with sorted keys for stable output.
+fn append_string_map(lines: &mut Vec<String>, key: &str, map: Option<&HashMap<String, String>>) {
+    if let Some(m) = map {
+        if !m.is_empty() {
+            lines.push(format!("{key}:"));
+            let mut entries: Vec<_> = m.iter().collect();
+            entries.sort_by_key(|(k, _)| k.to_owned());
+            for (k, v) in entries {
+                lines.push(format!("  {}: {}", yaml_safe_key(k), yaml_safe_value(v)));
+            }
+        }
+    }
+}
+
+/// Quote a YAML key if it contains special characters.
+fn yaml_safe_key(key: &str) -> String {
+    if key.contains(':') || key.contains('#') || key.contains(' ') {
+        format!("\"{}\"", key.replace('"', "\\\""))
+    } else {
+        key.to_string()
+    }
+}
+
+/// Quote a YAML value if it contains special characters.
+fn yaml_safe_value(value: &str) -> String {
+    if value.contains(':')
+        || value.contains('#')
+        || value.starts_with('"')
+        || value.starts_with('\'')
+    {
+        format!("\"{}\"", value.replace('"', "\\\""))
+    } else {
+        value.to_string()
+    }
+}
+
+/// Migrate `hidden_sections` from `config/ui.config.md` to `visible: false`
+/// on Type notes. Returns the number of Type notes updated.
+///
+/// For each type name in `hidden_sections`:
+/// - If `type/<slug>.md` exists, adds `visible: false` to its frontmatter
+/// - If it doesn't exist, creates it with `type: Type`, `title: <name>`, `visible: false`
+/// - Re-saves the config without `hidden_sections`
+pub fn migrate_hidden_sections_to_visible(vault_path: &str) -> Result<usize, String> {
+    let path = config_path(vault_path);
+    if !path.exists() {
+        return Ok(0);
+    }
+
+    let content =
+        std::fs::read_to_string(&path).map_err(|e| format!("Failed to read config: {e}"))?;
+
+    let hidden = extract_hidden_sections(&content);
+    if hidden.is_empty() {
+        return Ok(0);
+    }
+
+    let type_dir = Path::new(vault_path).join("type");
+    if !type_dir.exists() {
+        std::fs::create_dir_all(&type_dir)
+            .map_err(|e| format!("Failed to create type dir: {e}"))?;
+    }
+
+    let mut migrated = 0;
+    for type_name in &hidden {
+        let slug = type_name_to_slug(type_name);
+        let type_path = type_dir.join(format!("{slug}.md"));
+
+        if type_path.exists() {
+            let type_content = std::fs::read_to_string(&type_path)
+                .map_err(|e| format!("Failed to read {}: {e}", type_path.display()))?;
+            if !type_content.contains("visible:") {
+                let updated = crate::frontmatter::update_frontmatter_content(
+                    &type_content,
+                    "visible",
+                    Some(crate::frontmatter::FrontmatterValue::Bool(false)),
+                )
+                .map_err(|e| format!("Failed to update {}: {e}", type_path.display()))?;
+                std::fs::write(&type_path, updated)
+                    .map_err(|e| format!("Failed to write {}: {e}", type_path.display()))?;
+            }
+        } else {
+            let new_content = format!(
+                "---\ntype: Type\ntitle: {}\nvisible: false\n---\n\n# {}\n",
+                type_name, type_name
+            );
+            std::fs::write(&type_path, new_content)
+                .map_err(|e| format!("Failed to write {}: {e}", type_path.display()))?;
+        }
+        migrated += 1;
+    }
+
+    // Re-save config without hidden_sections
+    let config = parse_vault_config(&content)?;
+    save_vault_config(vault_path, config)?;
+
+    Ok(migrated)
+}
+
+/// Extract `hidden_sections` from raw YAML frontmatter.
+fn extract_hidden_sections(content: &str) -> Vec<String> {
+    let matter = Matter::<YAML>::new();
+    let parsed = matter.parse(content);
+
+    let hash = match parsed.data {
+        Some(gray_matter::Pod::Hash(map)) => map,
+        _ => return vec![],
+    };
+
+    match hash.get("hidden_sections") {
+        Some(gray_matter::Pod::Array(arr)) => arr
+            .iter()
+            .filter_map(|v| match v {
+                gray_matter::Pod::String(s) => Some(s.clone()),
+                _ => None,
+            })
+            .collect(),
+        _ => vec![],
+    }
+}
+
+/// Convert a Type name to a filesystem slug.
+fn type_name_to_slug(name: &str) -> String {
+    name.chars()
+        .map(|c| {
+            if c.is_ascii_alphanumeric() {
+                c.to_ascii_lowercase()
+            } else {
+                '-'
+            }
+        })
+        .collect::<String>()
+        .split('-')
+        .filter(|s| !s.is_empty())
+        .collect::<Vec<_>>()
+        .join("-")
+}
+
+/// Convert gray_matter::Pod to serde_json::Value.
+fn pod_to_json(pod: gray_matter::Pod) -> serde_json::Value {
+    match pod {
+        gray_matter::Pod::String(s) => serde_json::Value::String(s),
+        gray_matter::Pod::Integer(i) => serde_json::json!(i),
+        gray_matter::Pod::Float(f) => serde_json::json!(f),
+        gray_matter::Pod::Boolean(b) => serde_json::Value::Bool(b),
+        gray_matter::Pod::Array(arr) => {
+            serde_json::Value::Array(arr.into_iter().map(pod_to_json).collect())
+        }
+        gray_matter::Pod::Hash(map) => {
+            let obj: serde_json::Map<String, serde_json::Value> =
+                map.into_iter().map(|(k, v)| (k, pod_to_json(v))).collect();
+            serde_json::Value::Object(obj)
+        }
+        gray_matter::Pod::Null => serde_json::Value::Null,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_empty_returns_defaults() {
+        let config = parse_vault_config("").unwrap();
+        assert!(config.zoom.is_none());
+        assert!(config.view_mode.is_none());
+        assert!(config.tag_colors.is_none());
+    }
+
+    #[test]
+    fn parse_full_config() {
+        let content = r#"---
+type: config
+zoom: 1.1
+view_mode: all
+tag_colors:
+  engineering: blue
+  personal: green
+status_colors:
+  Active: green
+  Done: blue
+property_display_modes:
+  deadline: date
+---
+"#;
+        let config = parse_vault_config(content).unwrap();
+        assert_eq!(config.zoom, Some(1.1));
+        assert_eq!(config.view_mode.as_deref(), Some("all"));
+        let tags = config.tag_colors.unwrap();
+        assert_eq!(tags.get("engineering").unwrap(), "blue");
+        assert_eq!(tags.get("personal").unwrap(), "green");
+        let statuses = config.status_colors.unwrap();
+        assert_eq!(statuses.get("Active").unwrap(), "green");
+        let props = config.property_display_modes.unwrap();
+        assert_eq!(props.get("deadline").unwrap(), "date");
+    }
+
+    #[test]
+    fn roundtrip_serialization() {
+        let mut tag_colors = HashMap::new();
+        tag_colors.insert("work".to_string(), "blue".to_string());
+        let config = VaultConfig {
+            zoom: Some(1.2),
+            view_mode: Some("editor-only".to_string()),
+            tag_colors: Some(tag_colors),
+            status_colors: None,
+            property_display_modes: None,
+        };
+        let serialized = serialize_config(&config);
+        let parsed = parse_vault_config(&serialized).unwrap();
+        assert_eq!(parsed.zoom, Some(1.2));
+        assert_eq!(parsed.view_mode.as_deref(), Some("editor-only"));
+        assert_eq!(parsed.tag_colors.unwrap().get("work").unwrap(), "blue");
+    }
+
+    #[test]
+    fn get_config_missing_file() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let config = get_vault_config(dir.path().to_str().unwrap()).unwrap();
+        assert!(config.zoom.is_none());
+    }
+
+    #[test]
+    fn save_and_read_config() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let vault_path = dir.path().to_str().unwrap();
+        let mut status_colors = HashMap::new();
+        status_colors.insert("Active".to_string(), "green".to_string());
+        let config = VaultConfig {
+            zoom: Some(0.9),
+            view_mode: None,
+            tag_colors: None,
+            status_colors: Some(status_colors),
+            property_display_modes: None,
+        };
+        save_vault_config(vault_path, config).unwrap();
+
+        let loaded = get_vault_config(vault_path).unwrap();
+        assert_eq!(loaded.zoom, Some(0.9));
+        assert_eq!(
+            loaded.status_colors.unwrap().get("Active").unwrap(),
+            "green"
+        );
+    }
+
+    #[test]
+    fn migrate_hidden_sections_creates_type_notes_with_visible_false() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let vault_path = dir.path().to_str().unwrap();
+
+        // Create config with hidden_sections
+        let config_dir = dir.path().join("config");
+        std::fs::create_dir_all(&config_dir).unwrap();
+        std::fs::write(
+            config_dir.join("ui.config.md"),
+            "---\ntype: config\nhidden_sections:\n  - Bookmark\n  - Recipe\n---\n",
+        )
+        .unwrap();
+
+        let count = migrate_hidden_sections_to_visible(vault_path).unwrap();
+        assert_eq!(count, 2);
+
+        // Check type notes were created
+        let bookmark = std::fs::read_to_string(dir.path().join("type/bookmark.md")).unwrap();
+        assert!(bookmark.contains("visible: false"));
+        assert!(bookmark.contains("title: Bookmark"));
+
+        let recipe = std::fs::read_to_string(dir.path().join("type/recipe.md")).unwrap();
+        assert!(recipe.contains("visible: false"));
+
+        // Config should no longer have hidden_sections
+        let config_content = std::fs::read_to_string(config_dir.join("ui.config.md")).unwrap();
+        assert!(!config_content.contains("hidden_sections"));
+    }
+
+    #[test]
+    fn migrate_hidden_sections_updates_existing_type_note() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let vault_path = dir.path().to_str().unwrap();
+
+        // Create config with hidden_sections
+        let config_dir = dir.path().join("config");
+        std::fs::create_dir_all(&config_dir).unwrap();
+        std::fs::write(
+            config_dir.join("ui.config.md"),
+            "---\ntype: config\nhidden_sections:\n  - Project\n---\n",
+        )
+        .unwrap();
+
+        // Create existing type note without visible
+        let type_dir = dir.path().join("type");
+        std::fs::create_dir_all(&type_dir).unwrap();
+        std::fs::write(
+            type_dir.join("project.md"),
+            "---\ntype: Type\ntitle: Project\nicon: briefcase\n---\n\n# Project\n",
+        )
+        .unwrap();
+
+        let count = migrate_hidden_sections_to_visible(vault_path).unwrap();
+        assert_eq!(count, 1);
+
+        let content = std::fs::read_to_string(type_dir.join("project.md")).unwrap();
+        assert!(content.contains("visible: false"));
+        assert!(
+            content.contains("icon: briefcase"),
+            "should preserve existing fields"
+        );
+    }
+
+    #[test]
+    fn migrate_hidden_sections_skips_when_no_hidden_sections() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let vault_path = dir.path().to_str().unwrap();
+
+        let config_dir = dir.path().join("config");
+        std::fs::create_dir_all(&config_dir).unwrap();
+        std::fs::write(
+            config_dir.join("ui.config.md"),
+            "---\ntype: config\nzoom: 1.0\n---\n",
+        )
+        .unwrap();
+
+        let count = migrate_hidden_sections_to_visible(vault_path).unwrap();
+        assert_eq!(count, 0);
+    }
+
+    #[test]
+    fn migrate_hidden_sections_skips_when_no_config_file() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let count = migrate_hidden_sections_to_visible(dir.path().to_str().unwrap()).unwrap();
+        assert_eq!(count, 0);
+    }
+
+    #[test]
+    fn migrate_hidden_sections_does_not_duplicate_visible() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let vault_path = dir.path().to_str().unwrap();
+
+        let config_dir = dir.path().join("config");
+        std::fs::create_dir_all(&config_dir).unwrap();
+        std::fs::write(
+            config_dir.join("ui.config.md"),
+            "---\ntype: config\nhidden_sections:\n  - Note\n---\n",
+        )
+        .unwrap();
+
+        // Type note already has visible: false
+        let type_dir = dir.path().join("type");
+        std::fs::create_dir_all(&type_dir).unwrap();
+        std::fs::write(
+            type_dir.join("note.md"),
+            "---\ntype: Type\ntitle: Note\nvisible: false\n---\n",
+        )
+        .unwrap();
+
+        let count = migrate_hidden_sections_to_visible(vault_path).unwrap();
+        assert_eq!(count, 1);
+
+        let content = std::fs::read_to_string(type_dir.join("note.md")).unwrap();
+        // Should have exactly one visible: false, not two
+        assert_eq!(content.matches("visible:").count(), 1);
+    }
+
+    #[test]
+    fn type_name_to_slug_converts_names() {
+        assert_eq!(type_name_to_slug("Project"), "project");
+        assert_eq!(type_name_to_slug("Weekly Review"), "weekly-review");
+        assert_eq!(type_name_to_slug("My Note!"), "my-note");
+    }
+
+    #[test]
+    fn yaml_safe_key_quoting() {
+        assert_eq!(yaml_safe_key("simple"), "simple");
+        assert_eq!(yaml_safe_key("has space"), "\"has space\"");
+        assert_eq!(yaml_safe_key("has:colon"), "\"has:colon\"");
+    }
+}

src-tauri/tauri.conf.json

@@ -7,7 +7,7 @@
     "frontendDist": "../dist",
     "devUrl": "http://localhost:5202",
     "beforeDevCommand": "pnpm dev",
-    "beforeBuildCommand": "pnpm build && pnpm bundle-mcp"
+    "beforeBuildCommand": "pnpm build && pnpm bundle-mcp && bash scripts/bundle-qmd.sh"
   },
   "app": {
     "withGlobalTauri": true,
@@ -38,7 +38,8 @@
     "targets": "all",
     "createUpdaterArtifacts": true,
     "resources": {
-      "resources/mcp-server/**/*": "mcp-server/"
+      "resources/mcp-server/**/*": "mcp-server/",
+      "resources/qmd/**/*": "qmd/"
     },
     "icon": [
       "icons/32x32.png",

src/App.css

@@ -61,3 +61,14 @@
 .tab-status-pulse {
   animation: tab-status-pulse 1.2s ease-in-out infinite;
 }
+
+/* AI highlight animation — applied by useAiActivity when MCP calls ui_highlight */
+@keyframes ai-highlight-glow {
+  0% { box-shadow: inset 0 0 0 2px rgba(99, 102, 241, 0.8); }
+  50% { box-shadow: inset 0 0 8px 2px rgba(99, 102, 241, 0.4); }
+  100% { box-shadow: inset 0 0 0 2px rgba(99, 102, 241, 0); }
+}
+
+.ai-highlight {
+  animation: ai-highlight-glow 0.8s ease-out;
+}

src/App.test.tsx

@@ -179,7 +179,7 @@ describe('App', () => {
     await waitFor(() => {
       // "All Notes" should be rendered as the selected nav item
       expect(screen.getByText('All Notes')).toBeInTheDocument()
-      expect(screen.getByText('Favorites')).toBeInTheDocument()
+      expect(screen.getByText('Archive')).toBeInTheDocument()
     })
   })
 

src/App.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { Sidebar } from './components/Sidebar'
 import { NoteList } from './components/NoteList'
 import { Editor } from './components/Editor'
@@ -9,11 +9,12 @@ import { CommandPalette } from './components/CommandPalette'
 import { SearchPanel } from './components/SearchPanel'
 import { Toast } from './components/Toast'
 import { CommitDialog } from './components/CommitDialog'
+import { PulseView } from './components/PulseView'
 import { StatusBar } from './components/StatusBar'
 import { SettingsPanel } from './components/SettingsPanel'
 import { GitHubVaultModal } from './components/GitHubVaultModal'
 import { WelcomeScreen } from './components/WelcomeScreen'
-import { useMcpRegistration } from './hooks/useMcpRegistration'
+import { useMcpStatus } from './hooks/useMcpStatus'
 import { useVaultLoader } from './hooks/useVaultLoader'
 import { useSettings } from './hooks/useSettings'
 import { useNoteActions } from './hooks/useNoteActions'
@@ -30,22 +31,29 @@ import { useAutoSync } from './hooks/useAutoSync'
 import { useConflictResolver } from './hooks/useConflictResolver'
 import { useIndexing } from './hooks/useIndexing'
 import { useZoom } from './hooks/useZoom'
+import { useVaultConfig } from './hooks/useVaultConfig'
 import { useBuildNumber } from './hooks/useBuildNumber'
 import { useOnboarding } from './hooks/useOnboarding'
 import { useThemeManager } from './hooks/useThemeManager'
 import { useEditorSaveWithLinks } from './hooks/useEditorSaveWithLinks'
 import { useNavigationGestures } from './hooks/useNavigationGestures'
+import { useAiActivity } from './hooks/useAiActivity'
 import { ConflictResolverModal } from './components/ConflictResolverModal'
 import { UpdateBanner } from './components/UpdateBanner'
 import { invoke } from '@tauri-apps/api/core'
 import { isTauri, mockInvoke } from './mock-tauri'
-import type { SidebarSelection } from './types'
+import type { SidebarSelection, VaultEntry } from './types'
+import type { NoteListItem } from './utils/ai-context'
+import { filterEntries } from './utils/noteListHelpers'
+import { openLocalFile } from './utils/url'
 import './App.css'
 
-// Type declaration for mock content storage
+// Type declarations for mock content storage and test overrides
 declare global {
   interface Window {
     __mockContent?: Record<string, string>
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- mock handler map for Playwright test overrides
+    __mockHandlers?: Record<string, (args: any) => any>
   }
 }
 
@@ -99,15 +107,19 @@ function App() {
   // When onboarding resolves to a different vault path, update the switcher
   const resolvedPath = onboarding.state.status === 'ready' ? onboarding.state.vaultPath : vaultSwitcher.vaultPath
   const vault = useVaultLoader(resolvedPath)
+  useVaultConfig(resolvedPath)
   const { settings, saveSettings } = useSettings()
-  const themeManager = useThemeManager(resolvedPath, vault.entries, vault.allContent)
+  const themeManager = useThemeManager(resolvedPath, vault.entries, vault.allContent, vault.updateContent)
 
-  useMcpRegistration(resolvedPath, setToastMessage)
+  const { mcpStatus, installMcp } = useMcpStatus(resolvedPath, setToastMessage)
+
+  const indexing = useIndexing(resolvedPath)
 
   const autoSync = useAutoSync({
     vaultPath: resolvedPath,
     intervalMinutes: settings.auto_pull_interval_minutes,
     onVaultUpdated: vault.reloadVault,
+    onSyncUpdated: indexing.triggerIncrementalIndex,
     onConflict: (files) => {
       const names = files.map((f) => f.split('/').pop()).join(', ')
       setToastMessage(`Conflict in ${names} — click to resolve`)
@@ -118,8 +130,6 @@ function App() {
   // Ref bridges for conflict resolution callbacks (notes declared below)
   const openConflictFileRef = useRef<(relativePath: string) => void>(() => {})
 
-  const indexing = useIndexing(resolvedPath)
-
   const conflictResolver = useConflictResolver({
     vaultPath: resolvedPath,
     onResolved: () => {
@@ -132,12 +142,27 @@ function App() {
     onOpenFile: (relativePath) => openConflictFileRef.current(relativePath),
   })
 
-  const handleOpenConflictResolver = useCallback(() => {
-    if (autoSync.conflictFiles.length === 0) return
+  const handleOpenConflictResolver = useCallback(async () => {
+    let files = autoSync.conflictFiles
+    // If no cached conflicts, check directly — there may be pre-existing
+    // conflicts from a prior session that the pull flow didn't detect.
+    if (files.length === 0) {
+      try {
+        files = isTauri()
+          ? await invoke<string[]>('get_conflict_files', { vaultPath: resolvedPath })
+          : await mockInvoke<string[]>('get_conflict_files', { vaultPath: resolvedPath })
+      } catch {
+        return
+      }
+      if (files.length === 0) {
+        setToastMessage('No merge conflicts to resolve')
+        return
+      }
+    }
     autoSync.pausePull()
-    conflictResolver.initFiles(autoSync.conflictFiles)
+    conflictResolver.initFiles(files)
     dialogs.openConflictResolver()
-  }, [autoSync, conflictResolver, dialogs])
+  }, [autoSync, conflictResolver, dialogs, resolvedPath])
 
   const handleCloseConflictResolver = useCallback(() => {
     autoSync.resumePull()
@@ -208,6 +233,64 @@ function App() {
 
   useNavigationGestures({ onGoBack: handleGoBack, onGoForward: handleGoForward })
 
+  // O(1) path lookup map — rebuilt only when vault.entries changes
+  const entriesByPath = useMemo(() => {
+    const map = new Map<string, VaultEntry>()
+    for (const e of vault.entries) map.set(e.path, e)
+    return map
+  }, [vault.entries])
+
+  // MCP UI bridge: react to AI-driven open/highlight/vault-change events
+  const openNoteByPath = useCallback((path: string) => {
+    const entry = entriesByPath.get(path) ?? entriesByPath.get(`${resolvedPath}/${path}`)
+    if (entry) {
+      notes.handleSelectNote(entry)
+    } else {
+      // Entry not yet in vault (just created) — reload then open
+      vault.reloadVault().then(freshEntries => {
+        const fresh = (freshEntries as VaultEntry[]).find(e => e.path === path || e.path === `${resolvedPath}/${path}`)
+        if (fresh) notes.handleSelectNote(fresh)
+      })
+    }
+  }, [entriesByPath, vault, notes, resolvedPath])
+
+  const aiActivity = useAiActivity({
+    onOpenNote: openNoteByPath,
+    onOpenTab: openNoteByPath,
+    onSetFilter: (filterType) => {
+      setSelection({ kind: 'sectionGroup', type: filterType })
+    },
+    onVaultChanged: () => { vault.reloadVault() },
+  })
+
+  // Stable callback for Pulse "open note" — never triggers reloadVault.
+  // Pulse files always exist in the vault; if somehow not found, silently skip.
+  const handlePulseOpenNote = useCallback((relativePath: string) => {
+    const fullPath = `${resolvedPath}/${relativePath}`
+    const entry = entriesByPath.get(fullPath) ?? entriesByPath.get(relativePath)
+    if (entry) notes.handleSelectNote(entry)
+  }, [entriesByPath, resolvedPath, notes])
+
+  // Agent file operation handlers: auto-open created notes, live-refresh modified notes
+  const handleAgentFileCreated = useCallback((relativePath: string) => {
+    vault.reloadVault().then(freshEntries => {
+      const entry = (freshEntries as VaultEntry[]).find(e => e.path === relativePath || e.path === `${resolvedPath}/${relativePath}`)
+      if (entry) notes.handleSelectNote(entry)
+    })
+  }, [vault, notes, resolvedPath])
+
+  const handleAgentFileModified = useCallback((relativePath: string) => {
+    const fullPath = `${resolvedPath}/${relativePath}`
+    const matchPath = notes.tabs.some(t => t.entry.path === relativePath) ? relativePath : fullPath
+    if (notes.tabs.some(t => t.entry.path === matchPath)) {
+      vault.reloadVault()
+    }
+  }, [vault, notes, resolvedPath])
+
+  const handleAgentVaultChanged = useCallback(() => {
+    vault.reloadVault()
+  }, [vault])
+
   const { triggerIncrementalIndex } = indexing
   const onAfterSave = useCallback(() => {
     vault.loadModifiedFiles()
@@ -227,8 +310,13 @@ function App() {
       const fullPath = `${resolvedPath}/${relativePath}`
       const entry = vault.entries.find(e => e.path === fullPath)
       if (entry) {
+        // Markdown note — open inside Laputa editor
         notes.handleSelectNote(entry)
         dialogs.closeConflictResolver()
+      } else {
+        // Non-note file (e.g. .laputa-cache.json, settings.json) —
+        // open with system default app so the user can inspect/edit it
+        openLocalFile(fullPath)
       }
     }
   }, [resolvedPath, vault.entries, notes, dialogs])
@@ -249,6 +337,7 @@ function App() {
     handleUpdateFrontmatter: notes.handleUpdateFrontmatter,
     handleDeleteProperty: notes.handleDeleteProperty, setToastMessage,
     createTypeEntry: notes.createTypeEntrySilent,
+    onFrontmatterPersisted: vault.loadModifiedFiles,
   })
 
   const handleDeleteNote = useCallback(async (path: string) => {
@@ -314,6 +403,32 @@ function App() {
     // 'available' → UpdateBanner handles it automatically
   }, [updateActions, updateStatus.state, setToastMessage])
 
+  const handleRestoreDefaultThemes = useCallback(async () => {
+    if (!resolvedPath) return
+    try {
+      const tauriInvoke = isTauri() ? invoke : mockInvoke
+      const msg = await tauriInvoke<string>('restore_default_themes', { vaultPath: resolvedPath })
+      await vault.reloadVault()
+      await themeManager.reloadThemes()
+      setToastMessage(msg)
+    } catch (err) {
+      setToastMessage(`Failed to restore themes: ${err}`)
+    }
+  }, [resolvedPath, vault, themeManager, setToastMessage])
+
+  const handleRepairVault = useCallback(async () => {
+    if (!resolvedPath) return
+    try {
+      const tauriInvoke = isTauri() ? invoke : mockInvoke
+      const msg = await tauriInvoke<string>('repair_vault', { vaultPath: resolvedPath })
+      await vault.reloadVault()
+      await themeManager.reloadThemes()
+      setToastMessage(msg)
+    } catch (err) {
+      setToastMessage(`Failed to repair vault: ${err}`)
+    }
+  }, [resolvedPath, vault, themeManager, setToastMessage])
+
   const commands = useAppCommands({
     activeTabPath: notes.activeTabPath, activeTabPathRef: notes.activeTabPathRef,
     handleCloseTabRef: notes.handleCloseTabRef, tabs: notes.tabs,
@@ -332,7 +447,6 @@ function App() {
     onArchiveNote: entryActions.handleArchiveNote, onUnarchiveNote: entryActions.handleUnarchiveNote,
     onCommitPush: commitFlow.openCommitDialog,
     onResolveConflicts: handleOpenConflictResolver,
-    conflictCount: autoSync.conflictFiles.length,
     onSetViewMode: setViewMode,
     onToggleInspector: () => layout.setInspectorCollapsed(c => !c),
     onToggleDiff: () => diffToggleRef.current(),
@@ -365,12 +479,30 @@ function App() {
     onCheckForUpdates: handleCheckForUpdates,
     onRemoveActiveVault: () => vaultSwitcher.removeVault(vaultSwitcher.vaultPath),
     onRestoreGettingStarted: vaultSwitcher.restoreGettingStarted,
+    onRestoreDefaultThemes: handleRestoreDefaultThemes,
     isGettingStartedHidden: vaultSwitcher.isGettingStartedHidden,
     vaultCount: vaultSwitcher.allVaults.length,
+    mcpStatus,
+    onInstallMcp: installMcp,
+    onReindexVault: indexing.triggerFullReindex,
+    onRepairVault: handleRepairVault,
   })
 
   const activeTab = notes.tabs.find((t) => t.entry.path === notes.activeTabPath) ?? null
 
+  const aiNoteList = useMemo<NoteListItem[]>(() => {
+    return filterEntries(vault.entries, selection).map(e => ({
+      path: e.path, title: e.title, type: e.isA ?? 'Note',
+    }))
+  }, [vault.entries, selection])
+
+  const aiNoteListFilter = useMemo(() => {
+    if (selection.kind === 'sectionGroup') return { type: selection.type, query: '' }
+    if (selection.kind === 'topic') return { type: null, query: selection.entry.title }
+    if (selection.kind === 'entity') return { type: null, query: selection.entry.title }
+    return { type: null, query: '' }
+  }, [selection])
+
   // Show welcome/onboarding screen when vault doesn't exist
   if (onboarding.state.status === 'welcome' || onboarding.state.status === 'vault-missing') {
     const defaultPath = onboarding.state.defaultPath
@@ -406,20 +538,24 @@ function App() {
         {sidebarVisible && (
           <>
             <div className="app__sidebar" style={{ width: layout.sidebarWidth }}>
-              <Sidebar entries={vault.entries} selection={selection} onSelect={setSelection} onSelectNote={notes.handleSelectNote} onCreateType={notes.handleCreateNoteImmediate} onCreateNewType={dialogs.openCreateType} onCustomizeType={entryActions.handleCustomizeType} onUpdateTypeTemplate={entryActions.handleUpdateTypeTemplate} onReorderSections={entryActions.handleReorderSections} onRenameSection={entryActions.handleRenameSection} modifiedCount={vault.modifiedFiles.length} onCommitPush={commitFlow.openCommitDialog} />
+              <Sidebar entries={vault.entries} selection={selection} onSelect={setSelection} onSelectNote={notes.handleSelectNote} onCreateType={notes.handleCreateNoteImmediate} onCreateNewType={dialogs.openCreateType} onCustomizeType={entryActions.handleCustomizeType} onUpdateTypeTemplate={entryActions.handleUpdateTypeTemplate} onReorderSections={entryActions.handleReorderSections} onRenameSection={entryActions.handleRenameSection} onToggleTypeVisibility={entryActions.handleToggleTypeVisibility} modifiedCount={vault.modifiedFiles.length} onCommitPush={commitFlow.openCommitDialog} isGitVault={!vault.modifiedFilesError} />
             </div>
             <ResizeHandle onResize={layout.handleSidebarResize} />
           </>
         )}
         {noteListVisible && (
           <>
-            <div className="app__note-list" style={{ width: layout.noteListWidth }}>
-              <NoteList entries={vault.entries} selection={selection} selectedNote={activeTab?.entry ?? null} allContent={vault.allContent} modifiedFiles={vault.modifiedFiles} modifiedFilesError={vault.modifiedFilesError} getNoteStatus={vault.getNoteStatus} sidebarCollapsed={!sidebarVisible} onSelectNote={notes.handleSelectNote} onReplaceActiveTab={notes.handleReplaceActiveTab} onCreateNote={notes.handleCreateNoteImmediate} onBulkArchive={bulkActions.handleBulkArchive} onBulkTrash={bulkActions.handleBulkTrash} onUpdateTypeSort={notes.handleUpdateFrontmatter} updateEntry={vault.updateEntry} />
+            <div className={`app__note-list${aiActivity.highlightElement === 'notelist' ? ' ai-highlight' : ''}`} style={{ width: layout.noteListWidth }}>
+              {selection.kind === 'filter' && selection.filter === 'pulse' ? (
+                <PulseView vaultPath={resolvedPath} onOpenNote={handlePulseOpenNote} sidebarCollapsed={!sidebarVisible} onExpandSidebar={() => setViewMode('all')} />
+              ) : (
+                <NoteList entries={vault.entries} selection={selection} selectedNote={activeTab?.entry ?? null} allContent={vault.allContent} modifiedFiles={vault.modifiedFiles} modifiedFilesError={vault.modifiedFilesError} getNoteStatus={vault.getNoteStatus} sidebarCollapsed={!sidebarVisible} onSelectNote={notes.handleSelectNote} onReplaceActiveTab={notes.handleReplaceActiveTab} onCreateNote={notes.handleCreateNoteImmediate} onBulkArchive={bulkActions.handleBulkArchive} onBulkTrash={bulkActions.handleBulkTrash} onUpdateTypeSort={notes.handleUpdateFrontmatter} updateEntry={vault.updateEntry} />
+              )}
             </div>
             <ResizeHandle onResize={layout.handleNoteListResize} />
           </>
         )}
-        <div className="app__editor">
+        <div className={`app__editor${aiActivity.highlightElement === 'editor' || aiActivity.highlightElement === 'tab' ? ' ai-highlight' : ''}`}>
           <Editor
             tabs={notes.tabs}
             activeTabPath={notes.activeTabPath}
@@ -446,6 +582,8 @@ function App() {
             showAIChat={dialogs.showAIChat}
             onToggleAIChat={dialogs.toggleAIChat}
             vaultPath={resolvedPath}
+            noteList={aiNoteList}
+            noteListFilter={aiNoteListFilter}
             onTrashNote={entryActions.handleTrashNote}
             onRestoreNote={entryActions.handleRestoreNote}
             onDeleteNote={handleDeleteNote}
@@ -463,11 +601,14 @@ function App() {
             onGoForward={handleGoForward}
             leftPanelsCollapsed={!sidebarVisible && !noteListVisible}
             isDarkTheme={themeManager.isDark}
+            onFileCreated={handleAgentFileCreated}
+            onFileModified={handleAgentFileModified}
+            onVaultChanged={handleAgentVaultChanged}
           />
         </div>
       </div>
       <UpdateBanner status={updateStatus} actions={updateActions} />
-      <StatusBar noteCount={vault.entries.length} modifiedCount={vault.modifiedFiles.length} vaultPath={vaultSwitcher.vaultPath} vaults={vaultSwitcher.allVaults} onSwitchVault={vaultSwitcher.switchVault} onOpenSettings={dialogs.openSettings} onOpenLocalFolder={vaultSwitcher.handleOpenLocalFolder} onConnectGitHub={dialogs.openGitHubVault} onClickPending={() => setSelection({ kind: 'filter', filter: 'changes' })} hasGitHub={!!settings.github_token} syncStatus={autoSync.syncStatus} lastSyncTime={autoSync.lastSyncTime} conflictCount={autoSync.conflictFiles.length} lastCommitInfo={autoSync.lastCommitInfo} onTriggerSync={autoSync.triggerSync} onOpenConflictResolver={handleOpenConflictResolver} zoomLevel={zoom.zoomLevel} onZoomReset={zoom.zoomReset} buildNumber={buildNumber} onCheckForUpdates={handleCheckForUpdates} indexingProgress={indexing.progress} onRetryIndexing={indexing.retryIndexing} onRemoveVault={vaultSwitcher.removeVault} />
+      <StatusBar noteCount={vault.entries.length} modifiedCount={vault.modifiedFiles.length} vaultPath={vaultSwitcher.vaultPath} vaults={vaultSwitcher.allVaults} onSwitchVault={vaultSwitcher.switchVault} onOpenSettings={dialogs.openSettings} onOpenLocalFolder={vaultSwitcher.handleOpenLocalFolder} onConnectGitHub={dialogs.openGitHubVault} onClickPending={() => setSelection({ kind: 'filter', filter: 'changes' })} hasGitHub={!!settings.github_token} syncStatus={autoSync.syncStatus} lastSyncTime={autoSync.lastSyncTime} conflictCount={autoSync.conflictFiles.length} lastCommitInfo={autoSync.lastCommitInfo} onTriggerSync={autoSync.triggerSync} onOpenConflictResolver={handleOpenConflictResolver} zoomLevel={zoom.zoomLevel} onZoomReset={zoom.zoomReset} buildNumber={buildNumber} onCheckForUpdates={handleCheckForUpdates} indexingProgress={indexing.progress} lastIndexedTime={indexing.lastIndexedTime} onRetryIndexing={indexing.retryIndexing} onReindexVault={indexing.triggerFullReindex} onRemoveVault={vaultSwitcher.removeVault} mcpStatus={mcpStatus} onInstallMcp={installMcp} />
       <Toast message={toastMessage} onDismiss={() => setToastMessage(null)} />
       <QuickOpenPalette open={dialogs.showQuickOpen} entries={vault.entries} onSelect={notes.handleSelectNote} onClose={dialogs.closeQuickOpen} />
       <CommandPalette open={dialogs.showCommandPalette} commands={commands} onClose={dialogs.closeCommandPalette} />

src/components/AIChatPanel.tsx

@@ -18,6 +18,7 @@ interface AIChatPanelProps {
   allContent: Record<string, string>
   entries?: VaultEntry[]
   onClose: () => void
+  onNavigateWikilink?: (target: string) => void
 }
 
 function TypingIndicator() {
@@ -99,10 +100,10 @@ function ContextSearchDropdown({
   )
 }
 
-function AssistantMessage({ msg, onRetry }: { msg: ChatMessage; onRetry: () => void }) {
+function AssistantMessage({ msg, onRetry, onNavigateWikilink }: { msg: ChatMessage; onRetry: () => void; onNavigateWikilink?: (target: string) => void }) {
   return (
     <div>
-      <MarkdownContent content={msg.content} />
+      <MarkdownContent content={msg.content} onWikilinkClick={onNavigateWikilink} />
       <div className="flex items-center gap-3" style={{ marginTop: 4 }}>
         <button className="border-none bg-transparent p-0 text-muted-foreground cursor-pointer hover:underline"
           style={{ fontSize: 11 }} onClick={() => navigator.clipboard.writeText(msg.content)}>
@@ -121,10 +122,10 @@ function AssistantMessage({ msg, onRetry }: { msg: ChatMessage; onRetry: () => v
   )
 }
 
-function StreamingContent({ content }: { content: string }) {
+function StreamingContent({ content, onNavigateWikilink }: { content: string; onNavigateWikilink?: (target: string) => void }) {
   return (
     <div style={{ marginBottom: 12 }}>
-      <MarkdownContent content={content} />
+      <MarkdownContent content={content} onWikilinkClick={onNavigateWikilink} />
     </div>
   )
 }
@@ -176,7 +177,7 @@ function useContextNotes(entry: VaultEntry | null) {
 
 // --- Main component ---
 
-export function AIChatPanel({ entry, allContent, entries = [], onClose }: AIChatPanelProps) {
+export function AIChatPanel({ entry, allContent, entries = [], onClose, onNavigateWikilink }: AIChatPanelProps) {
   const [input, setInput] = useState('')
   const [showSearch, setShowSearch] = useState(false)
   const messagesEndRef = useRef<HTMLDivElement>(null)
@@ -213,7 +214,7 @@ export function AIChatPanel({ entry, allContent, entries = [], onClose }: AIChat
       <MessageList
         messages={chat.messages} isStreaming={chat.isStreaming}
         streamingContent={chat.streamingContent} onRetry={chat.retryMessage}
-        messagesEndRef={messagesEndRef}
+        messagesEndRef={messagesEndRef} onNavigateWikilink={onNavigateWikilink}
       />
 
       <QuickActionsBar actions={QUICK_ACTIONS} disabled={chat.isStreaming}
@@ -284,10 +285,11 @@ function ContextBar({
 }
 
 function MessageList({
-  messages, isStreaming, streamingContent, onRetry, messagesEndRef,
+  messages, isStreaming, streamingContent, onRetry, messagesEndRef, onNavigateWikilink,
 }: {
   messages: ChatMessage[]; isStreaming: boolean; streamingContent: string
   onRetry: (idx: number) => void; messagesEndRef: React.RefObject<HTMLDivElement | null>
+  onNavigateWikilink?: (target: string) => void
 }) {
   return (
     <div className="flex-1 overflow-y-auto" style={{ padding: 12 }}>
@@ -302,10 +304,10 @@ function MessageList({
         <div key={msg.id} style={{ marginBottom: 12 }}>
           {msg.role === 'user'
             ? <UserBubble content={msg.content} />
-            : <AssistantMessage msg={msg} onRetry={() => onRetry(idx)} />}
+            : <AssistantMessage msg={msg} onRetry={() => onRetry(idx)} onNavigateWikilink={onNavigateWikilink} />}
         </div>
       ))}
-      {isStreaming && streamingContent && <StreamingContent content={streamingContent} />}
+      {isStreaming && streamingContent && <StreamingContent content={streamingContent} onNavigateWikilink={onNavigateWikilink} />}
       {isStreaming && !streamingContent && <TypingIndicator />}
       <div ref={messagesEndRef} />
     </div>

src/components/AiActionCard.test.tsx

@@ -66,8 +66,8 @@ describe('AiActionCard', () => {
     expect(header.getAttribute('tabindex')).toBe('0')
   })
 
-  it('uses lighter background for ui_ tools', () => {
-    render(<AiActionCard {...defaults} tool="ui_open_tab" label="Opened tab" />)
+  it('uses lighter background for open_note tool', () => {
+    render(<AiActionCard {...defaults} tool="open_note" label="Opening note" />)
     const card = screen.getByTestId('ai-action-card')
     expect(card.style.background).toContain('0.06')
   })

src/components/AiActionCard.tsx

@@ -1,7 +1,8 @@
 import { type KeyboardEvent, type ReactNode, useCallback } from 'react'
 import {
-  PencilSimple, MagnifyingGlass, Link, Trash, ChartBar, Eye, Sparkle,
+  PencilSimple, MagnifyingGlass, Trash, ChartBar, Eye,
   CircleNotch, CheckCircle, XCircle, CaretRight, CaretDown,
+  Terminal, File, FolderOpen, NotePencil,
 } from '@phosphor-icons/react'
 
 export type AiActionStatus = 'pending' | 'done' | 'error'
@@ -23,18 +24,21 @@ const MAX_DETAIL_LENGTH = 800
 type IconRenderer = (size: number) => ReactNode
 
 const TOOL_ICON_MAP: Record<string, IconRenderer> = {
-  create_note: (s) => <PencilSimple size={s} />,
-  edit_note_frontmatter: (s) => <PencilSimple size={s} />,
-  append_to_note: (s) => <PencilSimple size={s} />,
+  // Native Claude Code tools
+  Bash: (s) => <Terminal size={s} />,
+  Write: (s) => <PencilSimple size={s} />,
+  Edit: (s) => <NotePencil size={s} />,
+  Read: (s) => <File size={s} />,
+  Glob: (s) => <FolderOpen size={s} />,
+  Grep: (s) => <MagnifyingGlass size={s} />,
+  // Laputa MCP tools
   search_notes: (s) => <MagnifyingGlass size={s} />,
-  list_notes: (s) => <MagnifyingGlass size={s} />,
-  link_notes: (s) => <Link size={s} />,
+  get_vault_context: (s) => <ChartBar size={s} />,
+  get_note: (s) => <File size={s} />,
+  open_note: (s) => <Eye size={s} />,
+  // Legacy tools (for backward compatibility with existing messages)
+  create_note: (s) => <PencilSimple size={s} />,
   delete_note: (s) => <Trash size={s} />,
-  vault_context: (s) => <ChartBar size={s} />,
-  ui_open_note: (s) => <Eye size={s} />,
-  ui_open_tab: (s) => <Eye size={s} />,
-  ui_highlight: (s) => <Sparkle size={s} />,
-  ui_set_filter: (s) => <Sparkle size={s} />,
 }
 
 const DEFAULT_ICON: IconRenderer = (s) => <PencilSimple size={s} />
@@ -96,11 +100,15 @@ function DetailBlock({ label, content, isError }: {
   )
 }
 
+/** Whether this tool is a Laputa UI-only tool (lighter styling). */
+function isUiOnlyTool(tool: string): boolean {
+  return tool === 'open_note'
+}
+
 export function AiActionCard({
   tool, label, path, status, input, output, expanded, onToggle, onOpenNote,
 }: AiActionCardProps) {
   const renderIcon = TOOL_ICON_MAP[tool] ?? DEFAULT_ICON
-  const isUiTool = tool.startsWith('ui_')
   const hasDetails = !!(input || output)
 
   const handleKeyDown = useCallback((e: KeyboardEvent) => {
@@ -129,7 +137,7 @@ export function AiActionCard({
       className="rounded"
       style={{
         fontSize: 12,
-        background: isUiTool ? 'rgba(74, 158, 255, 0.06)' : 'rgba(74, 158, 255, 0.1)',
+        background: isUiOnlyTool(tool) ? 'rgba(74, 158, 255, 0.06)' : 'rgba(74, 158, 255, 0.1)',
       }}
     >
       <div

src/components/AiMessage.test.tsx

@@ -2,15 +2,20 @@ import { describe, it, expect, vi } from 'vitest'
 import { render, screen, fireEvent } from '@testing-library/react'
 import { AiMessage } from './AiMessage'
 
+vi.mock('./MarkdownContent', () => ({
+  MarkdownContent: ({ content }: { content: string }) => <div data-testid="markdown-content">{content}</div>,
+}))
+
 describe('AiMessage', () => {
   it('renders user message', () => {
     render(<AiMessage userMessage="Hello AI" actions={[]} />)
     expect(screen.getByText('Hello AI')).toBeTruthy()
   })
 
-  it('renders response text', () => {
-    render(<AiMessage userMessage="Ask" actions={[]} response="Here is the answer" />)
-    expect(screen.getByText('Here is the answer')).toBeTruthy()
+  it('renders response as markdown', () => {
+    render(<AiMessage userMessage="Ask" actions={[]} response="Here is the **answer**" />)
+    expect(screen.getByTestId('markdown-content')).toBeTruthy()
+    expect(screen.getByText('Here is the **answer**')).toBeTruthy()
   })
 
   it('shows undo button with response', () => {
@@ -18,23 +23,31 @@ describe('AiMessage', () => {
     expect(screen.getByTestId('undo-button')).toBeTruthy()
   })
 
-  it('renders reasoning toggle collapsed by default', () => {
-    render(<AiMessage userMessage="Ask" reasoning="Thinking about it..." actions={[]} />)
+  it('shows reasoning expanded while streaming (reasoningDone=false)', () => {
+    render(<AiMessage userMessage="Ask" reasoning="Thinking about it..." reasoningDone={false} actions={[]} />)
     expect(screen.getByTestId('reasoning-toggle')).toBeTruthy()
-    expect(screen.queryByTestId('reasoning-content')).toBeNull()
-  })
-
-  it('expands reasoning on toggle click', () => {
-    render(<AiMessage userMessage="Ask" reasoning="Thinking about it..." actions={[]} />)
-    fireEvent.click(screen.getByTestId('reasoning-toggle'))
     expect(screen.getByTestId('reasoning-content')).toBeTruthy()
     expect(screen.getByText('Thinking about it...')).toBeTruthy()
   })
 
-  it('collapses reasoning on second click', () => {
-    render(<AiMessage userMessage="Ask" reasoning="Thinking..." actions={[]} />)
+  it('auto-collapses reasoning when reasoningDone=true', () => {
+    render(<AiMessage userMessage="Ask" reasoning="Thinking..." reasoningDone actions={[]} />)
+    expect(screen.getByTestId('reasoning-toggle')).toBeTruthy()
+    expect(screen.queryByTestId('reasoning-content')).toBeNull()
+  })
+
+  it('expands collapsed reasoning on toggle click', () => {
+    render(<AiMessage userMessage="Ask" reasoning="Thinking..." reasoningDone actions={[]} />)
+    // Starts collapsed (reasoningDone=true)
+    expect(screen.queryByTestId('reasoning-content')).toBeNull()
     fireEvent.click(screen.getByTestId('reasoning-toggle'))
     expect(screen.getByTestId('reasoning-content')).toBeTruthy()
+  })
+
+  it('collapses expanded reasoning on toggle click', () => {
+    render(<AiMessage userMessage="Ask" reasoning="Thinking..." reasoningDone={false} actions={[]} />)
+    // Starts expanded (reasoningDone=false)
+    expect(screen.getByTestId('reasoning-content')).toBeTruthy()
     fireEvent.click(screen.getByTestId('reasoning-toggle'))
     expect(screen.queryByTestId('reasoning-content')).toBeNull()
   })
@@ -89,6 +102,47 @@ describe('AiMessage', () => {
     expect(screen.queryByTestId('ai-action-card')).toBeNull()
   })
 
+  it('renders reference pills in user bubble', () => {
+    render(
+      <AiMessage
+        userMessage="Tell me about this"
+        references={[
+          { title: 'Marco', path: 'person/marco.md', type: 'Person' },
+          { title: 'Project X', path: 'project/x.md', type: 'Project' },
+        ]}
+        actions={[]}
+      />,
+    )
+    const pills = screen.getAllByTestId('message-reference-pill')
+    expect(pills).toHaveLength(2)
+    expect(pills[0].textContent).toBe('Marco')
+    expect(pills[1].textContent).toBe('Project X')
+  })
+
+  it('does not render pills when no references', () => {
+    render(<AiMessage userMessage="Hello" actions={[]} />)
+    expect(screen.queryAllByTestId('message-reference-pill')).toHaveLength(0)
+  })
+
+  it('does not render pills when references array is empty', () => {
+    render(<AiMessage userMessage="Hello" references={[]} actions={[]} />)
+    expect(screen.queryAllByTestId('message-reference-pill')).toHaveLength(0)
+  })
+
+  it('calls onOpenNote when a reference pill is clicked', () => {
+    const onOpenNote = vi.fn()
+    render(
+      <AiMessage
+        userMessage="Check this"
+        references={[{ title: 'Alpha', path: 'note/alpha.md', type: 'Note' }]}
+        actions={[]}
+        onOpenNote={onOpenNote}
+      />,
+    )
+    fireEvent.click(screen.getByTestId('message-reference-pill'))
+    expect(onOpenNote).toHaveBeenCalledWith('note/alpha.md')
+  })
+
   it('expands and collapses action cards independently', () => {
     render(
       <AiMessage

src/components/AiMessage.tsx

@@ -1,6 +1,9 @@
-import { useState, useCallback } from 'react'
+import { useState, useCallback, useEffect, useRef } from 'react'
 import { CaretRight, CaretDown, Brain, ArrowCounterClockwise } from '@phosphor-icons/react'
 import { AiActionCard, type AiActionStatus } from './AiActionCard'
+import { MarkdownContent } from './MarkdownContent'
+import type { NoteReference } from '../utils/ai-context'
+import { getTypeColor, getTypeLightColor } from '../utils/typeColors'
 
 export interface AiAction {
   tool: string
@@ -14,14 +17,48 @@ export interface AiAction {
 
 export interface AiMessageProps {
   userMessage: string
+  references?: NoteReference[]
   reasoning?: string
+  reasoningDone?: boolean
   actions: AiAction[]
   response?: string
   isStreaming?: boolean
   onOpenNote?: (path: string) => void
+  onNavigateWikilink?: (target: string) => void
 }
 
-function UserBubble({ content }: { content: string }) {
+function ReferencePill({ reference, onClick }: {
+  reference: NoteReference
+  onClick?: (path: string) => void
+}) {
+  const color = getTypeColor(reference.type)
+  const lightColor = getTypeLightColor(reference.type)
+  return (
+    <button
+      className="inline-flex items-center border-none cursor-pointer transition-opacity hover:opacity-80"
+      style={{
+        background: lightColor,
+        color,
+        borderRadius: 9999,
+        padding: '1px 8px',
+        fontSize: 11,
+        fontWeight: 500,
+        fontFamily: 'inherit',
+        lineHeight: 1.4,
+      }}
+      onClick={() => onClick?.(reference.path)}
+      data-testid="message-reference-pill"
+    >
+      {reference.title}
+    </button>
+  )
+}
+
+function UserBubble({ content, references, onOpenNote }: {
+  content: string
+  references?: NoteReference[]
+  onOpenNote?: (path: string) => void
+}) {
   return (
     <div className="flex justify-end" style={{ marginBottom: 8 }}>
       <div
@@ -35,6 +72,13 @@ function UserBubble({ content }: { content: string }) {
           lineHeight: 1.5,
         }}
       >
+        {references && references.length > 0 && (
+          <div className="flex flex-wrap gap-1" style={{ marginBottom: 4 }}>
+            {references.map(ref => (
+              <ReferencePill key={ref.path} reference={ref} onClick={onOpenNote} />
+            ))}
+          </div>
+        )}
         {content}
       </div>
     </div>
@@ -44,6 +88,14 @@ function UserBubble({ content }: { content: string }) {
 function ReasoningBlock({ text, expanded, onToggle }: {
   text: string; expanded: boolean; onToggle: () => void
 }) {
+  const contentRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (expanded && contentRef.current) {
+      contentRef.current.scrollTop = contentRef.current.scrollHeight
+    }
+  }, [expanded, text])
+
   return (
     <div style={{ marginBottom: 8 }}>
       <button
@@ -58,8 +110,9 @@ function ReasoningBlock({ text, expanded, onToggle }: {
       </button>
       {expanded && (
         <div
+          ref={contentRef}
           className="text-muted-foreground"
-          style={{ fontSize: 12, lineHeight: 1.5, padding: '4px 0 4px 20px' }}
+          style={{ fontSize: 12, lineHeight: 1.5, padding: '4px 0 4px 20px', maxHeight: 200, overflowY: 'auto' }}
           data-testid="reasoning-content"
         >
           {text}
@@ -95,10 +148,10 @@ function ActionCardsList({ actions, onOpenNote, expandedIds, onToggleExpand }: {
   )
 }
 
-function ResponseBlock({ text }: { text: string }) {
+function ResponseBlock({ text, onNavigateWikilink }: { text: string; onNavigateWikilink?: (target: string) => void }) {
   return (
     <div style={{ marginBottom: 4 }}>
-      <div style={{ fontSize: 13, lineHeight: 1.6 }}>{text}</div>
+      <MarkdownContent content={text} onWikilinkClick={onNavigateWikilink} />
       <button
         className="flex items-center gap-1 border-none bg-transparent p-0 text-muted-foreground cursor-pointer hover:text-foreground transition-colors"
         style={{ fontSize: 11, marginTop: 4 }}
@@ -123,10 +176,16 @@ function StreamingIndicator() {
   )
 }
 
-export function AiMessage({ userMessage, reasoning, actions, response, isStreaming, onOpenNote }: AiMessageProps) {
-  const [reasoningExpanded, setReasoningExpanded] = useState(false)
+export function AiMessage({ userMessage, references, reasoning, reasoningDone, actions, response, isStreaming, onOpenNote, onNavigateWikilink }: AiMessageProps) {
+  // Manual override: null = follow auto behavior, true/false = user forced
+  const [userOverride, setUserOverride] = useState(false)
   const [expandedActions, setExpandedActions] = useState<Set<string>>(new Set())
 
+  // Auto: expanded while reasoning streams, collapsed once done
+  // User can manually toggle to override the auto state
+  const autoExpanded = !reasoningDone
+  const reasoningExpanded = userOverride ? !autoExpanded : autoExpanded
+
   const toggleAction = useCallback((toolId: string) => {
     setExpandedActions(prev => {
       const next = new Set(prev)
@@ -138,12 +197,12 @@ export function AiMessage({ userMessage, reasoning, actions, response, isStreami
 
   return (
     <div data-testid="ai-message" style={{ marginBottom: 16 }}>
-      <UserBubble content={userMessage} />
+      <UserBubble content={userMessage} references={references} onOpenNote={onOpenNote} />
       {reasoning && (
         <ReasoningBlock
           text={reasoning}
           expanded={reasoningExpanded}
-          onToggle={() => setReasoningExpanded(!reasoningExpanded)}
+          onToggle={() => setUserOverride(prev => !prev)}
         />
       )}
       {actions.length > 0 && (
@@ -154,7 +213,7 @@ export function AiMessage({ userMessage, reasoning, actions, response, isStreami
           onToggleExpand={toggleAction}
         />
       )}
-      {response && <ResponseBlock text={response} />}
+      {response && <ResponseBlock text={response} onNavigateWikilink={onNavigateWikilink} />}
       {isStreaming && !response && <StreamingIndicator />}
     </div>
   )

src/components/AiPanel.test.tsx

@@ -4,10 +4,12 @@ import { AiPanel } from './AiPanel'
 import type { VaultEntry } from '../types'
 
 // Mock the hooks and utils to isolate component tests
+let mockMessages: ReturnType<typeof import('../hooks/useAiAgent').useAiAgent>['messages'] = []
+let mockStatus: ReturnType<typeof import('../hooks/useAiAgent').useAiAgent>['status'] = 'idle'
 vi.mock('../hooks/useAiAgent', () => ({
   useAiAgent: () => ({
-    messages: [],
-    status: 'idle',
+    messages: mockMessages,
+    status: mockStatus,
     sendMessage: vi.fn(),
     clearConversation: vi.fn(),
   }),
@@ -45,6 +47,11 @@ const makeEntry = (overrides: Partial<VaultEntry> = {}): VaultEntry => ({
 })
 
 describe('AiPanel', () => {
+  beforeEach(() => {
+    mockMessages = []
+    mockStatus = 'idle'
+  })
+
   it('renders panel with AI Chat header', () => {
     render(<AiPanel onClose={vi.fn()} vaultPath="/tmp/vault" />)
     expect(screen.getByText('AI Chat')).toBeTruthy()
@@ -162,4 +169,41 @@ describe('AiPanel', () => {
     fireEvent.keyDown(panel, { key: 'Escape' })
     expect(onClose).toHaveBeenCalledOnce()
   })
+
+  it('clicking a wikilink in AI response calls onOpenNote with the target', () => {
+    mockMessages = [{
+      userMessage: 'Tell me about notes',
+      actions: [],
+      response: 'Check out [[Build Laputa App]] for details.',
+      id: 'msg-1',
+    }]
+    const onOpenNote = vi.fn()
+    const { container } = render(
+      <AiPanel onClose={vi.fn()} vaultPath="/tmp/vault" onOpenNote={onOpenNote} />,
+    )
+    const wikilink = container.querySelector('.chat-wikilink')
+    expect(wikilink).toBeTruthy()
+    expect(wikilink!.textContent).toBe('Build Laputa App')
+    fireEvent.click(wikilink!)
+    expect(onOpenNote).toHaveBeenCalledWith('Build Laputa App')
+  })
+
+  it('renders wikilinks with special characters and clicking works', () => {
+    mockMessages = [{
+      userMessage: 'Tell me about meetings',
+      actions: [],
+      response: 'See [[Meeting — 2024/01/15]] and [[Pasta Carbonara]].',
+      id: 'msg-2',
+    }]
+    const onOpenNote = vi.fn()
+    const { container } = render(
+      <AiPanel onClose={vi.fn()} vaultPath="/tmp/vault" onOpenNote={onOpenNote} />,
+    )
+    const wikilinks = container.querySelectorAll('.chat-wikilink')
+    expect(wikilinks).toHaveLength(2)
+    fireEvent.click(wikilinks[0])
+    expect(onOpenNote).toHaveBeenCalledWith('Meeting — 2024/01/15')
+    fireEvent.click(wikilinks[1])
+    expect(onOpenNote).toHaveBeenCalledWith('Pasta Carbonara')
+  })
 })

src/components/AiPanel.tsx

@@ -1,8 +1,9 @@
 import { useState, useRef, useEffect, useCallback, useMemo } from 'react'
 import { Robot, X, PaperPlaneRight, Plus, Link } from '@phosphor-icons/react'
 import { AiMessage } from './AiMessage'
-import { useAiAgent, type AiAgentMessage } from '../hooks/useAiAgent'
-import { collectLinkedEntries, buildContextualPrompt } from '../utils/ai-context'
+import { WikilinkChatInput } from './WikilinkChatInput'
+import { useAiAgent, type AiAgentMessage, type AgentFileCallbacks } from '../hooks/useAiAgent'
+import { collectLinkedEntries, buildContextSnapshot, type NoteReference, type NoteListItem } from '../utils/ai-context'
 import type { VaultEntry } from '../types'
 
 export type { AiAgentMessage } from '../hooks/useAiAgent'
@@ -10,10 +11,18 @@ export type { AiAgentMessage } from '../hooks/useAiAgent'
 interface AiPanelProps {
   onClose: () => void
   onOpenNote?: (path: string) => void
+  onFileCreated?: (relativePath: string) => void
+  onFileModified?: (relativePath: string) => void
+  onVaultChanged?: () => void
   vaultPath: string
   activeEntry?: VaultEntry | null
+  /** Direct content of the active note from the editor tab. */
+  activeNoteContent?: string | null
   entries?: VaultEntry[]
   allContent?: Record<string, string>
+  openTabs?: VaultEntry[]
+  noteList?: NoteListItem[]
+  noteListFilter?: { type: string | null; query: string }
 }
 
 function PanelHeader({ onClose, onClear }: { onClose: () => void; onClear: () => void }) {
@@ -83,8 +92,8 @@ function EmptyState({ hasContext }: { hasContext: boolean }) {
   )
 }
 
-function MessageHistory({ messages, isActive, onOpenNote, hasContext }: {
-  messages: AiAgentMessage[]; isActive: boolean; onOpenNote?: (path: string) => void; hasContext: boolean
+function MessageHistory({ messages, isActive, onOpenNote, onNavigateWikilink, hasContext }: {
+  messages: AiAgentMessage[]; isActive: boolean; onOpenNote?: (path: string) => void; onNavigateWikilink?: (target: string) => void; hasContext: boolean
 }) {
   const endRef = useRef<HTMLDivElement>(null)
 
@@ -96,61 +105,16 @@ function MessageHistory({ messages, isActive, onOpenNote, hasContext }: {
     <div className="flex-1 overflow-y-auto" style={{ padding: 12 }}>
       {messages.length === 0 && !isActive && <EmptyState hasContext={hasContext} />}
       {messages.map((msg, i) => (
-        <AiMessage key={msg.id ?? i} {...msg} onOpenNote={onOpenNote} />
+        <AiMessage key={msg.id ?? i} {...msg} onOpenNote={onOpenNote} onNavigateWikilink={onNavigateWikilink} />
       ))}
       <div ref={endRef} />
     </div>
   )
 }
 
-function InputBar({ input, onInputChange, onSend, onKeyDown, isActive, hasContext, inputRef }: {
-  input: string; onInputChange: (v: string) => void
-  onSend: () => void; onKeyDown: (e: React.KeyboardEvent) => void
-  isActive: boolean; hasContext: boolean; inputRef: React.RefObject<HTMLInputElement | null>
-}) {
-  const sendDisabled = isActive || !input.trim()
-  return (
-    <div
-      className="flex shrink-0 flex-col border-t border-border"
-      style={{ padding: '8px 12px' }}
-    >
-      <div className="flex items-end gap-2">
-        <input
-          ref={inputRef}
-          value={input}
-          onChange={e => onInputChange(e.target.value)}
-          onKeyDown={onKeyDown}
-          className="flex-1 border border-border bg-transparent text-foreground"
-          style={{
-            fontSize: 13, borderRadius: 8, padding: '8px 10px',
-            outline: 'none', fontFamily: 'inherit',
-          }}
-          placeholder={hasContext ? 'Ask about this note...' : 'Ask the AI agent...'}
-          disabled={isActive}
-          data-testid="agent-input"
-        />
-        <button
-          className="shrink-0 flex items-center justify-center border-none cursor-pointer transition-colors"
-          style={{
-            background: sendDisabled ? 'var(--muted)' : 'var(--primary)',
-            color: sendDisabled ? 'var(--muted-foreground)' : 'white',
-            borderRadius: 8, width: 32, height: 34,
-            cursor: sendDisabled ? 'not-allowed' : 'pointer',
-          }}
-          onClick={onSend}
-          disabled={sendDisabled}
-          title="Send message"
-          data-testid="agent-send"
-        >
-          <PaperPlaneRight size={16} />
-        </button>
-      </div>
-    </div>
-  )
-}
-
-export function AiPanel({ onClose, onOpenNote, vaultPath, activeEntry, entries, allContent }: AiPanelProps) {
+export function AiPanel({ onClose, onOpenNote, onFileCreated, onFileModified, onVaultChanged, vaultPath, activeEntry, activeNoteContent, entries, allContent, openTabs, noteList, noteListFilter }: AiPanelProps) {
   const [input, setInput] = useState('')
+  const [pendingRefs, setPendingRefs] = useState<NoteReference[]>([])
   const inputRef = useRef<HTMLInputElement>(null)
   const panelRef = useRef<HTMLElement>(null)
 
@@ -160,11 +124,26 @@ export function AiPanel({ onClose, onOpenNote, vaultPath, activeEntry, entries,
   }, [activeEntry, entries])
 
   const contextPrompt = useMemo(() => {
-    if (!activeEntry || !allContent) return undefined
-    return buildContextualPrompt(activeEntry, linkedEntries, allContent)
-  }, [activeEntry, linkedEntries, allContent])
+    if (!activeEntry || !entries) return undefined
+    return buildContextSnapshot({
+      activeEntry,
+      allContent: allContent ?? {},
+      activeNoteContent: activeNoteContent ?? undefined,
+      openTabs,
+      noteList,
+      noteListFilter,
+      entries,
+      references: pendingRefs.length > 0 ? pendingRefs : undefined,
+    })
+  }, [activeEntry, activeNoteContent, allContent, openTabs, noteList, noteListFilter, entries, pendingRefs])
 
-  const agent = useAiAgent(vaultPath, contextPrompt)
+  const fileCallbacks = useMemo<AgentFileCallbacks>(() => ({
+    onFileCreated,
+    onFileModified,
+    onVaultChanged,
+  }), [onFileCreated, onFileModified, onVaultChanged])
+
+  const agent = useAiAgent(vaultPath, contextPrompt, fileCallbacks)
   const hasContext = !!activeEntry
   const isActive = agent.status === 'thinking' || agent.status === 'tool-executing'
 
@@ -193,26 +172,32 @@ export function AiPanel({ onClose, onOpenNote, vaultPath, activeEntry, entries,
     return () => window.removeEventListener('keydown', handleEscape)
   }, [handleEscape])
 
-  const handleSend = () => {
-    if (!input.trim() || isActive) return
-    agent.sendMessage(input)
-    setInput('')
-  }
+  const handleNavigateWikilink = useCallback((target: string) => {
+    onOpenNote?.(target)
+  }, [onOpenNote])
 
-  const handleKeyDown = (e: React.KeyboardEvent) => {
-    if (e.key === 'Enter' && !e.shiftKey) {
-      e.preventDefault()
-      handleSend()
-    }
-  }
+  const handleSend = useCallback((text: string, references: NoteReference[]) => {
+    if (!text.trim() || isActive) return
+    setPendingRefs(references)
+    agent.sendMessage(text, references)
+    setInput('')
+  }, [isActive, agent])
 
   return (
     <aside
       ref={panelRef}
       tabIndex={-1}
-      className="flex flex-1 flex-col overflow-hidden border-l border-border bg-background text-foreground"
-      style={{ outline: 'none' }}
+      className="flex flex-1 flex-col overflow-hidden bg-background text-foreground"
+      style={{
+        outline: 'none',
+        borderLeft: isActive
+          ? '2px solid var(--accent-blue, #3b82f6)'
+          : '1px solid var(--border)',
+        animation: isActive ? 'ai-border-pulse 2s ease-in-out infinite' : undefined,
+        transition: 'border-color 0.3s ease',
+      }}
       data-testid="ai-panel"
+      data-ai-active={isActive || undefined}
     >
       <PanelHeader onClose={onClose} onClear={agent.clearConversation} />
       {activeEntry && (
@@ -222,17 +207,42 @@ export function AiPanel({ onClose, onOpenNote, vaultPath, activeEntry, entries,
         messages={agent.messages}
         isActive={isActive}
         onOpenNote={onOpenNote}
+        onNavigateWikilink={handleNavigateWikilink}
         hasContext={hasContext}
       />
-      <InputBar
-        input={input}
-        onInputChange={setInput}
-        onSend={handleSend}
-        onKeyDown={handleKeyDown}
-        isActive={isActive}
-        hasContext={hasContext}
-        inputRef={inputRef}
-      />
+      <div
+        className="flex shrink-0 flex-col border-t border-border"
+        style={{ padding: '8px 12px' }}
+      >
+        <div className="flex items-end gap-2">
+          <div className="flex-1">
+            <WikilinkChatInput
+              entries={entries ?? []}
+              value={input}
+              onChange={setInput}
+              onSend={handleSend}
+              disabled={isActive}
+              placeholder={hasContext ? 'Ask about this note...' : 'Ask the AI agent...'}
+              inputRef={inputRef}
+            />
+          </div>
+          <button
+            className="shrink-0 flex items-center justify-center border-none cursor-pointer transition-colors"
+            style={{
+              background: (isActive || !input.trim()) ? 'var(--muted)' : 'var(--primary)',
+              color: (isActive || !input.trim()) ? 'var(--muted-foreground)' : 'white',
+              borderRadius: 8, width: 32, height: 34,
+              cursor: (isActive || !input.trim()) ? 'not-allowed' : 'pointer',
+            }}
+            onClick={() => handleSend(input, pendingRefs)}
+            disabled={isActive || !input.trim()}
+            title="Send message"
+            data-testid="agent-send"
+          >
+            <PaperPlaneRight size={16} />
+          </button>
+        </div>
+      </div>
     </aside>
   )
 }

src/components/ColorInput.test.tsx

@@ -0,0 +1,96 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { ColorSwatch, ColorEditableValue } from './ColorInput'
+
+describe('ColorSwatch', () => {
+  it('renders a swatch button with the given color', () => {
+    render(<ColorSwatch color="#3b82f6" />)
+    const swatch = screen.getByTestId('color-swatch')
+    expect(swatch).toBeTruthy()
+    // Browser normalizes hex to rgb() in computed style
+    expect(swatch.style.background).toBeTruthy()
+  })
+
+  it('contains a hidden color input', () => {
+    render(<ColorSwatch color="#ff0000" />)
+    const input = screen.getByTestId('color-picker-input') as HTMLInputElement
+    expect(input.type).toBe('color')
+    expect(input.value).toBe('#ff0000')
+  })
+
+  it('calls onChange when color is picked', () => {
+    const onChange = vi.fn()
+    render(<ColorSwatch color="#ff0000" onChange={onChange} />)
+    const input = screen.getByTestId('color-picker-input') as HTMLInputElement
+    fireEvent.change(input, { target: { value: '#00ff00' } })
+    expect(onChange).toHaveBeenCalledWith('#00ff00')
+  })
+
+  it('opens color input on Enter key', () => {
+    const clickSpy = vi.fn()
+    render(<ColorSwatch color="#ff0000" />)
+    const input = screen.getByTestId('color-picker-input') as HTMLInputElement
+    input.click = clickSpy
+    const swatch = screen.getByTestId('color-swatch')
+    fireEvent.keyDown(swatch, { key: 'Enter' })
+    expect(clickSpy).toHaveBeenCalled()
+  })
+
+  it('opens color input on Space key', () => {
+    const clickSpy = vi.fn()
+    render(<ColorSwatch color="#ff0000" />)
+    const input = screen.getByTestId('color-picker-input') as HTMLInputElement
+    input.click = clickSpy
+    const swatch = screen.getByTestId('color-swatch')
+    fireEvent.keyDown(swatch, { key: ' ' })
+    expect(clickSpy).toHaveBeenCalled()
+  })
+})
+
+describe('ColorEditableValue', () => {
+  it('shows swatch when value is a valid hex color', () => {
+    render(<ColorEditableValue value="#3b82f6" isEditing={false} onStartEdit={vi.fn()} onSave={vi.fn()} onCancel={vi.fn()} />)
+    expect(screen.getByTestId('color-swatch')).toBeTruthy()
+  })
+
+  it('does not show swatch when value is not a color', () => {
+    render(<ColorEditableValue value="hello world" isEditing={false} onStartEdit={vi.fn()} onSave={vi.fn()} onCancel={vi.fn()} />)
+    expect(screen.queryByTestId('color-swatch')).toBeNull()
+  })
+
+  it('does not show swatch for empty string', () => {
+    render(<ColorEditableValue value="" isEditing={false} onStartEdit={vi.fn()} onSave={vi.fn()} onCancel={vi.fn()} />)
+    expect(screen.queryByTestId('color-swatch')).toBeNull()
+  })
+
+  it('shows swatch in edit mode for valid color', () => {
+    render(<ColorEditableValue value="#ff0000" isEditing={true} onStartEdit={vi.fn()} onSave={vi.fn()} onCancel={vi.fn()} />)
+    expect(screen.getByTestId('color-swatch')).toBeTruthy()
+    expect(screen.getByTestId('color-text-input')).toBeTruthy()
+  })
+
+  it('updates value when color is picked', () => {
+    const onSave = vi.fn()
+    render(<ColorEditableValue value="#ff0000" isEditing={false} onStartEdit={vi.fn()} onSave={onSave} onCancel={vi.fn()} />)
+    const input = screen.getByTestId('color-picker-input') as HTMLInputElement
+    fireEvent.change(input, { target: { value: '#00ff00' } })
+    expect(onSave).toHaveBeenCalledWith('#00ff00')
+  })
+
+  it('text field works independently in edit mode', () => {
+    const onSave = vi.fn()
+    render(<ColorEditableValue value="#ff0000" isEditing={true} onStartEdit={vi.fn()} onSave={onSave} onCancel={vi.fn()} />)
+    const textInput = screen.getByTestId('color-text-input') as HTMLInputElement
+    fireEvent.change(textInput, { target: { value: '#0000ff' } })
+    fireEvent.keyDown(textInput, { key: 'Enter' })
+    expect(onSave).toHaveBeenCalledWith('#0000ff')
+  })
+
+  it('Escape cancels edit', () => {
+    const onCancel = vi.fn()
+    render(<ColorEditableValue value="#ff0000" isEditing={true} onStartEdit={vi.fn()} onSave={vi.fn()} onCancel={onCancel} />)
+    const textInput = screen.getByTestId('color-text-input') as HTMLInputElement
+    fireEvent.keyDown(textInput, { key: 'Escape' })
+    expect(onCancel).toHaveBeenCalled()
+  })
+})

src/components/ColorInput.tsx

@@ -0,0 +1,113 @@
+import { useState, useRef, useCallback } from 'react'
+import { isValidCssColor, toHexColor } from '../utils/colorUtils'
+
+/**
+ * Inline color swatch button that opens a native color picker.
+ * Shows nothing if the value is not a valid CSS color.
+ */
+export function ColorSwatch({ color, onChange }: {
+  color: string
+  onChange?: (hex: string) => void
+}) {
+  const hex = toHexColor(color) ?? '#000000'
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  const handleClick = useCallback(() => {
+    inputRef.current?.click()
+  }, [])
+
+  const handleChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    onChange?.(e.target.value)
+  }, [onChange])
+
+  const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      inputRef.current?.click()
+    }
+  }, [])
+
+  return (
+    <span className="inline-flex shrink-0 items-center">
+      <button
+        type="button"
+        className="relative size-4 shrink-0 cursor-pointer rounded-[3px] border border-border p-0 transition-shadow hover:ring-1 hover:ring-primary focus:outline-none focus:ring-2 focus:ring-primary"
+        style={{ background: color }}
+        onClick={handleClick}
+        onKeyDown={handleKeyDown}
+        title="Open color picker"
+        aria-label={`Color: ${color}. Click to open color picker`}
+        data-testid="color-swatch"
+      >
+        <input
+          ref={inputRef}
+          type="color"
+          value={hex}
+          onChange={handleChange}
+          className="pointer-events-none absolute inset-0 opacity-0"
+          tabIndex={-1}
+          aria-hidden="true"
+          data-testid="color-picker-input"
+        />
+      </button>
+    </span>
+  )
+}
+
+/**
+ * Editable text field with an inline color swatch.
+ * The swatch only appears when the value is a valid CSS color.
+ */
+export function ColorEditableValue({ value, isEditing, onStartEdit, onSave, onCancel }: {
+  value: string
+  isEditing: boolean
+  onStartEdit: () => void
+  onSave: (newValue: string) => void
+  onCancel: () => void
+}) {
+  const [editValue, setEditValue] = useState(value)
+  const showSwatch = isValidCssColor(isEditing ? editValue : value)
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Enter') onSave(editValue)
+    else if (e.key === 'Escape') { setEditValue(value); onCancel() }
+  }
+
+  const handlePickerChange = useCallback((hex: string) => {
+    if (isEditing) {
+      setEditValue(hex)
+    }
+    onSave(hex)
+  }, [isEditing, onSave])
+
+  if (isEditing) {
+    return (
+      <span className="flex w-full items-center gap-1.5">
+        {showSwatch && <ColorSwatch color={editValue} onChange={handlePickerChange} />}
+        <input
+          className="w-full rounded border border-ring bg-muted px-2 py-1 text-[12px] text-foreground outline-none focus:border-primary"
+          type="text"
+          value={editValue}
+          onChange={(e) => setEditValue(e.target.value)}
+          onKeyDown={handleKeyDown}
+          onBlur={() => onSave(editValue)}
+          autoFocus
+          data-testid="color-text-input"
+        />
+      </span>
+    )
+  }
+
+  return (
+    <span className="inline-flex min-w-0 items-center gap-1.5">
+      {showSwatch && <ColorSwatch color={value} onChange={handlePickerChange} />}
+      <span
+        className="min-w-0 cursor-pointer truncate rounded px-1 py-0.5 text-right text-[12px] text-secondary-foreground transition-colors hover:bg-muted"
+        onClick={onStartEdit}
+        title={value || 'Click to edit'}
+      >
+        {value || '\u2014'}
+      </span>
+    </span>
+  )
+}

src/components/CommandPalette.test.tsx

@@ -165,4 +165,64 @@ describe('CommandPalette', () => {
     expect(screen.getByText('↵ select')).toBeInTheDocument()
     expect(screen.getByText('esc close')).toBeInTheDocument()
   })
+
+  describe('relevance ranking', () => {
+    const relevanceCommands: CommandAction[] = [
+      makeCommand({ id: 'create-note', label: 'Create New Note', group: 'Note' }),
+      makeCommand({ id: 'toggle-raw', label: 'Toggle Raw Editor', group: 'View' }),
+      makeCommand({ id: 'switch-theme', label: 'Switch Theme', group: 'Appearance', keywords: ['dark', 'light'] }),
+      makeCommand({ id: 'search-notes', label: 'Search Notes', group: 'Navigation' }),
+    ]
+
+    function getVisibleLabels() {
+      return screen.getAllByText(
+        (_content, el) =>
+          el?.tagName === 'SPAN' &&
+          el.classList.contains('text-foreground') &&
+          !!el.textContent,
+      ).map(el => el.textContent)
+    }
+
+    it('ranks "Toggle Raw Editor" before "Create New Note" for query "raw"', () => {
+      render(<CommandPalette open={true} commands={relevanceCommands} onClose={onClose} />)
+      fireEvent.change(screen.getByPlaceholderText('Type a command...'), { target: { value: 'raw' } })
+
+      const labels = getVisibleLabels()
+      const rawIdx = labels.indexOf('Toggle Raw Editor')
+      const createIdx = labels.indexOf('Create New Note')
+      expect(rawIdx).toBeGreaterThanOrEqual(0)
+      expect(createIdx).toBeGreaterThanOrEqual(0)
+      expect(rawIdx).toBeLessThan(createIdx)
+    })
+
+    it('ranks "Create New Note" first for query "new note"', () => {
+      render(<CommandPalette open={true} commands={relevanceCommands} onClose={onClose} />)
+      fireEvent.change(screen.getByPlaceholderText('Type a command...'), { target: { value: 'new note' } })
+
+      const labels = getVisibleLabels()
+      expect(labels[0]).toBe('Create New Note')
+    })
+
+    it('ranks theme commands first for query "theme"', () => {
+      render(<CommandPalette open={true} commands={relevanceCommands} onClose={onClose} />)
+      fireEvent.change(screen.getByPlaceholderText('Type a command...'), { target: { value: 'theme' } })
+
+      const labels = getVisibleLabels()
+      expect(labels[0]).toBe('Switch Theme')
+    })
+
+    it('preserves default section order with empty query', () => {
+      render(<CommandPalette open={true} commands={relevanceCommands} onClose={onClose} />)
+
+      const groupHeaders = screen.getAllByText(
+        (_content, el) =>
+          el?.tagName === 'DIV' &&
+          el.classList.contains('uppercase') &&
+          !!el.textContent,
+      ).map(el => el.textContent)
+
+      // Default order: Navigation < Note < View < Appearance
+      expect(groupHeaders).toEqual(['Navigation', 'Note', 'View', 'Appearance'])
+    })
+  })
 })

src/components/CommandPalette.tsx

@@ -30,16 +30,21 @@ function matchCommand(query: string, cmd: CommandAction): ScoredCommand | null {
   return null
 }
 
-function groupResults(commands: CommandAction[]): { group: CommandGroup; items: CommandAction[] }[] {
+function groupResults(
+  commands: CommandAction[],
+  byRelevance: boolean,
+): { group: CommandGroup; items: CommandAction[] }[] {
   const map = new Map<CommandGroup, CommandAction[]>()
   for (const cmd of commands) {
     const list = map.get(cmd.group)
     if (list) list.push(cmd)
     else map.set(cmd.group, [cmd])
   }
-  return Array.from(map.entries())
-    .sort((a, b) => groupSortKey(a[0]) - groupSortKey(b[0]))
-    .map(([group, items]) => ({ group, items }))
+  const entries = Array.from(map.entries())
+  if (!byRelevance) {
+    entries.sort((a, b) => groupSortKey(a[0]) - groupSortKey(b[0]))
+  }
+  return entries.map(([group, items]) => ({ group, items }))
 }
 
 export function CommandPalette({ open, commands, onClose }: CommandPaletteProps) {
@@ -70,7 +75,8 @@ export function CommandPalette({ open, commands, onClose }: CommandPaletteProps)
       .map(r => r.command)
   }, [enabledCommands, query])
 
-  const groups = useMemo(() => groupResults(filtered), [filtered])
+  const hasQuery = !!query.trim()
+  const groups = useMemo(() => groupResults(filtered, hasQuery), [filtered, hasQuery])
   const flatList = useMemo(() => groups.flatMap(g => g.items), [groups])
 
   useEffect(() => {

src/components/ConflictResolverModal.test.tsx

@@ -0,0 +1,130 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { ConflictResolverModal } from './ConflictResolverModal'
+import type { ConflictFileState } from '../hooks/useConflictResolver'
+
+function makeFileStates(overrides?: Partial<ConflictFileState>[]): ConflictFileState[] {
+  const defaults: ConflictFileState[] = [
+    { file: 'notes/project.md', resolution: null, resolving: false },
+    { file: 'notes/plan.md', resolution: null, resolving: false },
+  ]
+  if (!overrides) return defaults
+  return defaults.map((d, i) => ({ ...d, ...(overrides[i] ?? {}) }))
+}
+
+function renderModal(overrides: Record<string, unknown> = {}) {
+  const props = {
+    open: true,
+    fileStates: makeFileStates(),
+    allResolved: false,
+    committing: false,
+    error: null,
+    onResolveFile: vi.fn(),
+    onOpenInEditor: vi.fn(),
+    onCommit: vi.fn(),
+    onClose: vi.fn(),
+    ...overrides,
+  }
+  return { ...render(<ConflictResolverModal {...props} />), props }
+}
+
+describe('ConflictResolverModal', () => {
+  it('renders conflict file list when open', () => {
+    renderModal()
+    expect(screen.getByText('Resolve Merge Conflicts')).toBeInTheDocument()
+    expect(screen.getByTestId('conflict-file-list')).toBeInTheDocument()
+    expect(screen.getByTestId('conflict-file-notes/project.md')).toBeInTheDocument()
+    expect(screen.getByTestId('conflict-file-notes/plan.md')).toBeInTheDocument()
+  })
+
+  it('shows file count description', () => {
+    renderModal()
+    expect(screen.getByText(/2 files have merge conflicts/)).toBeInTheDocument()
+  })
+
+  it('shows singular description for one file', () => {
+    renderModal({ fileStates: [{ file: 'note.md', resolution: null, resolving: false }] })
+    expect(screen.getByText(/1 file has merge conflicts/)).toBeInTheDocument()
+  })
+
+  it('calls onResolveFile when Keep mine is clicked', () => {
+    const { props } = renderModal()
+    fireEvent.click(screen.getByTestId('resolve-ours-notes/project.md'))
+    expect(props.onResolveFile).toHaveBeenCalledWith('notes/project.md', 'ours')
+  })
+
+  it('calls onResolveFile when Keep theirs is clicked', () => {
+    const { props } = renderModal()
+    fireEvent.click(screen.getByTestId('resolve-theirs-notes/plan.md'))
+    expect(props.onResolveFile).toHaveBeenCalledWith('notes/plan.md', 'theirs')
+  })
+
+  it('calls onOpenInEditor when Open in editor is clicked', () => {
+    const { props } = renderModal()
+    fireEvent.click(screen.getByTestId('resolve-open-notes/project.md'))
+    expect(props.onOpenInEditor).toHaveBeenCalledWith('notes/project.md')
+  })
+
+  it('hides Open in editor for binary files', () => {
+    renderModal({
+      fileStates: [{ file: 'images/photo.png', resolution: null, resolving: false }],
+    })
+    expect(screen.queryByTestId('resolve-open-images/photo.png')).not.toBeInTheDocument()
+    // Keep mine/theirs should still be visible
+    expect(screen.getByTestId('resolve-ours-images/photo.png')).toBeInTheDocument()
+  })
+
+  it('Commit & continue button is disabled when not all resolved', () => {
+    renderModal({ allResolved: false })
+    expect(screen.getByTestId('conflict-commit-btn')).toBeDisabled()
+  })
+
+  it('Commit & continue button is enabled when all resolved', () => {
+    renderModal({ allResolved: true })
+    expect(screen.getByTestId('conflict-commit-btn')).toBeEnabled()
+  })
+
+  it('calls onCommit when Commit & continue is clicked', () => {
+    const { props } = renderModal({ allResolved: true })
+    fireEvent.click(screen.getByTestId('conflict-commit-btn'))
+    expect(props.onCommit).toHaveBeenCalled()
+  })
+
+  it('shows committing state', () => {
+    renderModal({ allResolved: true, committing: true })
+    expect(screen.getByText('Committing…')).toBeInTheDocument()
+    expect(screen.getByTestId('conflict-commit-btn')).toBeDisabled()
+  })
+
+  it('shows error message', () => {
+    renderModal({ error: 'git commit failed: user.email not set' })
+    expect(screen.getByTestId('conflict-error')).toHaveTextContent('git commit failed')
+  })
+
+  it('shows resolution labels after file is resolved', () => {
+    renderModal({
+      fileStates: makeFileStates([{ resolution: 'ours' }, { resolution: 'theirs' }]),
+    })
+    expect(screen.getByText('Keeping mine')).toBeInTheDocument()
+    expect(screen.getByText('Keeping theirs')).toBeInTheDocument()
+  })
+
+  it('shows spinner when file is resolving', () => {
+    renderModal({
+      fileStates: [{ file: 'note.md', resolution: null, resolving: true }],
+    })
+    // Buttons hidden during resolving, spinner shown instead
+    expect(screen.queryByTestId('resolve-ours-note.md')).not.toBeInTheDocument()
+  })
+
+  it('calls onClose when Cancel is clicked', () => {
+    const { props } = renderModal()
+    fireEvent.click(screen.getByText('Cancel'))
+    expect(props.onClose).toHaveBeenCalled()
+  })
+
+  it('shows keyboard shortcut hint', () => {
+    renderModal()
+    expect(screen.getByText(/K = keep mine/)).toBeInTheDocument()
+  })
+})

src/components/DynamicPropertiesPanel.test.tsx

@@ -2,20 +2,8 @@ import { describe, it, expect, vi, beforeEach, beforeAll } from 'vitest'
 import { render, screen, fireEvent } from '@testing-library/react'
 import { DynamicPropertiesPanel, containsWikilinks } from './DynamicPropertiesPanel'
 import type { VaultEntry } from '../types'
-
-// Mock localStorage (jsdom's may be incomplete)
-const localStorageMock = (() => {
-  let store: Record<string, string> = {}
-  return {
-    getItem: (key: string) => store[key] ?? null,
-    setItem: vi.fn((key: string, value: string) => { store[key] = value }),
-    removeItem: (key: string) => { delete store[key] },
-    clear: () => { store = {} },
-    get length() { return Object.keys(store).length },
-    key: (i: number) => Object.keys(store)[i] ?? null,
-  }
-})()
-Object.defineProperty(globalThis, 'localStorage', { value: localStorageMock, writable: true })
+import { bindVaultConfigStore, getVaultConfig, resetVaultConfigStore } from '../utils/vaultConfigStore'
+import { initDisplayModeOverrides } from '../utils/propertyTypes'
 
 // Radix Select needs ResizeObserver and pointer/scroll APIs in JSDOM
 beforeAll(() => {
@@ -847,7 +835,12 @@ describe('DynamicPropertiesPanel', () => {
 
   describe('display mode override', () => {
     beforeEach(() => {
-      localStorageMock.clear()
+      resetVaultConfigStore()
+      bindVaultConfigStore(
+        { zoom: null, view_mode: null, tag_colors: null, status_colors: null, property_display_modes: null },
+        vi.fn(),
+      )
+      initDisplayModeOverrides({})
     })
 
     it('renders display mode trigger on property rows', () => {
@@ -880,7 +873,7 @@ describe('DynamicPropertiesPanel', () => {
       expect(screen.getByTestId('display-mode-option-url')).toBeInTheDocument()
     })
 
-    it('persists override to localStorage when mode selected', () => {
+    it('persists override to vault config when mode selected', () => {
       render(
         <DynamicPropertiesPanel
           entry={makeEntry()}
@@ -891,12 +884,13 @@ describe('DynamicPropertiesPanel', () => {
       )
       fireEvent.click(screen.getByTestId('display-mode-trigger'))
       fireEvent.click(screen.getByTestId('display-mode-option-status'))
-      const stored = JSON.parse(localStorageMock.getItem('laputa:display-mode-overrides') ?? '{}')
+      const stored = getVaultConfig().property_display_modes as Record<string, string>
+      expect(stored).toBeTruthy()
       expect(stored.cadence).toBe('status')
     })
 
     it('overrides rendering to status badge when status mode selected', () => {
-      localStorageMock.setItem('laputa:display-mode-overrides', JSON.stringify({ cadence: 'status' }))
+      initDisplayModeOverrides({ cadence: 'status' })
       render(
         <DynamicPropertiesPanel
           entry={makeEntry()}
@@ -909,7 +903,7 @@ describe('DynamicPropertiesPanel', () => {
     })
 
     it('renders boolean toggle for string "true" when boolean mode overridden', () => {
-      localStorageMock.setItem('laputa:display-mode-overrides', JSON.stringify({ draft: 'boolean' }))
+      initDisplayModeOverrides({ draft: 'boolean' })
       render(
         <DynamicPropertiesPanel
           entry={makeEntry()}
@@ -923,7 +917,7 @@ describe('DynamicPropertiesPanel', () => {
     })
 
     it('renders boolean toggle for string "false" when boolean mode overridden', () => {
-      localStorageMock.setItem('laputa:display-mode-overrides', JSON.stringify({ draft: 'boolean' }))
+      initDisplayModeOverrides({ draft: 'boolean' })
       render(
         <DynamicPropertiesPanel
           entry={makeEntry()}
@@ -937,7 +931,7 @@ describe('DynamicPropertiesPanel', () => {
     })
 
     it('toggles string boolean from false to true', () => {
-      localStorageMock.setItem('laputa:display-mode-overrides', JSON.stringify({ draft: 'boolean' }))
+      initDisplayModeOverrides({ draft: 'boolean' })
       render(
         <DynamicPropertiesPanel
           entry={makeEntry()}
@@ -951,7 +945,7 @@ describe('DynamicPropertiesPanel', () => {
     })
 
     it('renders date picker for empty value when date mode overridden', () => {
-      localStorageMock.setItem('laputa:display-mode-overrides', JSON.stringify({ due: 'date' }))
+      initDisplayModeOverrides({ due: 'date' })
       render(
         <DynamicPropertiesPanel
           entry={makeEntry()}
@@ -965,7 +959,7 @@ describe('DynamicPropertiesPanel', () => {
     })
 
     it('renders date picker for non-date string when date mode overridden', () => {
-      localStorageMock.setItem('laputa:display-mode-overrides', JSON.stringify({ deadline: 'date' }))
+      initDisplayModeOverrides({ deadline: 'date' })
       render(
         <DynamicPropertiesPanel
           entry={makeEntry()}

src/components/DynamicPropertiesPanel.tsx

@@ -1,17 +1,18 @@
-import { useMemo, useState, useCallback, useRef } from 'react'
+import { useState, useCallback, useRef } from 'react'
 import { createPortal } from 'react-dom'
 import type { VaultEntry } from '../types'
 import type { FrontmatterValue } from './Inspector'
 import type { ParsedFrontmatter } from '../utils/frontmatter'
-import { parseFrontmatter } from '../utils/frontmatter'
 import { EditableValue, TagPillList, UrlValue } from './EditableValue'
 import { isUrlValue } from '../utils/url'
+import { usePropertyPanelState } from '../hooks/usePropertyPanelState'
 import { Button } from '@/components/ui/button'
 import { Calendar } from '@/components/ui/calendar'
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
 import { Select, SelectContent, SelectItem, SelectSeparator, SelectTrigger, SelectValue } from '@/components/ui/select'
-import { CalendarIcon, XIcon, Check, X, Type, ToggleLeft, Circle, Link, Tag } from 'lucide-react'
+import { CalendarIcon, XIcon, Check, X, Type, ToggleLeft, Circle, Link, Tag, Palette } from 'lucide-react'
 import { getTypeColor, getTypeLightColor } from '../utils/typeColors'
+import { isValidCssColor } from '../utils/colorUtils'
 import { getTypeIcon } from './NoteItem'
 import { countWords } from '../utils/wikilinks'
 import {
@@ -19,14 +20,12 @@ import {
   getEffectiveDisplayMode,
   formatDateValue,
   toISODate,
-  loadDisplayModeOverrides,
-  saveDisplayModeOverride,
-  removeDisplayModeOverride,
   detectPropertyType,
 } from '../utils/propertyTypes'
 import { StatusPill, StatusDropdown } from './StatusDropdown'
 import { TagsDropdown } from './TagsDropdown'
 import { getTagStyle } from '../utils/tagStyles'
+import { ColorEditableValue } from './ColorInput'
 
 // Keys that are relationships (contain wikilinks)
 export const RELATIONSHIP_KEYS = new Set([
@@ -34,9 +33,6 @@ export const RELATIONSHIP_KEYS = new Set([
   'Advances', 'Parent', 'Children', 'Has', 'Notes',
 ])
 
-// Keys to skip showing in Properties (handled by dedicated UI or internal)
-const SKIP_KEYS = new Set(['aliases', 'notion_id', 'workspace', 'title', 'type', 'is_a', 'Is A'])
-
 // eslint-disable-next-line react-refresh/only-export-components -- utility co-located with component
 export function containsWikilinks(value: FrontmatterValue): boolean {
   if (typeof value === 'string') return /^\[\[.*\]\]$/.test(value)
@@ -51,19 +47,6 @@ function formatDate(timestamp: number | null): string {
   return d.toLocaleDateString('en-US', { year: 'numeric', month: 'short', day: 'numeric' })
 }
 
-function coerceValue(raw: string): FrontmatterValue {
-  if (raw.toLowerCase() === 'true') return true
-  if (raw.toLowerCase() === 'false') return false
-  if (!isNaN(Number(raw)) && raw.trim() !== '') return Number(raw)
-  return raw
-}
-
-function parseNewValue(rawValue: string): FrontmatterValue {
-  if (!rawValue.includes(',')) return rawValue.trim() || ''
-  const items = rawValue.split(',').map(s => s.trim()).filter(s => s)
-  return items.length === 1 ? items[0] : items
-}
-
 function formatFileSize(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`
   const kb = bytes / 1024
@@ -253,6 +236,7 @@ const DISPLAY_MODE_OPTIONS: { value: PropertyDisplayMode; label: string }[] = [
   { value: 'status', label: 'Status' },
   { value: 'url', label: 'URL' },
   { value: 'tags', label: 'Tags' },
+  { value: 'color', label: 'Color' },
 ]
 
 function DisplayModeSelector({ propKey, currentMode, autoMode, onSelect }: {
@@ -331,7 +315,7 @@ function DisplayModeSelector({ propKey, currentMode, autoMode, onSelect }: {
 }
 
 const DISPLAY_MODE_ICONS: Record<PropertyDisplayMode, typeof Type> = {
-  text: Type, date: CalendarIcon, boolean: ToggleLeft, status: Circle, url: Link, tags: Tag,
+  text: Type, date: CalendarIcon, boolean: ToggleLeft, status: Circle, url: Link, tags: Tag, color: Palette,
 }
 
 const ADD_INPUT_CLASS = "h-[26px] min-w-[60px] flex-1 rounded border border-border bg-muted px-1.5 text-[12px] text-foreground outline-none focus:border-primary"
@@ -565,6 +549,7 @@ function toBooleanValue(value: FrontmatterValue): boolean {
 function autoDetectFromValue(value: FrontmatterValue): PropertyDisplayMode {
   if (typeof value === 'boolean') return 'boolean'
   if (typeof value === 'string' && isUrlValue(value)) return 'url'
+  if (typeof value === 'string' && isValidCssColor(value) && value.startsWith('#')) return 'color'
   return 'text'
 }
 
@@ -591,6 +576,8 @@ function ScalarValueCell({ propKey, value, displayMode, isEditing, vaultStatuses
     }
     case 'url':
       return <UrlValue {...editProps} />
+    case 'color':
+      return <ColorEditableValue {...editProps} />
     default:
       return <EditableValue {...editProps} />
   }
@@ -670,134 +657,6 @@ function NoteInfoSection({ entry, wordCount }: { entry: VaultEntry; wordCount: n
   )
 }
 
-function reconcileListUpdate(
-  newItems: string[],
-  onUpdate: (key: string, value: FrontmatterValue) => void,
-  onDelete: ((key: string) => void) | undefined,
-  key: string,
-) {
-  if (newItems.length === 0) onDelete?.(key)
-  else if (newItems.length === 1) onUpdate(key, newItems[0])
-  else onUpdate(key, newItems)
-}
-
-function deriveTypeInfo(entries: VaultEntry[] | undefined, entryIsA: string | null) {
-  const typeEntries = (entries ?? []).filter(e => e.isA === 'Type')
-  const typeColorKeys: Record<string, string | null> = {}
-  const typeIconKeys: Record<string, string | null> = {}
-  for (const e of typeEntries) {
-    typeColorKeys[e.title] = e.color ?? null
-    typeIconKeys[e.title] = e.icon ?? null
-  }
-  return {
-    availableTypes: typeEntries.map(e => e.title).sort((a, b) => a.localeCompare(b)),
-    customColorKey: entryIsA ? (typeColorKeys[entryIsA] ?? null) : null,
-    typeColorKeys,
-    typeIconKeys,
-  }
-}
-
-function collectVaultStatuses(entries: VaultEntry[] | undefined): string[] {
-  const seen = new Set<string>()
-  for (const e of entries ?? []) {
-    if (e.status) seen.add(e.status)
-  }
-  return Array.from(seen).sort((a, b) => a.localeCompare(b))
-}
-
-function mergeArrayFieldsInto(fm: ParsedFrontmatter, tagsByKey: Map<string, Set<string>>): void {
-  for (const [key, value] of Object.entries(fm)) {
-    if (!Array.isArray(value)) continue
-    let set = tagsByKey.get(key)
-    if (!set) { set = new Set(); tagsByKey.set(key, set) }
-    for (const tag of value) set.add(String(tag))
-  }
-}
-
-function collectAllVaultTags(entries: VaultEntry[] | undefined, allContent: Record<string, string> | undefined): Record<string, string[]> {
-  if (!entries || !allContent) return {}
-  const tagsByKey = new Map<string, Set<string>>()
-  for (const entry of entries) {
-    const content = allContent[entry.path]
-    if (!content) continue
-    mergeArrayFieldsInto(parseFrontmatter(content), tagsByKey)
-  }
-  const result: Record<string, string[]> = {}
-  for (const [key, set] of tagsByKey) result[key] = Array.from(set).sort((a, b) => a.localeCompare(b))
-  return result
-}
-
-function isVisibleProperty([key, value]: [string, FrontmatterValue]): boolean {
-  return !SKIP_KEYS.has(key) && !RELATIONSHIP_KEYS.has(key) && !containsWikilinks(value)
-}
-
-function parseAddedValue(rawValue: string, mode: PropertyDisplayMode): FrontmatterValue {
-  if (mode === 'boolean') return rawValue.toLowerCase() === 'true'
-  if (mode === 'tags') {
-    const items = rawValue.split(',').map(s => s.trim()).filter(s => s)
-    return items
-  }
-  return parseNewValue(rawValue)
-}
-
-function persistModeOverride(key: string, mode: PropertyDisplayMode | null) {
-  if (mode === null) removeDisplayModeOverride(key)
-  else saveDisplayModeOverride(key, mode)
-}
-
-interface PropertyPanelDeps {
-  entries: VaultEntry[] | undefined
-  entryIsA: string | null
-  frontmatter: ParsedFrontmatter
-  allContent: Record<string, string> | undefined
-  onUpdateProperty?: (key: string, value: FrontmatterValue) => void
-  onDeleteProperty?: (key: string) => void
-  onAddProperty?: (key: string, value: FrontmatterValue) => void
-}
-
-function usePropertyPanelState(deps: PropertyPanelDeps) {
-  const { entries, entryIsA, frontmatter, allContent, onUpdateProperty, onDeleteProperty, onAddProperty } = deps
-  const [editingKey, setEditingKey] = useState<string | null>(null)
-  const [showAddDialog, setShowAddDialog] = useState(false)
-  const [displayOverrides, setDisplayOverrides] = useState(() => loadDisplayModeOverrides())
-
-  const { availableTypes, customColorKey, typeColorKeys, typeIconKeys } = useMemo(() => deriveTypeInfo(entries, entryIsA), [entries, entryIsA])
-  const vaultStatuses = useMemo(() => collectVaultStatuses(entries), [entries])
-  const vaultTagsByKey = useMemo(() => collectAllVaultTags(entries, allContent), [entries, allContent])
-  const propertyEntries = useMemo(() => Object.entries(frontmatter).filter(isVisibleProperty), [frontmatter])
-
-  const handleSaveValue = useCallback((key: string, newValue: string) => {
-    setEditingKey(null)
-    if (onUpdateProperty) onUpdateProperty(key, coerceValue(newValue))
-  }, [onUpdateProperty])
-
-  const handleSaveList = useCallback((key: string, newItems: string[]) => {
-    if (!onUpdateProperty) return
-    reconcileListUpdate(newItems, onUpdateProperty, onDeleteProperty, key)
-  }, [onUpdateProperty, onDeleteProperty])
-
-  const handleAdd = useCallback((rawKey: string, rawValue: string, mode: PropertyDisplayMode) => {
-    if (!rawKey.trim() || !onAddProperty) return
-    onAddProperty(rawKey.trim(), parseAddedValue(rawValue, mode))
-    if (mode !== 'text') {
-      persistModeOverride(rawKey.trim(), mode)
-      setDisplayOverrides(loadDisplayModeOverrides())
-    }
-    setShowAddDialog(false)
-  }, [onAddProperty])
-
-  const handleDisplayModeChange = useCallback((key: string, mode: PropertyDisplayMode | null) => {
-    persistModeOverride(key, mode)
-    setDisplayOverrides(loadDisplayModeOverrides())
-  }, [])
-
-  return {
-    editingKey, setEditingKey, showAddDialog, setShowAddDialog, displayOverrides,
-    availableTypes, customColorKey, typeColorKeys, typeIconKeys, vaultStatuses, vaultTagsByKey, propertyEntries,
-    handleSaveValue, handleSaveList, handleAdd, handleDisplayModeChange,
-  }
-}
-
 export function DynamicPropertiesPanel({
   entry, content, frontmatter, entries, allContent,
   onUpdateProperty, onDeleteProperty, onAddProperty, onNavigate,

src/components/Editor.tsx

@@ -1,10 +1,11 @@
-import { useRef, useEffect, useCallback, memo } from 'react'
+import { useRef, useEffect, useCallback, memo, useMemo } from 'react'
 import { useEditorTabSwap, getH1TextFromBlocks } from '../hooks/useEditorTabSwap'
 import { useHeadingTitleSync } from '../hooks/useHeadingTitleSync'
 import { useCreateBlockNote } from '@blocknote/react'
 import '@blocknote/mantine/style.css'
 import { uploadImageFile } from '../hooks/useImageDrop'
 import type { VaultEntry, GitCommit, NoteStatus } from '../types'
+import type { NoteListItem } from '../utils/ai-context'
 import type { FrontmatterValue } from './Inspector'
 import { ResizeHandle } from './ResizeHandle'
 import { TabBar } from './TabBar'
@@ -14,6 +15,7 @@ import { useEditorFocus } from '../hooks/useEditorFocus'
 import { EditorRightPanel } from './EditorRightPanel'
 import { EditorContent } from './EditorContent'
 import { schema } from './editorSchema'
+import { mergeTabContent } from '../utils/mergeTabContent'
 import './Editor.css'
 import './EditorTheme.css'
 
@@ -48,6 +50,8 @@ interface EditorProps {
   showAIChat?: boolean
   onToggleAIChat?: () => void
   vaultPath?: string
+  noteList?: NoteListItem[]
+  noteListFilter?: { type: string | null; query: string }
   onTrashNote?: (path: string) => void
   onRestoreNote?: (path: string) => void
   onDeleteNote?: (path: string) => void
@@ -68,6 +72,9 @@ interface EditorProps {
   rawToggleRef?: React.MutableRefObject<() => void>
   /** Mutable ref that Editor registers its diff-mode toggle into, for command palette access. */
   diffToggleRef?: React.MutableRefObject<() => void>
+  onFileCreated?: (relativePath: string) => void
+  onFileModified?: (relativePath: string) => void
+  onVaultChanged?: () => void
 }
 
 function useEditorModeExclusion({
@@ -117,13 +124,16 @@ export const Editor = memo(function Editor({
   inspectorEntry, inspectorContent, allContent, gitHistory,
   onUpdateFrontmatter, onDeleteProperty, onAddProperty,
   showAIChat, onToggleAIChat,
-  vaultPath,
+  vaultPath, noteList, noteListFilter,
   onTrashNote, onRestoreNote, onDeleteNote, onArchiveNote, onUnarchiveNote,
   onRenameTab, onContentChange, onSave, onTitleSync,
   canGoBack, canGoForward, onGoBack, onGoForward, leftPanelsCollapsed,
   isDarkTheme,
   rawToggleRef,
   diffToggleRef,
+  onFileCreated,
+  onFileModified,
+  onVaultChanged,
 }: EditorProps) {
   const vaultPathRef = useRef(vaultPath)
   useEffect(() => { vaultPathRef.current = vaultPath }, [vaultPath])
@@ -163,6 +173,11 @@ export const Editor = memo(function Editor({
     diffMode, rawMode, handleToggleDiff, handleToggleRaw, rawToggleRef, diffToggleRef,
   })
 
+  const enrichedAllContent = useMemo(
+    () => mergeTabContent(allContent, tabs),
+    [allContent, tabs],
+  )
+
   const isLoadingNewTab = activeTabPath !== null && !activeTab
   const activeStatus = activeTab ? getNoteStatus?.(activeTab.entry.path) ?? 'clean' : 'clean'
   const showDiffToggle = !!(activeTab && (diffMode || activeStatus === 'modified'))
@@ -225,9 +240,12 @@ export const Editor = memo(function Editor({
           inspectorEntry={inspectorEntry}
           inspectorContent={inspectorContent}
           entries={entries}
-          allContent={allContent}
+          allContent={enrichedAllContent}
           gitHistory={gitHistory}
           vaultPath={vaultPath ?? ''}
+          openTabs={tabs.map(t => t.entry)}
+          noteList={noteList}
+          noteListFilter={noteListFilter}
           onToggleInspector={onToggleInspector}
           onToggleAIChat={onToggleAIChat}
           onNavigateWikilink={onNavigateWikilink}
@@ -236,6 +254,9 @@ export const Editor = memo(function Editor({
           onDeleteProperty={onDeleteProperty}
           onAddProperty={onAddProperty}
           onOpenNote={onNavigateWikilink}
+          onFileCreated={onFileCreated}
+          onFileModified={onFileModified}
+          onVaultChanged={onVaultChanged}
         />
       </div>
     </div>

src/components/EditorRightPanel.tsx

@@ -1,4 +1,5 @@
 import type { VaultEntry, GitCommit } from '../types'
+import type { NoteListItem } from '../utils/ai-context'
 import { Inspector, type FrontmatterValue } from './Inspector'
 import { AiPanel } from './AiPanel'
 
@@ -12,6 +13,9 @@ interface EditorRightPanelProps {
   allContent: Record<string, string>
   gitHistory: GitCommit[]
   vaultPath: string
+  openTabs?: VaultEntry[]
+  noteList?: NoteListItem[]
+  noteListFilter?: { type: string | null; query: string }
   onToggleInspector: () => void
   onToggleAIChat?: () => void
   onNavigateWikilink: (target: string) => void
@@ -20,13 +24,18 @@ interface EditorRightPanelProps {
   onDeleteProperty?: (path: string, key: string) => Promise<void>
   onAddProperty?: (path: string, key: string, value: FrontmatterValue) => Promise<void>
   onOpenNote?: (path: string) => void
+  onFileCreated?: (relativePath: string) => void
+  onFileModified?: (relativePath: string) => void
+  onVaultChanged?: () => void
 }
 
 export function EditorRightPanel({
   showAIChat, inspectorCollapsed, inspectorWidth,
-  inspectorEntry, inspectorContent, entries, allContent, gitHistory, vaultPath,
+  inspectorEntry, inspectorContent, entries, allContent, gitHistory, vaultPath, openTabs,
+  noteList, noteListFilter,
   onToggleInspector, onToggleAIChat, onNavigateWikilink, onViewCommitDiff,
   onUpdateFrontmatter, onDeleteProperty, onAddProperty, onOpenNote,
+  onFileCreated, onFileModified, onVaultChanged,
 }: EditorRightPanelProps) {
   if (showAIChat) {
     return (
@@ -37,10 +46,17 @@ export function EditorRightPanel({
         <AiPanel
           onClose={() => onToggleAIChat?.()}
           onOpenNote={onOpenNote}
+          onFileCreated={onFileCreated}
+          onFileModified={onFileModified}
+          onVaultChanged={onVaultChanged}
           vaultPath={vaultPath}
           activeEntry={inspectorEntry}
+          activeNoteContent={inspectorContent}
           entries={entries}
           allContent={allContent}
+          openTabs={openTabs}
+          noteList={noteList}
+          noteListFilter={noteListFilter}
         />
       </div>
     )

src/components/InspectorPanels.tsx

@@ -1,538 +1,6 @@
-import { useMemo, useCallback, useState, useRef } from 'react'
-import type { ComponentType, SVGAttributes } from 'react'
-import { wikilinkTarget, wikilinkDisplay } from '../utils/wikilink'
-import type { VaultEntry, GitCommit } from '../types'
-import { CaretRight, Trash, X } from '@phosphor-icons/react'
-import type { ParsedFrontmatter } from '../utils/frontmatter'
-import { RELATIONSHIP_KEYS, containsWikilinks } from './DynamicPropertiesPanel'
-import { getTypeColor, getTypeLightColor } from '../utils/typeColors'
-import { getTypeIcon } from './NoteItem'
-import { findEntryByTarget } from '../utils/wikilinkColors'
-import type { FrontmatterValue } from './Inspector'
-import { NoteSearchList } from './NoteSearchList'
-import { useNoteSearch } from '../hooks/useNoteSearch'
-
-function isWikilink(value: string): boolean {
-  return /^\[\[.*\]\]$/.test(value)
-}
-
-function resolveRef(ref: string, entries: VaultEntry[]): VaultEntry | undefined {
-  const target = wikilinkTarget(ref)
-  const byTitle = findEntryByTarget(entries, target)
-  if (byTitle) return byTitle
-  const lastSegment = target.split('/').pop()
-  return entries.find((e) => {
-    const stem = e.path.replace(/^.*\/Laputa\//, '').replace(/\.md$/, '')
-    if (stem === target) return true
-    return e.filename.replace(/\.md$/, '') === lastSegment
-  })
-}
-
-function StatusSuffix({ isArchived, isTrashed }: { isArchived: boolean; isTrashed: boolean }) {
-  if (isTrashed) return <span style={{ fontSize: 10, opacity: 0.8 }}>(trashed)</span>
-  if (isArchived) return <span style={{ marginLeft: 4, fontSize: 10, opacity: 0.8 }}>(archived)</span>
-  return null
-}
-
-function LinkButton({ label, typeColor, bgColor, isArchived, isTrashed, onClick, onRemove, title, TypeIcon }: {
-  label: string
-  typeColor: string
-  bgColor?: string
-  isArchived: boolean
-  isTrashed: boolean
-  onClick: () => void
-  onRemove?: () => void
-  title?: string
-  TypeIcon: ComponentType<SVGAttributes<SVGSVGElement>>
-}) {
-  const isDimmed = isArchived || isTrashed
-  const color = isDimmed ? 'var(--muted-foreground)' : typeColor
-  return (
-    <button
-      className={`group/link flex w-full items-center justify-between gap-2 border-none text-left cursor-pointer min-w-0${bgColor ? ' ring-inset hover:ring-1 hover:ring-current' : ' hover:opacity-80'}`}
-      style={{
-        background: isDimmed ? 'var(--muted)' : (bgColor ?? 'transparent'),
-        color, borderRadius: 6, padding: bgColor ? '6px 10px' : '4px 0',
-        fontSize: 12, fontWeight: 500, opacity: isDimmed ? 0.7 : 1,
-      }}
-      onClick={onClick}
-      title={title}
-    >
-      <span className="flex items-center gap-1 flex-1 truncate">
-        {isTrashed && <Trash size={12} className="shrink-0" />}
-        {label}
-        <StatusSuffix isArchived={isArchived} isTrashed={isTrashed} />
-      </span>
-      <span className="flex items-center gap-1.5 shrink-0">
-        {onRemove && (
-          <span
-            className="flex items-center opacity-0 transition-opacity group-hover/link:opacity-100"
-            onClick={(e) => { e.stopPropagation(); onRemove() }}
-            role="button"
-            title="Remove from relation"
-            data-testid="remove-relation-ref"
-          >
-            <X size={14} />
-          </span>
-        )}
-        <TypeIcon width={14} height={14} className="shrink-0" style={{ color, opacity: 0.5 }} />
-      </span>
-    </button>
-  )
-}
-
-function entryStatusTitle(entry: VaultEntry | undefined): string | undefined {
-  if (entry?.trashed) return 'Trashed'
-  if (entry?.archived) return 'Archived'
-  return undefined
-}
-
-function resolveRefProps(ref: string, entries: VaultEntry[], typeEntryMap: Record<string, VaultEntry>) {
-  const resolved = resolveRef(ref, entries)
-  const refType = resolved?.isA ?? null
-  const te = typeEntryMap[refType ?? '']
-  return {
-    label: wikilinkDisplay(ref),
-    typeColor: getTypeColor(refType, te?.color),
-    bgColor: getTypeLightColor(refType, te?.color),
-    isArchived: resolved?.archived ?? false,
-    isTrashed: resolved?.trashed ?? false,
-    target: wikilinkTarget(ref),
-    title: entryStatusTitle(resolved),
-    TypeIcon: getTypeIcon(refType, te?.icon),
-  }
-}
-
-function SearchDropdown({ search, onSelect }: {
-  search: ReturnType<typeof useNoteSearch>
-  onSelect: (title: string) => void
-}) {
-  return (
-    <div className="absolute left-0 right-0 top-full z-50 mt-0.5 rounded border border-border bg-popover shadow-md">
-      <NoteSearchList
-        items={search.results}
-        selectedIndex={search.selectedIndex}
-        getItemKey={(item) => item.entry.path}
-        onItemClick={(item) => onSelect(item.entry.title)}
-        onItemHover={(i) => search.setSelectedIndex(i)}
-        className="max-h-[160px] overflow-y-auto"
-      />
-    </div>
-  )
-}
-
-function InlineAddNote({ entries, onAdd }: {
-  entries: VaultEntry[]
-  onAdd: (noteTitle: string) => void
-}) {
-  const [active, setActive] = useState(false)
-  const [query, setQuery] = useState('')
-  const inputRef = useRef<HTMLInputElement>(null)
-  const search = useNoteSearch(entries, query, 8)
-
-  const selectAndClose = useCallback((title: string) => {
-    onAdd(title)
-    setQuery('')
-    setActive(false)
-  }, [onAdd])
-
-  const handleConfirm = useCallback(() => {
-    const title = search.selectedEntry?.title ?? query.trim()
-    if (title) selectAndClose(title)
-  }, [search.selectedEntry, query, selectAndClose])
-
-  const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
-    search.handleKeyDown(e)
-    if (e.key === 'Enter') { e.preventDefault(); handleConfirm() }
-    else if (e.key === 'Escape') { setQuery(''); setActive(false) }
-  }, [search, handleConfirm])
-
-  if (!active) {
-    return (
-      <button
-        className="mt-1 w-full border border-dashed border-border bg-transparent text-left text-muted-foreground cursor-pointer hover:border-foreground hover:text-foreground"
-        style={{ borderRadius: 6, padding: '6px 10px', fontSize: 12 }}
-        onClick={() => setActive(true)}
-        data-testid="add-relation-ref"
-      >
-        Add
-      </button>
-    )
-  }
-
-  return (
-    <div className="relative mt-1">
-      <div className="group/add relative flex items-center">
-        <input
-          ref={inputRef}
-          autoFocus
-          className="w-full border border-border bg-transparent text-foreground"
-          style={{ borderRadius: 6, outline: 'none', minWidth: 0, padding: '6px 10px', fontSize: 12 }}
-          placeholder="Note title"
-          value={query}
-          onChange={e => setQuery(e.target.value)}
-          onKeyDown={handleKeyDown}
-          data-testid="add-relation-ref-input"
-        />
-        <button
-          className="absolute right-1 top-1/2 -translate-y-1/2 border-none bg-transparent p-0.5 text-muted-foreground opacity-0 transition-opacity hover:text-foreground group-hover/add:opacity-100"
-          onClick={() => { setQuery(''); setActive(false) }}
-        >
-          <X size={12} />
-        </button>
-      </div>
-      {query.trim() && search.results.length > 0 && (
-        <SearchDropdown search={search} onSelect={selectAndClose} />
-      )}
-    </div>
-  )
-}
-
-function RelationshipGroup({ label, refs, entries, typeEntryMap, onNavigate, onRemoveRef, onAddRef }: {
-  label: string; refs: string[]; entries: VaultEntry[]; typeEntryMap: Record<string, VaultEntry>
-  onNavigate: (target: string) => void
-  onRemoveRef?: (ref: string) => void; onAddRef?: (noteTitle: string) => void
-}) {
-  if (refs.length === 0) return null
-  return (
-    <div className="mb-2.5">
-      <span className="font-mono-overline mb-1 block text-muted-foreground">{label}</span>
-      <div className="flex flex-col gap-1">
-        {refs.map((ref, idx) => {
-          const props = resolveRefProps(ref, entries, typeEntryMap)
-          return (
-            <LinkButton
-              key={`${ref}-${idx}`}
-              {...props}
-              onClick={() => onNavigate(props.target)}
-              onRemove={onRemoveRef ? () => onRemoveRef(ref) : undefined}
-            />
-          )
-        })}
-      </div>
-      {onAddRef && <InlineAddNote entries={entries} onAdd={onAddRef} />}
-    </div>
-  )
-}
-
-function extractRelationshipRefs(frontmatter: ParsedFrontmatter): { key: string; refs: string[] }[] {
-  return Object.entries(frontmatter)
-    .filter(([key, value]) => key !== 'Type' && (RELATIONSHIP_KEYS.has(key) || containsWikilinks(value)))
-    .map(([key, value]) => {
-      const refs: string[] = []
-      if (typeof value === 'string' && isWikilink(value)) refs.push(value)
-      else if (Array.isArray(value)) value.forEach(v => { if (typeof v === 'string' && isWikilink(v)) refs.push(v) })
-      return { key, refs }
-    })
-    .filter(({ refs }) => refs.length > 0)
-}
-
-function NoteTargetInput({ entries, value, onChange, onSubmit, onCancel }: {
-  entries: VaultEntry[]
-  value: string
-  onChange: (v: string) => void
-  onSubmit?: () => void
-  onCancel?: () => void
-}) {
-  const [focused, setFocused] = useState(false)
-  const search = useNoteSearch(entries, value, 8)
-
-  const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
-    search.handleKeyDown(e)
-    if (e.key === 'Enter') {
-      e.preventDefault()
-      if (search.selectedEntry) { onChange(search.selectedEntry.title); setFocused(false) }
-      else onSubmit?.()
-    } else if (e.key === 'Escape') { onCancel?.() }
-  }, [search, onChange, onSubmit, onCancel])
-
-  const showDropdown = focused && value.trim() && search.results.length > 0
-
-  return (
-    <div className="relative">
-      <input
-        className="w-full border border-border bg-transparent px-2 py-1 text-xs text-foreground"
-        style={{ borderRadius: 4, outline: 'none' }}
-        placeholder="Note title"
-        value={value}
-        onChange={e => onChange(e.target.value)}
-        onFocus={() => setFocused(true)}
-        onBlur={() => setTimeout(() => setFocused(false), 150)}
-        onKeyDown={handleKeyDown}
-      />
-      {showDropdown && (
-        <SearchDropdown search={search} onSelect={(title) => { onChange(title); setFocused(false) }} />
-      )}
-    </div>
-  )
-}
-
-function AddRelationshipForm({ entries, onAddProperty }: {
-  entries: VaultEntry[]
-  onAddProperty: (key: string, value: FrontmatterValue) => void
-}) {
-  const [relKey, setRelKey] = useState('')
-  const [relTarget, setRelTarget] = useState('')
-  const [showForm, setShowForm] = useState(false)
-  const keyInputRef = useRef<HTMLInputElement>(null)
-
-  const submitForm = useCallback((targetOverride?: string) => {
-    const key = relKey.trim()
-    const target = (targetOverride ?? relTarget).trim()
-    if (!key || !target) return
-    onAddProperty(key, `[[${target}]]`)
-    setRelKey(''); setRelTarget(''); setShowForm(false)
-  }, [relKey, relTarget, onAddProperty])
-
-  const resetForm = useCallback(() => {
-    setShowForm(false); setRelKey(''); setRelTarget('')
-  }, [])
-
-  if (!showForm) {
-    return (
-      <button className="mt-2 w-full border border-border bg-transparent text-center text-muted-foreground" style={{ borderRadius: 6, padding: '6px 12px', fontSize: 12, cursor: 'pointer' }} onClick={() => { setShowForm(true); setTimeout(() => keyInputRef.current?.focus(), 0) }}>+ Link existing</button>
-    )
-  }
-
-  return (
-    <div className="mt-2 flex flex-col gap-1.5">
-      <input
-        ref={keyInputRef}
-        autoFocus
-        className="w-full border border-border bg-transparent px-2 py-1 text-xs text-foreground"
-        style={{ borderRadius: 4, outline: 'none' }}
-        placeholder="Relationship name"
-        value={relKey}
-        onChange={e => setRelKey(e.target.value)}
-        onKeyDown={e => { if (e.key === 'Enter') submitForm(); else if (e.key === 'Escape') resetForm() }}
-      />
-      <NoteTargetInput entries={entries} value={relTarget} onChange={setRelTarget} onSubmit={submitForm} onCancel={resetForm} />
-      <div className="flex gap-1.5">
-        <button className="flex-1 border border-border bg-transparent text-xs text-foreground" style={{ borderRadius: 4, padding: '4px 0' }} onClick={() => submitForm()} disabled={!relKey.trim() || !relTarget.trim()}>Add</button>
-        <button className="border border-border bg-transparent text-xs text-muted-foreground" style={{ borderRadius: 4, padding: '4px 8px' }} onClick={resetForm}>Cancel</button>
-      </div>
-    </div>
-  )
-}
-
-function updateRefsForRemoval(refs: string[], refToRemove: string): FrontmatterValue | null {
-  const remaining = refs.filter(r => r !== refToRemove)
-  if (remaining.length === 0) return null
-  return remaining.length === 1 ? remaining[0] : remaining
-}
-
-function updateRefsForAddition(refs: string[], noteTitle: string): FrontmatterValue | false {
-  const newRef = `[[${noteTitle}]]`
-  if (refs.includes(newRef)) return false
-  const updated = [...refs, newRef]
-  return updated.length === 1 ? updated[0] : updated
-}
-
-export function DynamicRelationshipsPanel({ frontmatter, entries, typeEntryMap, onNavigate, onAddProperty, onUpdateProperty, onDeleteProperty }: {
-  frontmatter: ParsedFrontmatter; entries: VaultEntry[]; typeEntryMap: Record<string, VaultEntry>
-  onNavigate: (target: string) => void
-  onAddProperty?: (key: string, value: FrontmatterValue) => void
-  onUpdateProperty?: (key: string, value: FrontmatterValue) => void
-  onDeleteProperty?: (key: string) => void
-}) {
-  const relationshipEntries = useMemo(() => extractRelationshipRefs(frontmatter), [frontmatter])
-
-  const handleRemoveRef = useCallback((key: string, refToRemove: string) => {
-    if (!onUpdateProperty || !onDeleteProperty) return
-    const group = relationshipEntries.find(g => g.key === key)
-    if (!group) return
-    const result = updateRefsForRemoval(group.refs, refToRemove)
-    if (result === null) onDeleteProperty(key)
-    else onUpdateProperty(key, result)
-  }, [relationshipEntries, onUpdateProperty, onDeleteProperty])
-
-  const handleAddRef = useCallback((key: string, noteTitle: string) => {
-    if (!onUpdateProperty) return
-    const existing = relationshipEntries.find(g => g.key === key)?.refs ?? []
-    const result = updateRefsForAddition(existing, noteTitle)
-    if (result !== false) onUpdateProperty(key, result)
-  }, [relationshipEntries, onUpdateProperty])
-
-  const canEdit = !!onUpdateProperty && !!onDeleteProperty
-
-  return (
-    <div>
-      {relationshipEntries.map(({ key, refs }) => (
-        <RelationshipGroup
-          key={key} label={key} refs={refs} entries={entries} typeEntryMap={typeEntryMap} onNavigate={onNavigate}
-          onRemoveRef={canEdit ? (ref) => handleRemoveRef(key, ref) : undefined}
-          onAddRef={canEdit ? (noteTitle) => handleAddRef(key, noteTitle) : undefined}
-        />
-      ))}
-      {onAddProperty
-        ? <AddRelationshipForm entries={entries} onAddProperty={onAddProperty} />
-        : <button className="mt-2 w-full border border-border bg-transparent text-center text-muted-foreground" style={{ borderRadius: 6, padding: '6px 12px', fontSize: 12, opacity: 0.5, cursor: 'not-allowed' }} disabled>+ Link existing</button>
-      }
-    </div>
-  )
-}
-
-export interface BacklinkItem {
-  entry: VaultEntry
-  context: string | null
-}
-
-function BacklinkEntry({ entry, context, typeEntryMap, onNavigate }: {
-  entry: VaultEntry
-  context: string | null
-  typeEntryMap: Record<string, VaultEntry>
-  onNavigate: (target: string) => void
-}) {
-  const te = typeEntryMap[entry.isA ?? '']
-  const isDimmed = entry.archived || entry.trashed
-  return (
-    <button
-      className="flex w-full cursor-pointer flex-col items-start gap-0.5 border-none bg-transparent p-0 text-left hover:opacity-80"
-      onClick={() => onNavigate(entry.title)}
-      title={entryStatusTitle(entry)}
-    >
-      <span
-        className="flex items-center gap-1 text-xs font-medium"
-        style={{ color: isDimmed ? 'var(--muted-foreground)' : getTypeColor(entry.isA, te?.color) }}
-      >
-        {entry.trashed && <Trash size={12} className="shrink-0" />}
-        {entry.title}
-        <StatusSuffix isArchived={entry.archived} isTrashed={entry.trashed} />
-      </span>
-      {context && (
-        <span className="line-clamp-2 text-[11px] leading-snug text-muted-foreground">
-          {context}
-        </span>
-      )}
-    </button>
-  )
-}
-
-export function BacklinksPanel({ backlinks, typeEntryMap, onNavigate }: {
-  backlinks: BacklinkItem[]
-  typeEntryMap: Record<string, VaultEntry>
-  onNavigate: (target: string) => void
-}) {
-  const [expanded, setExpanded] = useState(false)
-
-  if (backlinks.length === 0) return null
-
-  return (
-    <div>
-      <button
-        className="font-mono-overline mb-2 flex w-full cursor-pointer items-center gap-1 border-none bg-transparent p-0 text-left text-muted-foreground hover:text-foreground"
-        onClick={() => setExpanded((v) => !v)}
-        data-testid="backlinks-toggle"
-      >
-        <CaretRight
-          size={12}
-          className="shrink-0 transition-transform"
-          style={{ transform: expanded ? 'rotate(90deg)' : undefined }}
-        />
-        Backlinks ({backlinks.length})
-      </button>
-      {expanded && (
-        <div className="flex flex-col gap-1.5" data-testid="backlinks-list">
-          {backlinks.map(({ entry, context }) => (
-            <BacklinkEntry
-              key={entry.path}
-              entry={entry}
-              context={context}
-              typeEntryMap={typeEntryMap}
-              onNavigate={onNavigate}
-            />
-          ))}
-        </div>
-      )}
-    </div>
-  )
-}
-
-export interface ReferencedByItem {
-  entry: VaultEntry
-  viaKey: string
-}
-
-export function ReferencedByPanel({ items, typeEntryMap, onNavigate }: {
-  items: ReferencedByItem[]
-  typeEntryMap: Record<string, VaultEntry>
-  onNavigate: (target: string) => void
-}) {
-  const grouped = useMemo(() => {
-    const map = new Map<string, VaultEntry[]>()
-    for (const item of items) {
-      const existing = map.get(item.viaKey)
-      if (existing) existing.push(item.entry)
-      else map.set(item.viaKey, [item.entry])
-    }
-    return Array.from(map.entries())
-  }, [items])
-
-  if (items.length === 0) return null
-
-  return (
-    <div className="referenced-by-panel">
-      <div className="flex flex-col gap-2.5">
-        {grouped.map(([viaKey, groupEntries]) => (
-          <div key={viaKey}>
-            <span className="mb-1 block font-mono text-muted-foreground" style={{ fontSize: 9, fontWeight: 400, letterSpacing: '1.2px', textTransform: 'uppercase', opacity: 0.7 }}>
-              ← {viaKey}
-            </span>
-            <div className="flex flex-col gap-0.5">
-              {groupEntries.map((e) => {
-                const te = typeEntryMap[e.isA ?? '']
-                return (
-                  <LinkButton
-                    key={e.path}
-                    label={e.title}
-                    typeColor={getTypeColor(e.isA, te?.color)}
-                    isArchived={e.archived}
-                    isTrashed={e.trashed}
-                    onClick={() => onNavigate(e.title)}
-                    title={e.trashed ? 'Trashed' : e.archived ? 'Archived' : undefined}
-                    TypeIcon={getTypeIcon(e.isA, te?.icon)}
-                  />
-                )
-              })}
-            </div>
-          </div>
-        ))}
-      </div>
-    </div>
-  )
-}
-
-function formatRelativeDate(timestamp: number): string {
-  const now = Math.floor(Date.now() / 1000)
-  const days = Math.floor((now - timestamp) / 86400)
-  if (days < 1) return 'today'
-  if (days === 1) return 'yesterday'
-  if (days < 30) return `${days}d ago`
-  const months = Math.floor(days / 30)
-  return months === 1 ? '1mo ago' : `${months}mo ago`
-}
-
-export function GitHistoryPanel({ commits, onViewCommitDiff }: { commits: GitCommit[]; onViewCommitDiff?: (commitHash: string) => void }) {
-  return (
-    <div>
-      <h4 className="font-mono-overline mb-2 text-muted-foreground">History</h4>
-      {commits.length === 0
-        ? <p className="m-0 text-[13px] text-muted-foreground">No revision history</p>
-        : (
-          <div className="flex flex-col gap-2.5">
-            {commits.map((c) => (
-              <div key={c.hash} style={{ borderLeft: '2px solid var(--border)', paddingLeft: 10 }}>
-                <div className="mb-0.5 flex items-center justify-between">
-                  <button className="border-none bg-transparent p-0 font-mono text-primary cursor-pointer hover:underline" style={{ fontSize: 11 }} onClick={() => onViewCommitDiff?.(c.hash)} title={`View diff for ${c.shortHash}`}>{c.shortHash}</button>
-                  <span className="text-muted-foreground" style={{ fontSize: 10 }}>{formatRelativeDate(c.date)}</span>
-                </div>
-                <div className="truncate text-xs text-secondary-foreground">{c.message}</div>
-                {c.author && <div className="truncate text-muted-foreground" style={{ fontSize: 10, marginTop: 1 }}>{c.author}</div>}
-              </div>
-            ))}
-          </div>
-        )
-      }
-    </div>
-  )
-}
+export { DynamicRelationshipsPanel } from './inspector/RelationshipsPanel'
+export { BacklinksPanel } from './inspector/BacklinksPanel'
+export type { BacklinkItem } from './inspector/BacklinksPanel'
+export { ReferencedByPanel } from './inspector/ReferencedByPanel'
+export type { ReferencedByItem } from './inspector/ReferencedByPanel'
+export { GitHistoryPanel } from './inspector/GitHistoryPanel'

src/components/MarkdownContent.test.tsx

@@ -1,6 +1,7 @@
-import { describe, it, expect } from 'vitest'
-import { render, screen } from '@testing-library/react'
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
 import { MarkdownContent } from './MarkdownContent'
+import { preprocessWikilinks } from '../utils/chatWikilinks'
 
 describe('MarkdownContent', () => {
   it('renders bold text', () => {
@@ -72,4 +73,110 @@ describe('MarkdownContent', () => {
     expect(bq).toBeTruthy()
     expect(bq!.textContent).toContain('A quote')
   })
+
+  describe('wikilinks', () => {
+    it('preprocessWikilinks converts [[Target]] to markdown links', () => {
+      expect(preprocessWikilinks('See [[My Note]]')).toBe('See [My Note](wikilink://My%20Note)')
+      expect(preprocessWikilinks('[[A]] and [[B]]')).toBe('[A](wikilink://A) and [B](wikilink://B)')
+      expect(preprocessWikilinks('`[[code]]`')).toBe('`[[code]]`')
+    })
+
+    it('renders [[Note Title]] as a clickable wikilink chip', () => {
+      const onClick = vi.fn()
+      const { container } = render(
+        <MarkdownContent content="Check out [[My Note]]" onWikilinkClick={onClick} />,
+      )
+      const wikilink = container.querySelector('.chat-wikilink')
+      expect(wikilink).toBeTruthy()
+      expect(wikilink!.textContent).toBe('My Note')
+      expect(wikilink!.getAttribute('data-wikilink-target')).toBe('My Note')
+    })
+
+    it('fires onWikilinkClick when a wikilink is clicked', () => {
+      const onClick = vi.fn()
+      const { container } = render(
+        <MarkdownContent content="See [[Daily Log]]" onWikilinkClick={onClick} />,
+      )
+      const wikilink = container.querySelector('.chat-wikilink')!
+      fireEvent.click(wikilink)
+      expect(onClick).toHaveBeenCalledWith('Daily Log')
+    })
+
+    it('renders multiple wikilinks in the same paragraph', () => {
+      const onClick = vi.fn()
+      const { container } = render(
+        <MarkdownContent content="See [[Note A]] and [[Note B]]" onWikilinkClick={onClick} />,
+      )
+      const wikilinks = container.querySelectorAll('.chat-wikilink')
+      expect(wikilinks).toHaveLength(2)
+      expect(wikilinks[0].textContent).toBe('Note A')
+      expect(wikilinks[1].textContent).toBe('Note B')
+    })
+
+    it('handles pipe syntax [[target|display]]', () => {
+      const onClick = vi.fn()
+      const { container } = render(
+        <MarkdownContent content="See [[path/to/note|My Display]]" onWikilinkClick={onClick} />,
+      )
+      const wikilink = container.querySelector('.chat-wikilink')!
+      expect(wikilink.textContent).toBe('My Display')
+      expect(wikilink.getAttribute('data-wikilink-target')).toBe('path/to/note')
+      fireEvent.click(wikilink)
+      expect(onClick).toHaveBeenCalledWith('path/to/note')
+    })
+
+    it('does not render wikilinks inside inline code', () => {
+      const onClick = vi.fn()
+      const { container } = render(
+        <MarkdownContent content="Use `[[Not a link]]` syntax" onWikilinkClick={onClick} />,
+      )
+      expect(container.querySelector('.chat-wikilink')).toBeNull()
+    })
+
+    it('does not render wikilinks inside code blocks', () => {
+      const onClick = vi.fn()
+      const { container } = render(
+        <MarkdownContent content={'```\n[[Not a link]]\n```'} onWikilinkClick={onClick} />,
+      )
+      expect(container.querySelector('.chat-wikilink')).toBeNull()
+    })
+
+    it('handles notes with special characters in title', () => {
+      const onClick = vi.fn()
+      const { container } = render(
+        <MarkdownContent content="Check [[Meeting — 2024/01/15]]" onWikilinkClick={onClick} />,
+      )
+      const wikilink = container.querySelector('.chat-wikilink')!
+      expect(wikilink.textContent).toBe('Meeting — 2024/01/15')
+      fireEvent.click(wikilink)
+      expect(onClick).toHaveBeenCalledWith('Meeting — 2024/01/15')
+    })
+
+    it('does not transform wikilinks when onWikilinkClick is not provided', () => {
+      const { container } = render(
+        <MarkdownContent content="See [[Some Note]]" />,
+      )
+      expect(container.querySelector('.chat-wikilink')).toBeNull()
+      expect(container.textContent).toContain('[[Some Note]]')
+    })
+
+    it('renders wikilinks inside list items', () => {
+      const onClick = vi.fn()
+      const { container } = render(
+        <MarkdownContent content={'- First [[Note A]]\n- Second [[Note B]]'} onWikilinkClick={onClick} />,
+      )
+      const wikilinks = container.querySelectorAll('.chat-wikilink')
+      expect(wikilinks).toHaveLength(2)
+    })
+
+    it('has role="link" and tabIndex for accessibility', () => {
+      const onClick = vi.fn()
+      const { container } = render(
+        <MarkdownContent content="See [[Accessible Note]]" onWikilinkClick={onClick} />,
+      )
+      const wikilink = container.querySelector('.chat-wikilink')!
+      expect(wikilink.getAttribute('role')).toBe('link')
+      expect(wikilink.getAttribute('tabindex')).toBe('0')
+    })
+  })
 })

src/components/MarkdownContent.tsx

@@ -1,18 +1,63 @@
-import { memo, useMemo } from 'react'
-import Markdown from 'react-markdown'
+import { memo, useMemo, useCallback, type MouseEvent } from 'react'
+import Markdown, { defaultUrlTransform } from 'react-markdown'
 import remarkGfm from 'remark-gfm'
 import rehypeHighlight from 'rehype-highlight'
+import { preprocessWikilinks, WIKILINK_SCHEME } from '../utils/chatWikilinks'
 
 const REMARK_PLUGINS = [remarkGfm]
 const REHYPE_PLUGINS = [rehypeHighlight]
 
-export const MarkdownContent = memo(function MarkdownContent({ content }: { content: string }) {
-  const rendered = useMemo(() => (
-    <div className="ai-markdown">
-      <Markdown remarkPlugins={REMARK_PLUGINS} rehypePlugins={REHYPE_PLUGINS}>
-        {content}
+function wikilinkUrlTransform(url: string): string {
+  if (url.startsWith(WIKILINK_SCHEME)) return url
+  return defaultUrlTransform(url)
+}
+
+interface MarkdownContentProps {
+  content: string
+  onWikilinkClick?: (target: string) => void
+}
+
+export const MarkdownContent = memo(function MarkdownContent({ content, onWikilinkClick }: MarkdownContentProps) {
+  const processedContent = useMemo(
+    () => onWikilinkClick ? preprocessWikilinks(content) : content,
+    [content, onWikilinkClick],
+  )
+
+  const handleClick = useCallback((e: MouseEvent) => {
+    const el = (e.target as HTMLElement).closest<HTMLElement>('[data-wikilink-target]')
+    if (el) {
+      e.preventDefault()
+      onWikilinkClick?.(el.dataset.wikilinkTarget!)
+    }
+  }, [onWikilinkClick])
+
+  const components = useMemo(() => {
+    if (!onWikilinkClick) return undefined
+    return {
+      a: ({ href, children }: { href?: string; children?: React.ReactNode }) => {
+        if (href?.startsWith(WIKILINK_SCHEME)) {
+          const target = decodeURIComponent(href.slice(WIKILINK_SCHEME.length))
+          return (
+            <span className="chat-wikilink" data-wikilink-target={target} role="link" tabIndex={0}>
+              {children}
+            </span>
+          )
+        }
+        return <a href={href}>{children}</a>
+      },
+    }
+  }, [onWikilinkClick])
+
+  return (
+    <div className="ai-markdown" onClick={onWikilinkClick ? handleClick : undefined} role="presentation">
+      <Markdown
+        remarkPlugins={REMARK_PLUGINS}
+        rehypePlugins={REHYPE_PLUGINS}
+        components={components}
+        urlTransform={onWikilinkClick ? wikilinkUrlTransform : undefined}
+      >
+        {processedContent}
       </Markdown>
     </div>
-  ), [content])
-  return rendered
+  )
 })

src/components/NoteList.tsx

@@ -10,7 +10,7 @@ import { getTypeColor, getTypeLightColor, buildTypeEntryMap } from '../utils/typ
 import { NoteItem, getTypeIcon } from './NoteItem'
 import { SortDropdown } from './SortDropdown'
 import { BulkActionBar } from './BulkActionBar'
-import { useMultiSelect } from '../hooks/useMultiSelect'
+import { useMultiSelect, type MultiSelectState } from '../hooks/useMultiSelect'
 import { useNoteListKeyboard } from '../hooks/useNoteListKeyboard'
 import {
   type SortOption, type SortDirection, type SortConfig, type RelationshipGroup,
@@ -148,13 +148,20 @@ function ListViewHeader({ isTrashView, expiredTrashCount }: {
   return <TrashWarningBanner expiredCount={isTrashView ? expiredTrashCount : 0} />
 }
 
+function resolveEmptyText(isChangesView: boolean, changesError: string | null | undefined, isTrashView: boolean, query: string): string {
+  if (isChangesView && changesError) return `Failed to load changes: ${changesError}`
+  if (isChangesView) return 'No pending changes'
+  if (isTrashView) return 'Trash is empty'
+  return query ? 'No matching notes' : 'No notes found'
+}
+
 function ListView({ isTrashView, isChangesView, changesError, expiredTrashCount, searched, query, renderItem, virtuosoRef }: {
   isTrashView: boolean; isChangesView?: boolean; changesError?: string | null; expiredTrashCount: number
   searched: VaultEntry[]; query: string
   renderItem: (entry: VaultEntry) => React.ReactNode
   virtuosoRef?: React.RefObject<VirtuosoHandle | null>
 }) {
-  const emptyText = (isChangesView && changesError) ? `Failed to load changes: ${changesError}` : isChangesView ? 'No pending changes' : isTrashView ? 'Trash is empty' : (query ? 'No matching notes' : 'No notes found')
+  const emptyText = resolveEmptyText(!!isChangesView, changesError ?? null, isTrashView, query)
   const hasHeader = isTrashView && expiredTrashCount > 0
 
   if (searched.length === 0) {
@@ -198,17 +205,16 @@ function countExpiredTrash(entries: VaultEntry[]): number {
 
 // --- Click routing ---
 
-type MultiSelectActions = { selectRange: (path: string) => void; clear: () => void; setAnchor: (path: string) => void }
+interface ClickActions {
+  onReplace: (entry: VaultEntry) => void
+  onSelect: (entry: VaultEntry) => void
+  multiSelect: { selectRange: (path: string) => void; clear: () => void; setAnchor: (path: string) => void }
+}
 
-function routeNoteClick(
-  entry: VaultEntry, e: React.MouseEvent,
-  onReplaceActiveTab: (entry: VaultEntry) => void,
-  onSelectNote: (entry: VaultEntry) => void,
-  multiSelect: MultiSelectActions,
-) {
-  if (e.shiftKey) { multiSelect.selectRange(entry.path) }
-  else if (e.metaKey || e.ctrlKey) { multiSelect.clear(); onSelectNote(entry) }
-  else { multiSelect.clear(); multiSelect.setAnchor(entry.path); onReplaceActiveTab(entry) }
+function routeNoteClick(entry: VaultEntry, e: React.MouseEvent, actions: ClickActions) {
+  if (e.shiftKey) { actions.multiSelect.selectRange(entry.path) }
+  else if (e.metaKey || e.ctrlKey) { actions.multiSelect.clear(); actions.onSelect(entry) }
+  else { actions.multiSelect.clear(); actions.multiSelect.setAnchor(entry.path); actions.onReplace(entry) }
 }
 
 // --- Pure helpers extracted from NoteListInner to reduce cyclomatic complexity ---
@@ -292,170 +298,162 @@ function resolveListSortConfig(typeDocument: VaultEntry | null, sortPrefs: Recor
   return sortPrefs['__list__'] ?? DEFAULT_LIST_CONFIG
 }
 
-// --- Main component ---
+// --- Extracted hooks ---
 
-const defaultGetNoteStatus = (): NoteStatus => 'clean'
+interface SortPersistence {
+  onUpdateTypeSort: (path: string, key: string, value: string) => void
+  updateEntry: (path: string, patch: Partial<VaultEntry>) => void
+}
 
-function NoteListInner({ entries, selection, selectedNote, allContent, modifiedFiles, modifiedFilesError, getNoteStatus, sidebarCollapsed, onSelectNote, onReplaceActiveTab, onCreateNote, onBulkArchive, onBulkTrash, onUpdateTypeSort, updateEntry }: NoteListProps) {
-  const [search, setSearch] = useState('')
-  const [searchVisible, setSearchVisible] = useState(false)
-  const [collapsedGroups, setCollapsedGroups] = useState<Set<string>>(new Set())
+function persistSortToType(path: string, config: SortConfig, persistence: SortPersistence) {
+  const serialized = serializeSortConfig(config)
+  persistence.onUpdateTypeSort(path, 'sort', serialized)
+  persistence.updateEntry(path, { sort: serialized })
+  clearListSortFromLocalStorage()
+}
+
+function migrateListSortToType(typeDoc: VaultEntry, sortPrefs: Record<string, SortConfig>, migrationDone: Set<string>, persistence: SortPersistence) {
+  if (typeDoc.sort || migrationDone.has(typeDoc.path)) return
+  const lsConfig = sortPrefs['__list__']
+  if (!lsConfig) return
+  migrationDone.add(typeDoc.path)
+  persistSortToType(typeDoc.path, lsConfig, persistence)
+}
+
+function saveGroupSort(groupLabel: string, option: SortOption, direction: SortDirection, setSortPrefs: React.Dispatch<React.SetStateAction<Record<string, SortConfig>>>) {
+  setSortPrefs((prev) => { const next = { ...prev, [groupLabel]: { option, direction } }; saveSortPreferences(next); return next })
+}
+
+function deriveEffectiveSort(configOption: SortOption, customProperties: string[]): SortOption {
+  if (!configOption.startsWith('property:')) return configOption
+  return customProperties.includes(configOption.slice('property:'.length)) ? configOption : 'modified'
+}
+
+interface UseNoteListSortParams {
+  entries: VaultEntry[]
+  selection: SidebarSelection
+  modifiedPathSet: Set<string>
+  modifiedSuffixes: string[]
+  onUpdateTypeSort?: (path: string, key: string, value: string | number | boolean | string[] | null) => void
+  updateEntry?: (path: string, patch: Partial<VaultEntry>) => void
+}
+
+function useNoteListSort({ entries, selection, modifiedPathSet, modifiedSuffixes, onUpdateTypeSort, updateEntry }: UseNoteListSortParams) {
   const [sortPrefs, setSortPrefs] = useState<Record<string, SortConfig>>(loadSortPreferences)
-  const { onMouseDown: onDragMouseDown } = useDragRegion()
 
-  const modifiedPathSet = useMemo(
-    () => new Set((modifiedFiles ?? []).map((f) => f.path)),
-    [modifiedFiles],
-  )
-
-  // Suffix patterns for cross-machine robustness: if the vault cache carried
-  // stale absolute paths from another machine, fall back to matching by the
-  // relative path suffix so the changes view stays in sync with the badge.
-  const modifiedSuffixes = useMemo(
-    () => (modifiedFiles ?? []).map((f) => '/' + f.relativePath),
-    [modifiedFiles],
-  )
-
-  const resolvedGetNoteStatus = useMemo<(path: string) => NoteStatus>(
-    () => createNoteStatusResolver(getNoteStatus, modifiedFiles, modifiedPathSet),
-    [getNoteStatus, modifiedFiles, modifiedPathSet],
-  )
-
-  // Resolve the type document for sectionGroup selections (needs to be above sort logic)
   const typeDocument = useMemo(() => {
     if (selection.kind !== 'sectionGroup') return null
     return entries.find((e) => e.isA === 'Type' && e.title === selection.type) ?? null
   }, [selection, entries])
 
-  // Resolve list sort config: read from type frontmatter for sectionGroup, else localStorage
   const listConfig = resolveListSortConfig(typeDocument, sortPrefs)
+  const persistence = useMemo<SortPersistence | null>(
+    () => (onUpdateTypeSort && updateEntry) ? { onUpdateTypeSort, updateEntry } : null,
+    [onUpdateTypeSort, updateEntry],
+  )
 
-  // Silent migration: if type has no sort in frontmatter but localStorage has __list__, migrate it
   const migrationDoneRef = useRef<Set<string>>(new Set())
   useEffect(() => {
-    if (!typeDocument || typeDocument.sort || !onUpdateTypeSort || !updateEntry) return
-    if (migrationDoneRef.current.has(typeDocument.path)) return
-    const lsConfig = sortPrefs['__list__']
-    if (!lsConfig) return
-    migrationDoneRef.current.add(typeDocument.path)
-    const serialized = serializeSortConfig(lsConfig)
-    onUpdateTypeSort(typeDocument.path, 'sort', serialized)
-    updateEntry(typeDocument.path, { sort: serialized })
-    clearListSortFromLocalStorage()
-  }, [typeDocument, sortPrefs, onUpdateTypeSort, updateEntry])
+    if (!typeDocument || !persistence) return
+    migrateListSortToType(typeDocument, sortPrefs, migrationDoneRef.current, persistence)
+  }, [typeDocument, sortPrefs, persistence])
 
   const handleSortChange = useCallback((groupLabel: string, option: SortOption, direction: SortDirection) => {
-    if (groupLabel === '__list__' && typeDocument && onUpdateTypeSort && updateEntry) {
-      // Persist sort to type file frontmatter
-      const config: SortConfig = { option, direction }
-      const serialized = serializeSortConfig(config)
-      onUpdateTypeSort(typeDocument.path, 'sort', serialized)
-      updateEntry(typeDocument.path, { sort: serialized })
-      // Clear old localStorage __list__ entry if present (migration cleanup)
-      clearListSortFromLocalStorage()
+    if (groupLabel === '__list__' && typeDocument && persistence) {
+      persistSortToType(typeDocument.path, { option, direction }, persistence)
     } else {
-      // Relationship group sorts still use localStorage
-      setSortPrefs((prev) => { const next = { ...prev, [groupLabel]: { option, direction } }; saveSortPreferences(next); return next })
+      saveGroupSort(groupLabel, option, direction, setSortPrefs)
     }
-  }, [typeDocument, onUpdateTypeSort, updateEntry])
+  }, [typeDocument, persistence])
 
-  const toggleGroup = useCallback((label: string) => {
-    setCollapsedGroups((prev) => toggleSetMember(prev, label))
-  }, [])
-
-  const typeEntryMap = useTypeEntryMap(entries)
-  const query = search.trim().toLowerCase()
-
-  // Compute custom properties and derive effective sort before sorting entries
   const filteredEntries = useFilteredEntries(entries, selection, modifiedPathSet, modifiedSuffixes)
   const customProperties = useMemo(() => extractSortableProperties(filteredEntries), [filteredEntries])
-  const listSort = useMemo<SortOption>(() => {
-    const opt = listConfig.option
-    if (!opt.startsWith('property:')) return opt
-    return customProperties.includes(opt.slice('property:'.length)) ? opt : 'modified'
-  }, [listConfig.option, customProperties])
+  const listSort = useMemo<SortOption>(() => deriveEffectiveSort(listConfig.option, customProperties), [listConfig.option, customProperties])
   const listDirection = listSort === listConfig.option ? listConfig.direction : 'desc'
-  const { isEntityView, isTrashView, searched, searchedGroups, expiredTrashCount } = useNoteListData({ entries, selection, allContent, query, listSort, listDirection, modifiedPathSet, modifiedSuffixes })
-  const isChangesView = selection.kind === 'filter' && selection.filter === 'changes'
 
-  const noteListKeyboard = useNoteListKeyboard({
-    items: searched,
-    selectedNotePath: selectedNote?.path ?? null,
-    onOpen: onReplaceActiveTab,
-    enabled: !isEntityView,
-  })
+  return { listSort, listDirection, customProperties, handleSortChange, sortPrefs, typeDocument }
+}
 
-  const multiSelect = useMultiSelect(searched, selectedNote?.path ?? null)
+function useNoteListSearch() {
+  const [search, setSearch] = useState('')
+  const [searchVisible, setSearchVisible] = useState(false)
+  const query = search.trim().toLowerCase()
 
-  // Clear multi-select when sidebar selection changes
-  useEffect(() => { multiSelect.clear() }, [selection]) // eslint-disable-line react-hooks/exhaustive-deps -- clear on selection change only
+  const toggleSearch = useCallback(() => {
+    setSearchVisible((v) => { if (v) setSearch(''); return !v })
+  }, [])
 
-  const handleClickNote = useCallback((entry: VaultEntry, e: React.MouseEvent) => {
-    routeNoteClick(entry, e, onReplaceActiveTab, onSelectNote, multiSelect)
-  }, [onReplaceActiveTab, onSelectNote, multiSelect])
+  return { search, setSearch, query, searchVisible, toggleSearch }
+}
 
-  const handleBulkArchive = useCallback(() => {
-    const paths = [...multiSelect.selectedPaths]
-    multiSelect.clear()
-    onBulkArchive?.(paths)
-  }, [multiSelect, onBulkArchive])
+function isInputFocused(): boolean {
+  const el = document.activeElement
+  return el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || !!(el as HTMLElement)?.isContentEditable
+}
 
-  const handleBulkTrash = useCallback(() => {
-    const paths = [...multiSelect.selectedPaths]
-    multiSelect.clear()
-    onBulkTrash?.(paths)
-  }, [multiSelect, onBulkTrash])
+function handleEscapeKey(e: KeyboardEvent, multiSelect: MultiSelectState) {
+  if (e.key !== 'Escape' || !multiSelect.isMultiSelecting) return
+  e.preventDefault()
+  multiSelect.clear()
+}
 
-  // Keyboard: Escape to clear, Cmd+A to select all, Cmd+E/Cmd+Delete for bulk actions
-  // Uses capture phase so bulk shortcuts preempt the global single-note handler
+function handleSelectAllKey(e: KeyboardEvent, multiSelect: MultiSelectState, isEntityView: boolean) {
+  if (e.key !== 'a' || !(e.metaKey || e.ctrlKey) || isEntityView || isInputFocused()) return
+  e.preventDefault()
+  multiSelect.selectAll()
+}
+
+function handleBulkActionKey(e: KeyboardEvent, multiSelect: MultiSelectState, onArchive: () => void, onTrash: () => void) {
+  if (!multiSelect.isMultiSelecting || !(e.metaKey || e.ctrlKey)) return
+  if (e.key === 'e') { e.preventDefault(); e.stopPropagation(); onArchive() }
+  if (e.key === 'Backspace' || e.key === 'Delete') { e.preventDefault(); e.stopPropagation(); onTrash() }
+}
+
+function useMultiSelectKeyboard(multiSelect: MultiSelectState, isEntityView: boolean, onBulkArchive: () => void, onBulkTrash: () => void) {
   useEffect(() => {
     function handleKeyDown(e: KeyboardEvent) {
-      if (e.key === 'Escape' && multiSelect.isMultiSelecting) {
-        e.preventDefault()
-        multiSelect.clear()
-      }
-      if (e.key === 'a' && (e.metaKey || e.ctrlKey) && !isEntityView) {
-        const active = document.activeElement
-        const isInput = active instanceof HTMLInputElement || active instanceof HTMLTextAreaElement || (active as HTMLElement)?.isContentEditable
-        if (!isInput) {
-          e.preventDefault()
-          multiSelect.selectAll()
-        }
-      }
-      if (multiSelect.isMultiSelecting && (e.metaKey || e.ctrlKey)) {
-        if (e.key === 'e') {
-          e.preventDefault()
-          e.stopPropagation()
-          handleBulkArchive()
-        } else if (e.key === 'Backspace' || e.key === 'Delete') {
-          e.preventDefault()
-          e.stopPropagation()
-          handleBulkTrash()
-        }
-      }
+      handleEscapeKey(e, multiSelect)
+      handleSelectAllKey(e, multiSelect, isEntityView)
+      handleBulkActionKey(e, multiSelect, onBulkArchive, onBulkTrash)
     }
     window.addEventListener('keydown', handleKeyDown, true)
     return () => window.removeEventListener('keydown', handleKeyDown, true)
-  }, [multiSelect, isEntityView, handleBulkArchive, handleBulkTrash])
+  }, [multiSelect, isEntityView, onBulkArchive, onBulkTrash])
+}
 
-  const renderItem = useCallback((entry: VaultEntry) => (
-    <NoteItem key={entry.path} entry={entry} isSelected={selectedNote?.path === entry.path} isMultiSelected={multiSelect.selectedPaths.has(entry.path)} isHighlighted={entry.path === noteListKeyboard.highlightedPath} noteStatus={resolvedGetNoteStatus(entry.path)} typeEntryMap={typeEntryMap} onClickNote={handleClickNote} />
-  ), [selectedNote?.path, handleClickNote, typeEntryMap, resolvedGetNoteStatus, multiSelect.selectedPaths, noteListKeyboard.highlightedPath])
+// --- Header component ---
 
+function NoteListHeader({ title, typeDocument, isEntityView, listSort, listDirection, customProperties, sidebarCollapsed, searchVisible, search, onSortChange, onCreateNote, onOpenType, onToggleSearch, onSearchChange }: {
+  title: string
+  typeDocument: VaultEntry | null
+  isEntityView: boolean
+  listSort: SortOption
+  listDirection: SortDirection
+  customProperties: string[]
+  sidebarCollapsed?: boolean
+  searchVisible: boolean
+  search: string
+  onSortChange: (groupLabel: string, option: SortOption, direction: SortDirection) => void
+  onCreateNote: () => void
+  onOpenType: (entry: VaultEntry) => void
+  onToggleSearch: () => void
+  onSearchChange: (value: string) => void
+}) {
+  const { onMouseDown: onDragMouseDown } = useDragRegion()
   return (
-    <div className="flex flex-col select-none overflow-hidden border-r border-border bg-card text-foreground" style={{ height: '100%' }}>
+    <>
       <div className="flex h-[52px] shrink-0 items-center justify-between border-b border-border px-4" onMouseDown={onDragMouseDown} style={{ cursor: 'default', paddingLeft: sidebarCollapsed ? 80 : undefined }}>
         <h3
           className="m-0 min-w-0 flex-1 truncate text-[14px] font-semibold"
           style={typeDocument ? { cursor: 'pointer' } : undefined}
-          onClick={typeDocument ? () => onReplaceActiveTab(typeDocument) : undefined}
+          onClick={typeDocument ? () => onOpenType(typeDocument) : undefined}
           data-testid={typeDocument ? 'type-header-link' : undefined}
         >
-          {resolveHeaderTitle(selection, typeDocument)}
+          {title}
         </h3>
         <div className="flex items-center gap-3" style={{ WebkitAppRegion: 'no-drag' } as React.CSSProperties}>
-          {!isEntityView && <SortDropdown groupLabel="__list__" current={listSort} direction={listDirection} customProperties={customProperties} onChange={handleSortChange} />}
-          <button className="flex items-center text-muted-foreground transition-colors hover:text-foreground" onClick={() => { setSearchVisible(!searchVisible); if (searchVisible) setSearch('') }} title="Search notes">
+          {!isEntityView && <SortDropdown groupLabel="__list__" current={listSort} direction={listDirection} customProperties={customProperties} onChange={onSortChange} />}
+          <button className="flex items-center text-muted-foreground transition-colors hover:text-foreground" onClick={onToggleSearch} title="Search notes">
             <MagnifyingGlass size={16} />
           </button>
           <button className="flex items-center text-muted-foreground transition-colors hover:text-foreground" onClick={() => onCreateNote()} title="Create new note">
@@ -463,21 +461,69 @@ function NoteListInner({ entries, selection, selectedNote, allContent, modifiedF
           </button>
         </div>
       </div>
-
       {searchVisible && (
         <div className="border-b border-border px-3 py-2">
-          <Input placeholder="Search notes..." value={search} onChange={(e) => setSearch(e.target.value)} className="h-8 text-[13px]" autoFocus />
+          <Input placeholder="Search notes..." value={search} onChange={(e) => onSearchChange(e.target.value)} className="h-8 text-[13px]" autoFocus />
         </div>
       )}
+    </>
+  )
+}
 
+// --- Main component ---
+
+const defaultGetNoteStatus = (): NoteStatus => 'clean'
+
+function useModifiedFilesState(modifiedFiles: ModifiedFile[] | undefined, getNoteStatus: ((path: string) => NoteStatus) | undefined) {
+  const modifiedPathSet = useMemo(() => new Set((modifiedFiles ?? []).map((f) => f.path)), [modifiedFiles])
+  const modifiedSuffixes = useMemo(() => (modifiedFiles ?? []).map((f) => '/' + f.relativePath), [modifiedFiles])
+  const resolvedGetNoteStatus = useMemo<(path: string) => NoteStatus>(
+    () => createNoteStatusResolver(getNoteStatus, modifiedFiles, modifiedPathSet),
+    [getNoteStatus, modifiedFiles, modifiedPathSet],
+  )
+  return { modifiedPathSet, modifiedSuffixes, resolvedGetNoteStatus }
+}
+
+function NoteListInner({ entries, selection, selectedNote, allContent, modifiedFiles, modifiedFilesError, getNoteStatus, sidebarCollapsed, onSelectNote, onReplaceActiveTab, onCreateNote, onBulkArchive, onBulkTrash, onUpdateTypeSort, updateEntry }: NoteListProps) {
+  const { modifiedPathSet, modifiedSuffixes, resolvedGetNoteStatus } = useModifiedFilesState(modifiedFiles, getNoteStatus)
+  const { listSort, listDirection, customProperties, handleSortChange, sortPrefs, typeDocument } = useNoteListSort({ entries, selection, modifiedPathSet, modifiedSuffixes, onUpdateTypeSort, updateEntry })
+  const { search, setSearch, query, searchVisible, toggleSearch } = useNoteListSearch()
+  const [collapsedGroups, setCollapsedGroups] = useState<Set<string>>(new Set())
+
+  const typeEntryMap = useTypeEntryMap(entries)
+  const { isEntityView, isTrashView, searched, searchedGroups, expiredTrashCount } = useNoteListData({ entries, selection, allContent, query, listSort, listDirection, modifiedPathSet, modifiedSuffixes })
+  const isChangesView = selection.kind === 'filter' && selection.filter === 'changes'
+  const entitySelection = isEntityView && selection.kind === 'entity' ? selection : null
+
+  const noteListKeyboard = useNoteListKeyboard({ items: searched, selectedNotePath: selectedNote?.path ?? null, onOpen: onReplaceActiveTab, enabled: !isEntityView })
+  const multiSelect = useMultiSelect(searched, selectedNote?.path ?? null)
+  useEffect(() => { multiSelect.clear() }, [selection]) // eslint-disable-line react-hooks/exhaustive-deps -- clear on selection change only
+
+  const handleClickNote = useCallback((entry: VaultEntry, e: React.MouseEvent) => {
+    routeNoteClick(entry, e, { onReplace: onReplaceActiveTab, onSelect: onSelectNote, multiSelect })
+  }, [onReplaceActiveTab, onSelectNote, multiSelect])
+
+  const handleBulkArchive = useCallback(() => { const paths = [...multiSelect.selectedPaths]; multiSelect.clear(); onBulkArchive?.(paths) }, [multiSelect, onBulkArchive])
+  const handleBulkTrash = useCallback(() => { const paths = [...multiSelect.selectedPaths]; multiSelect.clear(); onBulkTrash?.(paths) }, [multiSelect, onBulkTrash])
+  useMultiSelectKeyboard(multiSelect, isEntityView, handleBulkArchive, handleBulkTrash)
+
+  const renderItem = useCallback((entry: VaultEntry) => (
+    <NoteItem key={entry.path} entry={entry} isSelected={selectedNote?.path === entry.path} isMultiSelected={multiSelect.selectedPaths.has(entry.path)} isHighlighted={entry.path === noteListKeyboard.highlightedPath} noteStatus={resolvedGetNoteStatus(entry.path)} typeEntryMap={typeEntryMap} onClickNote={handleClickNote} />
+  ), [selectedNote?.path, handleClickNote, typeEntryMap, resolvedGetNoteStatus, multiSelect.selectedPaths, noteListKeyboard.highlightedPath])
+
+  const toggleGroup = useCallback((label: string) => { setCollapsedGroups((prev) => toggleSetMember(prev, label)) }, [])
+  const title = resolveHeaderTitle(selection, typeDocument)
+
+  return (
+    <div className="flex flex-col select-none overflow-hidden border-r border-border bg-card text-foreground" style={{ height: '100%' }}>
+      <NoteListHeader title={title} typeDocument={typeDocument} isEntityView={isEntityView} listSort={listSort} listDirection={listDirection} customProperties={customProperties} sidebarCollapsed={sidebarCollapsed} searchVisible={searchVisible} search={search} onSortChange={handleSortChange} onCreateNote={onCreateNote} onOpenType={onReplaceActiveTab} onToggleSearch={toggleSearch} onSearchChange={setSearch} />
       <div className="flex-1 overflow-hidden outline-none" style={{ minHeight: 0 }} tabIndex={0} onKeyDown={noteListKeyboard.handleKeyDown} onFocus={noteListKeyboard.handleFocus} data-testid="note-list-container">
-        {isEntityView && selection.kind === 'entity' ? (
-          <EntityView entity={selection.entry} groups={searchedGroups} query={query} collapsedGroups={collapsedGroups} sortPrefs={sortPrefs} onToggleGroup={toggleGroup} onSortChange={handleSortChange} renderItem={renderItem} typeEntryMap={typeEntryMap} onClickNote={handleClickNote} />
+        {entitySelection ? (
+          <EntityView entity={entitySelection.entry} groups={searchedGroups} query={query} collapsedGroups={collapsedGroups} sortPrefs={sortPrefs} onToggleGroup={toggleGroup} onSortChange={handleSortChange} renderItem={renderItem} typeEntryMap={typeEntryMap} onClickNote={handleClickNote} />
         ) : (
           <ListView isTrashView={isTrashView} isChangesView={isChangesView} changesError={modifiedFilesError} expiredTrashCount={expiredTrashCount} searched={searched} query={query} renderItem={renderItem} virtuosoRef={noteListKeyboard.virtuosoRef} />
         )}
       </div>
-
       {multiSelect.isMultiSelecting && (
         <BulkActionBar count={multiSelect.selectedPaths.size} onArchive={handleBulkArchive} onTrash={handleBulkTrash} onClear={multiSelect.clear} />
       )}

src/components/PulseView.test.tsx

@@ -0,0 +1,240 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { PulseView } from './PulseView'
+import type { PulseCommit } from '../types'
+
+const mockCommits: PulseCommit[] = [
+  {
+    hash: 'abc123def456',
+    shortHash: 'abc123d',
+    message: 'Update project notes',
+    date: Math.floor(Date.now() / 1000) - 3600,
+    githubUrl: 'https://github.com/owner/repo/commit/abc123def456',
+    files: [
+      { path: 'project/my-project.md', status: 'modified', title: 'my project' },
+      { path: 'note/new-note.md', status: 'added', title: 'new note' },
+    ],
+    added: 1,
+    modified: 1,
+    deleted: 0,
+  },
+  {
+    hash: 'def456abc789',
+    shortHash: 'def456a',
+    message: 'Remove old notes',
+    date: Math.floor(Date.now() / 1000) - 86400,
+    githubUrl: null,
+    files: [
+      { path: 'note/old.md', status: 'deleted', title: 'old' },
+    ],
+    added: 0,
+    modified: 0,
+    deleted: 1,
+  },
+]
+
+const mockInvokeFn = vi.fn()
+vi.mock('@tauri-apps/api/core', () => ({
+  invoke: (...args: unknown[]) => mockInvokeFn(...args),
+}))
+vi.mock('../mock-tauri', () => ({
+  isTauri: () => false,
+  mockInvoke: (...args: unknown[]) => mockInvokeFn(...args),
+}))
+
+describe('PulseView', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('shows loading state initially', () => {
+    mockInvokeFn.mockReturnValue(new Promise(() => {})) // never resolves
+    render(<PulseView vaultPath="/test/vault" />)
+    expect(screen.getByText('Loading activity…')).toBeInTheDocument()
+  })
+
+  it('renders commits grouped by day', async () => {
+    mockInvokeFn.mockResolvedValue(mockCommits)
+
+    render(<PulseView vaultPath="/test/vault" />)
+
+    await waitFor(() => {
+      expect(screen.getByText('Update project notes')).toBeInTheDocument()
+    })
+
+    expect(screen.getByText('Remove old notes')).toBeInTheDocument()
+  })
+
+  it('shows summary badges for added/modified/deleted', async () => {
+    mockInvokeFn.mockResolvedValue(mockCommits)
+
+    render(<PulseView vaultPath="/test/vault" />)
+
+    await waitFor(() => {
+      expect(screen.getByText('+1')).toBeInTheDocument()
+    })
+    expect(screen.getByText('~1')).toBeInTheDocument()
+    expect(screen.getByText('-1')).toBeInTheDocument()
+  })
+
+  it('shows commit hashes', async () => {
+    mockInvokeFn.mockResolvedValue(mockCommits)
+
+    render(<PulseView vaultPath="/test/vault" />)
+
+    await waitFor(() => {
+      expect(screen.getByText('abc123d')).toBeInTheDocument()
+    })
+    expect(screen.getByText('def456a')).toBeInTheDocument()
+  })
+
+  it('renders GitHub links for commits with githubUrl', async () => {
+    mockInvokeFn.mockResolvedValue(mockCommits)
+
+    render(<PulseView vaultPath="/test/vault" />)
+
+    await waitFor(() => {
+      const link = screen.getByText('abc123d')
+      expect(link.tagName).toBe('A')
+      expect(link).toHaveAttribute('href', 'https://github.com/owner/repo/commit/abc123def456')
+    })
+
+    // Non-GitHub commit should be a span
+    const nonLink = screen.getByText('def456a')
+    expect(nonLink.tagName).toBe('SPAN')
+  })
+
+  it('renders file list with correct titles when expanded', async () => {
+    mockInvokeFn.mockResolvedValue(mockCommits)
+
+    render(<PulseView vaultPath="/test/vault" />)
+
+    // Files are collapsed by default — expand all commit cards first
+    await waitFor(() => {
+      expect(screen.getAllByLabelText('Expand files').length).toBeGreaterThan(0)
+    })
+    screen.getAllByLabelText('Expand files').forEach((btn) => fireEvent.click(btn))
+
+    await waitFor(() => {
+      expect(screen.getByText('my project')).toBeInTheDocument()
+    })
+    expect(screen.getByText('new note')).toBeInTheDocument()
+    expect(screen.getByText('old')).toBeInTheDocument()
+  })
+
+  it('calls onOpenNote when clicking a non-deleted file', async () => {
+    mockInvokeFn.mockResolvedValue(mockCommits)
+    const onOpenNote = vi.fn()
+
+    render(<PulseView vaultPath="/test/vault" onOpenNote={onOpenNote} />)
+
+    // Expand first commit card
+    await waitFor(() => {
+      expect(screen.getAllByLabelText('Expand files').length).toBeGreaterThan(0)
+    })
+    fireEvent.click(screen.getAllByLabelText('Expand files')[0])
+
+    await waitFor(() => {
+      expect(screen.getByText('my project')).toBeInTheDocument()
+    })
+
+    fireEvent.click(screen.getByText('my project'))
+    expect(onOpenNote).toHaveBeenCalledWith('project/my-project.md')
+  })
+
+  it('does not call onOpenNote when clicking a deleted file', async () => {
+    mockInvokeFn.mockResolvedValue(mockCommits)
+    const onOpenNote = vi.fn()
+
+    render(<PulseView vaultPath="/test/vault" onOpenNote={onOpenNote} />)
+
+    // Expand all commit cards to find the deleted file
+    await waitFor(() => {
+      expect(screen.getAllByLabelText('Expand files').length).toBeGreaterThan(0)
+    })
+    screen.getAllByLabelText('Expand files').forEach((btn) => fireEvent.click(btn))
+
+    await waitFor(() => {
+      expect(screen.getByText('old')).toBeInTheDocument()
+    })
+
+    fireEvent.click(screen.getByText('old'))
+    expect(onOpenNote).not.toHaveBeenCalled()
+  })
+
+  it('shows empty state when no commits', async () => {
+    mockInvokeFn.mockResolvedValue([])
+
+    render(<PulseView vaultPath="/test/vault" />)
+
+    await waitFor(() => {
+      expect(screen.getByText('No activity yet')).toBeInTheDocument()
+    })
+  })
+
+  it('shows error state and retry button', async () => {
+    mockInvokeFn.mockRejectedValue('Not a git repository')
+
+    render(<PulseView vaultPath="/test/vault" />)
+
+    await waitFor(() => {
+      expect(screen.getByText('Not a git repository')).toBeInTheDocument()
+    })
+    expect(screen.getByText('Retry')).toBeInTheDocument()
+  })
+
+  it('calls get_vault_pulse with skip=0 on initial load and passes correct page size', async () => {
+    mockInvokeFn.mockResolvedValue([])
+
+    render(<PulseView vaultPath="/test/vault" />)
+
+    await waitFor(() => {
+      expect(mockInvokeFn).toHaveBeenCalledWith('get_vault_pulse', { vaultPath: '/test/vault', limit: 20, skip: 0 })
+    })
+  })
+
+  it('calls get_vault_pulse with correct arguments', async () => {
+    mockInvokeFn.mockResolvedValue([])
+
+    render(<PulseView vaultPath="/my/vault" />)
+
+    await waitFor(() => {
+      expect(mockInvokeFn).toHaveBeenCalledWith('get_vault_pulse', { vaultPath: '/my/vault', limit: 20, skip: 0 })
+    })
+  })
+
+  it('toggles file list visibility when clicking expand/collapse button', async () => {
+    mockInvokeFn.mockResolvedValue(mockCommits)
+
+    render(<PulseView vaultPath="/test/vault" />)
+
+    // Files are collapsed by default
+    await waitFor(() => {
+      expect(screen.getAllByLabelText('Expand files').length).toBeGreaterThan(0)
+    })
+    expect(screen.queryByText('my project')).not.toBeInTheDocument()
+
+    // Click expand on first commit card
+    fireEvent.click(screen.getAllByLabelText('Expand files')[0])
+
+    // Files should now be visible
+    await waitFor(() => {
+      expect(screen.getByText('my project')).toBeInTheDocument()
+    })
+
+    // Click collapse to hide again
+    fireEvent.click(screen.getAllByLabelText('Collapse files')[0])
+
+    expect(screen.queryByText('my project')).not.toBeInTheDocument()
+  })
+
+  it('renders Pulse header', async () => {
+    mockInvokeFn.mockResolvedValue([])
+
+    render(<PulseView vaultPath="/test/vault" />)
+
+    await waitFor(() => {
+      expect(screen.getByText('Pulse')).toBeInTheDocument()
+    })
+  })
+})

src/components/PulseView.tsx

@@ -0,0 +1,325 @@
+import { useState, useEffect, useCallback, useRef, memo } from 'react'
+import { invoke } from '@tauri-apps/api/core'
+import { isTauri, mockInvoke } from '../mock-tauri'
+import type { PulseCommit, PulseFile } from '../types'
+import { relativeDate } from '../utils/noteListHelpers'
+import {
+  Plus, Minus, PencilSimple, GitCommit, ArrowSquareOut,
+  FileText, CaretDown, CaretRight, Pulse,
+} from '@phosphor-icons/react'
+
+function tauriCall<T>(command: string, args: Record<string, unknown>): Promise<T> {
+  return isTauri() ? invoke<T>(command, args) : mockInvoke<T>(command, args)
+}
+
+interface PulseViewProps {
+  vaultPath: string
+  onOpenNote?: (relativePath: string) => void
+  sidebarCollapsed?: boolean
+  onExpandSidebar?: () => void
+}
+
+function groupCommitsByDay(commits: PulseCommit[]): Map<string, PulseCommit[]> {
+  const groups = new Map<string, PulseCommit[]>()
+  for (const commit of commits) {
+    const date = new Date(commit.date * 1000)
+    const key = date.toLocaleDateString('en-US', { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' })
+    const existing = groups.get(key)
+    if (existing) {
+      existing.push(commit)
+    } else {
+      groups.set(key, [commit])
+    }
+  }
+  return groups
+}
+
+function isToday(dateKey: string): boolean {
+  const today = new Date().toLocaleDateString('en-US', { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' })
+  return dateKey === today
+}
+
+function isYesterday(dateKey: string): boolean {
+  const yesterday = new Date(Date.now() - 86400000)
+    .toLocaleDateString('en-US', { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' })
+  return dateKey === yesterday
+}
+
+function formatDayLabel(dateKey: string): string {
+  if (isToday(dateKey)) return 'Today'
+  if (isYesterday(dateKey)) return 'Yesterday'
+  return dateKey
+}
+
+const STATUS_ICON = {
+  added: Plus,
+  modified: PencilSimple,
+  deleted: Minus,
+} as const
+
+const STATUS_COLOR = {
+  added: 'var(--accent-green, #16a34a)',
+  modified: 'var(--accent-orange, #ea580c)',
+  deleted: 'var(--destructive, #dc2626)',
+} as const
+
+function SummaryBadges({ added, modified, deleted }: { added: number; modified: number; deleted: number }) {
+  return (
+    <div className="flex items-center" style={{ gap: 8 }}>
+      {added > 0 && <span className="text-[11px] font-medium" style={{ color: STATUS_COLOR.added }}>+{added}</span>}
+      {modified > 0 && <span className="text-[11px] font-medium" style={{ color: STATUS_COLOR.modified }}>~{modified}</span>}
+      {deleted > 0 && <span className="text-[11px] font-medium" style={{ color: STATUS_COLOR.deleted }}>-{deleted}</span>}
+    </div>
+  )
+}
+
+function FileItem({ file, onOpenNote }: { file: PulseFile; onOpenNote?: (path: string) => void }) {
+  const Icon = STATUS_ICON[file.status] ?? FileText
+  const color = STATUS_COLOR[file.status] ?? 'var(--muted-foreground)'
+  const isDeleted = file.status === 'deleted'
+
+  return (
+    <div
+      className={`flex items-center rounded transition-colors ${isDeleted ? '' : 'cursor-pointer hover:bg-accent'}`}
+      style={{ gap: 6, padding: '3px 8px' }}
+      onClick={isDeleted ? undefined : () => onOpenNote?.(file.path)}
+      title={file.path}
+    >
+      <Icon size={12} style={{ color, flexShrink: 0 }} weight="bold" />
+      <span
+        className={`truncate text-[12px] ${isDeleted ? 'text-muted-foreground line-through' : 'text-foreground'}`}
+      >
+        {file.title}
+      </span>
+    </div>
+  )
+}
+
+function CommitCard({ commit, onOpenNote }: { commit: PulseCommit; onOpenNote?: (path: string) => void }) {
+  const [expanded, setExpanded] = useState(false)
+  const Chevron = expanded ? CaretDown : CaretRight
+
+  return (
+    <div className="border-b border-border" style={{ padding: '10px 16px' }}>
+      <div className="flex items-start justify-between" style={{ gap: 8 }}>
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center" style={{ gap: 6, marginBottom: 2 }}>
+            <GitCommit size={13} className="text-muted-foreground" style={{ flexShrink: 0 }} />
+            <span className="truncate text-[13px] font-medium text-foreground">{commit.message}</span>
+          </div>
+          <div className="flex items-center" style={{ gap: 8 }}>
+            <span className="text-[11px] text-muted-foreground">{relativeDate(commit.date)}</span>
+            {commit.githubUrl ? (
+              <a
+                className="flex items-center text-[11px] font-mono text-primary no-underline hover:underline"
+                style={{ gap: 3 }}
+                href={commit.githubUrl}
+                onClick={(e) => {
+                  e.preventDefault()
+                  if (isTauri()) {
+                    import('@tauri-apps/plugin-opener').then((mod) => mod.openUrl(commit.githubUrl!))
+                  } else {
+                    window.open(commit.githubUrl!, '_blank')
+                  }
+                }}
+                title="Open on GitHub"
+              >
+                {commit.shortHash}
+                <ArrowSquareOut size={10} />
+              </a>
+            ) : (
+              <span className="text-[11px] font-mono text-muted-foreground">{commit.shortHash}</span>
+            )}
+            <SummaryBadges added={commit.added} modified={commit.modified} deleted={commit.deleted} />
+          </div>
+        </div>
+        <button
+          className="flex shrink-0 cursor-pointer items-center justify-center rounded border-none bg-transparent p-0 text-muted-foreground hover:text-foreground"
+          style={{ width: 20, height: 20 }}
+          onClick={() => setExpanded((v) => !v)}
+          aria-label={expanded ? 'Collapse files' : 'Expand files'}
+        >
+          <Chevron size={12} />
+        </button>
+      </div>
+      {expanded && commit.files.length > 0 && (
+        <div style={{ marginTop: 6, marginLeft: 4 }}>
+          {commit.files.map((file) => (
+            <FileItem key={file.path} file={file} onOpenNote={onOpenNote} />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+function DayGroup({ label, commits, onOpenNote }: {
+  label: string; commits: PulseCommit[]; onOpenNote?: (path: string) => void
+}) {
+  const [collapsed, setCollapsed] = useState(false)
+  const Chevron = collapsed ? CaretRight : CaretDown
+
+  return (
+    <div>
+      <div
+        className="flex cursor-pointer select-none items-center border-b border-border bg-muted/50 transition-colors hover:bg-muted"
+        style={{ padding: '6px 16px', gap: 6 }}
+        onClick={() => setCollapsed((v) => !v)}
+      >
+        <Chevron size={12} className="text-muted-foreground" />
+        <span className="text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">
+          {label}
+        </span>
+        <span className="text-[11px] text-muted-foreground">
+          ({commits.length} {commits.length === 1 ? 'commit' : 'commits'})
+        </span>
+      </div>
+      {!collapsed && commits.map((commit) => (
+        <CommitCard key={commit.hash} commit={commit} onOpenNote={onOpenNote} />
+      ))}
+    </div>
+  )
+}
+
+function EmptyState() {
+  return (
+    <div className="flex flex-1 flex-col items-center justify-center text-muted-foreground" style={{ padding: 32 }}>
+      <Pulse size={32} style={{ marginBottom: 8, opacity: 0.5 }} />
+      <p className="text-[13px]">No activity yet</p>
+      <p className="text-[12px]" style={{ marginTop: 4 }}>
+        Commit changes to see your vault's pulse
+      </p>
+    </div>
+  )
+}
+
+function ErrorState({ message, onRetry }: { message: string; onRetry: () => void }) {
+  return (
+    <div className="flex flex-1 flex-col items-center justify-center text-muted-foreground" style={{ padding: 32 }}>
+      <p className="text-[13px]">{message}</p>
+      <button
+        className="mt-2 cursor-pointer rounded border border-border bg-transparent px-3 py-1 text-[12px] text-foreground transition-colors hover:bg-accent"
+        onClick={onRetry}
+      >
+        Retry
+      </button>
+    </div>
+  )
+}
+
+const PAGE_SIZE = 20
+
+export const PulseView = memo(function PulseView({ vaultPath, onOpenNote, sidebarCollapsed, onExpandSidebar }: PulseViewProps) {
+  const [commits, setCommits] = useState<PulseCommit[]>([])
+  const [loading, setLoading] = useState(true)
+  const [loadingMore, setLoadingMore] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [hasMore, setHasMore] = useState(true)
+  const [skip, setSkip] = useState(0)
+  const sentinelRef = useRef<HTMLDivElement | null>(null)
+
+  // Initial load
+  const loadInitial = useCallback(async () => {
+    setLoading(true)
+    setError(null)
+    setCommits([])
+    setSkip(0)
+    setHasMore(true)
+    try {
+      const result = await tauriCall<PulseCommit[]>('get_vault_pulse', { vaultPath, limit: PAGE_SIZE, skip: 0 })
+      setCommits(result)
+      setHasMore(result.length >= PAGE_SIZE)
+      setSkip(result.length)
+    } catch (err) {
+      const msg = typeof err === 'string' ? err : 'Failed to load activity'
+      setError(msg)
+    } finally {
+      setLoading(false)
+    }
+  }, [vaultPath])
+
+  // Append next page
+  const loadMore = useCallback(async () => {
+    if (loadingMore || !hasMore) return
+    setLoadingMore(true)
+    try {
+      const result = await tauriCall<PulseCommit[]>('get_vault_pulse', { vaultPath, limit: PAGE_SIZE, skip })
+      setCommits((prev) => [...prev, ...result])
+      setHasMore(result.length >= PAGE_SIZE)
+      setSkip((s) => s + result.length)
+    } catch {
+      // silently fail for pagination — user can scroll up/retry
+    } finally {
+      setLoadingMore(false)
+    }
+  }, [vaultPath, skip, loadingMore, hasMore])
+
+  useEffect(() => { loadInitial() }, [loadInitial])
+
+  // Intersection Observer for infinite scroll
+  useEffect(() => {
+    const sentinel = sentinelRef.current
+    if (!sentinel) return
+    const observer = new IntersectionObserver(
+      (entries) => { if (entries[0].isIntersecting) loadMore() },
+      { threshold: 0.1 },
+    )
+    observer.observe(sentinel)
+    return () => observer.disconnect()
+  }, [loadMore])
+
+  const dayGroups = groupCommitsByDay(commits)
+
+  return (
+    <div className="flex h-full flex-col overflow-hidden border-r border-[var(--sidebar-border)] bg-background">
+      {/* Header */}
+      <div className="flex shrink-0 items-center justify-between border-b border-border" style={{ height: 52, padding: '0 16px' }}>
+        <div className="flex items-center" style={{ gap: 8 }}>
+          {sidebarCollapsed && onExpandSidebar && (
+            <button
+              className="flex shrink-0 cursor-pointer items-center justify-center rounded border-none bg-transparent p-0 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
+              style={{ width: 24, height: 24 }}
+              onClick={onExpandSidebar}
+              aria-label="Expand sidebar"
+            >
+              <CaretRight size={14} weight="bold" />
+            </button>
+          )}
+          <Pulse size={16} className="text-primary" />
+          <span className="text-[14px] font-semibold text-foreground">Pulse</span>
+        </div>
+      </div>
+
+      {/* Feed */}
+      <div className="flex-1 overflow-y-auto">
+        {loading ? (
+          <div className="flex items-center justify-center" style={{ padding: 32 }}>
+            <span className="text-[13px] text-muted-foreground">Loading activity…</span>
+          </div>
+        ) : error ? (
+          <ErrorState message={error} onRetry={loadInitial} />
+        ) : commits.length === 0 ? (
+          <EmptyState />
+        ) : (
+          <>
+            {Array.from(dayGroups.entries()).map(([day, dayCommits]) => (
+              <DayGroup
+                key={day}
+                label={formatDayLabel(day)}
+                commits={dayCommits}
+                onOpenNote={onOpenNote}
+              />
+            ))}
+            {/* Sentinel for infinite scroll */}
+            <div ref={sentinelRef} style={{ height: 1 }} />
+            {loadingMore && (
+              <div className="flex items-center justify-center" style={{ padding: 12 }}>
+                <span className="text-[12px] text-muted-foreground">Loading…</span>
+              </div>
+            )}
+          </>
+        )}
+      </div>
+    </div>
+  )
+})

src/components/SettingsPanel.tsx

@@ -1,6 +1,7 @@
 import { useState, useRef, useCallback, useEffect } from 'react'
 import { X, Eye, EyeSlash, GithubLogo, SignOut, Check, Plus } from '@phosphor-icons/react'
 import { GitHubDeviceFlow } from './GitHubDeviceFlow'
+import { ThemePropertyEditor } from './ThemePropertyEditor'
 import type { Settings, ThemeFile } from '../types'
 import type { ThemeManager } from '../hooks/useThemeManager'
 
@@ -356,6 +357,13 @@ function AppearanceSection({ themeManager }: { themeManager: ThemeManager }) {
         <Plus size={14} />
         New Theme
       </button>
+
+      {activeThemeId && (
+        <>
+          <div style={{ height: 1, background: 'var(--border)', margin: '4px 0' }} />
+          <ThemePropertyEditor themeManager={themeManager} />
+        </>
+      )}
     </>
   )
 }

src/components/Sidebar.test.tsx

@@ -1,20 +1,8 @@
 import { render, screen, fireEvent } from '@testing-library/react'
-import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { describe, it, expect, vi } from 'vitest'
 import { Sidebar } from './Sidebar'
 import type { VaultEntry, SidebarSelection } from '../types'
 
-// Mock localStorage for section visibility tests
-const localStorageMock = (() => {
-  let store: Record<string, string> = {}
-  return {
-    getItem: (key: string) => store[key] ?? null,
-    setItem: (key: string, value: string) => { store[key] = value },
-    removeItem: (key: string) => { delete store[key] },
-    clear: () => { store = {} },
-  }
-})()
-Object.defineProperty(globalThis, 'localStorage', { value: localStorageMock, writable: true })
-
 const mockEntries: VaultEntry[] = [
   {
     path: '/vault/project/build-app.md',
@@ -245,10 +233,10 @@ const mockEntries: VaultEntry[] = [
 const defaultSelection: SidebarSelection = { kind: 'filter', filter: 'all' }
 
 describe('Sidebar', () => {
-  it('renders top nav items (All Notes and Favorites)', () => {
+  it('renders top nav items (All Notes)', () => {
     render(<Sidebar entries={[]} selection={defaultSelection} onSelect={() => {}} />)
     expect(screen.getByText('All Notes')).toBeInTheDocument()
-    expect(screen.getByText('Favorites')).toBeInTheDocument()
+    expect(screen.queryByText('Favorites')).not.toBeInTheDocument()
   })
 
   it('renders section group headers only for types present in entries', () => {
@@ -687,9 +675,96 @@ describe('Sidebar', () => {
     })
   })
 
-  describe('customize section visibility', () => {
-    beforeEach(() => {
-      localStorageMock.clear()
+  describe('type visibility via visible property', () => {
+    const makeTypeEntry = (title: string, visible: boolean | null): VaultEntry => ({
+      path: `/vault/type/${title.toLowerCase()}.md`,
+      filename: `${title.toLowerCase()}.md`,
+      title,
+      isA: 'Type',
+      aliases: [],
+      belongsTo: [],
+      relatedTo: [],
+      status: null,
+      owner: null,
+      cadence: null,
+      archived: false,
+      trashed: false,
+      trashedAt: null,
+      modifiedAt: 1700000000,
+      createdAt: null,
+      fileSize: 200,
+      snippet: '',
+      wordCount: 0,
+      relationships: {},
+      icon: null,
+      color: null,
+      order: null,
+      sidebarLabel: null,
+      template: null,
+      sort: null,
+      view: null,
+      visible,
+      outgoingLinks: [],
+      properties: {},
+    })
+
+    it('hides a section when its Type entry has visible: false', () => {
+      const entries: VaultEntry[] = [
+        ...mockEntries,
+        makeTypeEntry('Person', false),
+      ]
+      render(<Sidebar entries={entries} selection={defaultSelection} onSelect={() => {}} />)
+      expect(screen.queryByText('People')).not.toBeInTheDocument()
+      // Other sections should still be visible
+      expect(screen.getByText('Projects')).toBeInTheDocument()
+    })
+
+    it('shows a section when its Type entry has visible: true', () => {
+      const entries: VaultEntry[] = [
+        ...mockEntries,
+        makeTypeEntry('Person', true),
+      ]
+      render(<Sidebar entries={entries} selection={defaultSelection} onSelect={() => {}} />)
+      expect(screen.getByText('People')).toBeInTheDocument()
+    })
+
+    it('shows a section when its Type entry has visible: null (default)', () => {
+      const entries: VaultEntry[] = [
+        ...mockEntries,
+        makeTypeEntry('Person', null),
+      ]
+      render(<Sidebar entries={entries} selection={defaultSelection} onSelect={() => {}} />)
+      expect(screen.getByText('People')).toBeInTheDocument()
+    })
+
+    it('shows a section when there is no Type entry at all (default visible)', () => {
+      // mockEntries has Person instances but no Type entry for Person
+      render(<Sidebar entries={mockEntries} selection={defaultSelection} onSelect={() => {}} />)
+      expect(screen.getByText('People')).toBeInTheDocument()
+    })
+
+    it('hides multiple sections when their Type entries have visible: false', () => {
+      const entries: VaultEntry[] = [
+        ...mockEntries,
+        makeTypeEntry('Person', false),
+        makeTypeEntry('Event', false),
+      ]
+      render(<Sidebar entries={entries} selection={defaultSelection} onSelect={() => {}} />)
+      expect(screen.queryByText('People')).not.toBeInTheDocument()
+      expect(screen.queryByText('Events')).not.toBeInTheDocument()
+      expect(screen.getByText('Projects')).toBeInTheDocument()
+      expect(screen.getByText('Topics')).toBeInTheDocument()
+    })
+
+    it('does not affect All Notes or other sidebar filters when sections are hidden', () => {
+      const entries: VaultEntry[] = [
+        ...mockEntries,
+        makeTypeEntry('Project', false),
+        makeTypeEntry('Person', false),
+      ]
+      render(<Sidebar entries={entries} selection={defaultSelection} onSelect={() => {}} />)
+      expect(screen.getByText('All Notes')).toBeInTheDocument()
+      expect(screen.queryByText('Favorites')).not.toBeInTheDocument()
     })
 
     it('renders a "Customize sections" button', () => {
@@ -706,66 +781,12 @@ describe('Sidebar', () => {
       expect(screen.getByLabelText('Toggle Topics')).toBeInTheDocument()
     })
 
-    it('hides a section when its toggle is clicked off', () => {
-      render(<Sidebar entries={mockEntries} selection={defaultSelection} onSelect={() => {}} />)
-      // People section header should be visible initially
-      expect(screen.getByText('People')).toBeInTheDocument()
-
-      // Open customize popover and toggle People off
+    it('calls onToggleTypeVisibility when toggling a section in the popover', () => {
+      const onToggleTypeVisibility = vi.fn()
+      render(<Sidebar entries={mockEntries} selection={defaultSelection} onSelect={() => {}} onToggleTypeVisibility={onToggleTypeVisibility} />)
       fireEvent.click(screen.getByTitle('Customize sections'))
       fireEvent.click(screen.getByLabelText('Toggle People'))
-
-      // People section header should be gone (use getAllByText to handle popover)
-      const peopleElements = screen.queryAllByText('People')
-      // Only the toggle label in the popover should remain, not the section header
-      expect(peopleElements.length).toBeLessThanOrEqual(1)
-    })
-
-    it('re-shows a section when its toggle is clicked on again', () => {
-      render(<Sidebar entries={mockEntries} selection={defaultSelection} onSelect={() => {}} />)
-
-      // Hide People
-      fireEvent.click(screen.getByTitle('Customize sections'))
-      fireEvent.click(screen.getByLabelText('Toggle People'))
-
-      // Show People again
-      fireEvent.click(screen.getByLabelText('Toggle People'))
-      // People section should be visible again — popover toggle + section header = 2 "People" texts
-      const peopleElements = screen.getAllByText('People')
-      expect(peopleElements.length).toBe(2)
-    })
-
-    it('persists hidden sections in localStorage', () => {
-      const { unmount } = render(<Sidebar entries={mockEntries} selection={defaultSelection} onSelect={() => {}} />)
-      fireEvent.click(screen.getByTitle('Customize sections'))
-      fireEvent.click(screen.getByLabelText('Toggle Events'))
-      unmount()
-
-      // Verify localStorage was updated
-      const stored = JSON.parse(localStorage.getItem('laputa-hidden-sections') || '[]')
-      expect(stored).toContain('Event')
-    })
-
-    it('restores hidden sections from localStorage on mount', () => {
-      localStorage.setItem('laputa-hidden-sections', JSON.stringify(['Person', 'Event']))
-      render(<Sidebar entries={mockEntries} selection={defaultSelection} onSelect={() => {}} />)
-
-      // People and Events section headers should be hidden
-      expect(screen.queryByText('People')).not.toBeInTheDocument()
-      expect(screen.queryByText('Events')).not.toBeInTheDocument()
-
-      // Other section headers should still be visible
-      expect(screen.getByText('Projects')).toBeInTheDocument()
-      expect(screen.getByText('Topics')).toBeInTheDocument()
-    })
-
-    it('does not affect All Notes or other sidebar filters when sections are hidden', () => {
-      localStorage.setItem('laputa-hidden-sections', JSON.stringify(['Project', 'Person']))
-      render(<Sidebar entries={mockEntries} selection={defaultSelection} onSelect={() => {}} />)
-
-      // Top nav items still present
-      expect(screen.getByText('All Notes')).toBeInTheDocument()
-      expect(screen.getByText('Favorites')).toBeInTheDocument()
+      expect(onToggleTypeVisibility).toHaveBeenCalledWith('Person')
     })
 
     it('closes popover when clicking outside', () => {
@@ -892,4 +913,42 @@ describe('Sidebar', () => {
       expect(screen.queryByRole('textbox', { name: 'Section name' })).not.toBeInTheDocument()
     })
   })
+
+  it('renders exactly one section for a hyphenated custom type like Monday Ideas', () => {
+    const entriesWithMondayIdeas: VaultEntry[] = [
+      ...mockEntries,
+      {
+        path: '/vault/monday-ideas/standup-bingo.md',
+        filename: 'standup-bingo.md',
+        title: 'Standup Bingo',
+        isA: 'Monday Ideas',
+        aliases: [], belongsTo: [], relatedTo: [],
+        status: null, owner: null, cadence: null,
+        archived: false, trashed: false, trashedAt: null,
+        modifiedAt: 1700000000, createdAt: null,
+        fileSize: 310, snippet: '', wordCount: 120,
+        relationships: {}, icon: null, color: null, order: null,
+        sidebarLabel: null, template: null, sort: null, view: null,
+        outgoingLinks: [], properties: {},
+      },
+      {
+        path: '/vault/monday-ideas/theme-days.md',
+        filename: 'theme-days.md',
+        title: 'Theme Days',
+        isA: 'Monday Ideas',
+        aliases: [], belongsTo: [], relatedTo: [],
+        status: null, owner: null, cadence: null,
+        archived: false, trashed: false, trashedAt: null,
+        modifiedAt: 1700000000, createdAt: null,
+        fileSize: 280, snippet: '', wordCount: 95,
+        relationships: {}, icon: null, color: null, order: null,
+        sidebarLabel: null, template: null, sort: null, view: null,
+        outgoingLinks: [], properties: {},
+      },
+    ]
+    render(<Sidebar entries={entriesWithMondayIdeas} selection={defaultSelection} onSelect={() => {}} />)
+    // "Monday Ideas" pluralized → "Monday Ideases" (the pluralizeType function)
+    const mondaySections = screen.getAllByText(/Monday Ideas/i)
+    expect(mondaySections).toHaveLength(1)
+  })
 })

src/components/Sidebar.tsx

@@ -4,7 +4,6 @@ import { resolveIcon } from '../utils/iconRegistry'
 import { buildTypeEntryMap } from '../utils/typeColors'
 import { pluralizeType } from '../hooks/useCommandRegistry'
 import { TypeCustomizePopover } from './TypeCustomizePopover'
-import { useSectionVisibility } from '../hooks/useSectionVisibility'
 import {
   DndContext, closestCenter, KeyboardSensor, PointerSensor,
   useSensor, useSensors, type DragEndEvent,
@@ -14,8 +13,8 @@ import {
 } from '@dnd-kit/sortable'
 import { CSS } from '@dnd-kit/utilities'
 import {
-  FileText, Star, Wrench, Flask, Target, ArrowsClockwise,
-  Users, CalendarBlank, Tag, TagSimple, Trash, StackSimple, Archive, CaretLeft, GitDiff,
+  FileText, Wrench, Flask, Target, ArrowsClockwise,
+  Users, CalendarBlank, Tag, Trash, StackSimple, Archive, CaretLeft, GitDiff, Pulse,
 } from '@phosphor-icons/react'
 import { GitCommitHorizontal, SlidersHorizontal } from 'lucide-react'
 import {
@@ -35,9 +34,11 @@ interface SidebarProps {
   onUpdateTypeTemplate?: (typeName: string, template: string) => void
   onReorderSections?: (orderedTypes: { typeName: string; order: number }[]) => void
   onRenameSection?: (typeName: string, label: string) => void
+  onToggleTypeVisibility?: (typeName: string) => void
   modifiedCount?: number
   onCommitPush?: () => void
   onCollapse?: () => void
+  isGitVault?: boolean
 }
 
 const BUILT_IN_SECTION_GROUPS: SectionGroup[] = [
@@ -103,13 +104,13 @@ function sortSections(groups: SectionGroup[], typeEntryMap: Record<string, Vault
   })
 }
 
-function useSidebarSections(entries: VaultEntry[], isSectionVisible: (type: string) => boolean) {
+function useSidebarSections(entries: VaultEntry[]) {
   const typeEntryMap = useMemo(() => buildTypeEntryMap(entries), [entries])
   const allSectionGroups = useMemo(() => {
     const sections = buildDynamicSections(entries, typeEntryMap)
     return sortSections(sections, typeEntryMap)
   }, [entries, typeEntryMap])
-  const visibleSections = useMemo(() => allSectionGroups.filter((g) => isSectionVisible(g.type)), [allSectionGroups, isSectionVisible])
+  const visibleSections = useMemo(() => allSectionGroups.filter((g) => typeEntryMap[g.type]?.visible !== false), [allSectionGroups, typeEntryMap])
   const sectionIds = useMemo(() => visibleSections.map((g) => g.type), [visibleSections])
   return { typeEntryMap, allSectionGroups, visibleSections, sectionIds }
 }
@@ -165,7 +166,7 @@ function SortableSection({ group, sectionProps }: {
   sectionProps: Omit<SectionContentProps, 'group' | 'items' | 'isCollapsed' | 'onToggle' | 'isRenaming' | 'renameInitialValue'>
     & { entries: VaultEntry[]; collapsed: Record<string, boolean>; onToggle: (type: string) => void; renamingType: string | null; renameInitialValue: string }
 }) {
-  const { attributes, setNodeRef, transform, transition, isDragging } = useSortable({ id: group.type })
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({ id: group.type })
   const items = sectionProps.entries.filter((e) => e.isA === group.type && !e.archived && !e.trashed)
   const isCollapsed = sectionProps.collapsed[group.type] ?? true
   const isRenaming = sectionProps.renamingType === group.type
@@ -178,6 +179,7 @@ function SortableSection({ group, sectionProps }: {
         onSelectNote={sectionProps.onSelectNote} onCreateType={sectionProps.onCreateType}
         onCreateNewType={sectionProps.onCreateNewType} onContextMenu={sectionProps.onContextMenu}
         onToggle={() => sectionProps.onToggle(group.type)}
+        dragHandleProps={listeners}
         isRenaming={isRenaming}
         renameInitialValue={isRenaming ? sectionProps.renameInitialValue : undefined}
         onRenameSubmit={sectionProps.onRenameSubmit}
@@ -269,7 +271,8 @@ function CustomizeOverlay({ target, typeEntryMap, innerRef, onCustomize, onChang
 export const Sidebar = memo(function Sidebar({
   entries, selection, onSelect, onSelectNote, onCreateType, onCreateNewType,
   onCustomizeType, onUpdateTypeTemplate, onReorderSections, onRenameSection,
-  modifiedCount = 0, onCommitPush, onCollapse,
+  onToggleTypeVisibility,
+  modifiedCount = 0, onCommitPush, onCollapse, isGitVault = false,
 }: SidebarProps) {
   const [collapsed, setCollapsed] = useState<Record<string, boolean>>({})
   const [customizeTarget, setCustomizeTarget] = useState<string | null>(null)
@@ -283,8 +286,10 @@ export const Sidebar = memo(function Sidebar({
   const popoverRef = useRef<HTMLDivElement>(null)
   const customizeRef = useRef<HTMLDivElement>(null)
 
-  const { toggleSection: toggleVisibility, isSectionVisible } = useSectionVisibility()
-  const { typeEntryMap, allSectionGroups, visibleSections, sectionIds } = useSidebarSections(entries, isSectionVisible)
+  const { typeEntryMap, allSectionGroups, visibleSections, sectionIds } = useSidebarSections(entries)
+
+  const isSectionVisible = useCallback((type: string) => typeEntryMap[type]?.visible !== false, [typeEntryMap])
+  const toggleVisibility = useCallback((type: string) => onToggleTypeVisibility?.(type), [onToggleTypeVisibility])
   const { activeCount, archivedCount, trashedCount } = useEntryCounts(entries)
 
   const closeContextMenu = useCallback(() => { setContextMenuPos(null); setContextMenuType(null) }, [])
@@ -351,13 +356,12 @@ export const Sidebar = memo(function Sidebar({
         {/* Top nav */}
         <div className="border-b border-border" style={{ padding: '4px 6px' }}>
           <NavItem icon={FileText} label="All Notes" count={activeCount} isActive={isSelectionActive(selection, { kind: 'filter', filter: 'all' })} badgeClassName="bg-primary text-primary-foreground" onClick={() => onSelect({ kind: 'filter', filter: 'all' })} />
-          <NavItem icon={Star} label="Favorites" isActive={isSelectionActive(selection, { kind: 'filter', filter: 'favorites' })} onClick={() => onSelect({ kind: 'filter', filter: 'favorites' })} />
           <NavItem icon={Archive} label="Archive" count={archivedCount} isActive={isSelectionActive(selection, { kind: 'filter', filter: 'archived' })} badgeClassName="text-muted-foreground" badgeStyle={{ background: 'var(--muted)' }} onClick={() => onSelect({ kind: 'filter', filter: 'archived' })} />
-          <NavItem icon={TagSimple} label="Untagged" disabled />
           <NavItem icon={Trash} label="Trash" count={trashedCount} isActive={isSelectionActive(selection, { kind: 'filter', filter: 'trash' })} activeClassName="bg-destructive/10 text-destructive" badgeClassName="text-muted-foreground" badgeStyle={{ background: 'var(--muted)' }} onClick={() => onSelect({ kind: 'filter', filter: 'trash' })} />
           {modifiedCount > 0 && (
             <NavItem icon={GitDiff} label="Changes" count={modifiedCount} isActive={isSelectionActive(selection, { kind: 'filter', filter: 'changes' })} activeClassName="bg-[color:var(--accent-orange)]/10 text-[var(--accent-orange)]" badgeClassName="text-white" badgeStyle={{ background: 'var(--accent-orange)' }} onClick={() => onSelect({ kind: 'filter', filter: 'changes' })} />
           )}
+          <NavItem icon={Pulse} label="Pulse" isActive={isSelectionActive(selection, { kind: 'filter', filter: 'pulse' })} disabled={!isGitVault} disabledTooltip="Pulse is only available for git-enabled vaults" onClick={isGitVault ? () => onSelect({ kind: 'filter', filter: 'pulse' }) : undefined} />
         </div>
 
         {/* Sections header + visibility popover */}

src/components/SidebarParts.tsx

@@ -26,7 +26,7 @@ export function isSelectionActive(current: SidebarSelection, check: SidebarSelec
 
 // --- NavItem ---
 
-export function NavItem({ icon: Icon, label, count, isActive, activeClassName = 'bg-primary/10 text-primary', badgeClassName, badgeStyle, onClick, disabled }: {
+export function NavItem({ icon: Icon, label, count, isActive, activeClassName = 'bg-primary/10 text-primary', badgeClassName, badgeStyle, onClick, disabled, disabledTooltip }: {
   icon: ComponentType<IconProps>
   label: string
   count?: number
@@ -36,10 +36,11 @@ export function NavItem({ icon: Icon, label, count, isActive, activeClassName =
   badgeStyle?: React.CSSProperties
   onClick?: () => void
   disabled?: boolean
+  disabledTooltip?: string
 }) {
   if (disabled) {
     return (
-      <div className="flex select-none items-center gap-2 rounded text-foreground" style={{ padding: '6px 16px', borderRadius: 4, opacity: 0.4, cursor: 'not-allowed' }} title="Coming soon">
+      <div className="flex select-none items-center gap-2 rounded text-foreground" style={{ padding: '6px 16px', borderRadius: 4, opacity: 0.4, cursor: 'not-allowed' }} title={disabledTooltip ?? "Coming soon"}>
         <Icon size={16} />
         <span className="flex-1 text-[13px] font-medium">{label}</span>
       </div>
@@ -75,6 +76,7 @@ export interface SectionContentProps {
   onCreateNewType?: () => void
   onContextMenu: (e: React.MouseEvent, type: string) => void
   onToggle: () => void
+  dragHandleProps?: Record<string, unknown>
   isRenaming?: boolean
   renameInitialValue?: string
   onRenameSubmit?: (value: string) => void
@@ -93,7 +95,7 @@ function resolveCreateHandler(type: string, onCreateType?: (type: string) => voi
 
 export function SectionContent({
   group, items, isCollapsed, selection, onSelect, onSelectNote,
-  onCreateType, onCreateNewType, onContextMenu, onToggle,
+  onCreateType, onCreateNewType, onContextMenu, onToggle, dragHandleProps,
   isRenaming, renameInitialValue, onRenameSubmit, onRenameCancel,
 }: SectionContentProps) {
   const { label, type, Icon, customColor } = group
@@ -113,6 +115,7 @@ export function SectionContent({
         onContextMenu={(e) => onContextMenu(e, type)}
         onToggle={onToggle}
         onCreate={(e) => { e.stopPropagation(); onCreate?.() }}
+        dragHandleProps={dragHandleProps}
         isRenaming={isRenaming}
         renameInitialValue={renameInitialValue}
         onRenameSubmit={onRenameSubmit}
@@ -182,11 +185,12 @@ function InlineRenameInput({ initialValue, onSubmit, onCancel }: {
   )
 }
 
-function SectionHeader({ label, type, Icon, sectionColor, isCollapsed, isActive, showCreate, onSelect, onContextMenu, onToggle, onCreate, isRenaming, renameInitialValue, onRenameSubmit, onRenameCancel }: {
+function SectionHeader({ label, type, Icon, sectionColor, isCollapsed, isActive, showCreate, onSelect, onContextMenu, onToggle, onCreate, dragHandleProps, isRenaming, renameInitialValue, onRenameSubmit, onRenameCancel }: {
   label: string; type: string; Icon: ComponentType<IconProps>
   sectionColor: string; isCollapsed: boolean; isActive: boolean; showCreate: boolean
   onSelect: () => void; onContextMenu: (e: React.MouseEvent) => void
   onToggle: () => void; onCreate: (e: React.MouseEvent) => void
+  dragHandleProps?: Record<string, unknown>
   isRenaming?: boolean; renameInitialValue?: string
   onRenameSubmit?: (value: string) => void; onRenameCancel?: () => void
 }) {
@@ -194,6 +198,7 @@ function SectionHeader({ label, type, Icon, sectionColor, isCollapsed, isActive,
     <div
       className={cn("group/section flex cursor-pointer select-none items-center justify-between rounded transition-colors", isActive ? "bg-secondary" : "hover:bg-accent")}
       style={{ padding: '6px 8px 6px 16px', borderRadius: 4, gap: 4 }}
+      {...dragHandleProps}
       onClick={() => {
         if (isRenaming) return
         if (isCollapsed) { onToggle(); onSelect() }

src/components/StatusBar.test.tsx

@@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest'
 import { render, screen, fireEvent } from '@testing-library/react'
 import { StatusBar } from './StatusBar'
 import type { VaultOption } from './StatusBar'
+import { formatIndexedElapsed } from '../utils/indexingHelpers'
 
 vi.mock('../utils/url', async () => {
   const actual = await vi.importActual('../utils/url')
@@ -339,4 +340,126 @@ describe('StatusBar', () => {
     )
     expect(screen.getByText('Installing search…')).toBeInTheDocument()
   })
+
+  it('shows MCP warning badge when status is not_installed', () => {
+    render(
+      <StatusBar noteCount={100} vaultPath="/Users/luca/Laputa" vaults={vaults} onSwitchVault={vi.fn()} mcpStatus="not_installed" />
+    )
+    expect(screen.getByTestId('status-mcp')).toBeInTheDocument()
+    expect(screen.getByTitle('MCP server not installed — click to install')).toBeInTheDocument()
+  })
+
+  it('shows MCP warning badge when status is no_claude_cli', () => {
+    render(
+      <StatusBar noteCount={100} vaultPath="/Users/luca/Laputa" vaults={vaults} onSwitchVault={vi.fn()} mcpStatus="no_claude_cli" />
+    )
+    expect(screen.getByTestId('status-mcp')).toBeInTheDocument()
+    expect(screen.getByTitle('Claude CLI not found — install it first')).toBeInTheDocument()
+  })
+
+  it('hides MCP badge when status is installed', () => {
+    render(
+      <StatusBar noteCount={100} vaultPath="/Users/luca/Laputa" vaults={vaults} onSwitchVault={vi.fn()} mcpStatus="installed" />
+    )
+    expect(screen.queryByTestId('status-mcp')).not.toBeInTheDocument()
+  })
+
+  it('hides MCP badge when status is checking', () => {
+    render(
+      <StatusBar noteCount={100} vaultPath="/Users/luca/Laputa" vaults={vaults} onSwitchVault={vi.fn()} mcpStatus="checking" />
+    )
+    expect(screen.queryByTestId('status-mcp')).not.toBeInTheDocument()
+  })
+
+  it('hides MCP badge when no mcpStatus prop provided', () => {
+    render(
+      <StatusBar noteCount={100} vaultPath="/Users/luca/Laputa" vaults={vaults} onSwitchVault={vi.fn()} />
+    )
+    expect(screen.queryByTestId('status-mcp')).not.toBeInTheDocument()
+  })
+
+  it('calls onInstallMcp when clicking MCP badge with not_installed status', () => {
+    const onInstallMcp = vi.fn()
+    render(
+      <StatusBar noteCount={100} vaultPath="/Users/luca/Laputa" vaults={vaults} onSwitchVault={vi.fn()} mcpStatus="not_installed" onInstallMcp={onInstallMcp} />
+    )
+    fireEvent.click(screen.getByTestId('status-mcp'))
+    expect(onInstallMcp).toHaveBeenCalledOnce()
+  })
+
+  it('does not call onInstallMcp when clicking MCP badge with no_claude_cli status', () => {
+    const onInstallMcp = vi.fn()
+    render(
+      <StatusBar noteCount={100} vaultPath="/Users/luca/Laputa" vaults={vaults} onSwitchVault={vi.fn()} mcpStatus="no_claude_cli" onInstallMcp={onInstallMcp} />
+    )
+    fireEvent.click(screen.getByTestId('status-mcp'))
+    expect(onInstallMcp).not.toHaveBeenCalled()
+  })
+
+  it('shows "Indexed just now" when lastIndexedTime is recent and phase is idle', () => {
+    render(
+      <StatusBar
+        noteCount={100}
+        vaultPath="/Users/luca/Laputa"
+        vaults={vaults}
+        onSwitchVault={vi.fn()}
+        indexingProgress={{ phase: 'idle', current: 0, total: 0, done: false, error: null }}
+        lastIndexedTime={Date.now() - 5000}
+      />
+    )
+    expect(screen.getByText(/Indexed just now/)).toBeInTheDocument()
+    expect(screen.getByTestId('status-indexed-time')).toBeInTheDocument()
+  })
+
+  it('calls onReindexVault when clicking the indexed time badge', () => {
+    const onReindexVault = vi.fn()
+    render(
+      <StatusBar
+        noteCount={100}
+        vaultPath="/Users/luca/Laputa"
+        vaults={vaults}
+        onSwitchVault={vi.fn()}
+        indexingProgress={{ phase: 'idle', current: 0, total: 0, done: false, error: null }}
+        lastIndexedTime={Date.now() - 5000}
+        onReindexVault={onReindexVault}
+      />
+    )
+    fireEvent.click(screen.getByTestId('status-indexed-time'))
+    expect(onReindexVault).toHaveBeenCalledOnce()
+  })
+
+  it('hides indexed time badge when no lastIndexedTime', () => {
+    render(
+      <StatusBar
+        noteCount={100}
+        vaultPath="/Users/luca/Laputa"
+        vaults={vaults}
+        onSwitchVault={vi.fn()}
+        indexingProgress={{ phase: 'idle', current: 0, total: 0, done: false, error: null }}
+      />
+    )
+    expect(screen.queryByTestId('status-indexed-time')).not.toBeInTheDocument()
+  })
+})
+
+describe('formatIndexedElapsed', () => {
+  it('returns empty string for null', () => {
+    expect(formatIndexedElapsed(null)).toBe('')
+  })
+
+  it('returns "Indexed just now" for < 60s', () => {
+    expect(formatIndexedElapsed(Date.now() - 30_000)).toBe('Indexed just now')
+  })
+
+  it('returns minutes for < 60min', () => {
+    expect(formatIndexedElapsed(Date.now() - 5 * 60_000)).toBe('Indexed 5m ago')
+  })
+
+  it('returns hours for < 24h', () => {
+    expect(formatIndexedElapsed(Date.now() - 3 * 3600_000)).toBe('Indexed 3h ago')
+  })
+
+  it('returns days for >= 24h', () => {
+    expect(formatIndexedElapsed(Date.now() - 48 * 3600_000)).toBe('Indexed 2d ago')
+  })
 })