docs: convert remaining ASCII diagrams to Mermaid + add Mermaid rule to CLAUDE.md

ARCHITECTURE.md:
- System Overview → flowchart (React Frontend / Rust Backend / External Services)
- MCP Server Architecture → flowchart (index.js, vault.js, ws-bridge, transports)
- WebSocket Bridge → flowchart LR (Frontend ↔ ws-bridge ↔ vault)
- Vault Cache Three Strategies → flowchart (full scan / incremental / cache hit)
- Auto-Save Flow → flowchart LR
- Git Sync Flow → flowchart TD (auto-sync + manual commit paths)

CLAUDE.md:
- Added 'Documentation Diagrams' section: Mermaid preferred for all new diagrams,
  convert ASCII on sight, exception for spatial wireframe layouts

(HOME)/.tauri/laputa-v2.key

@@ -1 +0,0 @@
-dW50cnVzdGVkIGNvbW1lbnQ6IHJzaWduIGVuY3J5cHRlZCBzZWNyZXQga2V5ClJXUlRZMEl5V3BxWUNBZU1LZWxOK3ZEZTZkdGhzM2l6cnpVUmIvUEtTTWgzLzNEU1VoZ0FBQkFBQUFBQUFBQUFBQUlBQUFBQUFpN2xxclpGK3YzRERub1EvZFdsdVdORktuOHZYVlB0S2U2QkhNdlMreElkRVdabTh6UllNYzNFb2VWYTVCayszNUpyOC94Z0dJS2pVQ3NSKzdKNEszZHpDZll0aGdtV1J6bWFXODc4VWJpOVFYdUhEai9tNHQ2U3ZRbVd1NHBkR01YS2ZrUDlPRVU9Cg==

(HOME)/.tauri/laputa-v2.key.pub

@@ -1 +0,0 @@
-dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IDVCQTVDRkIzNkFGRTYwQjUKUldTMVlQNXFzOCtsVzROZmJLR0JFVGw1a1UzKzViY3dUcWFoaUttRFhhVk8rVUhrc29QL1FPeXUK

.claude-pid

@@ -1 +0,0 @@
-45402

.codesceneignore

@@ -0,0 +1,5 @@
+# Exclude third-party tools and their dependencies from CodeScene analysis
+tools/
+e2e/
+tests/
+scripts/

.codescenerc

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

.github/workflows/release.yml

@@ -176,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
           {
@@ -186,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}"
               }
             }
           }

.gitignore

@@ -30,9 +30,6 @@ dist-ssr
 # Coverage reports
 /coverage/
 
-# Laputa vault cache
-.laputa-cache.json
-
 # Demo vault and helper scripts
 demo-vault/
 select_demo_notes*.py
@@ -45,3 +42,28 @@ src-tauri/target
 
 # Generated mcp-server bundle (built by scripts/bundle-mcp-server.mjs)
 src-tauri/resources/
+
+# Python cache
+__pycache__/
+*.py[cod]
+
+# Dev screenshots
+screenshots/
+
+# Stale planning docs (keep locally if needed, not in repo)
+REDESIGN-PLAN.md
+SF-SYMBOLS-MIGRATION.md
+CODE-HEALTH-REPORT.md
+
+# Local home dir artifact from worktree ops
+(HOME)/
+
+# Runtime / process files
+.claude-pid
+
+# Generated vault index files (qmd/search artifacts)
+.laputa-index.json
+
+# Tauri signing keys (never commit private keys)
+*.key
+*.key.pub

.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,29 +90,54 @@ 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 ────────────────────────────────────────
+echo ""
+echo "🏥 [5/5] CodeScene code health gate (hotspot ≥9.2, average ≥8.8)..."
 if [ -z "$CODESCENE_PAT" ] || [ -z "$CODESCENE_PROJECT_ID" ]; then
   echo "  ⚠️  CODESCENE_PAT or CODESCENE_PROJECT_ID not set — skipping"
 else
-  THRESHOLD=9.2
-  SCORE=$(curl -sf \
+  HOTSPOT_THRESHOLD=9.2
+  AVERAGE_THRESHOLD=8.8
+  API_RESPONSE=$(curl -sf \
     -H "Authorization: Bearer $CODESCENE_PAT" \
     -H "Accept: application/json" \
-    "https://api.codescene.io/v2/projects/$CODESCENE_PROJECT_ID" \
-    | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['analysis']['hotspot_code_health']['now'])")
-  echo "  Hotspot Code Health: $SCORE (threshold: $THRESHOLD)"
+    "https://api.codescene.io/v2/projects/$CODESCENE_PROJECT_ID")
+  HOTSPOT_SCORE=$(echo "$API_RESPONSE" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['analysis']['hotspot_code_health']['now'])")
+  AVERAGE_SCORE=$(echo "$API_RESPONSE" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['analysis']['average_code_health']['now'])")
+  echo "  Hotspot Code Health: $HOTSPOT_SCORE (threshold: $HOTSPOT_THRESHOLD)"
+  echo "  Average Code Health: $AVERAGE_SCORE (threshold: $AVERAGE_THRESHOLD)"
   python3 -c "
-score = float('$SCORE')
-threshold = float('$THRESHOLD')
-if score < threshold:
-    print(f'  ❌ Code Health {score:.2f} below threshold {threshold}')
+hotspot = float('$HOTSPOT_SCORE')
+average = float('$AVERAGE_SCORE')
+ht = float('$HOTSPOT_THRESHOLD')
+at = float('$AVERAGE_THRESHOLD')
+failed = False
+if hotspot < ht:
+    print(f'  ❌ Hotspot Code Health {hotspot:.2f} below threshold {ht}')
+    failed = True
+else:
+    print(f'  ✅ Hotspot Code Health {hotspot:.2f} ≥ {ht}')
+if average < at:
+    print(f'  ❌ Average Code Health {average:.2f} below threshold {at}')
+    failed = True
+else:
+    print(f'  ✅ Average Code Health {average:.2f} ≥ {at}')
+if failed:
     exit(1)
-print(f'  ✅ Code Health {score:.2f} ≥ {threshold}')
 "
 fi
 

CLAUDE.md

@@ -28,23 +28,58 @@ DEV_PID=$!
 sleep 3  # wait for vite to be ready
 
 # 2. Run Playwright smoke test for this task
-npx playwright test --headed=false tests/smoke/<slug>.spec.ts
+BASE_URL="http://localhost:<N>" npx playwright test tests/smoke/<slug>.spec.ts
 
-# 3. Or use the MCP Playwright tool directly in your session to drive the browser
-# e.g. navigate to localhost:<N>, open Cmd+K, verify command appears, etc.
+# 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
+**You must write a new Playwright test for this task** in `tests/smoke/<slug>.spec.ts` that covers every acceptance criterion. Do not rely only on existing smoke tests — they test the app in general, not your specific feature.
+
+**What to cover in your Playwright test:**
+- Every acceptance criterion from the task spec → one `test()` block per criterion
+- Every command palette entry → 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
+- **The happy path end-to-end**: simulate exactly what a user would do to use this feature
 
-**Playwright is non-negotiable even if tests pass.** Unit tests verify code; Playwright verifies the user experience in the real browser. Both are required.
+**The test must fail before your fix and pass after.** If you can't write a test that demonstrates the bug is fixed, your test doesn't cover the right thing.
 
-> **⚠️ 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.
+**Playwright is non-negotiable even if unit 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. **If your task touches the filesystem, AI context pipeline, MCP server, git integration, or any Tauri command that reads/writes real files, Playwright alone is not enough.** You must also do Phase 1b.
+
+### Phase 1b: Tauri dev QA (you do this for filesystem/native tasks)
+
+If your task touches **any of the following**, you must also test with `pnpm tauri dev` against the real vault before firing done:
+- File read/write (notes, cache, vault config)
+- AI chat context (what the AI actually receives as input)
+- MCP server / subprocess communication
+- Git integration (commit, push, history, diff)
+- Native dialogs or OS-level features
+
+```bash
+# Start Tauri dev app from your worktree
+pnpm tauri dev --port <N> &
+sleep 10  # wait for Tauri + Vite to boot
+
+# Then test using osascript keyboard events (NO mouse/cliclick)
+# Example:
+osascript -e 'tell application "laputa" to activate'
+osascript -e 'tell application "System Events" to keystroke "k" using command down'
+# ...simulate the full user flow from the acceptance criteria
+```
+
+**What to verify in Phase 1b:**
+- Open the feature on a real note in `~/Laputa` (not the demo vault)
+- Walk through every acceptance criterion step by step using keyboard only
+- Verify file changes with `git -C ~/Laputa diff` if the task writes files
+- Verify AI responses actually contain note content (not empty) if the task touches AI context
+
+**⚠️ Claude Code runs headless — you cannot see the screen.** Use `screencapture /tmp/qa-check.png` and then read/describe what you see if you need visual verification. Or rely on DOM state checks via osascript accessibility API.
 
 ### Phase 2: Native Tauri QA (Brian does this after you push)
 
@@ -64,6 +99,9 @@ Brian installs the release build and runs keyboard-only QA on the native app. Yo
 - 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.
 
+**⚠️ Phase 1 is YOUR quality gate, not a formality.**
+Brian's Phase 2 QA is a *reinforcement* check, not the primary gate. If Brian finds a bug in Phase 2 that you could have caught in Phase 1, that is a Phase 1 failure — not a Phase 2 discovery. Before firing the done signal, ask yourself: "Did I actually verify, in Playwright, that the feature works end-to-end exactly as the spec describes?" If the answer is "I ran the smoke tests and they passed", that is not enough. You must run your task-specific test and verify the acceptance criteria one by one.
+
 **⚠️ 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.
@@ -115,7 +153,29 @@ 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
+- **Update docs/** when changing architecture, abstractions, or significant design (mandatory — see rule below)
+
+## ⛔ 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)
 
@@ -278,3 +338,23 @@ git commit --no-verify   # also forbidden for pre-push bypass
 The hook runs: tsc, Vite build, frontend tests, frontend coverage, Rust coverage, Clippy, rustfmt, CodeScene. Fix any failures before pushing — do not skip.
 
 If a check fails, fix the issue and push again. The hook is the gate — not remote CI.
+
+## Documentation Diagrams
+
+**Prefer Mermaid for all diagrams in `docs/`.** Use ASCII art only when the diagram is inherently spatial (e.g. the four-panel UI wireframe). For everything else — architecture, flows, sequences, data models — use Mermaid:
+
+```markdown
+# Architecture diagrams
+flowchart TD / LR / BT
+
+# Sequence diagrams (multi-actor interactions)
+sequenceDiagram
+
+# Data models
+classDiagram
+
+# State machines
+stateDiagram-v2
+```
+
+When updating existing docs, convert ASCII diagrams to Mermaid. When adding new diagrams, always use Mermaid. GitHub renders Mermaid natively in markdown.

CODE-HEALTH-REPORT.md

@@ -1,345 +0,0 @@
-# Code Health Report — Laputa App
-
-**Date:** 2026-02-20
-**Branch:** `main`
-**Overall Project Score:** 9.33 / 10.0 (Green — up from 9.14)
-**Tool:** CodeScene Code Health Analysis (project ID: 76865)
-**Previous Report:** 2026-02-20 on `main` — 9.14 / 10.0
-
----
-
-## Summary
-
-The Laputa App codebase scores **9.33** overall — a further improvement of **+0.19** from the previous report (9.14). The codebase remains solidly in **Green**, driven by the `vault.rs` refactoring (+2.59 to 8.81) and the `frontmatter.rs` refactoring (+2.79 to 9.68, now Green). Five files remain in the Yellow zone, down from six — `frontmatter.rs` has exited Yellow into Green.
-
-| Zone | Score Range | File Count | Description |
-|------|------------|------------|-------------|
-| Optimal | 10.0 | 8 | Perfect — optimized for human and AI comprehension |
-| Green | 9.0 – 9.9 | 15 | High quality, minor issues only |
-| Yellow | 4.0 – 8.9 | 5 | Problematic technical debt |
-| Red | 1.0 – 3.9 | 0 | — |
-| N/A | — | 6 | CSS files (4) and tiny utility files (2) — unsupported by CodeScene |
-
----
-
-## Refactoring Completed (vault.rs + frontmatter.rs)
-
-The following refactorings were executed on vault.rs and frontmatter.rs, raising both files significantly:
-
-### vault.rs: 6.22 → 8.81 (+2.59)
-
-Refactored in 5 commits across multiple phases:
-
-1. **Extracted `run_git` helper** — Consolidated duplicated git command execution into a single helper function, flattening git functions (`git_changed_files`, `git_uncommitted_new_files`).
-2. **Decomposed `parse_md_file`** — Extracted `parse_frontmatter_fields`, `extract_title`, `extract_snippet`, and `extract_relationships` into focused sub-functions. Flattened deep nesting with early returns.
-3. **Decomposed `scan_vault_cached`** — Extracted `process_vault_entry`, `collect_vault_entries`, `apply_git_status`, and `build_vault_response` as focused functions.
-4. **Split large test assertion blocks** — Broke monolithic assertion blocks into per-field assertions for readability and maintainability.
-5. **Converted internal functions to use `&Path`** instead of `&str` for vault/file paths, reducing string-heavy arguments.
-
-All 8 original code smells (3 Bumpy Roads, 4 Deep Nestings, 2 Complex Methods, 2 Large Methods, String-Heavy Args, Large Assertion Blocks) have been resolved. The CodeScene review now reports **zero code smells**.
-
-### frontmatter.rs: 6.89 → 9.68 (+2.79) — Yellow → Green
-
-Refactored in 4 commits:
-
-1. **Flattened `update_frontmatter_content`** — Used early returns and extracted `find_key_line_range` and `build_updated_content` helpers. Eliminated bumpy road (4 bumps) and deep nesting (4 levels).
-2. **Simplified `FrontmatterValue::to_yaml_value`** — Extracted `needs_yaml_quoting` predicate, simplified match arms. Reduced cc from 17.
-3. **Simplified `format_yaml_key`** — Extracted key-quoting rules into `key_needs_quoting` predicate. Reduced complex conditionals from 5.
-4. **Extracted line-parsing helpers** — `line_is_key` and related helpers for clean YAML line detection.
-
-All original code smells (1 Bumpy Road, 1 Deep Nesting, 2 Complex Methods, 4 Complex Conditionals) have been resolved. Only one minor issue remains: **String Heavy Function Arguments** (73% of args are string types).
-
----
-
-## Change Summary vs Previous Report (Feb 17)
-
-| File | Previous | Current | Delta | Notes |
-|------|----------|---------|-------|-------|
-| `src/App.tsx` | 7.13 | **9.28** | **+2.15** | Yellow -> Green. Brain Method eliminated via hook extraction |
-| `src/components/Inspector.tsx` | 7.49 | **9.02** | **+1.53** | Yellow -> Green. Decomposed into sub-components |
-| `src-tauri/src/vault.rs` | 4.80 | **8.81** | **+4.01** | Still Yellow but near-Green. All code smells resolved |
-| `src-tauri/src/frontmatter.rs` | 6.89* | **9.68** | **+2.79** | Yellow -> Green. All major smells resolved |
-| `src/components/Editor.tsx` | 6.94 | **7.68** | **+0.74** | Still Yellow. DiffView/wikilinks extracted but Editor still too large |
-| `src/components/Sidebar.tsx` | 9.02 | **9.14** | +0.12 | Green (stable) |
-| `src/components/NoteList.tsx` | 8.11 | **8.05** | -0.06 | Yellow (stable, slight regression) |
-| `src/components/QuickOpenPalette.tsx` | 9.55 | **9.55** | = | Green (unchanged) |
-| `src-tauri/src/lib.rs` | 9.68 | **9.68** | = | Green (unchanged) |
-| `src-tauri/src/main.rs` | 10.0 | **10.0** | = | Optimal (unchanged) |
-| `src-tauri/src/git.rs` | 10.0 | **10.0** | = | Optimal (unchanged) |
-| `src/components/StatusBar.tsx` | 10.0 | **9.23** | -0.77 | Regression: Optimal -> Green (new features added) |
-| `src/mock-tauri.ts` | 10.0 | **9.37** | -0.63 | Regression: Optimal -> Green (new mock data added) |
-
-*frontmatter.rs was extracted from vault.rs; "previous" is its initial score after extraction.
-
-### New Files (not in previous report)
-
-| File | Score | Zone | Notes |
-|------|-------|------|-------|
-| `src/hooks/useNoteActions.ts` | **7.81** | Yellow | Extracted from App.tsx — still needs decomposition |
-| `src/components/AIChatPanel.tsx` | **8.51** | Yellow | New feature — large component |
-| `src/components/DynamicPropertiesPanel.tsx` | **9.06** | Green | Extracted from Inspector.tsx |
-| `src/components/DiffView.tsx` | **9.09** | Green | Extracted from Editor.tsx |
-| `src/utils/frontmatter.ts` | **9.24** | Green | Extracted from Inspector.tsx |
-| `src/components/CommitDialog.tsx` | **9.38** | Green | New component |
-| `src/hooks/useVaultLoader.ts` | **9.41** | Green | Extracted from App.tsx |
-| `src/utils/wikilinks.ts` | **9.53** | Green | Extracted from Editor.tsx |
-| `src/hooks/useTheme.ts` | **9.68** | Green | New hook |
-| `src/components/EditableValue.tsx` | **10.0** | Optimal | Extracted from Inspector.tsx |
-| `src/components/ResizeHandle.tsx` | **10.0** | Optimal | New component |
-| `src/components/CreateNoteDialog.tsx` | **10.0** | Optimal | New component |
-| `src/components/Toast.tsx` | **10.0** | Optimal | New component |
-| `src/utils/typeColors.ts` | **10.0** | Optimal | New utility |
-| `src/main.tsx` | **10.0** | Optimal | Entry point |
-
----
-
-## File-by-File Scores (All 34 Files)
-
-| File | LoC | Score | Zone | Key Issues |
-|------|-----|-------|------|------------|
-| `src-tauri/src/main.rs` | 6 | **10.0** | Optimal | None |
-| `src-tauri/src/git.rs` | 423 | **10.0** | Optimal | None |
-| `src/components/EditableValue.tsx` | 167 | **10.0** | Optimal | None |
-| `src/components/ResizeHandle.tsx` | 74 | **10.0** | Optimal | None |
-| `src/components/CreateNoteDialog.tsx` | 99 | **10.0** | Optimal | None |
-| `src/components/Toast.tsx` | 28 | **10.0** | Optimal | None |
-| `src/utils/typeColors.ts` | 37 | **10.0** | Optimal | None |
-| `src/main.tsx` | 16 | **10.0** | Optimal | None |
-| `src-tauri/src/frontmatter.rs` | 279 | **9.68** | Green | String-heavy function arguments (73%) |
-| `src-tauri/src/lib.rs` | 80 | **9.68** | Green | String-heavy function arguments |
-| `src/hooks/useTheme.ts` | 51 | **9.68** | Green | None significant |
-| `src/components/QuickOpenPalette.tsx` | 145 | **9.55** | Green | Complex Method (cc=16) |
-| `src/utils/wikilinks.ts` | 68 | **9.53** | Green | None significant |
-| `src/hooks/useVaultLoader.ts` | 123 | **9.41** | Green | None significant |
-| `src/components/CommitDialog.tsx` | 73 | **9.38** | Green | None significant |
-| `src/mock-tauri.ts` | 894 | **9.37** | Green | None significant |
-| `src/App.tsx` | 176 | **9.28** | Green | Complex Method: App() cc=16 / 130 LoC |
-| `src/utils/frontmatter.ts` | 72 | **9.24** | Green | None significant |
-| `src/components/StatusBar.tsx` | 159 | **9.23** | Green | None significant |
-| `src/components/Sidebar.tsx` | 208 | **9.14** | Green | None significant |
-| `src/components/DiffView.tsx` | 45 | **9.09** | Green | None significant |
-| `src/components/DynamicPropertiesPanel.tsx` | 265 | **9.06** | Green | None significant |
-| `src/components/Inspector.tsx` | 312 | **9.02** | Green | None significant |
-| `src-tauri/src/vault.rs` | 1111 | **8.81** | Yellow | No code smells reported — near Green threshold |
-| `src/components/AIChatPanel.tsx` | 364 | **8.51** | Yellow | Complex Method: AIChatPanel() cc=15 / 285 LoC |
-| `src/components/NoteList.tsx` | 434 | **8.05** | Yellow | Complex Method: NoteListInner() cc=28 / 208 LoC |
-| `src/hooks/useNoteActions.ts` | 280 | **7.81** | Yellow | Bumpy Road, Deep Nesting, Complex Method: useNoteActions() cc=30 / 169 LoC |
-| `src/components/Editor.tsx` | 575 | **7.68** | Yellow | **Brain Method**: Editor() cc=61 / 385 LoC, Bumpy Road |
-| `src/types.ts` | 38 | N/A | — | Type definitions only |
-| `src/lib/utils.ts` | 6 | N/A | — | Utility (too small) |
-| `src/App.css` | — | N/A | — | CSS not supported |
-| `src/index.css` | — | N/A | — | CSS not supported |
-| `src/components/Editor.css` | — | N/A | — | CSS not supported |
-| `src/components/EditorTheme.css` | — | N/A | — | CSS not supported |
-
----
-
-## Technical Debt Hotspots
-
-Based on code health scores, file sizes, and change frequency:
-
-| Priority | File | Score | LoC | Risk Factor |
-|----------|------|-------|-----|-------------|
-| 1 | `src/components/Editor.tsx` | 7.68 | 575 | **Brain Method** (cc=61, 385 LoC) — worst single function in codebase |
-| 2 | `src/hooks/useNoteActions.ts` | 7.81 | 280 | Brain Method (cc=30, 169 LoC), deep nesting in updateMockFrontmatter |
-| 3 | `src/components/NoteList.tsx` | 8.05 | 434 | Complex Method (cc=28, 208 LoC) |
-| 4 | `src/components/AIChatPanel.tsx` | 8.51 | 364 | Large component (cc=15, 285 LoC) — new, address before it grows |
-| 5 | `src-tauri/src/vault.rs` | 8.81 | 1111 | Near-Green, no code smells — minor improvement needed to cross 9.0 |
-
----
-
-## Detailed Analysis — Files Scoring Below 9.0
-
-### 1. `src/components/Editor.tsx` — Score: 7.68 (Now #1 Priority)
-
-The core `Editor` component function remains a **Brain Method** — the single worst function in the codebase at cc=61 and 385 LoC (3.2x the 120 LoC limit).
-
-**Code Smells Found:**
-
-| Smell | Location | Details | Severity |
-|-------|----------|---------|----------|
-| Bumpy Road | `Editor` (L154–575) | 2 bumps | High |
-| Complex Method | `Editor` (L154–575) | cc = 61 (**Brain Method**) | High |
-| Complex Conditional | `Editor:196` | 2 complex expressions | Medium |
-| Large Method | `Editor` (L154–575) | 385 LoC (limit: 120) | Medium |
-
----
-
-### 2. `src/hooks/useNoteActions.ts` — Score: 7.81
-
-Extracted from App.tsx. Contains the `updateMockFrontmatter` function which has deep nesting, plus the `useNoteActions` hook itself is still too large.
-
-**Code Smells Found:**
-
-| Smell | Location | Details | Severity |
-|-------|----------|---------|----------|
-| Bumpy Road | `updateMockFrontmatter` (L14–66) | 2 bumps | High |
-| Deep Nesting | `updateMockFrontmatter` (L14–66) | 4 levels deep | High |
-| Complex Method | `useNoteActions` (L93–280) | cc = 30 | Medium |
-| Complex Method | `updateMockFrontmatter` (L14–66) | cc = 17 | Medium |
-| Complex Method | `deleteMockFrontmatterProperty` (L68–91) | cc = 9 | Medium |
-| Large Method | `useNoteActions` (L93–280) | 169 LoC (limit: 70) | Medium |
-
----
-
-### 3. `src/components/NoteList.tsx` — Score: 8.05
-
-Slightly regressed from 8.11. The `NoteListInner` component and `buildRelationshipGroups` remain complex.
-
-**Code Smells Found:**
-
-| Smell | Location | Details | Severity |
-|-------|----------|---------|----------|
-| Complex Method | `NoteListInner` (L211–432) | cc = 28 | Medium |
-| Complex Method | `buildRelationshipGroups` (L125–188) | cc = 13 | Medium |
-| Large Method | `NoteListInner` (L211–432) | 208 LoC (limit: 120) | Medium |
-| Overall Code Complexity | File-wide | High mean cyclomatic complexity | Medium |
-
----
-
-### 4. `src/components/AIChatPanel.tsx` — Score: 8.51
-
-New file (mock AI chat feature). Already showing signs of complexity that should be addressed early.
-
-**Code Smells Found:**
-
-| Smell | Location | Details | Severity |
-|-------|----------|---------|----------|
-| Complex Method | `AIChatPanel` (L62–364) | cc = 15 | Medium |
-| Large Method | `AIChatPanel` (L62–364) | 285 LoC (limit: 120) | Medium |
-
----
-
-### 5. `src-tauri/src/vault.rs` — Score: 8.81
-
-Dramatically improved from 6.22. The CodeScene review reports **zero code smells** after the refactoring. The file is near the Green threshold (9.0) and may only need minor adjustments to cross it.
-
----
-
-## Quick Wins (Low Effort, High Impact)
-
-### 1. Decompose `Editor` into hooks (highest ROI)
-**File:** `src/components/Editor.tsx` | **Impact:** cc 61 -> ~10 per hook
-- Extract `useEditorExtensions()` — all CodeMirror extension setup (themes, keybindings, decorations)
-- Extract `useEditorContent()` — content loading, saving, dirty state management
-- Extract `useEditorKeymap()` — custom keymap handlers
-- The `Editor` component becomes a thin composition + JSX layer
-
-### 2. Decompose `useNoteActions` hook
-**File:** `src/hooks/useNoteActions.ts` | **Impact:** cc 30 -> ~8 per hook
-- Extract `useFrontmatterSync()` — `updateMockFrontmatter` + `deleteMockFrontmatterProperty`
-- Flatten `updateMockFrontmatter` with early returns and helper functions
-- Keep `useNoteActions` as pure action dispatch (create, delete, rename)
-
-### 3. Split `NoteListInner` into sub-components
-**File:** `src/components/NoteList.tsx` | **Impact:** cc 28 -> ~8 per component
-- Extract `NoteListItem` component for individual note rendering
-- Extract `RelationshipGroup` component for grouped entries
-- Extract `buildRelationshipGroups` to a utility file
-
-### 4. Extract `AIChatPanel` hooks early
-**File:** `src/components/AIChatPanel.tsx` | **Impact:** Prevent further complexity growth
-- Extract `useChatMessages()` — message state, send/receive logic
-- Extract `ChatMessage` component for individual message rendering
-
-### 5. Push `vault.rs` past 9.0
-**File:** `src-tauri/src/vault.rs` | **Impact:** 8.81 -> 9.0+
-- Minor: reduce string-heavy args further with `&Path` conversions
-- Minor: simplify any remaining complex expressions
-
----
-
-## Path to 9.5 Overall
-
-**Current:** 9.33 (28 scored files, sum = 261.20)
-**Target:** 9.5
-
-To reach 9.5, all 5 Yellow files must reach at least 9.5:
-
-| File | Current | Target | Points Needed |
-|------|---------|--------|---------------|
-| `vault.rs` | 8.81 | 9.5 | +0.69 |
-| `Editor.tsx` | 7.68 | 9.5 | +1.82 |
-| `useNoteActions.ts` | 7.81 | 9.5 | +1.69 |
-| `NoteList.tsx` | 8.05 | 9.5 | +1.45 |
-| `AIChatPanel.tsx` | 8.51 | 9.5 | +0.99 |
-| **Total points needed** | | | **+6.64** |
-
-**Projected score if all Yellow files reach 9.5:** (261.20 + 6.64) / 28 = **9.57**
-
-**Recommended execution order for maximum impact:**
-1. `Editor.tsx` (7.68 -> 9.5) — highest user-facing impact, hook extraction is mechanical
-2. `useNoteActions.ts` (7.81 -> 9.5) — extracted hook, straightforward decomposition
-3. `NoteList.tsx` (8.05 -> 9.5) — component extraction
-4. `AIChatPanel.tsx` (8.51 -> 9.5) — closest to target, prevent drift
-5. `vault.rs` (8.81 -> 9.5) — near-Green already, minor tweaks
-
----
-
-## Refactoring ROI Summary
-
-| File | Current | Target | Defect Reduction | Speed Improvement |
-|------|---------|--------|------------------|-------------------|
-| `Editor.tsx` | 7.68 | 9.5 | 25–38% | 19–30% |
-| `useNoteActions.ts` | 7.81 | 9.5 | 24–36% | 18–28% |
-| `NoteList.tsx` | 8.05 | 9.5 | 22–33% | 16–26% |
-| `AIChatPanel.tsx` | 8.51 | 9.5 | 18–27% | 13–21% |
-| `vault.rs` | 8.81 | 9.5 | 10–18% | 8–14% |
-
----
-
-## Files in Good Shape
-
-These files need no immediate attention:
-
-**Optimal (10.0):**
-- `src-tauri/src/main.rs` — 6 LoC, clean entry point
-- `src-tauri/src/git.rs` — 423 LoC, well-structured
-- `src/components/EditableValue.tsx` — 167 LoC, clean extracted component
-- `src/components/ResizeHandle.tsx` — 74 LoC, simple component
-- `src/components/CreateNoteDialog.tsx` — 99 LoC, clean dialog
-- `src/components/Toast.tsx` — 28 LoC, minimal component
-- `src/utils/typeColors.ts` — 37 LoC, simple utility
-- `src/main.tsx` — 16 LoC, entry point
-
-**Green (9.0–9.9):**
-- `src-tauri/src/frontmatter.rs` — 9.68 (up from 6.89! Only: string-heavy args)
-- `src-tauri/src/lib.rs` — 9.68 (minor: string-heavy args)
-- `src/hooks/useTheme.ts` — 9.68 (clean hook)
-- `src/components/QuickOpenPalette.tsx` — 9.55 (minor: cc=16)
-- `src/utils/wikilinks.ts` — 9.53 (clean utility)
-- `src/hooks/useVaultLoader.ts` — 9.41 (clean hook)
-- `src/components/CommitDialog.tsx` — 9.38 (clean component)
-- `src/mock-tauri.ts` — 9.37 (large but clean)
-- `src/App.tsx` — 9.28 (dramatically improved from 7.13)
-- `src/utils/frontmatter.ts` — 9.24 (clean utility)
-- `src/components/StatusBar.tsx` — 9.23 (slightly regressed from 10.0)
-- `src/components/Sidebar.tsx` — 9.14 (stable)
-- `src/components/DiffView.tsx` — 9.09 (clean extracted component)
-- `src/components/DynamicPropertiesPanel.tsx` — 9.06 (clean extracted component)
-- `src/components/Inspector.tsx` — 9.02 (dramatically improved from 7.49)
-
----
-
-## What Worked Since Last Report
-
-The following refactorings from the Feb 17 recommendations were executed:
-
-1. **App.tsx decomposition** (Plan C) — Extracted `useNoteActions`, `useVaultLoader`, and other hooks. App dropped from cc=56/381 LoC to cc=16/130 LoC. Score: 7.13 -> 9.28.
-2. **Inspector.tsx decomposition** (Plan D) — Extracted `DynamicPropertiesPanel`, `EditableValue`, and `frontmatter.ts` utility. Score: 7.49 -> 9.02.
-3. **vault.rs full refactoring** (Plan A) — Extracted `run_git` helper, decomposed `parse_md_file` and `scan_vault_cached`, split large assertion blocks, converted to `&Path` args. Score: 4.80 -> 8.81. **All code smells resolved.**
-4. **frontmatter.rs full refactoring** (Plan B) — Flattened `update_frontmatter_content`, simplified `to_yaml_value` and `format_yaml_key`, extracted line-parsing helpers. Score: 6.89 -> 9.68. **Yellow -> Green.**
-5. **Editor.tsx partial decomposition** (Plan B, Steps 2–3) — Extracted `DiffView.tsx` and `wikilinks.ts`. Score: 6.94 -> 7.68.
-
-## What Still Needs Work
-
-1. **Editor.tsx** — DiffView and wikilinks were extracted, but the core Editor function was NOT decomposed into hooks. It's now the worst function (cc=61, 385 LoC). Hook extraction (useEditorExtensions, useEditorContent, useEditorKeymap) is the next high-impact target.
-2. **useNoteActions.ts** — Inherited App.tsx's `updateMockFrontmatter` complexity. Needs decomposition into smaller hooks.
-3. **NoteList.tsx** — Slight regression, needs component extraction (NoteListItem, RelationshipGroup).
-4. **AIChatPanel.tsx** — New file already showing complexity. Address early before it grows.
-5. **vault.rs** — Near-Green at 8.81 with zero code smells. Minor tweaks may push it past 9.0.
-
----
-
-*Report generated by CodeScene MCP analysis on 2026-02-20. For interactive exploration, visit: https://codescene.io/projects/76865*
-*Note: CodeScene MCP Server MCP-0.1.5 was used. Version MCP-0.2.0 is available — consider updating via `brew upgrade cs-mcp`.*

REDESIGN-PLAN.md

@@ -1,362 +0,0 @@
-# Laputa App Redesign — Implementation Plan
-
-> Generated from `ui-design.pen` (V2) vs current implementation. **Analysis only — do not implement yet.**
-
----
-
-## Summary of Changes
-
-The V2 design introduces: a **Status Bar**, **Tab Bar** in the editor, an **Info Bar** (breadcrumb + actions), restructured **Sidebar** with Phosphor icons and collapsible groups with count badges, **IBM Plex Mono** for type pills, updated **color palette** (new primary `#155DFF`, new accent colors), and several layout/spacing refinements throughout.
-
----
-
-## Design Specs Reference (from .pen file)
-
-### Colors Changed
-| Variable | Old (Light) | New (Light) | Old (Dark) | New (Dark) |
-|---|---|---|---|---|
-| `--primary` | `#2383E2` | `#155DFF` | `#4a9eff` | `#155DFF` |
-| `--accent-green` | `#0F7B6C` | `#00B38B` | `#4caf50` | `#00B38B` |
-| `--accent-purple` | `#9065B0` | `#A932FF` | `#9c72ff` | `#A932FF` |
-| `--accent-blue` | `#2383E2` | `#155DFF` | `#4a9eff` | `#155DFF` |
-
-### New Color Variables (not in current CSS)
-| Variable | Light | Dark |
-|---|---|---|
-| `--accent-yellow` | `#F0B100` | `#F0B100` |
-| `--accent-blue-light` | `#155DFF14` | `#155DFF20` |
-| `--accent-green-light` | `#00B38B14` | `#00B38B20` |
-| `--accent-purple-light` | `#A932FF14` | `#A932FF20` |
-| `--accent-red-light` | `#E03E3E14` | `#f4433620` |
-| `--accent-yellow-light` | `#F0B10014` | `#F0B10020` |
-
-### Typography
-- **Font**: Inter (primary), IBM Plex Mono (labels/pills) — **IBM Plex Mono not currently loaded**
-- App title: 17px / Bold / letter-spacing -0.3
-- Sidebar items: 13px / Medium (font-weight 500)
-- Sidebar section headers: 13px / Semibold (600) — currently 11px
-- Type pills: 11px / IBM Plex Mono / normal weight / ALL CAPS
-- Editor H1: 32px / Bold / lh 1.2
-- Editor H2: 24px / Semibold / lh 1.3
-- Editor body: 16px / Regular / lh 1.6
-- Info bar / breadcrumb: 12px
-- Status bar: 11px
-
-### Panel Widths
-| Panel | Design | Current |
-|---|---|---|
-| Sidebar | 250px | 250px ✅ |
-| NoteList | 300px | 300px ✅ |
-| Editor | flexible | flexible ✅ |
-| Inspector | 260px (design) / 280px (spec) | 280px ✅ |
-
-### Border Radius Scale
-- 4px (sm) — chips
-- 6px (md) — buttons, inputs
-- 8px (lg) — cards, dialogs
-- 9999px — pills, badges (full-round)
-- 16px — larger badges
-
----
-
-## Difference Map
-
-### 1. NEW: Status Bar (bottom of app)
-**Files**: New component `StatusBar.tsx`, `App.tsx`, `App.css`
-- 30px height, `bg: --sidebar`, `border-top: 1px --border`
-- **Left**: box icon + "v0.4.2" | git-branch + "main" | refresh-cw (green) + "Synced 2m ago"
-- **Right**: sparkles (purple) + "Claude Sonnet 4" | file-text + "1,247 notes" | bell icon | settings icon
-- Padding: 0 8px, items aligned center, gap 12px between items
-- Font: Inter 11px, text color `--muted-foreground`
-- Separators: "|" in `--border` color
-- **All icons**: Lucide, 13-14px
-
-### 2. NEW: Tab Bar (top of editor panel)
-**Files**: `Editor.tsx`
-- 45px height, `bg: --sidebar`, `border-bottom: 1px --sidebar-border`
-- **Active tab**: `bg: --background`, border-right 1px `--border`, text 12px/500 `--foreground`, X close icon (14px lucide)
-- **Inactive tab**: no fill, border-right + border-bottom 1px `--sidebar-border`, text 12px/normal `--muted-foreground`, X icon opacity 0 (show on hover)
-- **Spacer**: fills remaining width, border-bottom 1px `--border`
-- **Controls area** (right): border-left + border-bottom 1px `--border`, gap 12px, padding 0 12px
-  - Plus icon (Phosphor, 16px)
-  - Columns/split icon (Phosphor, 16px) — **disabled placeholder**
-  - Arrows-out-simple/expand icon (Phosphor, 16px) — **disabled placeholder**
-
-### 3. NEW: Breadcrumb Bar (below tab bar, above editor content)
-**Files**: `Editor.tsx`
-- 45px height, `bg: --background`, `border-bottom: 1px --border`
-- Padding: 6px 16px
-- **Left (breadcrumb)**: "Project" (12px, muted) › "Laputa App" (12px/500, foreground) · "1,284 words" (12px, muted) · "M" (12px/600, `--accent-yellow`) — M only when file modified
-- **Right (actions)**: gap 12px, each 16px Phosphor icon in `--muted-foreground`
-  - magnifying-glass (search in file)
-  - git-branch (version history) — **disabled placeholder**
-  - cursor-text (focus mode) — **disabled placeholder**
-  - sparkle (AI assist) — **disabled placeholder**
-  - dots-three (more options) — **disabled placeholder**
-
-### 4. Sidebar Restructure
-**Files**: `Sidebar.tsx`
-
-#### Header changes:
-- Current: "Laputa" title + theme toggle button
-- New: "Laputa" title (17px/700, -0.3 ls) + search icon (16px Phosphor magnifying-glass) + settings/gear icon (16px)
-- Theme toggle moved elsewhere (or removed from header)
-- Padding: 12px 16px, height 45px, border-bottom 1px
-
-#### Search bar added:
-- Below header, padding 6px 12px, border-bottom 1px
-- Input with magnifying-glass icon prefix, 13px text, placeholder "Search notes..."
-- Height ~32px, border-radius 6px, bg `--secondary`
-
-#### Navigation section restructured:
-**Current**: flat list of filters (All Notes, People, Events, Changes, Favorites, Trash)
-**New**: Two items in top nav:
-- "All Notes" — file-text icon (Phosphor 16px) + label 13px/500 + count badge (pill, bg `--secondary`, 10px text)
-- "Favorites" — star icon (Phosphor 16px) + same style
-
-#### Section groups restructured:
-**Current**: PROJECTS, EXPERIMENTS, RESPONSIBILITIES, PROCEDURES as expandable sections with items listed under each
-**New**: Collapsible groups with consistent pattern:
-- Each group: chevron-right (12px Lucide) + icon (18px Phosphor, bold) + label (13px/600) + count badge (pill)
-- **Projects** — folder-open icon (Phosphor)
-- **Experiments** — flask icon (Phosphor)
-- **Responsibilities** — target icon (Phosphor) — **currently not in sidebar**
-- **Procedures** — arrows-clockwise icon (Phosphor)
-- **People** — users icon (Phosphor) — **moved from filter to section group**
-- **Events** — calendar-blank icon (Phosphor) — **moved from filter to section group**
-- **Topics** — tag icon (Phosphor) — **currently at bottom, now integrated as a group**
-
-Each group has:
-- Container: padding 4px 6px, border-bottom 1px (disabled in some), vertical layout, gap 2px
-- Header row: padding 6px 16px, corner-radius 4px, gap 8px, justify space-between
-- Badge: height 20px, bg `--secondary`, corner-radius 9999px, padding 0 6px
-
-#### Removed from sidebar:
-- "Untagged" filter — not in new design
-- "Changes" filter — not in new design (modified files shown elsewhere)
-- "Trash" filter — not in new design
-- "People" as top-level filter — now a collapsible section group
-- "Events" as top-level filter — now a collapsible section group
-
-#### Commit button:
-- Same concept but refined: padding 12px, border-top 1px
-- Button: fill `--primary`, corner-radius 6px, gap 6px, padding 8px 16px
-- Icon: git-commit-horizontal (Lucide 14px) in `--primary-foreground`
-- Text: "Commit & Push" (13px/500)
-- Badge: bg `#ffffff40`, corner-radius 9px, text `--white` 10px/600
-
-### 5. NoteList Changes
-**Files**: `NoteList.tsx`
-
-#### Header:
-- Current: title + count badge + create button
-- New: "Notes" title (14px/600) + search icon (16px Phosphor) + plus icon (16px Phosphor) — gap 12px
-- No separate count badge in header
-
-#### Search:
-- Current: always-visible search input below header
-- New: search icon in header (search may toggle inline or use command palette)
-- **Remove the always-visible search input** or keep it hidden until search icon clicked
-
-#### Type pills:
-- Current: rounded-full, border, `text-[11px]`, system font, "Projects 4" format
-- New: `IBM Plex Mono` font, 11px, ALL CAPS format "ALL 24" / "PROJECTS 4" / "NOTES 12" / "EVENTS 5"
-- Active pill: `bg: #4a9eff18` (blue tint), `border: 1px --primary`, text `--primary`
-- Inactive pill: `border: 1px --border`, text `--muted-foreground`
-- Pill padding: 2px 10px, corner-radius 9999px
-- Height: ~18px (compact)
-- Layout: absolute positioned at x offsets (12, 76, 166, 243) within 45px height container — effectively a horizontal scrollable row
-
-#### Note items:
-- Selected: `bg: #2383E212` (very light blue), left accent bar 3px `#2383E2`, title 13px/600
-- Normal: border-bottom 1px `#E9E9E7`, title 13px/500, time 11px, snippet 12px/lh1.5
-- Padding: 10px 16px
-- **No type badge** on individual items (simplified)
-- **No status text** on items
-
-### 6. Editor Content Area
-**⚠️ SKIP — Keep editor as-is. Editor changes in the design are NOT intentional.**
-
-### 7. Inspector Refinements
-**Files**: `Inspector.tsx`
-
-#### Header:
-- Current: collapsed toggle + title
-- New: sliders-horizontal icon (16px Phosphor) + "Properties" (13px/600, `--muted-foreground`) + X close button (16px Phosphor)
-- Height 45px, border-bottom 1px, padding 0 12px, gap 8px
-
-#### Properties section:
-- Key-value rows: label (12px, muted) — value (12px, foreground), space-between
-- Status badge: colored bg (e.g., `--accent-green-light`) with colored text (e.g., `--accent-green`), rounded, padding 1px 6px, 10px font
-- "+ Add property" button: full-width, border 1px `--border`, corner-radius 6px, padding 6px 12px, centered text (12px, muted)
-
-#### Relationships section:
-- Group title: 12px/600 foreground
-- Link buttons: full-width, bg `--accent-blue-light`, corner-radius 6px, padding 6px 10px, text `--primary` 12px/500, icon (tag/flask, Phosphor 14px, 0.5 opacity)
-- "+ Link existing" button: border 1px `--border`, corner-radius 6px, same padding
-
-#### Backlinks:
-- Title: "Backlinks" 12px/600 + count 11px/500 muted
-- Items: text `--primary` 12px
-
-#### History:
-- Title: "History" 12px/600
-- Items: left border 2px `--border`, padding-left 10px
-- Hash line: 11px foreground
-- Date line: 10px muted
-
-### 8. Icon Library Change
-**Current**: Lucide React throughout
-**New**: **SF Symbols** (Apple's native icon set) for all new/redesigned icons. Use `sf-symbols-react` or inline SVGs extracted from SF Symbols app.
-
-**Note**: The Pencil design used Phosphor as a placeholder — Luca's intent is SF Symbols throughout. Map Phosphor names to SF Symbol equivalents:
-- `magnifying-glass` → `magnifyingglass`
-- `star` → `star.fill`
-- `folder-open` → `folder`
-- `flask` → `flask`
-- `target` → `target`
-- `arrows-clockwise` → `arrow.clockwise`
-- `users` → `person.2`
-- `calendar-blank` → `calendar`
-- `tag` → `tag`
-- `plus` → `plus`
-- `columns` → `rectangle.split.2x1`
-- `arrows-out-simple` → `arrow.up.left.and.arrow.down.right`
-- `sliders-horizontal` → `slider.horizontal.3`
-- `cursor-text` → `character.cursor.ibeam`
-- `sparkle` → `sparkles`
-- `dots-three` → `ellipsis`
-- `git-branch` → `arrow.triangle.branch`
-- `gear` → `gearshape`
-
-**Action**: Find the best approach for SF Symbols in React/Tauri (e.g., `sf-symbols-react`, SVG extraction, or native font)
-
----
-
-## Implementation Phases
-
-### Phase 1: Theme & Typography Updates
-**Scope**: CSS variables, fonts, colors — no structural changes
-**Files**: `src/index.css`, `index.html` (or font import)
-**Estimated effort**: 1 Claude Code session
-
-1. **Add IBM Plex Mono font** — add Google Fonts import or npm package
-2. **Update color variables in `index.css`**:
-   - `:root` (light): `--primary: #155DFF`, `--accent-green: #00B38B`, `--accent-purple: #A932FF`, `--accent-blue: #155DFF`
-   - `.dark`: same primary `#155DFF`, accent-green `#00B38B`, accent-purple `#A932FF`
-   - Add new variables: `--accent-yellow`, `--accent-blue-light`, `--accent-green-light`, `--accent-purple-light`, `--accent-red-light`, `--accent-yellow-light` (both modes)
-   - Update all `--ring`, `--sidebar-primary`, `--sidebar-ring` to match new primary
-   - Update app-specific vars: `--accent-blue`, `--accent-green`, `--accent-purple`, `--accent-blue-bg` etc.
-3. **Update `theme.json`**:
-   - `headings.h2.fontSize`: 27 → 24
-   - `editor.paddingHorizontal`: 40 → 64
-   - `editor.paddingVertical`: 20 → 32
-4. **Install Phosphor Icons**: `pnpm add @phosphor-icons/react`
-
-### Phase 2: Sidebar Restructure
-**Scope**: Sidebar layout, navigation, icons
-**Files**: `src/components/Sidebar.tsx`
-**Estimated effort**: 1 Claude Code session
-
-1. **Header**: Replace theme toggle with search icon (Phosphor `MagnifyingGlass`) + gear icon. Move theme toggle to status bar settings or a menu.
-2. **Add search input** below header: Phosphor magnifying-glass prefix, 13px, bg `--secondary`, border-radius 6px
-3. **Top nav**: Reduce to "All Notes" (Phosphor `FileText` 16px) and "Favorites" (Phosphor `Star` 16px), each with count badge pill
-4. **Section groups**: Restructure to new pattern with:
-   - Consistent chevron + Phosphor icon (18px, bold) + label (13px/600) + count badge
-   - Icons: `FolderOpen` (Projects), `Flask` (Experiments), `Target` (Responsibilities), `ArrowsClockwise` (Procedures), `Users` (People), `CalendarBlank` (Events), `Tag` (Topics)
-   - Move People and Events from filters to section groups
-   - Remove "Untagged", "Changes", "Trash" from nav
-5. **Commit button**: Update styling to match design (padding, badge style)
-6. **Remove** People/Events/Changes/Trash/Untagged filter items
-
-### Phase 3: NoteList Updates
-**Scope**: Header, type pills, note item styling
-**Files**: `src/components/NoteList.tsx`
-**Estimated effort**: 1 Claude Code session
-
-1. **Header**: Replace badge + create button with search icon (Phosphor `MagnifyingGlass`) + plus icon (Phosphor `Plus`), gap 12px
-2. **Remove or hide** the always-visible search input — add toggle behavior on search icon click
-3. **Type pills**: Switch to IBM Plex Mono, ALL CAPS format ("ALL 24", "PROJECTS 4"), update active/inactive styles per design
-4. **Selected note**: Update to `bg: #2383E212`, left accent 3px `#2383E2` (update to new primary), remove type badge and status text from items
-5. **Note items**: Adjust padding to 10px 16px, snippet line-height 1.5, remove type/status badges from individual items
-
-### Phase 4: Editor — Tab Bar & Info Bar
-**Scope**: New sub-components within Editor
-**Files**: `src/components/Editor.tsx`, `src/components/Editor.css`
-**Estimated effort**: 1 Claude Code session
-
-1. **Tab Bar** (top of editor):
-   - 45px, bg `--sidebar`, border-bottom
-   - Active tab: bg `--background`, border-right, 12px/500 text, X close button
-   - Inactive tab: muted text, hidden X (show on hover)
-   - Right controls: Plus + Split (disabled) + Expand (disabled) — Phosphor icons
-2. **Info Bar** (below tab bar):
-   - 45px, bg `--background`, border-bottom
-   - Left: breadcrumb `Type › Title · N words · M` (M in accent-yellow when modified)
-   - Right: icon buttons (magnifying-glass functional, git-branch/cursor-text/sparkle/dots-three as **disabled placeholders** with `opacity: 0.4, cursor: not-allowed`)
-3. **Adjust editor content padding** to 32px 64px per design
-
-### Phase 5: Status Bar + Inspector Polish
-**Scope**: New StatusBar component, Inspector refinements
-**Files**: New `src/components/StatusBar.tsx`, `App.tsx`, `App.css`, `src/components/Inspector.tsx`
-**Estimated effort**: 1 Claude Code session
-
-1. **StatusBar.tsx** (new component):
-   - 30px fixed at bottom, bg `--sidebar`, border-top 1px
-   - Left: version + branch + sync status
-   - Right: AI model + notes count + bell (disabled placeholder) + settings (disabled placeholder)
-   - All Lucide icons 13-14px
-2. **App.tsx / App.css**: Add StatusBar below main content, wrap layout in vertical flex (main panels + status bar)
-3. **Inspector refinements**:
-   - Header: Phosphor `SlidersHorizontal` icon + "Properties" label + Phosphor `X` close
-   - Status badge: use `--accent-*-light` bg colors with `--accent-*` text
-   - "+ Add property" and "+ Link existing" buttons: match border/radius/padding from design
-   - History items: left-border 2px timeline style, 10px date text
-
-### Phase 6: Icon Migration & Cleanup
-**Scope**: Replace Lucide icons with Phosphor where specified
-**Files**: All components
-**Estimated effort**: 1 Claude Code session
-
-1. **Audit all icon usage** across components
-2. **Replace with Phosphor** where the design specifies (sidebar nav, section icons, NoteList header, editor toolbar icons, inspector)
-3. **Keep Lucide** for: chevrons, X/close, tab close, status bar icons, git-commit-horizontal
-4. **Remove unused Lucide imports**
-5. **Visual verification**: Run `pnpm dev` and compare with `ui-design-screenshot.png`
-
----
-
-## New Features as Disabled Placeholders
-
-These buttons/icons appear in the design but don't have backend functionality yet. Add them as disabled UI elements:
-
-| Element | Location | Icon | Notes |
-|---|---|---|---|
-| Split view | Tab bar controls | Phosphor `Columns` | `opacity: 0.4, cursor: not-allowed, title="Coming soon"` |
-| Expand/focus | Tab bar controls | Phosphor `ArrowsOutSimple` | Same |
-| Git branch viewer | Info bar right | Phosphor `GitBranch` | Same |
-| Focus mode | Info bar right | Phosphor `CursorText` | Same |
-| AI assist | Info bar right | Phosphor `Sparkle` | Same |
-| More options | Info bar right | Phosphor `DotsThree` | Same |
-| Bell/notifications | Status bar right | Lucide `Bell` | Same |
-| Settings | Status bar right | Lucide `Settings` | Same |
-| Gear/settings | Sidebar header | Phosphor `Gear` | Same |
-
----
-
-## Files Inventory
-
-| File | Changes |
-|---|---|
-| `src/index.css` | Color variables, font import |
-| `src/theme.json` | H2 size, editor padding |
-| `index.html` | IBM Plex Mono font link (if using CDN) |
-| `package.json` | Add `@phosphor-icons/react` |
-| `src/App.tsx` | Add StatusBar, adjust layout |
-| `src/App.css` | Vertical flex for status bar |
-| `src/components/Sidebar.tsx` | Major restructure |
-| `src/components/NoteList.tsx` | Header, pills, item styling |
-| `src/components/Editor.tsx` | Add TabBar, InfoBar sections |
-| `src/components/Editor.css` | Tab/info bar styles |
-| `src/components/Inspector.tsx` | Header, badges, history styling |
-| `src/components/StatusBar.tsx` | **NEW** |

SF-SYMBOLS-MIGRATION.md

@@ -1,130 +0,0 @@
-# SF Symbols Migration Plan
-
-> Current state: All icons use either **Phosphor Icons** (`@phosphor-icons/react`) or **Lucide React** (`lucide-react`). This document maps every icon to its SF Symbol equivalent for future migration.
-
----
-
-## Icon Audit Summary (Phase 6 — 2026-02-17)
-
-| Category | Count | Files | Status |
-|---|---|---|---|
-| Phosphor icons | 22 | `Sidebar.tsx`, `Editor.tsx`, `NoteList.tsx`, `Inspector.tsx` | All used, migrate to SF Symbols |
-| Phosphor types | 1 (`IconProps`) | `Sidebar.tsx` | Type only — replace when migrating |
-| Lucide (app components) | 4 | `Sidebar.tsx`, `Editor.tsx` | Evaluate per-icon |
-| Lucide (StatusBar) | 7 | `StatusBar.tsx` | Keep Lucide per design |
-| Lucide (shadcn/ui) | 7 | `ui/select.tsx`, `ui/dropdown-menu.tsx`, `ui/dialog.tsx` | Keep Lucide — library internals |
-| **Total icon imports** | **41** | **8 files** | **0 unused** |
-
-**Unused imports found**: None. All icon imports are actively used in JSX.
-
----
-
-## Phosphor Icons — Current Usage
-
-These are the primary UI icons introduced during the redesign. All should migrate to SF Symbols.
-
-| Phosphor Icon | SF Symbol Equivalent | File(s) | Usage |
-|---|---|---|---|
-| `MagnifyingGlass` | `magnifyingglass` | `Sidebar.tsx`, `NoteList.tsx`, `Editor.tsx` | Search icon in sidebar header, note list header, editor info bar |
-| `Gear` | `gearshape` | `Sidebar.tsx` | Settings icon in sidebar header (disabled placeholder) |
-| `FileText` | `doc.text` | `Sidebar.tsx` | "All Notes" nav item icon |
-| `Star` | `star.fill` | `Sidebar.tsx` | "Favorites" nav item icon |
-| `FolderOpen` | `folder` | `Sidebar.tsx` | "Projects" section group icon |
-| `Flask` | `flask` | `Sidebar.tsx` | "Experiments" section group icon |
-| `Target` | `target` | `Sidebar.tsx` | "Responsibilities" section group icon |
-| `ArrowsClockwise` | `arrow.clockwise` | `Sidebar.tsx` | "Procedures" section group icon |
-| `Users` | `person.2` | `Sidebar.tsx` | "People" section group icon |
-| `CalendarBlank` | `calendar` | `Sidebar.tsx` | "Events" section group icon |
-| `Tag` | `tag` | `Sidebar.tsx` | "Topics" section group icon |
-| `TagSimple` | `tag` | `Sidebar.tsx` | "Untagged" nav item icon |
-| `Trash` | `trash` | `Sidebar.tsx` | "Trash" nav item icon |
-| `Plus` | `plus` | `NoteList.tsx`, `Editor.tsx` | Create note button, new tab button |
-| `Columns` | `rectangle.split.2x1` | `Editor.tsx` | Split view button (disabled placeholder) |
-| `ArrowsOutSimple` | `arrow.up.left.and.arrow.down.right` | `Editor.tsx` | Expand/focus button (disabled placeholder) |
-| `GitBranch` | `arrow.triangle.branch` | `Editor.tsx` | Version history button (disabled placeholder) |
-| `CursorText` | `character.cursor.ibeam` | `Editor.tsx` | Focus mode button (disabled placeholder) |
-| `Sparkle` | `sparkles` | `Editor.tsx` | AI assist button (disabled placeholder) |
-| `DotsThree` | `ellipsis` | `Editor.tsx` | More options button (disabled placeholder) |
-| `SlidersHorizontal` | `slider.horizontal.3` | `Inspector.tsx` | Inspector header icon |
-| `X` (Phosphor) | `xmark` | `Inspector.tsx` | Inspector close button |
-| `IconProps` (type) | n/a | `Sidebar.tsx` | TypeScript type for icon component props |
-
----
-
-## Lucide React — Current Usage
-
-### App Components
-
-These Lucide icons are used in custom app components. Some may migrate to SF Symbols; others are kept for specific reasons.
-
-| Lucide Icon | SF Symbol Equivalent | File | Usage | Migration Notes |
-|---|---|---|---|---|
-| `ChevronRight` | `chevron.right` | `Sidebar.tsx` | Section group expand chevron | Keep Lucide or migrate — small utility icon |
-| `ChevronDown` | `chevron.down` | `Sidebar.tsx` | Section group collapse chevron | Keep Lucide or migrate — small utility icon |
-| `GitCommitHorizontal` | `circle.dotted` | `Sidebar.tsx` | Commit & Push button icon | Keep Lucide or migrate |
-| `X` (Lucide) | `xmark` | `Editor.tsx` | Tab close button | Keep Lucide or migrate |
-| `Package` | `shippingbox` | `StatusBar.tsx` | App version indicator | Keep Lucide — status bar uses Lucide per design |
-| `GitBranch` (Lucide) | `arrow.triangle.branch` | `StatusBar.tsx` | Git branch indicator | Keep Lucide — status bar uses Lucide per design |
-| `RefreshCw` | `arrow.clockwise` | `StatusBar.tsx` | Sync status indicator | Keep Lucide — status bar uses Lucide per design |
-| `Sparkles` (Lucide) | `sparkles` | `StatusBar.tsx` | AI model indicator | Keep Lucide — status bar uses Lucide per design |
-| `FileText` (Lucide) | `doc.text` | `StatusBar.tsx` | Notes count indicator | Keep Lucide — status bar uses Lucide per design |
-| `Bell` | `bell` | `StatusBar.tsx` | Notifications (disabled placeholder) | Keep Lucide — status bar uses Lucide per design |
-| `Settings` | `gearshape` | `StatusBar.tsx` | Settings (disabled placeholder) | Keep Lucide — status bar uses Lucide per design |
-
-### shadcn/ui Components (Keep Lucide)
-
-These are standard shadcn/ui library components that use Lucide as their built-in icon system. These should **not** be migrated — they are part of the component library's internal implementation.
-
-| Lucide Icon | File | Usage |
-|---|---|---|
-| `CheckIcon` | `ui/select.tsx` | Selected item indicator |
-| `ChevronDownIcon` | `ui/select.tsx` | Select trigger arrow, scroll-down button |
-| `ChevronUpIcon` | `ui/select.tsx` | Scroll-up button |
-| `CheckIcon` | `ui/dropdown-menu.tsx` | Checkbox item indicator |
-| `ChevronRightIcon` | `ui/dropdown-menu.tsx` | Sub-menu trigger arrow |
-| `CircleIcon` | `ui/dropdown-menu.tsx` | Radio item indicator |
-| `XIcon` | `ui/dialog.tsx` | Dialog close button |
-
----
-
-## Approach Options for SF Symbols in React/Tauri
-
-### Option 1: `sf-symbols-react` npm package
-- **Pros**: Drop-in React components, familiar API (`<SFSymbol name="magnifyingglass" />`)
-- **Cons**: Third-party package, may lag behind Apple's symbol updates, limited weight/rendering options
-- **Status**: Check npm for current maintenance state before adopting
-
-### Option 2: SVG extraction from SF Symbols app
-- **Pros**: Exact Apple-quality vectors, no runtime dependency, full control over styling
-- **Cons**: Manual export process per icon, potential licensing concerns (SF Symbols license restricts use to Apple platforms), need to manage SVG sprite or individual files
-- **How**: Export SVGs from the SF Symbols macOS app, create a `src/icons/` directory with individual SVG components or a sprite sheet
-
-### Option 3: Apple's SF Symbols font (native approach via Tauri)
-- **Pros**: Pixel-perfect on macOS, automatic weight matching, system-native feel
-- **Cons**: Only works on macOS (not cross-platform), requires Tauri native font access, won't render in browser dev mode
-- **How**: Use CSS `font-family: "SF Pro"` with Unicode code points, or invoke native APIs from Tauri's Rust backend
-
-### Option 4: Hybrid — SVG in browser, native in Tauri
-- **Pros**: Best of both worlds — browser dev mode uses SVGs, production Tauri build uses native SF Symbols
-- **Cons**: More complex build setup, need to maintain two icon systems
-- **How**: Build an `<Icon>` wrapper component that checks `window.__TAURI__` and renders native or SVG accordingly
-
-### Recommendation
-**Option 2 (SVG extraction)** is the most practical starting point:
-- Laputa is a macOS-only Tauri app, so SF Symbols licensing applies (Apple platform)
-- SVGs work in both browser dev mode and Tauri production
-- No third-party dependency to maintain
-- Can later upgrade to Option 4 (hybrid native) for perfect macOS integration
-
----
-
-## Migration Steps (Future)
-
-1. Export all needed SF Symbol SVGs from the SF Symbols macOS app
-2. Create `src/icons/sf-symbols/` with a React component per icon (or a single sprite)
-3. Build a thin `<SFIcon name="..." size={} />` wrapper for consistent API
-4. Replace Phosphor imports file-by-file (Sidebar → NoteList → Editor → Inspector)
-5. Decide whether to also replace Lucide in StatusBar and utility icons (chevrons, X)
-6. Keep Lucide in shadcn/ui components — do not modify those
-7. Once all Phosphor icons are replaced, remove `@phosphor-icons/react` from dependencies
-8. Run `pnpm build` and visually verify all icons render correctly

VISION.md

@@ -1,53 +0,0 @@
-# Laputa — Vision
-
-Laputa is a personal knowledge base where humans and AI agents collaborate as equals.
-
----
-
-## Core principles
-
-### 1. The vault is the source of truth
-Everything lives in the vault as plain text files. Notes, relations, configuration, instructions — all Markdown with YAML frontmatter. No proprietary database, no hidden state. If you can open a terminal, you can read your vault. If you can write Markdown, you can modify it.
-
-### 2. Vault-native configuration
-Laputa configures itself through files inside the vault — the same files you write and read every day. There is no separate "settings app" or admin panel. If you want to change a theme, you edit a note. If you want to give instructions to an AI agent, you write a note. If you want to define a template, you create a note.
-
-This applies to:
-- **`_themes/`** — themes as notes with a YAML block in the body. Edit `_themes/dark.md`, see the colors change in real time.
-- **`AGENTS.md`** — instructions for AI agents. Write what you want them to know about your vault in plain language. They read it before acting.
-- **`_templates/`** — note templates per type. Create `_templates/event.md` and every new event starts from that structure.
-- **`_procedures/`** — recurring tasks as notes with a `schedule` frontmatter field.
-
-The principle: **if it can be expressed in frontmatter + Markdown, it doesn't need a UI**.
-
-### 3. Structure through types, not folders
-Notes have a `type` field. Types determine folders, icons, and colors — but the structure is defined by the data, not the filesystem hierarchy. You can query "all events in February" without knowing anything about folder layout.
-
-Relations between notes are expressed as frontmatter arrays: `people: [Marco, Sara]`. A wikilink `[[Marco]]` in the body navigates to the person note. The graph emerges from the data, not from a separate graph database.
-
-### 4. The file is the interface
-You can use Laputa's UI, or you can open a terminal. Or a text editor. Or Claude Code. They all operate on the same files. There is no difference between "the app" and "the vault" — the vault is the app.
-
-This is why Laputa has an MCP server: external agents get the same tools the in-app AI panel uses. The interface is a convenience, not a requirement.
-
-### 5. Humans and AI as collaborators
-Pulse — the activity feed — shows the history of the vault without distinguishing between human commits and agent commits. That's intentional. Laputa is designed to be a space where you and your AI agents work together, each contributing to the same knowledge base.
-
-The AI doesn't have a separate workspace. It works in yours.
-
----
-
-## What Laputa is not
-
-- Not a todo app (though you can use it as one)
-- Not a note-taking app that syncs to the cloud (the vault is yours, sync however you want — git, iCloud, rsync)
-- Not a replacement for a terminal (power users will use both)
-- Not trying to abstract away git (git is a feature, not an implementation detail)
-
----
-
-## The long game
-
-A vault that grows with you for years. Events, people, projects, thoughts — all interconnected, all version-controlled, all accessible to any tool that can read a file.
-
-Ten years from now, your vault should still be readable. Plain text is forever.

analyze_broken_links.py

@@ -1,41 +0,0 @@
-#!/usr/bin/env python3
-"""Analyze which broken links are to existing vs non-existent notes."""
-
-import sys
-sys.path.insert(0, '/Users/luca/Workspace/laputa-app')
-from select_demo_notes import build_graph, select_notes, LAPUTA_ROOT
-
-nodes, link_lookup = build_graph()
-selected = select_notes(nodes, link_lookup, target_count=1000)
-
-print("\n🔍 Analyzing broken links...")
-
-# Count links by type
-total_outlinks = 0
-resolved = 0
-unresolved_but_exists = 0
-unresolved_not_exists = 0
-
-for path in selected:
-    node = nodes[path]
-    for link_ref in node['outlinks']:
-        total_outlinks += 1
-        
-        if link_ref in link_lookup:
-            target = link_lookup[link_ref]
-            if target in selected:
-                resolved += 1
-            else:
-                # Exists but not in selection
-                unresolved_but_exists += 1
-        else:
-            # Doesn't exist at all
-            unresolved_not_exists += 1
-
-print(f"Total outlinks: {total_outlinks}")
-print(f"  Resolved (in selection): {resolved} ({resolved/total_outlinks*100:.1f}%)")
-print(f"  Unresolved but note exists: {unresolved_but_exists} ({unresolved_but_exists/total_outlinks*100:.1f}%)")
-print(f"  Unresolved - note doesn't exist: {unresolved_not_exists} ({unresolved_not_exists/total_outlinks*100:.1f}%)")
-
-print(f"\nIf we include ALL existing notes (not just selected):")
-print(f"  Max possible resolution: {(resolved + unresolved_but_exists)/total_outlinks*100:.1f}%")

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/area/refactoring.md

@@ -0,0 +1,7 @@
+---
+Is A: Area
+Status: Active
+---
+# Refactoring
+
+Area note covering refactoring practices, principles, and techniques for improving code quality without changing external behavior.

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/refactoring-ideas.md

@@ -0,0 +1,6 @@
+---
+Is A: Note
+---
+# Refactoring Ideas
+
+Collection of ideas for refactoring the codebase to improve maintainability and performance.

demo-vault-v2/note/refactoring-key-ideas.md

@@ -0,0 +1,6 @@
+---
+Is A: Note
+---
+# Refactoring Key Ideas
+
+Key takeaways from Martin Fowler's Refactoring book and other refactoring resources.

demo-vault-v2/note/refactoring-patterns.md

@@ -0,0 +1,6 @@
+---
+Is A: Note
+---
+# Refactoring Patterns
+
+Common refactoring patterns including Extract Method, Rename Variable, and Replace Conditional with Polymorphism.

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/trash-management.pen

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

docs/ABSTRACTIONS.md

@@ -2,36 +2,119 @@
 
 Key abstractions and domain models in Laputa.
 
+## Design Philosophy
+
+Laputa's abstractions follow the **convention over configuration** principle: standard field names and folder structures have well-defined meanings and trigger UI behavior automatically. This makes vaults legible both to humans and to AI agents — the more a vault follows conventions, the less custom configuration an AI needs to navigate it correctly.
+
+The full set of design principles is documented in [ARCHITECTURE.md](./ARCHITECTURE.md#design-principles).
+
+## Semantic Field Names (conventions)
+
+These frontmatter field names have special meaning in Laputa's UI:
+
+| Field | Meaning | UI behavior |
+|---|---|---|
+| `type:` | Entity type (Project, Person, Quarter…) | Type chip in note list + sidebar grouping |
+| `status:` | Lifecycle stage (active, done, blocked…) | Colored chip in note list + editor header |
+| `url:` | External link | Clickable link chip in editor header |
+| `date:` | Single date | Formatted date badge |
+| `start_date:` + `end_date:` | Duration/timespan | Date range badge |
+| `goal:` + `result:` | Progress | Progress indicator in editor header |
+| `Workspace:` | Vault context filter | Global workspace filter |
+| `Belongs to:` | Parent relationship | Relationship chip in Properties panel |
+| `Related to:` | Lateral relationship | Relationship chip in Properties panel |
+
+The list of default-shown relationships and semantic property rendering rules can be customized via `config/relations.md` and `config/semantic-properties.md` in the vault.
+
 ## Document Model
 
 All data lives in markdown files with YAML frontmatter. There is no database — the filesystem is the source of truth.
 
 ### 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`).
+
+```mermaid
+classDiagram
+    class VaultEntry {
+        +String path
+        +String filename
+        +String title
+        +String? isA
+        +String[] aliases
+        +String[] belongsTo
+        +String[] relatedTo
+        +Record~string,string[]~ relationships
+        +String[] outgoingLinks
+        +String? status
+        +String? owner
+        +Number? modifiedAt
+        +Number? createdAt
+        +Number wordCount
+        +String? snippet
+        +Boolean archived
+        +Boolean trashed
+        +Number? trashedAt
+        +Record~string,string~ properties
+    }
+
+    class TypeDocument {
+        +String icon
+        +String color
+        +Number order
+        +String sidebarLabel
+        +String template
+        +String sort
+        +Boolean visible
+    }
+
+    class Frontmatter {
+        +String type
+        +String status
+        +String url
+        +String[] belongsTo
+        +String[] relatedTo
+        +String[] aliases
+        ...custom fields
+    }
+
+    VaultEntry --> Frontmatter : parsed from
+    VaultEntry --> TypeDocument : isA resolves to
+    VaultEntry "many" --> "1" TypeDocument : grouped by type
+```
 
 ```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. (from frontmatter `type:` field)
+  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)
 }
 ```
 
-### Entity Types (isA)
+### Entity Types (isA / type)
 
-Entity type is inferred from the folder structure. The vault is organized by type:
+Entity type is stored in the `type:` frontmatter field (e.g. `type: Quarter`). The legacy field name `Is A:` is still accepted as an alias for backwards compatibility but new notes use `type:`. The `VaultEntry.isA` property in TypeScript/Rust holds the resolved value.
+
+Type is also inferred from the folder structure when `type:` is absent. The vault is organized by type:
 
 ```
 ~/Laputa/
@@ -47,26 +130,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
+- Have `type: Type` in their frontmatter (`Is A: Type` also accepted as legacy alias)
+- 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 +186,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 +237,61 @@ 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 `type:` frontmatter; `Is A:` accepted as legacy alias)
+   - 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 cache from `~/.laputa/cache/<vault-hash>.json` (external to vault)
+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 atomically (write to `.tmp`, then rename)
+7. On first run, migrates any legacy `.laputa-cache.json` from inside the vault
+
 ### 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 +302,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 +358,206 @@ 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`:
+```mermaid
+flowchart LR
+    A["📄 Raw markdown\n(from disk)"] --> B["splitFrontmatter()\n→ yaml + body"]
+    B --> C["preProcessWikilinks(body)\n[[target]] → ‹token›"]
+    C --> D["tryParseMarkdownToBlocks()\n→ BlockNote block tree"]
+    D --> E["injectWikilinks(blocks)\n‹token› → WikiLink node"]
+    E --> F["editor.replaceBlocks()\n→ rendered editor"]
 
-```
-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
-  → editor.replaceBlocks()
+    style A fill:#f8f9fa,stroke:#6c757d,color:#000
+    style F fill:#d4edda,stroke:#28a745,color:#000
 ```
 
-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)
+
+```mermaid
+flowchart LR
+    A["✏️ BlockNote blocks\n(editor state)"] --> B["blocksToMarkdownLossy()"]
+    B --> C["postProcessWikilinks()\nWikiLink node → [[target]]"]
+    C --> D["prepend frontmatter yaml"]
+    D --> E["invoke('save_note_content')\n→ disk write"]
+
+    style A fill:#cce5ff,stroke:#004085,color:#000
+    style E fill:#d4edda,stroke:#28a745,color:#000
+```
 
 ### 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 `type: Theme` frontmatter. Each property becomes a CSS variable with `--` prefix.
+
+```yaml
+---
+type: 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` (`type`, `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.
+
+## Closed Tab History
+
+`useClosedTabHistory` hook (`src/hooks/useClosedTabHistory.ts`) provides a LIFO stack for closed tab entries, used by `useTabManagement` to support Cmd+Shift+T reopen. Each entry stores the note's path, tab index, and full `VaultEntry`. The stack is in-memory only (resets on restart), capped at 20 entries, and deduplicates by path.
+
+## 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/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 `type: 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 `type: 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()`)

docs/PROJECT-SPEC.md

@@ -263,7 +263,7 @@ M1 passed all tests but showed 0 notes — vault path wrong, error silently swal
 - [x] Tauri v2 + React 19 + TypeScript + Vite 7 project setup
 - [x] Configure Vitest (7 tests), Playwright (2 E2E tests), Rust tests (10 tests)
 - [x] Rust backend: `list_vault` command — scans directory, parses YAML frontmatter via `gray_matter` crate
-- [x] Rust backend: extracts Is A, aliases, Belongs to, Related to, Status, Owner, Cadence, title from H1
+- [x] Rust backend: extracts type (Is A), aliases, Belongs to, Related to, Status, Owner, Cadence, title from H1
 - [x] React: four-panel layout (Sidebar 250px, NoteList 300px, Editor flex, Inspector 280px), all resizable
 - [x] Tauri mock layer for browser testing (`src/mock-tauri.ts`)
 - [x] Screenshot verification via Playwright (`e2e/screenshot.spec.ts`)
@@ -281,7 +281,7 @@ bc75647 Remove unused Vite scaffold files
 ### M2: Sidebar & Note List
 **Goal:** Navigate the vault via sidebar, see filtered note lists.
 - [ ] Sidebar: Filters section (All Notes, Favorites, Trash)
-- [ ] Sidebar: Section Groups (Projects, Experiments, Responsibilities, Procedures) — populated from frontmatter `Is A`
+- [ ] Sidebar: Section Groups (Projects, Experiments, Responsibilities, Procedures) — populated from frontmatter `type:`
 - [ ] Sidebar: Topics — flat list, populated from `Related to` topic links
 - [ ] Note list: show title, preview snippet, date, type indicator
 - [ ] Note list: sort by last modified (descending)
@@ -313,7 +313,7 @@ bc75647 Remove unused Vite scaffold files
 
 ### M5: File Operations & Polish
 **Goal:** Create, rename, delete files. Polish for daily-driver use.
-- [ ] Create new note (with type selector → sets `Is A` and target folder)
+- [ ] Create new note (with type selector → sets `type:` and target folder)
 - [ ] Rename file (updates filename + title)
 - [ ] Delete → move to trash
 - [ ] Keyboard shortcuts (Cmd+N new, Cmd+S save, Cmd+P quick open/search)

docs/ROADMAP.md

@@ -0,0 +1,108 @@
+# Laputa — Product Roadmap
+
+*Strategic directions, not implementation tasks. Each item here represents a direction that will be broken down into many smaller tasks when the time comes.*
+
+*Updated: March 2026.*
+
+---
+
+## Consolidation sprint (current priority)
+
+Before building new features, the architectural foundations must be solid. Key structural fixes underway:
+
+- Move vault cache outside the vault directory (→ `~/.laputa/cache/`) with atomic writes
+- Flip `type:` to canonical field in Rust parser (`Is A:` becomes alias)
+- Remove `allContent` from the architecture — derive backlinks from open tabs only
+- ~~Remove hardcoded `RELATIONSHIP_KEYS` — detect wikilink fields dynamically~~ ✅ Done
+- Fix hardcoded vault path in `resolveNewNote` / `resolveNewType` / `resolveDailyNote`
+- Define and enforce the three-source-of-truth contract (filesystem → cache → React state)
+
+These are not features — they are the foundation everything else is built on.
+
+---
+
+## Strategic directions
+
+### 1. Semantic properties
+
+**What:** Conventional frontmatter field names (`status:`, `url:`, `start_date:`, `end_date:`, `goal:`, `result:`) trigger rich UI rendering beyond the Properties panel — chips in the note list, progress indicators in the editor header, date range badges.
+
+**Why:** Notes are not just documents. A Project has a start and end. A Responsibility has KPIs. A Procedure has an owner and a cadence. The app should surface this structure visually, not just store it as plain text.
+
+**Convention over configuration:** the rendering rules ship as sensible defaults. Users can override via `config/semantic-properties.md` in the vault — a plain markdown file, editable from within the app.
+
+**Draft tasks:** created in Todoist. To be prioritized after consolidation sprint.
+
+---
+
+### 2. Default relationships in Properties panel
+
+**What:** The Properties panel shows a set of relationship fields by default — even when empty — guiding the user toward a connected knowledge graph. Defaults include: Belongs to, Related to, Events, People (Type is already shown).
+
+**Why:** A new note starts with a completely empty Properties panel today. There's no guidance on how to connect it. Laputa is opinionated — it should show you the connections that matter.
+
+**Convention over configuration:** the default list is built in, but can be overridden via `config/relations.md` in the vault.
+
+**Draft tasks:** created in Todoist. Needs design discussion (per-type overrides?) before implementation.
+
+---
+
+### 3. Global workspace filter
+
+**What:** A top-level workspace switcher (below the traffic lights) that filters the entire app — sidebar, note list, search — to show only notes belonging to the selected workspace, plus shared notes (those without a Workspace field).
+
+**Why:** A single vault often contains both personal and work content. A workspace filter lets you focus on one context at a time without cognitive overhead.
+
+**How:** Notes opt into a workspace via `Workspace: [[workspace/refactoring]]` frontmatter. Workspace notes are auto-detected from the `workspace/` folder. No setup required.
+
+**Future trajectory:** Workspaces are the seed of a multi-vault, multi-user access control model. In the future, workspaces may map to separate Git repositories — each with their own access permissions. Different people see different workspaces (vaults). Git provides the audit trail. This enables Laputa to grow from a personal tool to a small-team knowledge base without rebuilding the product.
+
+**Draft tasks:** created in Todoist. Lower priority than semantic properties and default relationships.
+
+---
+
+### 4. Inbox and capture pipeline
+
+**What:** An Inbox section that surfaces all unorganized notes — those with no outgoing relationships. Replaces "All Notes" as the primary landing section. Capture integrations (Chrome extension, iPhone share sheet, Readwise sync) feed into the inbox automatically.
+
+**Why:** Capture and organize are fundamentally different activities and should be treated separately. Today Laputa has no concept of an unorganized note — everything lands in the same pool. The inbox makes the unorganized state visible and actionable, creating a discipline: Inbox Zero, reached weekly.
+
+**The inbox as a smart filter:** not a folder. Any note without `Belongs to:`, `Related to:`, or other meaningful relationship is automatically in the inbox. Connecting a note to something removes it from the inbox, automatically.
+
+**Capture integrations (future, each a separate feature):**
+- Chrome extension → saves URL/clip as a note to the vault via Git
+- iPhone share sheet → quick capture from any app
+- Readwise / Kindle highlights → synced via Git automation
+- Voice memo → transcribed and dropped into inbox
+
+**Priority:** The Inbox UI is high-value and can be implemented without the capture integrations. Integrations come after.
+
+---
+
+### 5. Mobile apps
+
+**What:** Native apps for iPhone and iPad — not ports of the desktop app, but purpose-built for each form factor.
+
+**iPhone:** Optimized for fast capture. Quick note creation, voice memos, brief thoughts. The primary use case is getting something into the vault quickly while away from the desk. Minimal reading and editing.
+
+**iPad:** A more capable mirror of the desktop experience — reading, editing, navigating the vault. Not a full four-panel layout, but enough to work on notes meaningfully. Think "laptop replacement for light work sessions."
+
+**Why it matters:** Laputa's value as a personal knowledge system depends on being able to capture things wherever you are. Without mobile capture, important notes get lost or end up scattered in other apps.
+
+**Sync:** Git-based, same as desktop. The vault is a Git repo — mobile apps commit and pull like any other client.
+
+**Priority:** After the desktop experience is solid. Not before.
+
+---
+
+## Principles for this roadmap
+
+- **Foundations before features** — a shaky architecture multiplies the cost of every feature built on top of it
+- **Convention over configuration** — ship strong defaults, allow customization via vault files
+- **File-first** — every strategic direction must be achievable without breaking the markdown-files-on-disk model
+- **AI-readable by design** — conventions that humans find intuitive should also be legible to AI agents navigating the vault
+
+---
+
+*For active tasks and bugs, see the Todoist board (Laputa App project).*
+*For architectural decisions and design principles, see [ARCHITECTURE.md](./ARCHITECTURE.md) and [VISION.md](./VISION.md).*

docs/VISION.md

@@ -1,156 +1,223 @@
 # Laputa — Product Vision
 
-*Written by Brian based on conversations with Luca Rossi, Feb 2026.*
+*Written by Brian based on conversations with Luca Rossi, Feb–Mar 2026.*
 *This is a living document — update it as the vision evolves.*
 
 ---
 
-## Why Laputa exists
+## Why this, why now, why us
 
-Luca has been doing personal knowledge management since university — long before it had a name. Over the years, through two startups, becoming a CTO, and eventually building Refactoring (a newsletter publishing 2-3 articles/week), note-taking evolved from a nice-to-have to a core part of his work. The ability to synthesize ideas, connect concepts across time, and turn accumulated knowledge into articles reliably every week — this only works with a well-structured system.
+Before the what and how: the why.
 
-For years, that system lived in Notion. But over time, the overlap between what Notion offers and what Luca actually needs started to shrink. Notion became simultaneously too narrow (missing specific things he needed) and too wide (full of flexibility he didn't want). The gap became impossible to ignore when AI entered the picture.
+The best projects are built by people who have an unusually strong answer to "why are you the right person to build this?" This is that answer.
 
-## The core insight: local files + Git = AI-native PKM
+**Luca Rossi** is a startup founder and former generalist CTO — someone who can build a product end-to-end across code, design, scope, and product. And for the last five years, full-time, he has run Refactoring: a technical newsletter with nearly 200,000 subscribers, for which he has written over 300 original articles. In word count, that's roughly two *Lord of the Rings* novels.
 
-The fundamental insight behind Laputa is architectural: **a knowledge base made of local Markdown files, version-controlled with Git, is orders of magnitude more AI-friendly than any SaaS-based system.**
+Personal knowledge management has been an obsession since university. But over the last five years it stopped being a hobby and became *table stakes* — the system that makes writing 300 articles possible. Laputa is an attempt to bottle that system.
 
-Notion's AI struggles with complex workspaces — slow, inaccurate, often failing to understand its own structure. Meanwhile, an AI like Claude or Claude Code working on a local vault of Markdown files can read, edit, and reorganize thousands of documents in seconds, with full comprehension.
+The credibility is real: if you wonder whether this person knows how to organize knowledge for sustained output, the output speaks for itself. The method inside Laputa is not theorized — it's been battle-tested for years at scale.
 
-This isn't a feature — it's a structural advantage that no Notion redesign can fix. The architecture *is* the product.
+**The distribution is built in.** Refactoring reaches ~200,000 engineers, managers, and technical leaders — exactly the people most receptive to a tool like this. The audience already trusts the author on this topic, because they've been reading his writing about knowledge management and learning for years.
 
-Additional benefits that fall out of this choice for free:
-- **Version control**: every change is tracked, diffable, reversible
-- **Open format**: your knowledge is yours, readable by any tool, forever
-- **Remote AI access**: an AI agent can commit to your Git repo from anywhere — your knowledge base becomes programmable
-- **Zero lock-in**: if something better comes along, you leave. The trust between Laputa and the user is earned daily, not enforced by proprietary formats
+This is not a product looking for a market. It's a tool built by its first power user, for an audience that already knows and trusts him.
 
-## Why not just use Obsidian?
+**Why Laputa, in the context of Refactoring.**
+
+Refactoring is a newsletter about how software is built, how teams work, and how digital products are developed — written from Luca's experience and conversations with other tech leaders. A natural question follows: what is the author's own current experience building software with AI?
+
+Laputa answers that question directly and publicly. If it works — if it becomes a real product used by real people — it validates the author's capabilities and authority to write about these topics. Not as theory, but as demonstrated practice. Anyone can look at the GitHub repository, see 100 commits a day, and verify: this person actually does this.
+
+This is why Laputa is **free and open source**: success becomes a reputation and acquisition channel for Refactoring. The attention and trust earned through a well-executed open source project converts — through sponsorships, paid subscriptions, and brand authority — into the business that Refactoring runs on.
+
+The strategy is coherent: build the tool you describe, make the work visible, let the product speak for the author.
+
+---
+
+## The problem
+
+Most people who want to work effectively with AI face a version of the same problem: **they don't have their knowledge organized in a way that AI can actually use.**
+
+They have notes scattered across Notion, Apple Notes, browser bookmarks, and email. Some of it is structured, most of it isn't. Even the people who do maintain a knowledge base discover that AI tools — ChatGPT, Notion AI, others — struggle to navigate it meaningfully. The knowledge is there, but it's not *accessible*.
+
+The problem has two distinct layers:
+
+1. **Architectural**: most knowledge tools store data in proprietary formats on remote servers. AI tools can't read them efficiently, can't commit changes back, can't reason over the full structure. The format itself creates a ceiling.
+
+2. **Methodological**: even with the right tool, most people don't know *how* to organize knowledge so it becomes useful over time — what to capture, how to connect things, how to turn raw notes into a system that works with you instead of against you.
+
+Laputa addresses both layers, together. That's what makes it different.
+
+---
+
+## The insight: tool and method, together
+
+Most PKM tools give you a blank canvas and leave the rest to you. They solve the first problem (somewhere to put things) but not the second (how to organize them). The result is that sophisticated users build complex custom systems, while everyone else gives up.
+
+Laputa's position is different: **we ship the method alongside the tool.**
+
+The method is opinionated but not rigid. It tells you: here's how to think about your work, here's where different kinds of notes belong, here's how to connect them. If it fits your needs — great, start immediately. If your situation is different — customize it. The types, the relationships, the structure can all be changed. But you don't have to figure it out from scratch.
+
+This combination — an opinionated method on top of a technically excellent foundation — is what makes Laputa genuinely useful to people who are stuck, not just people who already know what they're doing.
+
+---
+
+## The method: a framework for knowledge work
+
+### The knowledge ontology
+
+Laputa organizes work around two axes:
+
+|  | **One-time** | **Recurring** |
+|---|---|---|
+| **Multi-session** | **Project** (has a start and end) | **Responsibility** (no end, measured by KPIs) |
+| **Single-session** | *Task* (lives in a task manager) | **Procedure** (checklist, routine) |
+
+Everything else is context:
+- **Notes** — the atomic unit. Any note connects to one or more of the above.
+- **Topics** — areas of interest with no performance expectation. A knowledge repository.
+- **Events** — things that happened, anchored to a date.
+- **People** — contacts and their history.
+
+Relations between notes are first-class citizens — not just wiki-links, but typed, bidirectional connections that make the knowledge graph navigable.
+
+This ontology is not arbitrary. It maps cleanly to how both individuals and organizations actually structure their work: companies have projects, responsibilities, procedures, and people. So do independent creators. So do individuals managing their lives.
+
+### Knowledge has a purpose
+
+A principle that underlies everything in Laputa: **notes exist to get things done.** Not to be stored for some abstract future use. Not to show how organized you are. To do something.
+
+This is the difference between a knowledge system that works over years and one that collapses after a few weeks. Without a real purpose, the maintenance cost of taking notes is never justified, and people stop. With a purpose — writing regularly, building things, making decisions — the system pays for itself.
+
+What you *do* with organized knowledge depends on who you are:
+
+- **Writers and content creators** — the output is articles, essays, posts. Captures become highlights, highlights become **evergreen notes** (small, atomic, timeless ideas), evergreen notes become building blocks for articles. Evergreen notes are a middle layer: not the raw input, not the final output, but the refined reusable units that make writing easier and faster.
+- **Builders and project-driven people** — the output is shipped work. Captures feed projects, decisions, and procedures. Evergreen notes matter less; the project knowledge graph matters more.
+- **Operators and managers** — the output is better systems and decisions. Captures feed responsibilities (KPIs, workflows) and procedures (how we do things). The value accumulates in the recurring structure, not in individual notes.
+
+The framework is flexible enough to fit all three — and most people are a mix. What stays constant is the flow: **capture → organize → express**. The *what* of expressing changes; the discipline doesn't.
+
+### The two-phase workflow: capture and organize
+
+Notes move through two distinct phases, and the transition between them is intentional.
+
+**Capture** — fast, frictionless, available everywhere. A thought, a saved article, a Kindle highlight, a voice memo. The cardinal rule: never let friction during capture cause a good idea to be lost. Captured notes land in the vault unconnected — no relationships, no organization. That's fine. That's the point.
+
+**Organize** — a deliberate, periodic activity (weekly is the natural cadence). You ask: *what is this useful for?* Many things that seemed important when captured won't survive this question — deleting >50% of captures is normal and healthy. For the things that survive: connect them. Link to a Project, a Responsibility, a Topic. Every note should eventually connect to at least one actionable container. If you can't connect something to anything, that's a signal worth paying attention to.
+
+**The Inbox** is the UI expression of this split: a smart section that shows all unorganized notes — those with no outgoing relationships. The goal is Inbox Zero, reached periodically (weekly). The inbox is not a folder; it's a derived state. Connecting a note to something removes it automatically.
+
+### Convention over configuration
+
+The method lives in the app as *conventions*: standard field names and folder structures that have well-defined meanings and trigger specific behavior.
+
+`status:` shows a colored chip. `Workspace: [[workspace/refactoring]]` assigns a note to a context. `Belongs to:` connects it to its parent. `start_date:` and `end_date:` show a duration badge. The app recognizes these by convention, without any setup.
+
+Users who want more can override the defaults: `config/relations.md` changes which relationship fields appear by default; `config/semantic-properties.md` controls how fields are rendered. But the defaults work immediately, for everyone.
+
+This is convention *over* configuration — not convention *instead of* it.
+
+---
+
+## The foundation: architecture that earns trust
+
+The method is only as good as the system it runs on. Laputa's architecture is built around a single principle: **your knowledge is yours, permanently and unconditionally.**
+
+### Local files, version-controlled with Git
+
+Every note is a plain Markdown file on your disk. There is no database, no proprietary format, no sync lock-in. The files are readable by any tool that can open a text file — today and in twenty years.
+
+Git provides version control: every change is tracked, diffable, reversible. You have a full audit trail of what changed, when, and why. Collaboration happens via Git — the same way software teams have collaborated for decades, without any proprietary cloud in between.
+
+### AI-native by design
+
+A vault of plain Markdown files, version-controlled with Git, is dramatically more AI-friendly than any SaaS-based system.
+
+An AI agent working on a local vault can read thousands of notes in seconds, understand their structure, write new ones, connect existing ones, and commit the changes back — all with full comprehension. Notion's AI can't do this. No SaaS-based AI can do this, because the architecture doesn't allow it.
+
+More importantly: the more a vault follows Laputa's conventions, the *less configuration an AI needs* to navigate it. Shared conventions make knowledge legible to both humans and AI without bespoke instructions for every setup. The method and the AI-native architecture reinforce each other.
+
+### Open and exit-friendly
+
+The trust between Laputa and the user is earned daily, not enforced by format. If something better comes along, you take your Markdown files and leave. The exit door is always open.
+
+---
+
+## Why not Obsidian?
 
 Obsidian is the obvious comparison. The difference is philosophy:
 
-- **Obsidian** is a blank canvas. Infinitely configurable via plugins, themes, and community extensions. Great for power users who want to build their own system from scratch.
-- **Laputa** is opinionated. It ships with a point of view on how to organize knowledge, with sensible defaults that work out of the box — no plugin hunting required.
+- **Obsidian** is a blank canvas. Infinitely configurable via plugins and community extensions. Powerful for users who want to build their own system — and who have the time and patience to do so.
+- **Laputa** is opinionated. It ships with a complete point of view: a knowledge framework, semantic conventions, and defaults that work immediately. No plugin hunting. No configuration required to get started.
 
-Obsidian also treats Git as an afterthought (its business model is built around proprietary sync). In Laputa, **Git is a first-class citizen** — the obvious, natural way to sync and collaborate.
+Obsidian also treats Git as an afterthought — its business model is built around proprietary sync. In Laputa, Git is a first-class citizen: the natural, obvious way to sync, collaborate, and maintain history.
 
-## The knowledge ontology
+---
 
-Laputa is built around a clear conceptual model, inspired by PARA but adapted to Luca's real-world usage:
+## Who it's for, and where it's going
 
-**Two axes:**
-1. *One-time* vs *recurring*
-2. *Single-session* vs *multi-session*
+### Three stages of adoption
 
-**Four action types:**
-- **Projects** — one-time, multi-session (have a start and end)
-- **Responsibilities** — recurring, multi-session (no end, measured by KPIs)
-- **Tasks** — one-time, single-session (live in Todoist)
-- **Procedures** — recurring, single-session (checklists, routines)
+Laputa is designed to grow through three natural stages — not pivots, but extensions of the same foundation:
 
-**Knowledge containers:**
-- **Notes** — the atomic unit. Can belong to any of the above.
-- **Topics** — areas of interest with no performance expectation (like labels/tags). E.g. "front-end engineering", "interior design"
-- **Events** — things that happened, tied to a date
-- **People** — contacts, with a log of interactions
+**Stage 1: Personal PKM + AI context** *(current)*
+A single person manages their knowledge, life, and work in a local vault. The primary collaborator is AI. The vault gives structure to one person's context, making it legible to an AI that can assist meaningfully across all areas of work and life. The method helps structure the knowledge; the AI helps use it.
 
-**Relations** between notes are first-class citizens — not just wiki-links, but typed, bidirectional connections.
+**Stage 2: Independent knowledge workers**
+Content creators, freelancers, consultants. People with maximum incentive *and* maximum agency to build a real system. They have projects, clients, responsibilities — and they work alone or in very small teams. The same ontology applies: a newsletter creator has editorial projects, a subscriber-growth responsibility, and a publishing procedure. AI collaboration deepens: the AI can see not just personal notes but client commitments, content pipelines, recurring workflows.
 
-## The deeper mission: AI context scaffolding
+**Stage 3: Small teams**
+The ontology scales to organizations. Companies have projects, responsibilities, procedures, and people — the same categories, at a larger scale. The access model changes: different people see different subsets of the vault, via workspace filtering and Git-based access control. Version history gives teams a full audit trail. AI agents become shared collaborators on team knowledge, not just personal assistants.
 
-Most people today can't effectively share context about their lives with AI. They don't know what to write, how to structure it, or when. The result is that AI assistants — even the best ones — are working with a fraction of the context they need.
+**What makes this trajectory coherent:** the foundational model — local files, Git-versioned, structured by conventions — doesn't need to be rebuilt at each stage. It extends naturally.
 
-Laputa's goal is not just to be an efficient place to store things. It's to provide **scaffolding that makes it easy for people to externalize their knowledge in a structured, AI-readable way** — without having to figure out the system themselves.
+### The right early adopters
 
-The vision: a person who uses Laputa well has built a second brain that any AI can read, reason over, and contribute to. Not the naive "memory" that ChatGPT builds from chat history — but an intentional, curated, structured representation of their work and life.
-
-## Target user (v1)
-
-Developers and technically-minded knowledge workers who:
-- Are frustrated with Notion's complexity or performance
+The first users who will get the most from Laputa are technically-minded individuals who:
+- Are frustrated with Notion's performance, complexity, or lock-in
 - Understand or are comfortable with Git
 - Want a system that's AI-native by design, not by bolted-on features
-- Value owning their data and formats
+- Value owning their data
 
-Broader audiences (non-developers) are a future consideration — they'll need more onboarding and scaffolding to get started, but the underlying model is designed to work for anyone.
+Broader audiences will follow as the onboarding experience matures and the conventions become easier to adopt.
+
+---
 
 ## Current state
 
-A living snapshot of what's built vs what's missing. Updated as features ship.
+A living snapshot of what's built. Updated as features ship.
 
-### ✅ What's working today
+### ✅ Working today
 
-**Core editor & notes**
-- BlockNote-based editor (block-style, Notion-like) with Markdown files on disk
-- Cmd+S save with dirty state indicator (orange dot = modified, green dot = new)
-- Word count (frontmatter excluded)
-- Rename note by double-clicking tab
-- Drag & drop images into editor
-- Wiki-links with `[[` autocomplete (2+ chars, max 20 results, colored by note type)
-
-**Navigation & layout**
+- BlockNote editor with Markdown files on disk; Cmd+S save; dirty state indicator
 - 4-panel layout: sidebar / note list / editor / inspector
-- Collapsible sidebar and note list (Cmd+1/2/3)
-- Tabs with drag-to-reorder
-- Quick open (Cmd+P) by title
-- Virtual list rendering for NoteList (handles 9000+ notes without lag)
+- Tabs with drag-to-reorder; quick open (Cmd+P); virtual list (handles 9000+ notes)
+- `type:` as canonical frontmatter field; inspector with editable properties
+- Bidirectional relationships; editable relation chips; wikilink autocomplete (`[[`)
+- Sidebar sections with custom icons and colors
+- Git integration: commit & push, version history per note, dirty state tracking
+- Dynamic vault picker; create or clone vaults from GitHub
+- GitHub OAuth (device flow); AI chat panel; Claude CLI agent panel
+- Auto-updater; universal macOS binary; CI with coverage gates
 
-**Properties & types**
-- Inspector panel with editable vs read-only properties
-- Change note type from Inspector (picker/dropdown)
-- Property value text consistent at 12px
-- URL properties: click to open in browser, underline on hover
-- Bidirectional relationships (Referenced By panel)
-- Editable relations: add/remove linked notes
-- `type:` as canonical key (removed `is a:` property)
+### 🚧 Ahead (consolidation sprint → features)
 
-**Sections & customization**
-- Sidebar sections with custom icons (290 Phosphor icons, searchable) and colors
-- Changes view: click "N pending" in status bar → filtered list of modified notes
+**Consolidation sprint (current):**
+Fixing architectural foundations before building further — cache model, type field canonicalization, allContent removal, hardcoded paths.
 
-**Git integration**
-- Commit & push from within the app (saves pending changes first)
-- Modified files indicator in status bar, NoteList, and TabBar
-- Git history per note (version history)
-- Dirty state clears correctly after save/rename
+**Next features:**
+Inbox section, semantic properties (status chips, progress indicators), default relationships in properties panel, workspace filter, mobile apps (iPhone for capture, iPad as desktop mirror).
 
-**Vault management**
-- Dynamic vault picker (no hardcoded paths)
-- Create new local vault or clone/create from GitHub repo
-- GitHub OAuth login (device flow)
+*For the full roadmap, see [ROADMAP.md](./ROADMAP.md).*
 
-**Settings & infrastructure**
-- Settings panel (Cmd+,): AI provider API keys, stored in app_config_dir
-- In-app auto-updater (Tauri updater + GitHub Releases)
-- CI: lint, TypeScript, tests (84% frontend coverage, 85%+ Rust), CodeScene ≥9.2
-- Universal macOS binary, auto-released on every merge to main
-
-### 🚧 What's missing (Open tasks)
-
-**Bugs**
-- Word count still including some frontmatter in edge cases (under investigation)
-
-**Improvements**
-- Date picker for date-type properties
-- Vista Changes: differentiate new vs modified more clearly
-- Relation editing UX polish
-
-**Features (prioritized)**
-- Full-text search with semantic support (qmd integration)
-- Command palette (Cmd+K) — Raycast-style actions
-- `mock-tauri.ts` and `App.tsx` refactor (code health)
-
-**Vision-level features (not started)**
-- Onboarding / getting started flow with default note types
-- AI-powered features (search, summarization, linking suggestions)
-- Graph view
-- Mobile / web access via Git remote
+---
 
 ## Design principles
 
-1. **Opinionated but not rigid** — ship strong defaults, allow customization where it matters
-2. **Git-first** — sync, history, and collaboration via Git; no proprietary cloud
-3. **AI-native architecture** — local files, open formats, readable by any AI tool
-4. **Zero lock-in** — earn trust daily; the exit door is always open
-5. **Ready out of the box** — no plugin hunting, no theme configuration; it just works
-6. **Relations as first-class citizens** — connections between notes are as important as the notes themselves
+1. **Opinionated but not rigid** — ship the method and the defaults; allow customization where it matters
+2. **Convention over configuration** — standard field names trigger rich behavior automatically; users can override via vault config files
+3. **Git-first** — sync, history, collaboration, and audit trail via Git; no proprietary cloud
+4. **AI-native architecture** — local files, open formats, structured by conventions legible to both humans and AI
+5. **Zero lock-in** — earn trust daily; the exit door is always open
+6. **Capture and organize are separate** — the inbox makes unorganized notes visible; Inbox Zero is the discipline
+7. **Relations as first-class citizens** — connections between notes are as important as the notes themselves
+8. **Filesystem as the single source of truth** — the app never owns the data; cache and UI state are always derived and reconstructible

mcp-server/index.js

@@ -10,6 +10,8 @@
  *   - 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'
@@ -94,6 +96,28 @@ const TOOLS = [
       required: ['path'],
     },
   },
+  {
+    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: {
+        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: 'refresh_vault',
+    description: 'Trigger a vault rescan so new or modified files appear immediately in the Laputa note list.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Optional specific note path that changed' },
+      },
+    },
+  },
 ]
 
 const TOOL_HANDLERS = {
@@ -101,6 +125,8 @@ const TOOL_HANDLERS = {
   get_vault_context: handleVaultContext,
   get_note: handleGetNote,
   open_note: handleOpenNote,
+  highlight_editor: handleHighlightEditor,
+  refresh_vault: handleRefreshVault,
 }
 
 async function handleSearchNotes(args) {
@@ -122,14 +148,27 @@ async function handleGetNote(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 ${args.path} in Laputa` }] }
 }
 
+function handleHighlightEditor(args) {
+  broadcastUiAction('highlight', { element: args.element, path: args.path })
+  return { content: [{ type: 'text', text: `Highlighting ${args.element}` }] }
+}
+
+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.2.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

@@ -107,11 +107,22 @@ export async function vaultContext(vaultPath) {
   notesWithMtime.sort((a, b) => b.mtime - a.mtime)
   const recentNotes = notesWithMtime.slice(0, 20).map(({ mtime: _mtime, ...rest }) => rest)
 
+  // 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,
   }
 }

mcp-server/ws-bridge.js

@@ -46,10 +46,12 @@ const TOOL_HANDLERS = {
   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),
   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', { 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) {

package.json

@@ -13,6 +13,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "playwright test",
+    "playwright:smoke": "playwright test tests/smoke/",
+    "playwright:integration": "playwright test --config playwright.integration.config.ts",
     "test:coverage": "vitest run --coverage",
     "prepare": "husky"
   },
@@ -72,6 +74,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 +88,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: 1,
   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,
   },
 })

playwright.integration.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './tests/integration',
+  timeout: 30_000,
+  retries: 1,
+  workers: 1,
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:5365',
+    headless: true,
+  },
+  projects: [{ name: 'chromium', use: { browserName: 'chromium' } }],
+  webServer: {
+    command: `pnpm dev --port ${process.env.BASE_URL?.match(/:(\d+)/)?.[1] || '5365'}`,
+    url: process.env.BASE_URL || 'http://localhost:5365',
+    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

src-tauri/src/commands.rs

@@ -0,0 +1,787 @@
+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::{MoveResult, 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,
+    old_title: Option<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, old_title.as_deref())
+}
+
+#[tauri::command]
+pub fn move_note_to_type_folder(
+    vault_path: String,
+    note_path: String,
+    new_type: String,
+) -> Result<MoveResult, String> {
+    let vault_path = expand_tilde(&vault_path);
+    let note_path = expand_tilde(&note_path);
+    vault::move_note_to_type_folder(&vault_path, &note_path, &new_type)
+}
+
+#[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 batch_delete_notes(paths: Vec<String>) -> Result<Vec<String>, String> {
+    let expanded: Vec<String> = paths.iter().map(|p| expand_tilde(p).into_owned()).collect();
+    vault::batch_delete_notes(&expanded)
+}
+
+#[tauri::command]
+pub fn empty_trash(vault_path: String) -> Result<Vec<String>, String> {
+    let vault_path = expand_tilde(&vault_path);
+    vault::empty_trash(&vault_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 reload_vault(path: String) -> Result<Vec<VaultEntry>, String> {
+    let path = expand_tilde(&path);
+    vault::invalidate_cache(std::path::Path::new(path.as_ref()));
+    vault::scan_vault_cached(std::path::Path::new(path.as_ref()))
+}
+
+#[tauri::command]
+pub fn reload_vault_entry(path: String) -> Result<VaultEntry, String> {
+    let path = expand_tilde(&path);
+    vault::reload_entry(std::path::Path::new(path.as_ref()))
+}
+
+#[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_reload_vault_entry_reads_from_disk() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let note = dir.path().join("note.md");
+        std::fs::write(&note, "---\nStatus: Active\n---\n# Test\n").unwrap();
+
+        let entry = reload_vault_entry(note.to_str().unwrap().to_string()).unwrap();
+        assert_eq!(entry.title, "Test");
+        assert_eq!(entry.status, Some("Active".to_string()));
+
+        // Modify file on disk
+        std::fs::write(&note, "---\nStatus: Done\n---\n# Test\n").unwrap();
+        let fresh = reload_vault_entry(note.to_str().unwrap().to_string()).unwrap();
+        assert_eq!(fresh.status, Some("Done".to_string()));
+    }
+
+    #[test]
+    fn test_reload_vault_entry_nonexistent() {
+        let result = reload_vault_entry("/nonexistent/path.md".to_string());
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_reload_vault_invalidates_cache_and_rescans() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let vault = dir.path();
+        // Init git repo for caching to work
+        std::process::Command::new("git")
+            .args(["init"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        std::process::Command::new("git")
+            .args(["config", "user.email", "t@t.com"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        std::process::Command::new("git")
+            .args(["config", "user.name", "T"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        // Set test cache dir to avoid polluting real cache
+        let cache_dir = tempfile::TempDir::new().unwrap();
+        std::env::set_var(
+            "LAPUTA_CACHE_DIR",
+            cache_dir.path().to_string_lossy().as_ref(),
+        );
+
+        std::fs::write(vault.join("note.md"), "---\nTrashed: false\n---\n# Note\n").unwrap();
+        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 via list_vault
+        let entries = list_vault(vault.to_str().unwrap().to_string()).unwrap();
+        assert!(!entries[0].trashed);
+
+        // Trash the note on disk
+        std::fs::write(vault.join("note.md"), "---\nTrashed: true\n---\n# Note\n").unwrap();
+
+        // reload_vault must return the updated trashed state
+        let fresh = reload_vault(vault.to_str().unwrap().to_string()).unwrap();
+        assert!(
+            fresh[0].trashed,
+            "reload_vault must reflect disk state after trashing"
+        );
+    }
+
+    #[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/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() {
+        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/settings.json"),
+            ".gitignore should exclude settings.json"
+        );
+        // Cache is now stored outside the vault — no need for .gitignore entry
+        assert!(
+            !content.contains(".laputa-cache.json"),
+            ".gitignore should NOT contain .laputa-cache.json (cache is external)"
+        );
+    }
+
+    #[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,4 +1,4 @@
-use serde::Serialize;
+use serde::{Deserialize, Serialize};
 use std::path::{Path, PathBuf};
 use std::process::Command;
 use std::sync::Mutex;
@@ -223,10 +223,72 @@ 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 meta = load_index_metadata(vault_path);
+
     let qmd = match find_qmd_binary() {
         Some(b) => b,
         None => {
@@ -237,6 +299,8 @@ 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,
             }
         }
     };
@@ -244,7 +308,7 @@ pub fn check_index_status(vault_path: &str) -> IndexStatus {
     let vault_name = vault_dir_name(vault_path);
     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)
@@ -256,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 {
@@ -323,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,
     }
 }
 
@@ -392,7 +464,9 @@ where
 
     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,
@@ -403,7 +477,7 @@ where
 
     let update_output = qmd
         .command()
-        .args(["update"])
+        .args(["update", &vault_name])
         .output()
         .map_err(|e| format!("qmd update failed: {e}"))?;
 
@@ -432,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,
@@ -443,7 +517,7 @@ where
 
     let embed_output = qmd
         .command()
-        .args(["embed"])
+        .args(["embed", "-c", &vault_name])
         .output()
         .map_err(|e| format!("qmd embed failed: {e}"))?;
 
@@ -451,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,
@@ -461,6 +536,8 @@ where
         return Ok(());
     }
 
+    stamp_index_commit(vault_path);
+
     on_progress(IndexingProgress {
         phase: "complete".to_string(),
         current: total,
@@ -504,7 +581,7 @@ pub fn run_incremental_update(vault_path: &str) -> Result<(), String> {
 
     let output = qmd
         .command()
-        .args(["update"])
+        .args(["update", &vault_name])
         .output()
         .map_err(|e| format!("qmd incremental update failed: {e}"))?;
 
@@ -513,9 +590,23 @@ pub fn run_incremental_update(vault_path: &str) -> Result<(), String> {
         return Err(format!("qmd update failed: {stderr}"));
     }
 
+    stamp_index_commit(vault_path);
+
     Ok(())
 }
 
+/// 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,
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -698,4 +789,126 @@ Collections
         // 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;
@@ -13,544 +14,11 @@ 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, PulseCommit};
-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_config::VaultConfig;
-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 get_vault_pulse(vault_path: String, limit: Option<usize>) -> Result<Vec<PulseCommit>, String> {
-    let vault_path = expand_tilde(&vault_path);
-    let limit = limit.unwrap_or(30);
-    git::get_vault_pulse(&vault_path, limit)
-}
-
-#[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 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]
-fn get_conflict_mode(vault_path: String) -> String {
-    let vault_path = expand_tilde(&vault_path);
-    git::get_conflict_mode(&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,
-    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]
-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)
-}
-
-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()),
-        },
-    );
-}
-
-#[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 || {
-        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]
-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]
-async fn check_mcp_status() -> Result<mcp::McpStatus, String> {
-    tokio::task::spawn_blocking(mcp::check_mcp_status)
-        .await
-        .map_err(|e| format!("MCP status check 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)
-}
-
-#[tauri::command]
-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]
-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]
-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)
-}
-
 fn log_startup_result(label: &str, result: Result<usize, String>) {
     match result {
         Ok(n) if n > 0 => log::info!("{}: {} files", label, n),
@@ -576,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) {
@@ -589,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()
@@ -670,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())?;
@@ -693,68 +112,74 @@ 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,
-            get_vault_pulse,
-            git_commit,
-            get_build_number,
-            get_last_commit_info,
-            git_pull,
-            git_push,
-            get_conflict_files,
-            get_conflict_mode,
-            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,
-            check_mcp_status,
-            list_themes,
-            get_theme,
-            get_vault_settings,
-            save_vault_settings,
-            set_active_theme,
-            create_theme,
-            create_vault_theme,
-            ensure_vault_themes,
-            restore_default_themes,
-            get_vault_config,
-            save_vault_config
+            commands::list_vault,
+            commands::get_note_content,
+            commands::save_note_content,
+            commands::update_frontmatter,
+            commands::delete_frontmatter_property,
+            commands::rename_note,
+            commands::move_note_to_type_folder,
+            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::reload_vault,
+            commands::reload_vault_entry,
+            commands::save_image,
+            commands::copy_image_to_vault,
+            commands::purge_trash,
+            commands::delete_note,
+            commands::batch_delete_notes,
+            commands::empty_trash,
+            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/menu.rs

@@ -13,6 +13,7 @@ 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 FILE_REOPEN_CLOSED_TAB: &str = "file-reopen-closed-tab";
 
 const EDIT_FIND_IN_VAULT: &str = "edit-find-in-vault";
 const EDIT_TOGGLE_RAW_EDITOR: &str = "edit-toggle-raw-editor";
@@ -32,13 +33,13 @@ const VIEW_GO_BACK: &str = "view-go-back";
 const VIEW_GO_FORWARD: &str = "view-go-forward";
 
 const GO_ALL_NOTES: &str = "go-all-notes";
-const GO_FAVORITES: &str = "go-favorites";
 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 NOTE_EMPTY_TRASH: &str = "note-empty-trash";
 
 const VAULT_OPEN: &str = "vault-open";
 const VAULT_REMOVE: &str = "vault-remove";
@@ -49,6 +50,9 @@ 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_RELOAD: &str = "vault-reload";
+const VAULT_REPAIR: &str = "vault-repair";
 
 const CUSTOM_IDS: &[&str] = &[
     APP_SETTINGS,
@@ -59,6 +63,7 @@ const CUSTOM_IDS: &[&str] = &[
     FILE_QUICK_OPEN,
     FILE_SAVE,
     FILE_CLOSE_TAB,
+    FILE_REOPEN_CLOSED_TAB,
     EDIT_FIND_IN_VAULT,
     EDIT_TOGGLE_RAW_EDITOR,
     EDIT_TOGGLE_DIFF,
@@ -75,12 +80,12 @@ const CUSTOM_IDS: &[&str] = &[
     VIEW_GO_BACK,
     VIEW_GO_FORWARD,
     GO_ALL_NOTES,
-    GO_FAVORITES,
     GO_ARCHIVED,
     GO_TRASH,
     GO_CHANGES,
     NOTE_ARCHIVE,
     NOTE_TRASH,
+    NOTE_EMPTY_TRASH,
     VAULT_OPEN,
     VAULT_REMOVE,
     VAULT_RESTORE_GETTING_STARTED,
@@ -90,6 +95,9 @@ const CUSTOM_IDS: &[&str] = &[
     VAULT_RESOLVE_CONFLICTS,
     VAULT_VIEW_CHANGES,
     VAULT_INSTALL_MCP,
+    VAULT_REINDEX,
+    VAULT_RELOAD,
+    VAULT_REPAIR,
 ];
 
 /// IDs of menu items that should be disabled when no note tab is active.
@@ -161,6 +169,10 @@ fn build_file_menu(app: &App) -> MenuResult {
         .id(FILE_CLOSE_TAB)
         .accelerator("CmdOrCtrl+W")
         .build(app)?;
+    let reopen_closed_tab = MenuItemBuilder::new("Reopen Closed Tab")
+        .id(FILE_REOPEN_CLOSED_TAB)
+        .accelerator("CmdOrCtrl+Shift+T")
+        .build(app)?;
 
     Ok(SubmenuBuilder::new(app, "File")
         .item(&new_note)
@@ -170,6 +182,7 @@ fn build_file_menu(app: &App) -> MenuResult {
         .separator()
         .item(&save)
         .item(&close_tab)
+        .item(&reopen_closed_tab)
         .build()?)
 }
 
@@ -249,9 +262,6 @@ fn build_go_menu(app: &App) -> MenuResult {
     let all_notes = MenuItemBuilder::new("All Notes")
         .id(GO_ALL_NOTES)
         .build(app)?;
-    let favorites = MenuItemBuilder::new("Favorites")
-        .id(GO_FAVORITES)
-        .build(app)?;
     let archived = MenuItemBuilder::new("Archived")
         .id(GO_ARCHIVED)
         .build(app)?;
@@ -268,7 +278,6 @@ fn build_go_menu(app: &App) -> MenuResult {
 
     Ok(SubmenuBuilder::new(app, "Go")
         .item(&all_notes)
-        .item(&favorites)
         .item(&archived)
         .item(&trash)
         .item(&changes)
@@ -287,6 +296,9 @@ fn build_note_menu(app: &App) -> MenuResult {
         .id(NOTE_TRASH)
         .accelerator("CmdOrCtrl+Backspace")
         .build(app)?;
+    let empty_trash = MenuItemBuilder::new("Empty Trash…")
+        .id(NOTE_EMPTY_TRASH)
+        .build(app)?;
     let toggle_raw_editor = MenuItemBuilder::new("Toggle Raw Editor")
         .id(EDIT_TOGGLE_RAW_EDITOR)
         .accelerator("CmdOrCtrl+\\")
@@ -302,6 +314,7 @@ fn build_note_menu(app: &App) -> MenuResult {
     Ok(SubmenuBuilder::new(app, "Note")
         .item(&archive_note)
         .item(&trash_note)
+        .item(&empty_trash)
         .separator()
         .item(&toggle_raw_editor)
         .item(&toggle_ai_chat)
@@ -335,9 +348,18 @@ fn build_vault_menu(app: &App) -> MenuResult {
     let view_changes = MenuItemBuilder::new("View Pending Changes")
         .id(VAULT_VIEW_CHANGES)
         .build(app)?;
-    let install_mcp = MenuItemBuilder::new("Install MCP Server")
+    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 reload = MenuItemBuilder::new("Reload Vault")
+        .id(VAULT_RELOAD)
+        .build(app)?;
+    let repair = MenuItemBuilder::new("Repair Vault")
+        .id(VAULT_REPAIR)
+        .build(app)?;
 
     Ok(SubmenuBuilder::new(app, "Vault")
         .item(&open_vault)
@@ -351,6 +373,9 @@ fn build_vault_menu(app: &App) -> MenuResult {
         .item(&resolve_conflicts)
         .item(&view_changes)
         .separator()
+        .item(&reindex)
+        .item(&reload)
+        .item(&repair)
         .item(&install_mcp)
         .build()?)
 }
@@ -454,12 +479,12 @@ mod tests {
             VIEW_GO_BACK,
             VIEW_GO_FORWARD,
             GO_ALL_NOTES,
-            GO_FAVORITES,
             GO_ARCHIVED,
             GO_TRASH,
             GO_CHANGES,
             NOTE_ARCHIVE,
             NOTE_TRASH,
+            NOTE_EMPTY_TRASH,
             VAULT_OPEN,
             VAULT_REMOVE,
             VAULT_RESTORE_GETTING_STARTED,
@@ -469,6 +494,8 @@ mod tests {
             VAULT_RESOLVE_CONFLICTS,
             VAULT_VIEW_CHANGES,
             VAULT_INSTALL_MCP,
+            VAULT_REINDEX,
+            VAULT_RELOAD,
         ];
         for id in &expected {
             assert!(CUSTOM_IDS.contains(id), "missing custom ID: {id}");

src-tauri/src/search.rs

@@ -1,4 +1,5 @@
 use crate::indexing;
+use crate::vault;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::path::Path;
@@ -160,16 +161,19 @@ pub fn search_vault(
 
     let results: Vec<SearchResult> = qmd_results
         .into_iter()
-        .map(|r| {
+        .filter_map(|r| {
             let path = qmd_uri_to_vault_path(&r.file, vault_path);
+            if vault::is_file_trashed(Path::new(&path)) {
+                return None;
+            }
             let snippet = extract_clean_snippet(&r.snippet);
-            SearchResult {
+            Some(SearchResult {
                 title: r.title,
                 path,
                 snippet,
                 score: r.score,
                 note_type: None,
-            }
+            })
         })
         .collect();
 

src-tauri/src/theme/create.rs

@@ -0,0 +1,301 @@
+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(',') || 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");
+    }
+
+    #[test]
+    fn test_create_vault_theme_contains_all_default_css_vars() {
+        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("Full Theme")).unwrap();
+        let content = fs::read_to_string(&path).unwrap();
+
+        // Every entry in DEFAULT_VAULT_THEME_VARS must appear in the generated file
+        for (key, _) in &DEFAULT_VAULT_THEME_VARS {
+            assert!(
+                content.contains(&format!("{key}:")),
+                "missing key in theme file: {key}"
+            );
+        }
+
+        // Spot-check editor properties from theme.json that were previously missing
+        assert!(
+            content.contains("editor-font-family:"),
+            "missing editor-font-family"
+        );
+        assert!(
+            content.contains("editor-padding-horizontal:"),
+            "missing editor-padding-horizontal"
+        );
+        assert!(
+            content.contains("headings-h1-font-size:"),
+            "missing headings-h1-font-size"
+        );
+        assert!(
+            content.contains("lists-bullet-size:"),
+            "missing lists-bullet-size"
+        );
+        assert!(
+            content.contains("lists-bullet-color:"),
+            "missing lists-bullet-color"
+        );
+        assert!(
+            content.contains("checkboxes-size:"),
+            "missing checkboxes-size"
+        );
+        assert!(
+            content.contains("inline-styles-bold-font-weight:"),
+            "missing inline-styles-bold-font-weight"
+        );
+        assert!(
+            content.contains("code-blocks-font-family:"),
+            "missing code-blocks-font-family"
+        );
+        assert!(
+            content.contains("blockquote-border-left-width:"),
+            "missing blockquote-border-left-width"
+        );
+        assert!(
+            content.contains("table-border-color:"),
+            "missing table-border-color"
+        );
+        assert!(
+            content.contains("horizontal-rule-thickness:"),
+            "missing horizontal-rule-thickness"
+        );
+        assert!(content.contains("colors-text:"), "missing colors-text");
+        assert!(content.contains("colors-cursor:"), "missing colors-cursor");
+
+        // Numeric values that need CSS units must have px suffix
+        assert!(
+            content.contains("editor-font-size: 15px"),
+            "editor-font-size should have px unit"
+        );
+        assert!(
+            content.contains("editor-max-width: 720px"),
+            "editor-max-width should have px unit"
+        );
+        assert!(
+            content.contains("editor-padding-horizontal: 40px"),
+            "editor-padding-horizontal should have px unit"
+        );
+    }
+}

src-tauri/src/theme/defaults.rs

@@ -0,0 +1,453 @@
+/// 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"
+  }
+}"##;
+
+// ---------------------------------------------------------------------------
+// Vault-based theme notes (markdown with frontmatter CSS custom properties)
+// ---------------------------------------------------------------------------
+
+/// Complete set of CSS variable key-value pairs for the default light vault theme.
+/// Includes both UI chrome colours and all editor styling properties from theme.json.
+/// Numeric values that need CSS units include the `px` suffix; unitless values
+/// (line-height, font-weight) are bare numbers.
+pub const DEFAULT_VAULT_THEME_VARS: [(&str, &str); 140] = [
+    // ── shadcn/ui base colours ──────────────────────────────────────────
+    ("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-tertiary", "#B4B4B4"),
+    ("text-muted", "#B4B4B4"),
+    ("text-heading", "#37352F"),
+    // ── Backgrounds ─────────────────────────────────────────────────────
+    ("bg-primary", "#FFFFFF"),
+    ("bg-card", "#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 base ─────────────────────────────────────────────────
+    (
+        "font-family",
+        "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
+    ),
+    ("font-size-base", "14px"),
+    // ── Editor (from theme.json → editor) ───────────────────────────────
+    (
+        "editor-font-family",
+        "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
+    ),
+    ("editor-font-size", "15px"),
+    ("editor-line-height", "1.5"),
+    ("editor-max-width", "720px"),
+    ("editor-padding-horizontal", "40px"),
+    ("editor-padding-vertical", "20px"),
+    ("editor-paragraph-spacing", "8px"),
+    // ── Headings H1 ────────────────────────────────────────────────────
+    ("headings-h1-font-size", "32px"),
+    ("headings-h1-font-weight", "700"),
+    ("headings-h1-line-height", "1.2"),
+    ("headings-h1-margin-top", "32px"),
+    ("headings-h1-margin-bottom", "12px"),
+    ("headings-h1-color", "var(--text-heading)"),
+    ("headings-h1-letter-spacing", "-0.5px"),
+    // ── Headings H2 ────────────────────────────────────────────────────
+    ("headings-h2-font-size", "27px"),
+    ("headings-h2-font-weight", "600"),
+    ("headings-h2-line-height", "1.4"),
+    ("headings-h2-margin-top", "28px"),
+    ("headings-h2-margin-bottom", "10px"),
+    ("headings-h2-color", "var(--text-heading)"),
+    ("headings-h2-letter-spacing", "-0.5px"),
+    // ── Headings H3 ────────────────────────────────────────────────────
+    ("headings-h3-font-size", "20px"),
+    ("headings-h3-font-weight", "600"),
+    ("headings-h3-line-height", "1.4"),
+    ("headings-h3-margin-top", "24px"),
+    ("headings-h3-margin-bottom", "8px"),
+    ("headings-h3-color", "var(--text-heading)"),
+    ("headings-h3-letter-spacing", "-0.5px"),
+    // ── Headings H4 ────────────────────────────────────────────────────
+    ("headings-h4-font-size", "20px"),
+    ("headings-h4-font-weight", "600"),
+    ("headings-h4-line-height", "1.4"),
+    ("headings-h4-margin-top", "20px"),
+    ("headings-h4-margin-bottom", "6px"),
+    ("headings-h4-color", "var(--text-heading)"),
+    ("headings-h4-letter-spacing", "0px"),
+    // ── Lists ───────────────────────────────────────────────────────────
+    ("lists-bullet-size", "28px"),
+    ("lists-bullet-color", "#177bfd"),
+    ("lists-indent-size", "24px"),
+    ("lists-item-spacing", "4px"),
+    ("lists-padding-left", "8px"),
+    ("lists-bullet-gap", "6px"),
+    // ── Checkboxes ──────────────────────────────────────────────────────
+    ("checkboxes-size", "18px"),
+    ("checkboxes-border-radius", "3px"),
+    ("checkboxes-checked-color", "var(--accent-blue)"),
+    ("checkboxes-unchecked-border-color", "var(--text-muted)"),
+    ("checkboxes-gap", "8px"),
+    // ── Inline styles: bold ─────────────────────────────────────────────
+    ("inline-styles-bold-font-weight", "700"),
+    ("inline-styles-bold-color", "var(--text-primary)"),
+    // ── Inline styles: italic ───────────────────────────────────────────
+    ("inline-styles-italic-font-style", "italic"),
+    ("inline-styles-italic-color", "var(--text-primary)"),
+    // ── Inline styles: strikethrough ────────────────────────────────────
+    ("inline-styles-strikethrough-color", "var(--text-tertiary)"),
+    (
+        "inline-styles-strikethrough-text-decoration",
+        "line-through",
+    ),
+    // ── Inline styles: code ─────────────────────────────────────────────
+    (
+        "inline-styles-code-font-family",
+        "'SF Mono', 'Fira Code', monospace",
+    ),
+    ("inline-styles-code-font-size", "14px"),
+    (
+        "inline-styles-code-background-color",
+        "var(--bg-hover-subtle)",
+    ),
+    ("inline-styles-code-padding-horizontal", "4px"),
+    ("inline-styles-code-padding-vertical", "2px"),
+    ("inline-styles-code-border-radius", "3px"),
+    ("inline-styles-code-color", "var(--text-secondary)"),
+    // ── Inline styles: link ─────────────────────────────────────────────
+    ("inline-styles-link-color", "var(--accent-blue)"),
+    ("inline-styles-link-text-decoration", "underline"),
+    // ── Inline styles: wikilink ─────────────────────────────────────────
+    ("inline-styles-wikilink-color", "var(--accent-blue)"),
+    ("inline-styles-wikilink-text-decoration", "none"),
+    (
+        "inline-styles-wikilink-border-bottom",
+        "1px dotted currentColor",
+    ),
+    ("inline-styles-wikilink-cursor", "pointer"),
+    // ── Code blocks ─────────────────────────────────────────────────────
+    (
+        "code-blocks-font-family",
+        "'SF Mono', 'Fira Code', monospace",
+    ),
+    ("code-blocks-font-size", "13px"),
+    ("code-blocks-line-height", "1.5"),
+    ("code-blocks-background-color", "var(--bg-card)"),
+    ("code-blocks-padding-horizontal", "16px"),
+    ("code-blocks-padding-vertical", "12px"),
+    ("code-blocks-border-radius", "6px"),
+    ("code-blocks-margin-vertical", "12px"),
+    // ── Blockquote ──────────────────────────────────────────────────────
+    ("blockquote-border-left-width", "3px"),
+    ("blockquote-border-left-color", "var(--accent-blue)"),
+    ("blockquote-padding-left", "16px"),
+    ("blockquote-margin-vertical", "12px"),
+    ("blockquote-color", "var(--text-secondary)"),
+    ("blockquote-font-style", "italic"),
+    // ── Table ───────────────────────────────────────────────────────────
+    ("table-border-color", "var(--border-primary)"),
+    ("table-header-background", "var(--bg-card)"),
+    ("table-cell-padding-horizontal", "12px"),
+    ("table-cell-padding-vertical", "8px"),
+    ("table-font-size", "14px"),
+    // ── Horizontal rule ─────────────────────────────────────────────────
+    ("horizontal-rule-color", "var(--border-primary)"),
+    ("horizontal-rule-margin-vertical", "24px"),
+    ("horizontal-rule-thickness", "1px"),
+    // ── Colors (semantic aliases from theme.json → colors) ──────────────
+    ("colors-background", "var(--bg-primary)"),
+    ("colors-text", "var(--text-primary)"),
+    ("colors-text-secondary", "var(--text-secondary)"),
+    ("colors-text-muted", "var(--text-muted)"),
+    ("colors-heading", "var(--text-heading)"),
+    ("colors-accent", "var(--accent-blue)"),
+    ("colors-selection", "var(--bg-selected)"),
+    ("colors-cursor", "var(--text-primary)"),
+];
+
+/// UI-colour overrides for the Dark vault theme (keys that differ from default).
+const DARK_COLOR_OVERRIDES: &[(&str, &str)] = &[
+    ("background", "#0f0f1a"),
+    ("foreground", "#e0e0e0"),
+    ("card", "#16162a"),
+    ("popover", "#1e1e3a"),
+    ("secondary", "#2a2a4a"),
+    ("secondary-foreground", "#e0e0e0"),
+    ("muted", "#1e1e3a"),
+    ("muted-foreground", "#888888"),
+    ("accent", "#2a2a4a"),
+    ("accent-foreground", "#e0e0e0"),
+    ("destructive", "#f44336"),
+    ("border", "#2a2a4a"),
+    ("input", "#2a2a4a"),
+    ("sidebar", "#1a1a2e"),
+    ("sidebar-foreground", "#e0e0e0"),
+    ("sidebar-border", "#2a2a4a"),
+    ("sidebar-accent", "#2a2a4a"),
+    ("text-primary", "#e0e0e0"),
+    ("text-secondary", "#888888"),
+    ("text-tertiary", "#666666"),
+    ("text-muted", "#666666"),
+    ("text-heading", "#e0e0e0"),
+    ("bg-primary", "#0f0f1a"),
+    ("bg-card", "#16162a"),
+    ("bg-sidebar", "#1a1a2e"),
+    ("bg-hover", "#2a2a4a"),
+    ("bg-hover-subtle", "#1e1e3a"),
+    ("bg-selected", "#155DFF22"),
+    ("border-primary", "#2a2a4a"),
+    ("accent-red", "#f44336"),
+    ("accent-blue-light", "#155DFF33"),
+    ("accent-green-light", "#00B38B33"),
+    ("accent-purple-light", "#A932FF33"),
+    ("accent-red-light", "#f4433633"),
+    ("accent-yellow-light", "#F0B10033"),
+    ("lists-bullet-color", "#155DFF"),
+];
+
+/// UI-colour + editor-property overrides for the Minimal vault theme.
+const MINIMAL_OVERRIDES: &[(&str, &str)] = &[
+    ("background", "#FAFAFA"),
+    ("foreground", "#111111"),
+    ("primary", "#000000"),
+    ("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-tertiary", "#999999"),
+    ("text-muted", "#999999"),
+    ("text-heading", "#111111"),
+    ("bg-primary", "#FAFAFA"),
+    ("bg-card", "#FFFFFF"),
+    ("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", "15px"),
+    ("editor-line-height", "1.6"),
+    ("editor-max-width", "680px"),
+    ("lists-bullet-color", "#000000"),
+];
+
+/// Build a vault theme note string from a set of CSS variable pairs.
+///
+/// Values containing `#`, `'`, `,`, or `(` are YAML-quoted to avoid parse errors.
+fn build_vault_theme_note(name: &str, description: &str, vars: &[(&str, &str)]) -> String {
+    let mut fm = format!("---\ntype: Theme\nDescription: {description}\n");
+    for (key, value) in vars {
+        if value.contains('#') || 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\n{description}.\n"));
+    fm
+}
+
+/// Apply overrides on top of DEFAULT_VAULT_THEME_VARS, returning a new Vec.
+fn apply_overrides(
+    overrides: &[(&'static str, &'static str)],
+) -> Vec<(&'static str, &'static str)> {
+    let mut vars: Vec<(&'static str, &'static str)> = DEFAULT_VAULT_THEME_VARS.to_vec();
+    for &(key, value) in overrides {
+        if let Some(entry) = vars.iter_mut().find(|e| e.0 == key) {
+            entry.1 = value;
+        }
+    }
+    vars
+}
+
+/// Generate the Default vault theme note content.
+pub fn default_vault_theme() -> String {
+    build_vault_theme_note(
+        "Default",
+        "Light theme with warm, paper-like tones",
+        &DEFAULT_VAULT_THEME_VARS,
+    )
+}
+
+/// Generate the Dark vault theme note content.
+pub fn dark_vault_theme() -> String {
+    let vars = apply_overrides(DARK_COLOR_OVERRIDES);
+    build_vault_theme_note("Dark", "Dark variant with deep navy tones", &vars)
+}
+
+/// Generate the Minimal vault theme note content.
+pub fn minimal_vault_theme() -> String {
+    let vars = apply_overrides(MINIMAL_OVERRIDES);
+    build_vault_theme_note("Minimal", "High contrast, minimal chrome", &vars)
+}
+
+/// Type definition for the Theme note type.
+pub const THEME_TYPE_DEFINITION: &str = "---\n\
+type: 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,392 @@
+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",
+    );
+}
+
+/// Write a vault theme file if it doesn't exist or is empty (corrupt).
+fn write_if_missing(path: &Path, content: &str) -> Result<bool, String> {
+    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 {}: {e}", path.display()))?;
+    }
+    Ok(needs_write)
+}
+
+/// 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 default_content = default_vault_theme();
+    let dark_content = dark_vault_theme();
+    let minimal_content = minimal_vault_theme();
+    let defaults: &[(&str, &str)] = &[
+        ("default.md", &default_content),
+        ("dark.md", &dark_content),
+        ("minimal.md", &minimal_content),
+    ];
+    let mut seeded = false;
+    for (name, content) in defaults {
+        let wrote = write_if_missing(&theme_dir.join(name), content).unwrap_or(false);
+        seeded = seeded || wrote;
+    }
+    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 default_content = default_vault_theme();
+    let dark_content = dark_vault_theme();
+    let minimal_content = minimal_vault_theme();
+    let defaults: &[(&str, &str)] = &[
+        ("default.md", &default_content),
+        ("dark.md", &dark_content),
+        ("minimal.md", &minimal_content),
+    ];
+    for (name, content) in defaults {
+        write_if_missing(&theme_dir.join(name), 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 {
+        write_if_missing(&themes_dir.join(name), content)?;
+    }
+
+    // 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}"))?;
+    write_if_missing(&type_dir.join("theme.md"), THEME_TYPE_DEFINITION)?;
+    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("type: 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 = "---\ntype: 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("type: 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 = "---\ntype: 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("type: 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("type: 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 = "---\ntype: 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"));
+    }
+
+    #[test]
+    fn test_seeded_default_theme_contains_editor_properties() {
+        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();
+        let content = fs::read_to_string(vault.join("theme").join("default.md")).unwrap();
+
+        // Must contain all editor properties from theme.json
+        assert!(
+            content.contains("editor-font-family:"),
+            "missing editor-font-family"
+        );
+        assert!(
+            content.contains("headings-h1-font-size:"),
+            "missing headings-h1-font-size"
+        );
+        assert!(
+            content.contains("lists-bullet-size:"),
+            "missing lists-bullet-size"
+        );
+        assert!(
+            content.contains("checkboxes-size:"),
+            "missing checkboxes-size"
+        );
+        assert!(
+            content.contains("inline-styles-bold-font-weight:"),
+            "missing inline-styles-bold"
+        );
+        assert!(
+            content.contains("code-blocks-font-family:"),
+            "missing code-blocks-font-family"
+        );
+        assert!(
+            content.contains("blockquote-border-left-width:"),
+            "missing blockquote"
+        );
+        assert!(
+            content.contains("table-border-color:"),
+            "missing table-border-color"
+        );
+        assert!(
+            content.contains("horizontal-rule-thickness:"),
+            "missing horizontal-rule"
+        );
+        assert!(content.contains("colors-text:"), "missing colors-text");
+    }
+}

src-tauri/src/vault/cache.rs

@@ -1,13 +1,14 @@
 use serde::{Deserialize, Serialize};
 use std::fs;
-use std::path::Path;
+use std::hash::{Hash, Hasher};
+use std::path::{Path, PathBuf};
 
 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 = 6;
 
 #[derive(Debug, Serialize, Deserialize)]
 struct VaultCache {
@@ -25,7 +26,30 @@ fn default_cache_version() -> u32 {
     1
 }
 
-fn cache_path(vault: &Path) -> std::path::PathBuf {
+/// Compute a deterministic hex hash of the vault path for use as cache filename.
+fn vault_path_hash(vault: &Path) -> String {
+    let mut hasher = std::collections::hash_map::DefaultHasher::new();
+    vault.to_string_lossy().as_ref().hash(&mut hasher);
+    format!("{:016x}", hasher.finish())
+}
+
+/// Return the cache directory. Override with `LAPUTA_CACHE_DIR` env var (for tests).
+fn cache_dir() -> PathBuf {
+    if let Ok(dir) = std::env::var("LAPUTA_CACHE_DIR") {
+        return PathBuf::from(dir);
+    }
+    dirs::home_dir()
+        .unwrap_or_else(|| PathBuf::from("~"))
+        .join(".laputa")
+        .join("cache")
+}
+
+fn cache_path(vault: &Path) -> PathBuf {
+    cache_dir().join(format!("{}.json", vault_path_hash(vault)))
+}
+
+/// Legacy cache path inside the vault directory (pre-migration).
+fn legacy_cache_path(vault: &Path) -> PathBuf {
     vault.join(".laputa-cache.json")
 }
 
@@ -79,15 +103,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 +116,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> {
@@ -107,11 +147,18 @@ fn load_cache(vault: &Path) -> Option<VaultCache> {
     serde_json::from_str(&data).ok()
 }
 
+/// Write cache atomically: write to a temp file then rename.
 fn write_cache(vault: &Path, cache: &VaultCache) {
-    if let Ok(data) = serde_json::to_string(cache) {
-        let _ = fs::write(cache_path(vault), data);
+    let final_path = cache_path(vault);
+    if let Some(parent) = final_path.parent() {
+        let _ = fs::create_dir_all(parent);
+    }
+    let tmp_path = final_path.with_extension("tmp");
+    if let Ok(data) = serde_json::to_string(cache) {
+        if fs::write(&tmp_path, &data).is_ok() {
+            let _ = fs::rename(&tmp_path, &final_path);
+        }
     }
-    ensure_cache_excluded(vault);
 }
 
 /// Normalize an absolute path to a relative path for comparison with git output.
@@ -140,25 +187,67 @@ 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.
-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"));
+/// Copy legacy cache data to the new external location atomically.
+fn copy_legacy_cache_to(legacy: &Path, dest: &Path) {
+    if let Some(parent) = dest.parent() {
+        let _ = fs::create_dir_all(parent);
     }
+    let tmp_path = dest.with_extension("tmp");
+    if let Ok(data) = fs::read_to_string(legacy) {
+        if fs::write(&tmp_path, &data).is_ok() {
+            let _ = fs::rename(&tmp_path, dest);
+        }
+    }
+}
+
+/// Migrate legacy cache from inside the vault to the new external location.
+/// Also removes the legacy file from git tracking if present.
+fn migrate_legacy_cache(vault: &Path) {
+    let legacy = legacy_cache_path(vault);
+    if !legacy.exists() {
+        return;
+    }
+
+    let new_path = cache_path(vault);
+    if !new_path.exists() {
+        copy_legacy_cache_to(&legacy, &new_path);
+    }
+
+    // Remove legacy file from git tracking if present
+    let _ = std::process::Command::new("git")
+        .args([
+            "rm",
+            "--cached",
+            "--quiet",
+            "--ignore-unmatch",
+            ".laputa-cache.json",
+        ])
+        .current_dir(vault)
+        .output();
+
+    // Delete the legacy file from disk
+    let _ = fs::remove_file(&legacy);
+}
+
+/// Remove entries for files that no longer exist on disk and deduplicate
+/// by case-folded relative path (handles case-insensitive filesystems like macOS APFS).
+/// Returns `true` if any entries were removed.
+fn prune_stale_entries(vault: &Path, entries: &mut Vec<VaultEntry>) -> bool {
+    let before = entries.len();
+    // Remove entries whose files no longer exist on disk
+    entries.retain(|e| std::path::Path::new(&e.path).is_file());
+    // Deduplicate by case-folded relative path
+    let mut seen = std::collections::HashSet::new();
+    entries.retain(|e| {
+        let rel = to_relative_path(&e.path, vault).to_lowercase();
+        seen.insert(rel)
+    });
+    entries.len() != before
 }
 
 /// Sort entries by modified_at descending and write the cache.
 fn finalize_and_cache(vault: &Path, mut entries: Vec<VaultEntry>, hash: String) -> Vec<VaultEntry> {
+    prune_stale_entries(vault, &mut entries);
     entries.sort_by(|a, b| b.modified_at.cmp(&a.modified_at));
     write_cache(
         vault,
@@ -173,18 +262,18 @@ fn finalize_and_cache(vault: &Path, mut entries: Vec<VaultEntry>, hash: String)
 }
 
 /// Handle same-commit cache hit: re-parse any uncommitted changes (new or modified files).
+/// Always prunes stale entries even when git reports no changes, so that files
+/// deleted outside git (e.g., via Finder) are removed from the cache on vault open.
 fn update_same_commit(vault: &Path, cache: VaultCache) -> Vec<VaultEntry> {
     let changed = git_uncommitted_files(vault);
-    if changed.is_empty() {
-        return cache.entries;
+    let mut entries = cache.entries;
+    if !changed.is_empty() {
+        let changed_set: std::collections::HashSet<String> = changed.iter().cloned().collect();
+        entries.retain(|e| !changed_set.contains(&to_relative_path(&e.path, vault)));
+        entries.extend(parse_files_at(vault, &changed));
     }
-    let changed_set: std::collections::HashSet<String> = changed.iter().cloned().collect();
-    let mut entries: Vec<VaultEntry> = cache
-        .entries
-        .into_iter()
-        .filter(|e| !changed_set.contains(&to_relative_path(&e.path, vault)))
-        .collect();
-    entries.extend(parse_files_at(vault, &changed));
+    // Always finalize: prune_stale_entries inside finalize_and_cache removes
+    // entries for files deleted outside git (e.g., via Finder or another app).
     finalize_and_cache(vault, entries, cache.commit_hash)
 }
 
@@ -207,6 +296,14 @@ fn update_different_commit(
     finalize_and_cache(vault, entries, current_hash)
 }
 
+/// Delete the cache file for a vault, forcing a full rescan on the next
+/// call to `scan_vault_cached`. Used by the `reload_vault` command so that
+/// explicit user-triggered reloads always read from the filesystem.
+pub fn invalidate_cache(vault_path: &Path) {
+    let path = cache_path(vault_path);
+    let _ = fs::remove_file(&path);
+}
+
 /// Scan vault with incremental caching via git.
 /// Falls back to full scan if cache is missing/corrupt or git is unavailable.
 pub fn scan_vault_cached(vault_path: &Path) -> Result<Vec<VaultEntry>, String> {
@@ -217,6 +314,9 @@ pub fn scan_vault_cached(vault_path: &Path) -> Result<Vec<VaultEntry>, String> {
         ));
     }
 
+    // Migrate legacy in-vault cache to external location on first run
+    migrate_legacy_cache(vault_path);
+
     let current_hash = match git_head_hash(vault_path) {
         Some(h) => h,
         None => return scan_vault(vault_path),
@@ -246,8 +346,19 @@ pub fn scan_vault_cached(vault_path: &Path) -> Result<Vec<VaultEntry>, String> {
 mod tests {
     use super::*;
     use std::io::Write;
+    use std::sync::Mutex;
     use tempfile::TempDir;
 
+    /// Serialize all cache tests that mutate the LAPUTA_CACHE_DIR env var.
+    /// `std::env::set_var` is process-global, so parallel tests would race.
+    static ENV_LOCK: Mutex<()> = Mutex::new(());
+
+    /// Set up a temporary cache directory for test isolation.
+    /// Caller MUST hold `ENV_LOCK` for the duration of the test.
+    fn set_test_cache_dir(dir: &Path) {
+        std::env::set_var("LAPUTA_CACHE_DIR", dir.to_string_lossy().as_ref());
+    }
+
     fn create_test_file(dir: &Path, name: &str, content: &str) {
         let file_path = dir.join(name);
         if let Some(parent) = file_path.parent() {
@@ -257,8 +368,157 @@ mod tests {
         file.write_all(content.as_bytes()).unwrap();
     }
 
+    fn init_git_repo(vault: &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();
+    }
+
+    /// Common setup: acquire env lock, create temp cache dir + git-initialised vault.
+    /// Returns (lock_guard, cache_tmpdir, vault_tmpdir) — keep all alive for the test.
+    fn setup_git_vault() -> (std::sync::MutexGuard<'static, ()>, TempDir, TempDir) {
+        let lock = ENV_LOCK.lock().unwrap();
+        let cache_tmp = TempDir::new().unwrap();
+        set_test_cache_dir(cache_tmp.path());
+        let vault_tmp = TempDir::new().unwrap();
+        init_git_repo(vault_tmp.path());
+        (lock, cache_tmp, vault_tmp)
+    }
+
+    fn git_add_commit(vault: &Path, msg: &str) {
+        std::process::Command::new("git")
+            .args(["add", "."])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+        std::process::Command::new("git")
+            .args(["commit", "-m", msg])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+    }
+
+    #[test]
+    fn test_cache_path_is_outside_vault() {
+        let _lock = ENV_LOCK.lock().unwrap();
+        let cache_dir = TempDir::new().unwrap();
+        set_test_cache_dir(cache_dir.path());
+
+        let vault = Path::new("/Users/test/MyVault");
+        let path = cache_path(vault);
+
+        // Cache must NOT be inside the vault
+        assert!(
+            !path.starts_with(vault),
+            "cache path must be outside the vault, got: {}",
+            path.display()
+        );
+        // Cache must be under the cache directory
+        assert!(
+            path.starts_with(cache_dir.path()),
+            "cache path must be under cache dir, got: {}",
+            path.display()
+        );
+        // Must end with .json
+        assert_eq!(path.extension().unwrap(), "json");
+    }
+
+    #[test]
+    fn test_vault_path_hash_is_deterministic() {
+        let hash1 = vault_path_hash(Path::new("/Users/test/MyVault"));
+        let hash2 = vault_path_hash(Path::new("/Users/test/MyVault"));
+        assert_eq!(hash1, hash2);
+    }
+
+    #[test]
+    fn test_different_vaults_get_different_hashes() {
+        let hash1 = vault_path_hash(Path::new("/Users/test/Vault1"));
+        let hash2 = vault_path_hash(Path::new("/Users/test/Vault2"));
+        assert_ne!(hash1, hash2);
+    }
+
+    #[test]
+    fn test_atomic_write_no_tmp_file_left() {
+        let _lock = ENV_LOCK.lock().unwrap();
+        let cache_dir = TempDir::new().unwrap();
+        set_test_cache_dir(cache_dir.path());
+
+        let vault_dir = TempDir::new().unwrap();
+        let vault = vault_dir.path();
+
+        let cache = VaultCache {
+            version: CACHE_VERSION,
+            vault_path: vault.to_string_lossy().to_string(),
+            commit_hash: "abc123".to_string(),
+            entries: vec![],
+        };
+
+        write_cache(vault, &cache);
+
+        // Final file should exist
+        let final_path = cache_path(vault);
+        assert!(final_path.exists(), "cache file must exist after write");
+
+        // Tmp file should NOT exist (renamed away)
+        let tmp_path = final_path.with_extension("tmp");
+        assert!(
+            !tmp_path.exists(),
+            "tmp file must not exist after atomic write"
+        );
+
+        // Content must be valid JSON
+        let data = fs::read_to_string(&final_path).unwrap();
+        let loaded: VaultCache = serde_json::from_str(&data).unwrap();
+        assert_eq!(loaded.commit_hash, "abc123");
+    }
+
+    #[test]
+    fn test_legacy_cache_migration() {
+        let (_lock, _cache_tmp, vault_dir) = setup_git_vault();
+        let vault = vault_dir.path();
+
+        // Create a legacy cache file inside the vault
+        let legacy = legacy_cache_path(vault);
+        let cache = VaultCache {
+            version: CACHE_VERSION,
+            vault_path: vault.to_string_lossy().to_string(),
+            commit_hash: "old123".to_string(),
+            entries: vec![],
+        };
+        fs::write(&legacy, serde_json::to_string(&cache).unwrap()).unwrap();
+
+        // Run migration
+        migrate_legacy_cache(vault);
+
+        // New cache file should exist with migrated data
+        let new_path = cache_path(vault);
+        assert!(new_path.exists(), "migrated cache must exist");
+        let data = fs::read_to_string(&new_path).unwrap();
+        let loaded: VaultCache = serde_json::from_str(&data).unwrap();
+        assert_eq!(loaded.commit_hash, "old123");
+
+        // Legacy file should be deleted
+        assert!(!legacy.exists(), "legacy cache file must be removed");
+    }
+
     #[test]
     fn test_scan_vault_cached_no_git() {
+        let _lock = ENV_LOCK.lock().unwrap();
+        let cache_dir = TempDir::new().unwrap();
+        set_test_cache_dir(cache_dir.path());
+
         // Without git, scan_vault_cached falls back to scan_vault
         let dir = TempDir::new().unwrap();
         create_test_file(dir.path(), "note.md", "# Note\n\nContent here.");
@@ -271,43 +531,23 @@ mod tests {
 
     #[test]
     fn test_scan_vault_cached_with_git() {
-        let dir = TempDir::new().unwrap();
+        let (_lock, _cache_tmp, dir) = setup_git_vault();
         let vault = dir.path();
 
-        // Init git repo
-        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, "note.md", "# Note\n\nFirst version.");
-        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();
+        git_add_commit(vault, "init");
 
         // First call: full scan, writes cache
         let entries = scan_vault_cached(vault).unwrap();
         assert_eq!(entries.len(), 1);
         assert!(cache_path(vault).exists());
 
+        // Cache must NOT be inside the vault
+        assert!(
+            !cache_path(vault).starts_with(vault),
+            "cache must be outside the vault"
+        );
+
         // Second call: uses cache (same HEAD)
         let entries2 = scan_vault_cached(vault).unwrap();
         assert_eq!(entries2.len(), 1);
@@ -316,37 +556,11 @@ mod tests {
 
     #[test]
     fn test_scan_vault_cached_invalidates_stale_vault_path() {
-        let dir = TempDir::new().unwrap();
+        let (_lock, _cache_tmp, dir) = setup_git_vault();
         let vault = dir.path();
 
-        // Init git repo
-        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, "note.md", "# Note\n\nContent.");
-        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();
+        git_add_commit(vault, "init");
 
         // Build cache normally
         let entries = scan_vault_cached(vault).unwrap();
@@ -381,37 +595,11 @@ mod tests {
 
     #[test]
     fn test_scan_vault_cached_incremental_different_commit() {
-        let dir = TempDir::new().unwrap();
+        let (_lock, _cache_tmp, dir) = setup_git_vault();
         let vault = dir.path();
 
-        // Init git repo
-        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, "first.md", "# First\n\nFirst note.");
-        std::process::Command::new("git")
-            .args(["add", "."])
-            .current_dir(vault)
-            .output()
-            .unwrap();
-        std::process::Command::new("git")
-            .args(["commit", "-m", "first"])
-            .current_dir(vault)
-            .output()
-            .unwrap();
+        git_add_commit(vault, "first");
 
         // Build cache
         let entries = scan_vault_cached(vault).unwrap();
@@ -419,16 +607,7 @@ mod tests {
 
         // Add a second file and commit
         create_test_file(vault, "second.md", "# Second\n\nSecond note.");
-        std::process::Command::new("git")
-            .args(["add", "."])
-            .current_dir(vault)
-            .output()
-            .unwrap();
-        std::process::Command::new("git")
-            .args(["commit", "-m", "second"])
-            .current_dir(vault)
-            .output()
-            .unwrap();
+        git_add_commit(vault, "second");
 
         // Incremental update: cache has old commit, new commit adds second.md
         let entries2 = scan_vault_cached(vault).unwrap();
@@ -440,37 +619,12 @@ mod tests {
 
     #[test]
     fn test_update_same_commit_picks_up_modified_file() {
-        let dir = TempDir::new().unwrap();
+        let (_lock, _cache_tmp, dir) = setup_git_vault();
         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 without sidebar label
         create_test_file(vault, "type/news.md", "---\ntype: Type\n---\n# News\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();
+        git_add_commit(vault, "init");
 
         // Prime the cache (same commit hash)
         let entries = scan_vault_cached(vault).unwrap();
@@ -496,36 +650,11 @@ mod tests {
 
     #[test]
     fn test_update_same_commit_new_file_still_added() {
-        let dir = TempDir::new().unwrap();
+        let (_lock, _cache_tmp, dir) = setup_git_vault();
         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();
+        git_add_commit(vault, "init");
 
         // Prime cache
         let entries = scan_vault_cached(vault).unwrap();
@@ -541,4 +670,280 @@ mod tests {
         assert!(titles.contains(&"Existing"));
         assert!(titles.contains(&"New Note"));
     }
+
+    #[test]
+    fn test_update_same_commit_new_files_in_new_subdirectory() {
+        let (_lock, _cache_tmp, dir) = setup_git_vault();
+        let vault = dir.path();
+
+        create_test_file(vault, "existing.md", "# Existing\n");
+        git_add_commit(vault, "init");
+
+        // 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 (_lock, _cache_tmp, dir) = setup_git_vault();
+        let vault = dir.path();
+
+        // Commit a type note with visible: false
+        create_test_file(
+            vault,
+            "type/topic.md",
+            "---\ntype: Type\nvisible: false\n---\n# Topic\n",
+        );
+        git_add_commit(vault, "init");
+
+        // 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"
+        );
+    }
+
+    #[test]
+    fn test_deleted_file_removed_from_cache_on_rescan() {
+        let (_lock, _cache_tmp, dir) = setup_git_vault();
+        let vault = dir.path();
+
+        create_test_file(vault, "keep.md", "# Keep\n\nStays.");
+        create_test_file(vault, "remove.md", "# Remove\n\nGoes away.");
+        git_add_commit(vault, "init");
+
+        // Prime cache with both files
+        let entries = scan_vault_cached(vault).unwrap();
+        assert_eq!(entries.len(), 2);
+
+        // Delete file via filesystem (simulates Finder delete)
+        fs::remove_file(vault.join("remove.md")).unwrap();
+        // Also stage the deletion so git status is clean for this file
+        std::process::Command::new("git")
+            .args(["add", "remove.md"])
+            .current_dir(vault)
+            .output()
+            .unwrap();
+
+        // Rescan — deleted file must be pruned
+        let entries2 = scan_vault_cached(vault).unwrap();
+        assert_eq!(entries2.len(), 1, "deleted file must be pruned on rescan");
+        assert_eq!(entries2[0].title, "Keep");
+    }
+
+    #[test]
+    fn test_deleted_untracked_file_removed_from_cache() {
+        let (_lock, _cache_tmp, dir) = setup_git_vault();
+        let vault = dir.path();
+
+        create_test_file(vault, "tracked.md", "# Tracked\n\nCommitted.");
+        git_add_commit(vault, "init");
+
+        // Create untracked file and prime cache
+        create_test_file(vault, "temp.md", "# Temp\n\nUntracked.");
+        let entries = scan_vault_cached(vault).unwrap();
+        assert_eq!(entries.len(), 2);
+
+        // Delete the untracked file via filesystem
+        fs::remove_file(vault.join("temp.md")).unwrap();
+
+        // Rescan — untracked deleted file must be pruned
+        let entries2 = scan_vault_cached(vault).unwrap();
+        assert_eq!(
+            entries2.len(),
+            1,
+            "deleted untracked file must be pruned on rescan"
+        );
+        assert_eq!(entries2[0].title, "Tracked");
+    }
+
+    #[test]
+    fn test_case_rename_no_duplicates() {
+        let (_lock, _cache_tmp, dir) = setup_git_vault();
+        let vault = dir.path();
+
+        create_test_file(vault, "Note.md", "# Note\n\nOriginal case.");
+        git_add_commit(vault, "init");
+
+        // Prime cache
+        let entries = scan_vault_cached(vault).unwrap();
+        assert_eq!(entries.len(), 1);
+
+        // Simulate case-only rename on case-insensitive FS: delete old, create new
+        fs::remove_file(vault.join("Note.md")).unwrap();
+        create_test_file(vault, "note.md", "# Note\n\nRenamed case.");
+        git_add_commit(vault, "rename");
+
+        // Rescan — must not have duplicates
+        let entries2 = scan_vault_cached(vault).unwrap();
+        assert_eq!(
+            entries2.len(),
+            1,
+            "case-only rename must not create duplicates"
+        );
+    }
+
+    #[test]
+    fn test_invalidate_cache_deletes_cache_file() {
+        let (_lock, _cache_tmp, dir) = setup_git_vault();
+        let vault = dir.path();
+
+        create_test_file(vault, "note.md", "# Note\n\nContent.");
+        git_add_commit(vault, "init");
+
+        // Build cache
+        let _ = scan_vault_cached(vault).unwrap();
+        assert!(cache_path(vault).exists(), "cache file must exist");
+
+        // Invalidate
+        invalidate_cache(vault);
+        assert!(
+            !cache_path(vault).exists(),
+            "cache file must be deleted after invalidation"
+        );
+    }
+
+    #[test]
+    fn test_invalidate_then_scan_forces_full_rescan() {
+        let (_lock, _cache_tmp, dir) = setup_git_vault();
+        let vault = dir.path();
+
+        create_test_file(vault, "note.md", "---\nTrashed: false\n---\n# Note\n");
+        git_add_commit(vault, "init");
+
+        // Build cache — note is not trashed
+        let entries = scan_vault_cached(vault).unwrap();
+        assert_eq!(entries.len(), 1);
+        assert!(!entries[0].trashed, "note must not be trashed initially");
+
+        // Simulate trashing the note on disk (update frontmatter directly)
+        create_test_file(vault, "note.md", "---\nTrashed: true\n---\n# Note\n");
+        // Stage the change so git sees it
+        git_add_commit(vault, "trash");
+
+        // Without invalidation, scan_vault_cached uses incremental update.
+        // With invalidation, it must do a full rescan from disk.
+        invalidate_cache(vault);
+        let entries2 = scan_vault_cached(vault).unwrap();
+        assert_eq!(entries2.len(), 1);
+        assert!(
+            entries2[0].trashed,
+            "note must be trashed after invalidate + rescan"
+        );
+    }
+
+    /// Integration test: a note with `Archived: Yes` (string, not boolean)
+    /// must be recognized as archived through the full cached vault load path.
+    /// This catches the scenario where a stale cache stores `archived: false`
+    /// and the cache version bump forces a correct re-parse.
+    #[test]
+    fn test_cached_vault_archived_yes_string() {
+        let (_lock, _cache_tmp, dir) = setup_git_vault();
+        let vault = dir.path();
+
+        create_test_file(
+            vault,
+            "archived-note.md",
+            "---\nArchived: Yes\n---\n# Old Note\n",
+        );
+        git_add_commit(vault, "init");
+
+        let entries = scan_vault_cached(vault).unwrap();
+        assert_eq!(entries.len(), 1);
+        assert!(
+            entries[0].archived,
+            "'Archived: Yes' must be parsed as true through the cached vault path"
+        );
+    }
+
+    /// Integration test: `Trashed: Yes` (string) through full cached path.
+    #[test]
+    fn test_cached_vault_trashed_yes_string() {
+        let (_lock, _cache_tmp, dir) = setup_git_vault();
+        let vault = dir.path();
+
+        create_test_file(vault, "trashed-note.md", "---\nTrashed: Yes\n---\n# Gone\n");
+        git_add_commit(vault, "init");
+
+        let entries = scan_vault_cached(vault).unwrap();
+        assert_eq!(entries.len(), 1);
+        assert!(
+            entries[0].trashed,
+            "'Trashed: Yes' must be parsed as true through the cached vault path"
+        );
+    }
+
+    /// Integration test: stale cache with old version is invalidated and
+    /// re-parses `Archived: Yes` correctly after cache version bump.
+    #[test]
+    fn test_stale_cache_version_forces_rescan_of_archived_yes() {
+        let (_lock, _cache_tmp, dir) = setup_git_vault();
+        let vault = dir.path();
+
+        create_test_file(vault, "note.md", "---\nArchived: Yes\n---\n# Note\n");
+        git_add_commit(vault, "init");
+
+        let hash = git_head_hash(vault).unwrap();
+
+        // Simulate a stale cache written by old code that parsed Archived: Yes as false
+        let stale_entry = {
+            let mut e = parse_md_file(&vault.join("note.md")).unwrap();
+            e.archived = false; // simulate old parser behavior
+            e
+        };
+        let stale_cache = VaultCache {
+            version: CACHE_VERSION - 1, // old version
+            vault_path: vault.to_string_lossy().to_string(),
+            commit_hash: hash,
+            entries: vec![stale_entry],
+        };
+        write_cache(vault, &stale_cache);
+
+        // Load via cached path — stale version must trigger full rescan
+        let entries = scan_vault_cached(vault).unwrap();
+        assert_eq!(entries.len(), 1);
+        assert!(
+            entries[0].archived,
+            "stale cache with old version must be invalidated, re-parsing 'Archived: Yes' as true"
+        );
+    }
 }

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.
 
@@ -51,7 +51,7 @@ YAML frontmatter between `---` delimiters defines metadata:
 
 ```yaml
 ---
-Is A: Project
+type: Project
 Status: Active
 Owner: "[[person/jane-doe]]"
 Belongs to: "[[quarter/24q1]]"
@@ -65,7 +65,7 @@ Related to:
 
 | Field | Purpose |
 |-------|---------|
-| `Is A` | Entity type (usually inferred from folder) |
+| `type` | Entity type (usually inferred from folder) |
 | `Status` | Active, Done, Paused, Archived, Dropped |
 | `Owner` | Person responsible (wikilink) |
 | `Belongs to` | Parent relationship(s) |
@@ -98,7 +98,7 @@ Files in `type/` define entity types and control how they appear in the sidebar:
 
 ```yaml
 ---
-Is A: Type
+type: Type
 icon: rocket-launch
 color: purple
 order: 1
@@ -119,24 +119,32 @@ Available colors: red, purple, blue, green, yellow, orange. Icons are Phosphor n
 const SAMPLE_FILES: &[SampleFile] = &[
     SampleFile {
         rel_path: "type/project.md",
-        content: "---\nIs A: Type\nicon: rocket-launch\ncolor: purple\norder: 1\n---\n\n# Project\n\nA Project is a time-bounded effort with a clear goal and an eventual completion date. Projects belong to a quarter or area and advance specific goals.\n",
+        content: "---\ntype: Type\nicon: rocket-launch\ncolor: purple\norder: 1\n---\n\n# Project\n\nA Project is a time-bounded effort with a clear goal and an eventual completion date. Projects belong to a quarter or area and advance specific goals.\n",
     },
     SampleFile {
         rel_path: "type/note.md",
-        content: "---\nIs A: Type\nicon: note\ncolor: blue\norder: 2\n---\n\n# Note\n\nA Note is a general-purpose document — research notes, meeting notes, strategy docs, or anything that doesn't fit a more specific type.\n",
+        content: "---\ntype: Type\nicon: note\ncolor: blue\norder: 2\n---\n\n# Note\n\nA Note is a general-purpose document — research notes, meeting notes, strategy docs, or anything that doesn't fit a more specific type.\n",
     },
     SampleFile {
         rel_path: "type/person.md",
-        content: "---\nIs A: Type\nicon: user\ncolor: green\norder: 3\n---\n\n# Person\n\nA Person represents someone you interact with — a colleague, friend, mentor, or collaborator.\n",
+        content: "---\ntype: Type\nicon: user\ncolor: green\norder: 3\n---\n\n# Person\n\nA Person represents someone you interact with — a colleague, friend, mentor, or collaborator.\n",
     },
     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",
+        content: "---\ntype: 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: "---\ntype: 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: "---\ntype: 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#"---
-Is A: Note
+type: Note
 Related to:
   - "[[note/editor-basics]]"
   - "[[note/using-properties]]"
@@ -171,7 +179,7 @@ Every note is a markdown file with optional YAML frontmatter at the top. Notes l
     SampleFile {
         rel_path: "note/editor-basics.md",
         content: r#"---
-Is A: Note
+type: Note
 Related to: "[[note/welcome-to-laputa]]"
 ---
 
@@ -219,7 +227,7 @@ function hello() {
     SampleFile {
         rel_path: "note/using-properties.md",
         content: r#"---
-Is A: Note
+type: Note
 Status: Active
 Related to:
   - "[[note/welcome-to-laputa]]"
@@ -232,7 +240,7 @@ Every note can have **properties** defined in the YAML frontmatter at the top of
 
 ## Common properties
 
-- **Is A** — The note's type (Project, Note, Person, etc.)
+- **type** — The note's type (Project, Note, Person, etc.)
 - **Status** — Current state: Active, Done, Paused, Archived, Dropped
 - **Belongs to** — Parent relationship (e.g., a project belongs to a quarter)
 - **Related to** — Lateral connections to other notes
@@ -253,7 +261,7 @@ You can add any custom property. If the value contains `[[wiki-links]]`, Laputa
     SampleFile {
         rel_path: "note/wiki-links-and-relationships.md",
         content: r#"---
-Is A: Note
+type: Note
 Related to:
   - "[[note/welcome-to-laputa]]"
   - "[[note/using-properties]]"
@@ -292,7 +300,7 @@ Over time, your wiki-links form a rich web of connections. Use the **Referenced
     SampleFile {
         rel_path: "project/sample-project.md",
         content: r#"---
-Is A: Project
+type: Project
 Status: Active
 Owner: "[[person/sample-collaborator]]"
 Related to: "[[topic/getting-started]]"
@@ -321,7 +329,7 @@ This project is owned by [[person/sample-collaborator]] and relates to [[topic/g
     SampleFile {
         rel_path: "person/sample-collaborator.md",
         content: r#"---
-Is A: Person
+type: Person
 ---
 
 # Sample Collaborator
@@ -342,7 +350,7 @@ This person is the owner of [[project/sample-project]]. Check the **Referenced B
     SampleFile {
         rel_path: "topic/getting-started.md",
         content: r#"---
-Is A: Topic
+type: Topic
 ---
 
 # Getting Started
@@ -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;
@@ -6,16 +7,17 @@ mod parsing;
 mod rename;
 mod trash;
 
-pub use cache::scan_vault_cached;
+pub use cache::{invalidate_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;
-pub use rename::{rename_note, RenameResult};
-pub use trash::{delete_note, purge_trash};
+pub use rename::{move_note_to_type_folder, rename_note, MoveResult, RenameResult};
+pub use trash::{batch_delete_notes, delete_note, empty_trash, is_file_trashed, 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;
@@ -74,6 +76,8 @@ pub struct VaultEntry {
     /// 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,
@@ -90,7 +94,7 @@ pub struct VaultEntry {
 /// Intermediate struct to capture YAML frontmatter fields.
 #[derive(Debug, Deserialize, Default)]
 struct Frontmatter {
-    #[serde(rename = "Is A", alias = "type")]
+    #[serde(rename = "type", alias = "Is A", alias = "is_a")]
     is_a: Option<StringOrList>,
     #[serde(default)]
     aliases: Option<StringOrList>,
@@ -104,9 +108,19 @@ struct Frontmatter {
     owner: Option<String>,
     #[serde(rename = "Cadence")]
     cadence: Option<String>,
-    #[serde(rename = "Archived")]
+    #[serde(
+        rename = "Archived",
+        alias = "archived",
+        default,
+        deserialize_with = "deserialize_bool_or_string"
+    )]
     archived: Option<bool>,
-    #[serde(rename = "Trashed", alias = "trashed")]
+    #[serde(
+        rename = "Trashed",
+        alias = "trashed",
+        default,
+        deserialize_with = "deserialize_bool_or_string"
+    )]
     trashed: Option<bool>,
     #[serde(rename = "Trashed at", alias = "trashed_at")]
     trashed_at: Option<String>,
@@ -128,6 +142,58 @@ struct Frontmatter {
     sort: Option<String>,
     #[serde(default)]
     view: Option<String>,
+    #[serde(default)]
+    visible: Option<bool>,
+}
+
+/// Custom deserializer for boolean fields that may arrive as strings.
+/// YAML `Yes`/`No` get converted to JSON strings by gray_matter, so we
+/// need to accept both actual booleans and their string representations.
+fn deserialize_bool_or_string<'de, D>(deserializer: D) -> Result<Option<bool>, D::Error>
+where
+    D: serde::Deserializer<'de>,
+{
+    use serde::de;
+
+    struct BoolOrStringVisitor;
+
+    impl<'de> de::Visitor<'de> for BoolOrStringVisitor {
+        type Value = Option<bool>;
+
+        fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+            f.write_str("a boolean or a string representing a boolean")
+        }
+
+        fn visit_bool<E: de::Error>(self, v: bool) -> Result<Self::Value, E> {
+            Ok(Some(v))
+        }
+
+        fn visit_str<E: de::Error>(self, v: &str) -> Result<Self::Value, E> {
+            match v.to_lowercase().as_str() {
+                "true" | "yes" | "1" => Ok(Some(true)),
+                "false" | "no" | "0" | "" => Ok(Some(false)),
+                _ => Ok(Some(false)),
+            }
+        }
+
+        fn visit_i64<E: de::Error>(self, v: i64) -> Result<Self::Value, E> {
+            Ok(Some(v != 0))
+        }
+
+        fn visit_u64<E: de::Error>(self, v: u64) -> Result<Self::Value, E> {
+            Ok(Some(v != 0))
+        }
+
+        fn visit_none<E: de::Error>(self) -> Result<Self::Value, E> {
+            Ok(None)
+        }
+
+        fn visit_unit<E: de::Error>(self) -> Result<Self::Value, E> {
+            Ok(None)
+        }
+    }
+
+    deserializer.deserialize_any(BoolOrStringVisitor)
 }
 
 /// Handles YAML fields that can be either a single string or a list of strings.
@@ -175,6 +241,7 @@ const SKIP_KEYS: &[&str] = &[
     "template",
     "sort",
     "view",
+    "visible",
 ];
 
 /// Extract all wikilink-containing fields from raw YAML frontmatter.
@@ -272,9 +339,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()
 }
@@ -401,6 +469,7 @@ pub fn parse_md_file(path: &Path) -> Result<VaultEntry, String> {
         template: frontmatter.template,
         sort: frontmatter.sort,
         view: frontmatter.view,
+        visible: frontmatter.visible,
         word_count,
         outgoing_links,
         properties,
@@ -426,6 +495,15 @@ fn pod_to_json(pod: gray_matter::Pod) -> serde_json::Value {
     }
 }
 
+/// Re-read a single file from disk and return a fresh VaultEntry.
+/// Used after failed optimistic updates to restore the true filesystem state.
+pub fn reload_entry(path: &Path) -> Result<VaultEntry, String> {
+    if !path.exists() {
+        return Err(format!("File does not exist: {}", path.display()));
+    }
+    parse_md_file(path)
+}
+
 /// Read the content of a single note file.
 pub fn get_note_content(path: &Path) -> Result<String, String> {
     if !path.exists() {
@@ -534,6 +612,35 @@ mod tests {
         parse_md_file(&dir.path().join(name)).unwrap()
     }
 
+    #[test]
+    fn test_reload_entry_returns_fresh_data() {
+        let dir = TempDir::new().unwrap();
+        create_test_file(
+            dir.path(),
+            "note.md",
+            "---\nStatus: Active\n---\n# My Note\n\nOriginal.",
+        );
+        let entry = reload_entry(&dir.path().join("note.md")).unwrap();
+        assert_eq!(entry.title, "My Note");
+        assert_eq!(entry.status, Some("Active".to_string()));
+
+        // Modify on disk and reload — must see the new content
+        create_test_file(
+            dir.path(),
+            "note.md",
+            "---\nStatus: Done\n---\n# My Note\n\nUpdated.",
+        );
+        let fresh = reload_entry(&dir.path().join("note.md")).unwrap();
+        assert_eq!(fresh.status, Some("Done".to_string()));
+    }
+
+    #[test]
+    fn test_reload_entry_nonexistent_file() {
+        let result = reload_entry(std::path::Path::new("/nonexistent/path/note.md"));
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("does not exist"));
+    }
+
     const FULL_FM_CONTENT: &str = "---\nIs A: Project\naliases:\n  - Laputa\n  - Castle in the Sky\nBelongs to:\n  - Studio Ghibli\nRelated to:\n  - Miyazaki\nStatus: Active\nOwner: Luca\nCadence: Weekly\n---\n# Laputa Project\n\nThis is a project note.\n";
 
     #[test]
@@ -960,6 +1067,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();
@@ -1132,6 +1261,17 @@ References:
         assert_eq!(fs::read_to_string(&path).unwrap(), content);
     }
 
+    #[test]
+    fn test_save_note_content_deeply_nested_new_directory() {
+        let dir = TempDir::new().unwrap();
+        let path = dir.path().join("a/b/c/deep-note.md");
+        let content = "---\ntitle: Deep\n---\n";
+
+        save_note_content(path.to_str().unwrap(), content).unwrap();
+        assert!(path.exists());
+        assert_eq!(fs::read_to_string(&path).unwrap(), content);
+    }
+
     // --- sidebar_label tests ---
 
     #[test]
@@ -1343,6 +1483,25 @@ Company: Acme Corp
         );
     }
 
+    #[test]
+    fn test_parse_archived_lowercase_alias() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\narchived: true\n---\n# Old Quarter\n";
+        let entry = parse_test_entry(&dir, "old-quarter.md", content);
+        assert!(
+            entry.archived,
+            "lowercase 'archived' must be parsed via alias (frontend writes lowercase)"
+        );
+    }
+
+    #[test]
+    fn test_parse_archived_titlecase() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\nArchived: true\n---\n# Old Quarter\n";
+        let entry = parse_test_entry(&dir, "old-quarter-2.md", content);
+        assert!(entry.archived, "titlecase 'Archived' must also be parsed");
+    }
+
     #[test]
     fn test_trashed_false_when_absent() {
         let dir = TempDir::new().unwrap();
@@ -1352,6 +1511,159 @@ Company: Acme Corp
         assert!(entry.trashed_at.is_none());
     }
 
+    // --- archived/trashed string-value tests ---
+
+    #[test]
+    fn test_parse_archived_yes_titlecase() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\nArchived: Yes\n---\n# Old\n";
+        let entry = parse_test_entry(&dir, "old.md", content);
+        assert!(entry.archived, "'Archived: Yes' must be parsed as true");
+    }
+
+    #[test]
+    fn test_parse_archived_yes_lowercase() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\narchived: yes\n---\n# Old\n";
+        let entry = parse_test_entry(&dir, "old2.md", content);
+        assert!(entry.archived, "'archived: yes' must be parsed as true");
+    }
+
+    #[test]
+    fn test_parse_archived_yes_uppercase() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\nArchived: YES\n---\n# Old\n";
+        let entry = parse_test_entry(&dir, "old3.md", content);
+        assert!(entry.archived, "'Archived: YES' must be parsed as true");
+    }
+
+    #[test]
+    fn test_parse_archived_no() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\nArchived: No\n---\n# Active\n";
+        let entry = parse_test_entry(&dir, "active2.md", content);
+        assert!(!entry.archived, "'Archived: No' must be parsed as false");
+    }
+
+    #[test]
+    fn test_parse_archived_false_string() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\nArchived: \"false\"\n---\n# Active\n";
+        let entry = parse_test_entry(&dir, "active3.md", content);
+        assert!(
+            !entry.archived,
+            "'Archived: \"false\"' must be parsed as false"
+        );
+    }
+
+    #[test]
+    fn test_parse_archived_zero() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\nArchived: 0\n---\n# Active\n";
+        let entry = parse_test_entry(&dir, "active4.md", content);
+        assert!(!entry.archived, "'Archived: 0' must be parsed as false");
+    }
+
+    #[test]
+    fn test_parse_archived_absent() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\nIs A: Note\n---\n# Active\n";
+        let entry = parse_test_entry(&dir, "active5.md", content);
+        assert!(!entry.archived, "absent archived must default to false");
+    }
+
+    #[test]
+    fn test_parse_trashed_yes_titlecase() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\nTrashed: Yes\n---\n# Gone\n";
+        let entry = parse_test_entry(&dir, "gone2.md", content);
+        assert!(entry.trashed, "'Trashed: Yes' must be parsed as true");
+    }
+
+    #[test]
+    fn test_parse_trashed_yes_lowercase() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\ntrashed: yes\n---\n# Gone\n";
+        let entry = parse_test_entry(&dir, "gone3.md", content);
+        assert!(entry.trashed, "'trashed: yes' must be parsed as true");
+    }
+
+    #[test]
+    fn test_parse_trashed_no() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\nTrashed: No\n---\n# Active\n";
+        let entry = parse_test_entry(&dir, "active6.md", content);
+        assert!(!entry.trashed, "'Trashed: No' must be parsed as false");
+    }
+
+    // --- 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());
+    }
+
+    // --- round-trip: canonical `type:` field and `Is A:` alias ---
+
+    #[test]
+    fn test_roundtrip_type_key_parses_correctly() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\ntype: Quarter\n---\n# Q1 2026\n";
+        let entry = parse_test_entry(&dir, "quarter/q1.md", content);
+        assert_eq!(entry.is_a, Some("Quarter".to_string()));
+    }
+
+    #[test]
+    fn test_roundtrip_is_a_alias_still_works() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\nIs A: Quarter\n---\n# Q1 2026\n";
+        let entry = parse_test_entry(&dir, "quarter/q1.md", content);
+        assert_eq!(entry.is_a, Some("Quarter".to_string()));
+    }
+
+    #[test]
+    fn test_roundtrip_is_a_snake_case_alias_still_works() {
+        let dir = TempDir::new().unwrap();
+        let content = "---\nis_a: Quarter\n---\n# Q1 2026\n";
+        let entry = parse_test_entry(&dir, "quarter/q1.md", content);
+        assert_eq!(entry.is_a, Some("Quarter".to_string()));
+    }
+
     // 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

@@ -18,12 +18,18 @@ pub(super) fn extract_title(content: &str, filename: &str) -> String {
 }
 
 /// Remove YAML frontmatter (triple-dash delimited) from content.
+/// The closing `---` must appear at the start of a line to avoid matching
+/// occurrences inside frontmatter values (e.g. `title: foo---bar`).
 fn strip_frontmatter(content: &str) -> &str {
     let Some(rest) = content.strip_prefix("---") else {
         return content;
     };
-    match rest.find("---") {
-        Some(end) => rest[end + 3..].trim_start(),
+    // Find closing `---` at the start of a line (preceded by newline)
+    match rest.find("\n---") {
+        Some(end) => {
+            let after = end + 4; // skip past "\n---"
+            rest[after..].trim_start()
+        }
         None => content,
     }
 }
@@ -195,6 +201,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> {
@@ -374,6 +390,46 @@ mod tests {
         assert_eq!(count_body_words(content), 6);
     }
 
+    // --- strip_frontmatter tests ---
+
+    #[test]
+    fn test_strip_frontmatter_basic() {
+        let content = "---\ntitle: Test\n---\nBody content.";
+        assert_eq!(strip_frontmatter(content), "Body content.");
+    }
+
+    #[test]
+    fn test_strip_frontmatter_no_frontmatter() {
+        let content = "Just plain content.";
+        assert_eq!(strip_frontmatter(content), "Just plain content.");
+    }
+
+    #[test]
+    fn test_strip_frontmatter_dashes_in_value() {
+        // The closing --- must be at line start, not inside a value
+        let content = "---\ntitle: foo---bar\nstatus: active\n---\nBody here.";
+        assert_eq!(strip_frontmatter(content), "Body here.");
+    }
+
+    #[test]
+    fn test_strip_frontmatter_unclosed() {
+        let content = "---\ntitle: Test\nNo closing fence";
+        assert_eq!(strip_frontmatter(content), content);
+    }
+
+    #[test]
+    fn test_strip_frontmatter_empty_body() {
+        let content = "---\ntitle: Test\n---\n";
+        assert_eq!(strip_frontmatter(content), "");
+    }
+
+    #[test]
+    fn test_count_body_words_with_dashes_in_frontmatter_value() {
+        // Regression: strip_frontmatter previously matched --- inside values
+        let content = "---\ntitle: my---note\nstatus: active\n---\n# Title\n\nThree body words.";
+        assert_eq!(count_body_words(content), 3);
+    }
+
     // --- strip_markdown_chars tests ---
 
     #[test]
@@ -457,6 +513,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/rename.rs

@@ -166,11 +166,194 @@ fn to_path_stem<'a>(abs_path: &'a str, vault_prefix: &str) -> &'a str {
         .unwrap_or(abs_path)
 }
 
+/// Result of a move-to-type-folder operation.
+#[derive(Debug, Serialize, Deserialize)]
+pub struct MoveResult {
+    /// New absolute file path after move (same as old if no move happened).
+    pub new_path: String,
+    /// Number of other files updated (wikilink replacements).
+    pub updated_links: usize,
+    /// Whether the file was actually moved (false if already in the right folder).
+    pub moved: bool,
+}
+
+/// Convert a type name to a folder slug. All known types are single lowercase words;
+/// unknown types are slugified (lowercase, non-alphanumeric → hyphen).
+fn type_to_folder_slug(type_name: &str) -> String {
+    type_name
+        .to_lowercase()
+        .chars()
+        .map(|c| if c.is_ascii_alphanumeric() { c } else { '-' })
+        .collect::<String>()
+        .split('-')
+        .filter(|s| !s.is_empty())
+        .collect::<Vec<&str>>()
+        .join("-")
+}
+
+/// Determine a unique destination path, appending -2, -3, etc. if a file already exists.
+fn unique_dest_path(dest_dir: &Path, filename: &str) -> std::path::PathBuf {
+    let dest = dest_dir.join(filename);
+    if !dest.exists() {
+        return dest;
+    }
+    let stem = Path::new(filename)
+        .file_stem()
+        .map(|s| s.to_string_lossy().to_string())
+        .unwrap_or_default();
+    let ext = Path::new(filename)
+        .extension()
+        .map(|s| format!(".{}", s.to_string_lossy()))
+        .unwrap_or_default();
+    let mut counter = 2;
+    loop {
+        let candidate = dest_dir.join(format!("{}-{}{}", stem, counter, ext));
+        if !candidate.exists() {
+            return candidate;
+        }
+        counter += 1;
+    }
+}
+
+/// Move a note to the folder corresponding to its new type, and update wikilinks across the vault.
+///
+/// Returns `MoveResult` with `moved: false` if the note is already in the correct folder.
+/// Creates the target folder if it does not exist.
+pub fn move_note_to_type_folder(
+    vault_path: &str,
+    note_path: &str,
+    new_type: &str,
+) -> Result<MoveResult, String> {
+    let vault = Path::new(vault_path);
+    let old_file = Path::new(note_path);
+
+    if !old_file.exists() {
+        return Err(format!("File does not exist: {}", note_path));
+    }
+    let new_type = new_type.trim();
+    if new_type.is_empty() {
+        return Err("Type cannot be empty".to_string());
+    }
+
+    let folder_slug = type_to_folder_slug(new_type);
+
+    // Check if already in the correct folder
+    let current_folder = old_file
+        .parent()
+        .and_then(|p| p.file_name())
+        .map(|f| f.to_string_lossy().to_string())
+        .unwrap_or_default();
+    if current_folder == folder_slug {
+        return Ok(MoveResult {
+            new_path: note_path.to_string(),
+            updated_links: 0,
+            moved: false,
+        });
+    }
+
+    let filename = old_file
+        .file_name()
+        .map(|f| f.to_string_lossy().to_string())
+        .unwrap_or_default();
+
+    // Create target directory if needed
+    let dest_dir = vault.join(&folder_slug);
+    if !dest_dir.exists() {
+        fs::create_dir_all(&dest_dir)
+            .map_err(|e| format!("Failed to create directory {}: {}", dest_dir.display(), e))?;
+    }
+
+    // Determine destination path (handle collisions)
+    let new_file = unique_dest_path(&dest_dir, &filename);
+    let new_path_str = new_file.to_string_lossy().to_string();
+
+    // Read content and move
+    let content =
+        fs::read_to_string(old_file).map_err(|e| format!("Failed to read {}: {}", note_path, e))?;
+    fs::write(&new_file, &content)
+        .map_err(|e| format!("Failed to write {}: {}", new_path_str, e))?;
+    fs::remove_file(old_file)
+        .map_err(|e| format!("Failed to remove old file {}: {}", note_path, e))?;
+
+    // Extract title for wikilink matching
+    let old_filename = old_file
+        .file_name()
+        .map(|f| f.to_string_lossy().to_string())
+        .unwrap_or_default();
+    let old_title = super::extract_title(&content, &old_filename);
+
+    // Update wikilinks across the vault (title stays the same, path changes)
+    let vault_prefix = format!("{}/", vault.to_string_lossy());
+    let old_path_stem = to_path_stem(note_path, &vault_prefix);
+    let new_path_stem = to_path_stem(&new_path_str, &vault_prefix);
+
+    // Build pattern matching old path stem (e.g. "note/weekly-review")
+    let re = match build_wikilink_pattern(&old_title, old_path_stem) {
+        Some(r) => r,
+        None => {
+            return Ok(MoveResult {
+                new_path: new_path_str,
+                updated_links: 0,
+                moved: true,
+            })
+        }
+    };
+
+    // Determine the replacement: if path-style wikilinks were used, update to new path.
+    // Title-style wikilinks [[My Note]] stay the same (title hasn't changed).
+    let files = collect_md_files(vault, &new_file);
+    let updated_links = files
+        .iter()
+        .filter(|path| {
+            let file_content = match fs::read_to_string(path) {
+                Ok(c) => c,
+                Err(_) => return false,
+            };
+            if !re.is_match(&file_content) {
+                return false;
+            }
+            // Replace path-based wikilinks (old_path_stem → new_path_stem)
+            // and keep title-based wikilinks as-is.
+            let replaced = re.replace_all(&file_content, |caps: &regex::Captures| {
+                let full_match = caps.get(0).map(|m| m.as_str()).unwrap_or("");
+                let pipe = caps.get(1);
+                // If the match used the path stem, replace with new path stem
+                if full_match.contains(old_path_stem) {
+                    match pipe {
+                        Some(p) => format!("[[{}{}]]", new_path_stem, p.as_str()),
+                        None => format!("[[{}]]", new_path_stem),
+                    }
+                } else {
+                    // Title-based link — keep as-is (title hasn't changed)
+                    full_match.to_string()
+                }
+            });
+            if replaced != file_content {
+                fs::write(path, replaced.as_ref()).is_ok()
+            } else {
+                false
+            }
+        })
+        .count();
+
+    Ok(MoveResult {
+        new_path: new_path_str,
+        updated_links,
+        moved: true,
+    })
+}
+
 /// Rename a note: update its title, rename the file, and update wiki links across the vault.
+///
+/// When `old_title_hint` is provided it is used instead of extracting the title from
+/// the file's H1 heading.  This is needed when the caller has already saved updated
+/// content to disk (e.g. the editor saved a new H1 before triggering the rename)
+/// so the on-disk H1 already matches `new_title`.
 pub fn rename_note(
     vault_path: &str,
     old_path: &str,
     new_title: &str,
+    old_title_hint: Option<&str>,
 ) -> Result<RenameResult, String> {
     let vault = Path::new(vault_path);
     let old_file = Path::new(old_path);
@@ -189,23 +372,34 @@ pub fn rename_note(
         .file_name()
         .map(|f| f.to_string_lossy().to_string())
         .unwrap_or_default();
-    let old_title = super::extract_title(&content, &old_filename);
+    let extracted_title = super::extract_title(&content, &old_filename);
+    let old_title = old_title_hint.unwrap_or(&extracted_title);
 
-    if old_title == new_title {
+    // Check both title and filename: even if the title in content matches,
+    // the filename may still be stale (e.g. "untitled-note.md" after user changed H1).
+    let expected_filename = format!("{}.md", title_to_slug(new_title));
+    let title_unchanged = old_title == new_title;
+    let filename_matches = old_filename == expected_filename;
+
+    if title_unchanged && filename_matches {
         return Ok(RenameResult {
             new_path: old_path.to_string(),
             updated_files: 0,
         });
     }
 
-    // Update content (H1 + frontmatter title)
-    let updated_content = update_note_title_in_content(&content, new_title);
+    // Update content only if the title actually changed
+    let updated_content = if title_unchanged {
+        content.clone()
+    } else {
+        update_note_title_in_content(&content, new_title)
+    };
 
-    // Compute new path and write file
+    // Compute new path, handling collisions with numeric suffix
     let parent_dir = old_file
         .parent()
         .ok_or("Cannot determine parent directory")?;
-    let new_file = parent_dir.join(format!("{}.md", title_to_slug(new_title)));
+    let new_file = unique_dest_path(parent_dir, &expected_filename);
     let new_path_str = new_file.to_string_lossy().to_string();
 
     fs::write(&new_file, &updated_content)
@@ -220,7 +414,7 @@ pub fn rename_note(
     let old_path_stem = to_path_stem(old_path, &vault_prefix);
     let updated_files = update_wikilinks_in_vault(&WikilinkReplacement {
         vault_path: vault,
-        old_title: &old_title,
+        old_title,
         new_title,
         old_path_stem,
         exclude_path: &new_file,
@@ -278,6 +472,7 @@ mod tests {
             vault.to_str().unwrap(),
             old_path.to_str().unwrap(),
             "Sprint Retrospective",
+            None,
         )
         .unwrap();
 
@@ -314,6 +509,7 @@ mod tests {
             vault.to_str().unwrap(),
             old_path.to_str().unwrap(),
             "Sprint Retrospective",
+            None,
         )
         .unwrap();
 
@@ -338,6 +534,7 @@ mod tests {
             vault.to_str().unwrap(),
             old_path.to_str().unwrap(),
             "My Note",
+            None,
         )
         .unwrap();
 
@@ -352,7 +549,12 @@ mod tests {
         create_test_file(vault, "note/test.md", "# Test\n");
 
         let old_path = vault.join("note/test.md");
-        let result = rename_note(vault.to_str().unwrap(), old_path.to_str().unwrap(), "  ");
+        let result = rename_note(
+            vault.to_str().unwrap(),
+            old_path.to_str().unwrap(),
+            "  ",
+            None,
+        );
         assert!(result.is_err());
     }
 
@@ -372,6 +574,7 @@ mod tests {
             vault.to_str().unwrap(),
             old_path.to_str().unwrap(),
             "Sprint Retro",
+            None,
         )
         .unwrap();
 
@@ -395,6 +598,7 @@ mod tests {
             vault.to_str().unwrap(),
             old_path.to_str().unwrap(),
             "New Name",
+            None,
         )
         .unwrap();
 
@@ -417,6 +621,7 @@ mod tests {
             vault.to_str().unwrap(),
             old_path.to_str().unwrap(),
             new_title,
+            None,
         )
         .expect("rename_note should succeed");
 
@@ -471,4 +676,424 @@ mod tests {
         assert!(content.contains("title: Renamed Note"));
         assert!(content.contains("# Renamed Note"));
     }
+
+    // --- rename-on-save: filename doesn't match title slug ---
+
+    #[test]
+    fn test_rename_note_filename_mismatch_same_title() {
+        // Simulates: user created "Untitled note", changed H1 to "My New Note",
+        // saved content (H1 now correct), but filename is still "untitled-note.md".
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+        create_test_file(
+            vault,
+            "note/untitled-note.md",
+            "---\ntitle: My New Note\ntype: Note\n---\n\n# My New Note\n\nContent.\n",
+        );
+
+        let old_path = vault.join("note/untitled-note.md");
+        let result = rename_note(
+            vault.to_str().unwrap(),
+            old_path.to_str().unwrap(),
+            "My New Note",
+            None,
+        )
+        .unwrap();
+
+        // File should be renamed to match the title slug
+        assert!(
+            result.new_path.ends_with("my-new-note.md"),
+            "expected my-new-note.md, got {}",
+            result.new_path
+        );
+        assert!(!old_path.exists(), "old file should be removed");
+        assert!(Path::new(&result.new_path).exists());
+
+        // Content should be preserved (title was already correct)
+        let content = fs::read_to_string(&result.new_path).unwrap();
+        assert!(content.contains("# My New Note"));
+        assert!(content.contains("title: My New Note"));
+    }
+
+    #[test]
+    fn test_rename_note_collision_appends_suffix() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+        // Existing file with the slug we want
+        create_test_file(
+            vault,
+            "note/my-note.md",
+            "---\ntitle: My Note\ntype: Note\n---\n\n# My Note\n\nExisting.\n",
+        );
+        // File with wrong name that should be renamed to my-note.md
+        create_test_file(
+            vault,
+            "note/untitled-note.md",
+            "---\ntitle: My Note\ntype: Note\n---\n\n# My Note\n\nNew content.\n",
+        );
+
+        let old_path = vault.join("note/untitled-note.md");
+        let result = rename_note(
+            vault.to_str().unwrap(),
+            old_path.to_str().unwrap(),
+            "My Note",
+            None,
+        )
+        .unwrap();
+
+        // Should get a suffixed name to avoid collision
+        assert!(
+            result.new_path.ends_with("my-note-2.md"),
+            "expected my-note-2.md, got {}",
+            result.new_path
+        );
+        assert!(!old_path.exists());
+        assert!(Path::new(&result.new_path).exists());
+        // Original file should be untouched
+        assert!(vault.join("note/my-note.md").exists());
+    }
+
+    // --- move_note_to_type_folder tests ---
+
+    #[test]
+    fn test_type_to_folder_slug_known_types() {
+        assert_eq!(type_to_folder_slug("Person"), "person");
+        assert_eq!(type_to_folder_slug("Project"), "project");
+        assert_eq!(type_to_folder_slug("Quarter"), "quarter");
+        assert_eq!(type_to_folder_slug("Note"), "note");
+    }
+
+    #[test]
+    fn test_type_to_folder_slug_unknown_types() {
+        assert_eq!(type_to_folder_slug("Key Result"), "key-result");
+        assert_eq!(type_to_folder_slug("My Custom Type"), "my-custom-type");
+    }
+
+    #[test]
+    fn test_move_note_basic() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+        create_test_file(
+            vault,
+            "note/weekly-review.md",
+            "---\ntype: Quarter\n---\n# Weekly Review\n\nContent here.\n",
+        );
+
+        let old_path = vault.join("note/weekly-review.md");
+        let result = move_note_to_type_folder(
+            vault.to_str().unwrap(),
+            old_path.to_str().unwrap(),
+            "Quarter",
+        )
+        .unwrap();
+
+        assert!(result.moved);
+        assert!(result.new_path.contains("/quarter/weekly-review.md"));
+        assert!(!old_path.exists());
+        assert!(Path::new(&result.new_path).exists());
+    }
+
+    #[test]
+    fn test_move_note_already_in_correct_folder() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+        create_test_file(
+            vault,
+            "quarter/weekly-review.md",
+            "---\ntype: Quarter\n---\n# Weekly Review\n",
+        );
+
+        let path = vault.join("quarter/weekly-review.md");
+        let result =
+            move_note_to_type_folder(vault.to_str().unwrap(), path.to_str().unwrap(), "Quarter")
+                .unwrap();
+
+        assert!(!result.moved);
+        assert_eq!(result.new_path, path.to_str().unwrap());
+        assert_eq!(result.updated_links, 0);
+    }
+
+    #[test]
+    fn test_move_note_creates_target_folder() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+        create_test_file(
+            vault,
+            "note/my-note.md",
+            "---\ntype: Quarter\n---\n# My Note\n",
+        );
+
+        let dest_dir = vault.join("quarter");
+        assert!(!dest_dir.exists());
+
+        let old_path = vault.join("note/my-note.md");
+        let result = move_note_to_type_folder(
+            vault.to_str().unwrap(),
+            old_path.to_str().unwrap(),
+            "Quarter",
+        )
+        .unwrap();
+
+        assert!(result.moved);
+        assert!(dest_dir.exists());
+        assert!(Path::new(&result.new_path).exists());
+    }
+
+    #[test]
+    fn test_move_note_filename_collision() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+        create_test_file(
+            vault,
+            "note/my-note.md",
+            "---\ntype: Quarter\n---\n# My Note\n",
+        );
+        create_test_file(
+            vault,
+            "quarter/my-note.md",
+            "---\ntype: Quarter\n---\n# Existing Note\n",
+        );
+
+        let old_path = vault.join("note/my-note.md");
+        let result = move_note_to_type_folder(
+            vault.to_str().unwrap(),
+            old_path.to_str().unwrap(),
+            "Quarter",
+        )
+        .unwrap();
+
+        assert!(result.moved);
+        assert!(result.new_path.contains("/quarter/my-note-2.md"));
+        assert!(!old_path.exists());
+        assert!(Path::new(&result.new_path).exists());
+        // Original file should still exist
+        assert!(vault.join("quarter/my-note.md").exists());
+    }
+
+    #[test]
+    fn test_move_note_updates_path_wikilinks() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+        create_test_file(
+            vault,
+            "note/weekly-review.md",
+            "---\ntype: Quarter\n---\n# Weekly Review\n\nContent.\n",
+        );
+        create_test_file(
+            vault,
+            "project/my-project.md",
+            "---\ntype: Project\n---\n# My Project\n\nSee [[note/weekly-review]] for details.\n",
+        );
+
+        let old_path = vault.join("note/weekly-review.md");
+        let result = move_note_to_type_folder(
+            vault.to_str().unwrap(),
+            old_path.to_str().unwrap(),
+            "Quarter",
+        )
+        .unwrap();
+
+        assert!(result.moved);
+        assert_eq!(result.updated_links, 1);
+
+        let project_content = fs::read_to_string(vault.join("project/my-project.md")).unwrap();
+        assert!(project_content.contains("[[quarter/weekly-review]]"));
+        assert!(!project_content.contains("[[note/weekly-review]]"));
+    }
+
+    #[test]
+    fn test_move_note_preserves_title_wikilinks() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+        create_test_file(
+            vault,
+            "note/weekly-review.md",
+            "---\ntype: Quarter\n---\n# Weekly Review\n",
+        );
+        create_test_file(
+            vault,
+            "note/other.md",
+            "---\ntype: Note\n---\n# Other\n\nSee [[Weekly Review]] for details.\n",
+        );
+
+        let old_path = vault.join("note/weekly-review.md");
+        let result = move_note_to_type_folder(
+            vault.to_str().unwrap(),
+            old_path.to_str().unwrap(),
+            "Quarter",
+        )
+        .unwrap();
+
+        assert!(result.moved);
+        // Title-based wikilinks should be unchanged
+        let other_content = fs::read_to_string(vault.join("note/other.md")).unwrap();
+        assert!(other_content.contains("[[Weekly Review]]"));
+    }
+
+    #[test]
+    fn test_move_note_collision_preserves_both_contents() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+        let moving_content =
+            "---\ntype: Quarter\n---\n# Migrate newsletter to Beehiiv\n\nImportant content.\n";
+        let existing_content =
+            "---\ntype: Quarter\n---\n# Feedback for Laputa\n\nCompletely different note.\n";
+        create_test_file(vault, "note/my-note.md", moving_content);
+        create_test_file(vault, "quarter/my-note.md", existing_content);
+
+        let old_path = vault.join("note/my-note.md");
+        let result = move_note_to_type_folder(
+            vault.to_str().unwrap(),
+            old_path.to_str().unwrap(),
+            "Quarter",
+        )
+        .unwrap();
+
+        assert!(result.moved);
+        // Must get a unique path, not the existing file's path
+        assert!(result.new_path.contains("/quarter/my-note-2.md"));
+        // Moved note must retain its own content
+        let moved_content = fs::read_to_string(&result.new_path).unwrap();
+        assert_eq!(moved_content, moving_content);
+        // Existing note must be untouched
+        let untouched = fs::read_to_string(vault.join("quarter/my-note.md")).unwrap();
+        assert_eq!(untouched, existing_content);
+    }
+
+    #[test]
+    fn test_rename_note_with_old_title_hint_updates_wikilinks() {
+        // Simulates H1 sync: content already saved with new H1, but wikilinks still use old title.
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+        // Note file already has the NEW H1 (simulating savePendingForPath before rename)
+        create_test_file(
+            vault,
+            "note/weekly-review.md",
+            "---\nIs A: Note\n---\n# Sprint Retrospective\n\nContent.\n",
+        );
+        create_test_file(
+            vault,
+            "note/other.md",
+            "---\nIs A: Note\n---\n# Other\n\nSee [[Weekly Review]] for details.\n",
+        );
+        create_test_file(
+            vault,
+            "project/my-project.md",
+            "---\nIs A: Project\nRelated to:\n  - \"[[Weekly Review]]\"\n---\n# My Project\n",
+        );
+
+        let old_path = vault.join("note/weekly-review.md");
+        // Without old_title_hint, rename_note would see H1 = "Sprint Retrospective" == new_title → noop
+        // With old_title_hint = "Weekly Review", it knows to search for [[Weekly Review]] and replace
+        let result = rename_note(
+            vault.to_str().unwrap(),
+            old_path.to_str().unwrap(),
+            "Sprint Retrospective",
+            Some("Weekly Review"),
+        )
+        .unwrap();
+
+        assert_eq!(result.updated_files, 2);
+        assert!(result.new_path.ends_with("sprint-retrospective.md"));
+        assert!(!vault.join("note/weekly-review.md").exists());
+
+        let other_content = fs::read_to_string(vault.join("note/other.md")).unwrap();
+        assert!(other_content.contains("[[Sprint Retrospective]]"));
+        assert!(!other_content.contains("[[Weekly Review]]"));
+
+        let project_content = fs::read_to_string(vault.join("project/my-project.md")).unwrap();
+        assert!(project_content.contains("[[Sprint Retrospective]]"));
+    }
+
+    #[test]
+    fn test_rename_note_without_hint_backward_compatible() {
+        // Existing behavior: no hint, extracts title from H1
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+        create_test_file(
+            vault,
+            "note/weekly-review.md",
+            "---\nIs A: Note\n---\n# Weekly Review\n\nContent.\n",
+        );
+        create_test_file(
+            vault,
+            "note/other.md",
+            "See [[Weekly Review]] for details.\n",
+        );
+
+        let old_path = vault.join("note/weekly-review.md");
+        let result = rename_note(
+            vault.to_str().unwrap(),
+            old_path.to_str().unwrap(),
+            "Sprint Retrospective",
+            None,
+        )
+        .unwrap();
+
+        assert_eq!(result.updated_files, 1);
+        let other_content = fs::read_to_string(vault.join("note/other.md")).unwrap();
+        assert!(other_content.contains("[[Sprint Retrospective]]"));
+    }
+
+    #[test]
+    fn test_rename_note_hint_same_as_new_title_noop() {
+        // If old_title_hint == new_title, should be a noop
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+        create_test_file(vault, "note/my-note.md", "# My Note\n\nContent.\n");
+
+        let old_path = vault.join("note/my-note.md");
+        let result = rename_note(
+            vault.to_str().unwrap(),
+            old_path.to_str().unwrap(),
+            "My Note",
+            Some("My Note"),
+        )
+        .unwrap();
+
+        assert_eq!(result.new_path, old_path.to_str().unwrap());
+        assert_eq!(result.updated_files, 0);
+    }
+
+    #[test]
+    fn test_move_note_empty_type_error() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+        create_test_file(vault, "note/test.md", "# Test\n");
+
+        let path = vault.join("note/test.md");
+        let result = move_note_to_type_folder(vault.to_str().unwrap(), path.to_str().unwrap(), "");
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_move_note_nonexistent_file_error() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+        let result = move_note_to_type_folder(
+            vault.to_str().unwrap(),
+            vault.join("note/nope.md").to_str().unwrap(),
+            "Quarter",
+        );
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_move_note_preserves_content() {
+        let dir = TempDir::new().unwrap();
+        let vault = dir.path();
+        let original = "---\ntype: Quarter\ntitle: My Note\n---\n# My Note\n\nImportant content.\n";
+        create_test_file(vault, "note/my-note.md", original);
+
+        let old_path = vault.join("note/my-note.md");
+        let result = move_note_to_type_folder(
+            vault.to_str().unwrap(),
+            old_path.to_str().unwrap(),
+            "Quarter",
+        )
+        .unwrap();
+
+        let content = fs::read_to_string(&result.new_path).unwrap();
+        assert_eq!(content, original);
+    }
 }

src-tauri/src/vault/trash.rs

@@ -57,6 +57,78 @@ pub fn delete_note(path: &str) -> Result<String, String> {
     Ok(path.to_string())
 }
 
+/// Check whether a file's frontmatter marks it as trashed.
+/// Returns `true` if `Trashed: true` or `Trashed at` is present.
+pub fn is_file_trashed(path: &Path) -> bool {
+    let content = match fs::read_to_string(path) {
+        Ok(c) => c,
+        Err(_) => return false,
+    };
+    let matter = Matter::<YAML>::new();
+    let parsed = matter.parse(&content);
+
+    // Check for "Trashed at" field — its presence implies trashed
+    if extract_trashed_at_string(&parsed.data).is_some() {
+        return true;
+    }
+
+    // Check for "Trashed: true"
+    if let Some(gray_matter::Pod::Hash(ref map)) = parsed.data {
+        if let Some(pod) = map.get("Trashed").or_else(|| map.get("trashed")) {
+            return match pod {
+                gray_matter::Pod::Boolean(b) => *b,
+                gray_matter::Pod::String(s) => {
+                    matches!(s.to_ascii_lowercase().as_str(), "yes" | "true")
+                }
+                _ => false,
+            };
+        }
+    }
+
+    false
+}
+
+/// Delete multiple note files from disk.
+/// Returns the list of successfully deleted paths.
+/// Skips files that don't exist or fail to delete (logs warnings).
+pub fn batch_delete_notes(paths: &[String]) -> Result<Vec<String>, String> {
+    let mut deleted = Vec::new();
+    for path in paths {
+        let file = Path::new(path.as_str());
+        match try_purge_file(file) {
+            Some(p) => deleted.push(p),
+            None if !file.exists() => {
+                log::warn!("File does not exist, skipping: {}", path);
+            }
+            None => {} // try_purge_file already logged the warning
+        }
+    }
+    Ok(deleted)
+}
+
+/// Scan all markdown files in the vault and delete ALL trashed notes
+/// (regardless of age). Returns the list of deleted file paths.
+pub fn empty_trash(vault_path: &str) -> Result<Vec<String>, String> {
+    let vault = Path::new(vault_path);
+    if !vault.exists() || !vault.is_dir() {
+        return Err(format!(
+            "Vault path does not exist or is not a directory: {}",
+            vault_path
+        ));
+    }
+
+    let deleted: Vec<String> = WalkDir::new(vault)
+        .follow_links(true)
+        .into_iter()
+        .filter_map(|e| e.ok())
+        .filter(|e| is_markdown_file(e.path()))
+        .filter(|e| is_file_trashed(e.path()))
+        .filter_map(|entry| try_purge_file(entry.path()))
+        .collect();
+
+    Ok(deleted)
+}
+
 /// Scan all markdown files in the vault and delete those where
 /// `Trashed at` frontmatter is more than 30 days ago.
 /// Returns the list of deleted file paths.
@@ -155,7 +227,7 @@ mod tests {
         create_test_file(
             dir.path(),
             "normal.md",
-            "---\nIs A: Note\n---\n# Normal Note\n",
+            "---\ntype: Note\n---\n# Normal Note\n",
         );
 
         let deleted = purge_trash(dir.path().to_str().unwrap()).unwrap();
@@ -248,4 +320,144 @@ mod tests {
         assert_eq!(deleted.len(), 1);
         assert!(deleted[0].contains("old.md"));
     }
+
+    #[test]
+    fn test_is_file_trashed_with_trashed_true() {
+        let dir = TempDir::new().unwrap();
+        create_test_file(
+            dir.path(),
+            "trashed.md",
+            "---\nTrashed: true\n---\n# Gone\n",
+        );
+        assert!(is_file_trashed(&dir.path().join("trashed.md")));
+    }
+
+    #[test]
+    fn test_is_file_trashed_with_trashed_at() {
+        let dir = TempDir::new().unwrap();
+        create_test_file(
+            dir.path(),
+            "trashed.md",
+            "---\nTrashed at: \"2026-01-01\"\n---\n# Gone\n",
+        );
+        assert!(is_file_trashed(&dir.path().join("trashed.md")));
+    }
+
+    #[test]
+    fn test_is_file_trashed_with_trashed_yes() {
+        let dir = TempDir::new().unwrap();
+        create_test_file(dir.path(), "trashed.md", "---\nTrashed: Yes\n---\n# Gone\n");
+        assert!(is_file_trashed(&dir.path().join("trashed.md")));
+    }
+
+    #[test]
+    fn test_is_file_trashed_normal_note() {
+        let dir = TempDir::new().unwrap();
+        create_test_file(dir.path(), "normal.md", "---\ntype: Note\n---\n# Normal\n");
+        assert!(!is_file_trashed(&dir.path().join("normal.md")));
+    }
+
+    #[test]
+    fn test_is_file_trashed_archived_not_trashed() {
+        let dir = TempDir::new().unwrap();
+        create_test_file(
+            dir.path(),
+            "archived.md",
+            "---\nArchived: true\n---\n# Archived\n",
+        );
+        assert!(!is_file_trashed(&dir.path().join("archived.md")));
+    }
+
+    #[test]
+    fn test_is_file_trashed_nonexistent_file() {
+        assert!(!is_file_trashed(Path::new("/nonexistent/path.md")));
+    }
+
+    #[test]
+    fn test_is_file_trashed_with_trashed_false() {
+        let dir = TempDir::new().unwrap();
+        create_test_file(
+            dir.path(),
+            "active.md",
+            "---\nTrashed: false\n---\n# Active\n",
+        );
+        assert!(!is_file_trashed(&dir.path().join("active.md")));
+    }
+
+    #[test]
+    fn test_batch_delete_notes_removes_files() {
+        let dir = TempDir::new().unwrap();
+        create_test_file(dir.path(), "a.md", "---\ntitle: A\n---\n# A\n");
+        create_test_file(dir.path(), "b.md", "---\ntitle: B\n---\n# B\n");
+        create_test_file(dir.path(), "keep.md", "---\ntitle: Keep\n---\n# Keep\n");
+
+        let paths = vec![
+            dir.path().join("a.md").to_str().unwrap().to_string(),
+            dir.path().join("b.md").to_str().unwrap().to_string(),
+        ];
+        let deleted = batch_delete_notes(&paths).unwrap();
+        assert_eq!(deleted.len(), 2);
+        assert!(!dir.path().join("a.md").exists());
+        assert!(!dir.path().join("b.md").exists());
+        assert!(dir.path().join("keep.md").exists());
+    }
+
+    #[test]
+    fn test_batch_delete_notes_skips_nonexistent() {
+        let dir = TempDir::new().unwrap();
+        create_test_file(dir.path(), "exists.md", "---\ntitle: X\n---\n# X\n");
+
+        let paths = vec![
+            dir.path().join("exists.md").to_str().unwrap().to_string(),
+            "/nonexistent/path.md".to_string(),
+        ];
+        let deleted = batch_delete_notes(&paths).unwrap();
+        assert_eq!(deleted.len(), 1);
+        assert!(!dir.path().join("exists.md").exists());
+    }
+
+    #[test]
+    fn test_empty_trash_deletes_all_trashed() {
+        let dir = TempDir::new().unwrap();
+        // Recently trashed — should be deleted
+        let recent = chrono::Utc::now()
+            .date_naive()
+            .format("%Y-%m-%d")
+            .to_string();
+        create_test_file(
+            dir.path(),
+            "recent.md",
+            &format!(
+                "---\nTrashed: true\nTrashed at: \"{}\"\n---\n# Recent\n",
+                recent
+            ),
+        );
+        // Old trashed — should be deleted
+        create_test_file(
+            dir.path(),
+            "old.md",
+            "---\nTrashed: true\nTrashed at: \"2025-01-01\"\n---\n# Old\n",
+        );
+        // Not trashed — should be kept
+        create_test_file(dir.path(), "normal.md", "---\ntype: Note\n---\n# Normal\n");
+
+        let deleted = empty_trash(dir.path().to_str().unwrap()).unwrap();
+        assert_eq!(deleted.len(), 2);
+        assert!(!dir.path().join("recent.md").exists());
+        assert!(!dir.path().join("old.md").exists());
+        assert!(dir.path().join("normal.md").exists());
+    }
+
+    #[test]
+    fn test_empty_trash_empty_vault() {
+        let dir = TempDir::new().unwrap();
+        let deleted = empty_trash(dir.path().to_str().unwrap()).unwrap();
+        assert!(deleted.is_empty());
+    }
+
+    #[test]
+    fn test_empty_trash_nonexistent_path() {
+        let result = empty_trash("/nonexistent/path/that/does/not/exist");
+        assert!(result.is_err());
+    }
 }

src-tauri/src/vault_config.rs

@@ -18,8 +18,6 @@ pub struct VaultConfig {
     pub status_colors: Option<HashMap<String, String>>,
     #[serde(default)]
     pub property_display_modes: Option<HashMap<String, String>>,
-    #[serde(default)]
-    pub hidden_sections: Option<Vec<String>>,
 }
 
 const CONFIG_DIR: &str = "config";
@@ -100,15 +98,6 @@ fn serialize_config(config: &VaultConfig) -> String {
         "property_display_modes",
         config.property_display_modes.as_ref(),
     );
-    if let Some(ref sections) = config.hidden_sections {
-        if !sections.is_empty() {
-            lines.push("hidden_sections:".to_string());
-            for s in sections {
-                lines.push(format!("  - {s}"));
-            }
-        }
-    }
-
     lines.push("---".to_string());
     lines.join("\n") + "\n"
 }
@@ -149,6 +138,108 @@ fn yaml_safe_value(value: &str) -> 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 {
@@ -194,9 +285,6 @@ status_colors:
   Done: blue
 property_display_modes:
   deadline: date
-hidden_sections:
-  - Archived
-  - Trash
 ---
 "#;
         let config = parse_vault_config(content).unwrap();
@@ -209,8 +297,6 @@ hidden_sections:
         assert_eq!(statuses.get("Active").unwrap(), "green");
         let props = config.property_display_modes.unwrap();
         assert_eq!(props.get("deadline").unwrap(), "date");
-        let hidden = config.hidden_sections.unwrap();
-        assert_eq!(hidden, vec!["Archived", "Trash"]);
     }
 
     #[test]
@@ -223,14 +309,12 @@ hidden_sections:
             tag_colors: Some(tag_colors),
             status_colors: None,
             property_display_modes: None,
-            hidden_sections: Some(vec!["Trash".to_string()]),
         };
         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");
-        assert_eq!(parsed.hidden_sections.unwrap(), vec!["Trash"]);
     }
 
     #[test]
@@ -252,7 +336,6 @@ hidden_sections:
             tag_colors: None,
             status_colors: Some(status_colors),
             property_display_modes: None,
-            hidden_sections: None,
         };
         save_vault_config(vault_path, config).unwrap();
 
@@ -264,6 +347,131 @@ hidden_sections:
         );
     }
 
+    #[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");

src-tauri/tauri.conf.json

@@ -54,7 +54,7 @@
       "endpoints": [
         "https://refactoringhq.github.io/laputa-app/latest.json"
       ],
-      "pubkey": "dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IDRFQzlGQ0RFM0E1MTIzNDkKUldSSkkxRTYzdnpKVG13M0Zwd3M1RzErbWhJeEhBQUQyaG90bHBtMkNzMm1MNERZRlpXSGFRMTUK"
+      "pubkey": "dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IEE4NkQ5MDI3REVCRkFGNUMKUldSY3I3L2VKNUJ0cU5JRlRZZlp3NGhnU3ZwbkVKeGVvREpmb2sxRVJndHFpVFZPNlArbEE5R1IK"
     }
   }
 }

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

@@ -17,7 +17,7 @@ import { WelcomeScreen } from './components/WelcomeScreen'
 import { useMcpStatus } from './hooks/useMcpStatus'
 import { useVaultLoader } from './hooks/useVaultLoader'
 import { useSettings } from './hooks/useSettings'
-import { useNoteActions } from './hooks/useNoteActions'
+import { useNoteActions, needsRenameOnSave } from './hooks/useNoteActions'
 import { useCommitFlow } from './hooks/useCommitFlow'
 import { useViewMode } from './hooks/useViewMode'
 import { useEntryActions } from './hooks/useEntryActions'
@@ -26,7 +26,6 @@ import { useDialogs } from './hooks/useDialogs'
 import { useVaultSwitcher } from './hooks/useVaultSwitcher'
 import { useGitHistory } from './hooks/useGitHistory'
 import { useUpdater, restartApp } from './hooks/useUpdater'
-import { useNavigationHistory } from './hooks/useNavigationHistory'
 import { useAutoSync } from './hooks/useAutoSync'
 import { useConflictResolver } from './hooks/useConflictResolver'
 import { useIndexing } from './hooks/useIndexing'
@@ -36,54 +35,34 @@ 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 { useAppNavigation } from './hooks/useAppNavigation'
 import { useAiActivity } from './hooks/useAiActivity'
+import { useBulkActions } from './hooks/useBulkActions'
+import { useDeleteActions } from './hooks/useDeleteActions'
+import { useLayoutPanels } from './hooks/useLayoutPanels'
 import { ConflictResolverModal } from './components/ConflictResolverModal'
+import { ConfirmDeleteDialog } from './components/ConfirmDeleteDialog'
 import { UpdateBanner } from './components/UpdateBanner'
 import { invoke } from '@tauri-apps/api/core'
 import { isTauri, mockInvoke } from './mock-tauri'
 import type { SidebarSelection, VaultEntry } from './types'
 import type { NoteListItem } from './utils/ai-context'
 import { filterEntries } from './utils/noteListHelpers'
+import { openLocalFile } from './utils/url'
+import { flushEditorContent } from './utils/autoSave'
 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>
   }
 }
 
 const DEFAULT_SELECTION: SidebarSelection = { kind: 'filter', filter: 'all' }
 
-function useBulkActions(
-  entryActions: { handleArchiveNote: (path: string) => Promise<void>; handleTrashNote: (path: string) => Promise<void> },
-  setToastMessage: (msg: string | null) => void,
-) {
-  const handleBulkArchive = useCallback(async (paths: string[]) => {
-    for (const path of paths) await entryActions.handleArchiveNote(path)
-    setToastMessage(`${paths.length} note${paths.length > 1 ? 's' : ''} archived`)
-  }, [entryActions, setToastMessage])
-
-  const handleBulkTrash = useCallback(async (paths: string[]) => {
-    for (const path of paths) await entryActions.handleTrashNote(path)
-    setToastMessage(`${paths.length} note${paths.length > 1 ? 's' : ''} moved to trash`)
-  }, [entryActions, setToastMessage])
-
-  return { handleBulkArchive, handleBulkTrash }
-}
-
-function useLayoutPanels() {
-  const [sidebarWidth, setSidebarWidth] = useState(250)
-  const [noteListWidth, setNoteListWidth] = useState(300)
-  const [inspectorWidth, setInspectorWidth] = useState(280)
-  const [inspectorCollapsed, setInspectorCollapsed] = useState(false)
-  const handleSidebarResize = useCallback((delta: number) => setSidebarWidth((w) => Math.max(150, Math.min(400, w + delta))), [])
-  const handleNoteListResize = useCallback((delta: number) => setNoteListWidth((w) => Math.max(200, Math.min(500, w + delta))), [])
-  const handleInspectorResize = useCallback((delta: number) => setInspectorWidth((w) => Math.max(200, Math.min(500, w - delta))), [])
-  return { sidebarWidth, noteListWidth, inspectorWidth, inspectorCollapsed, setInspectorCollapsed, handleSidebarResize, handleNoteListResize, handleInspectorResize }
-}
-
 /** Wraps useEditorSave to also keep outgoingLinks in sync on save and on content change. */
 function App() {
   const [selection, setSelection] = useState<SidebarSelection>(DEFAULT_SELECTION)
@@ -106,14 +85,17 @@ function App() {
   const vault = useVaultLoader(resolvedPath)
   useVaultConfig(resolvedPath)
   const { settings, saveSettings } = useSettings()
-  const themeManager = useThemeManager(resolvedPath, vault.entries, vault.allContent, vault.updateContent)
+  const themeManager = useThemeManager(resolvedPath, vault.entries)
 
   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`)
@@ -124,8 +106,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: () => {
@@ -169,7 +149,7 @@ function App() {
   // Read at callback time, so it's always current when user presses Cmd+N.
   const contentChangeRef = useRef<(path: string, content: string) => void>(() => {})
 
-  const notes = useNoteActions({ addEntry: vault.addEntry, removeEntry: vault.removeEntry, updateContent: vault.updateContent, entries: vault.entries, setToastMessage, updateEntry: vault.updateEntry, addPendingSave: vault.addPendingSave, removePendingSave: vault.removePendingSave, trackUnsaved: vault.trackUnsaved, clearUnsaved: vault.clearUnsaved, unsavedPaths: vault.unsavedPaths, markContentPending: (path, content) => contentChangeRef.current(path, content), onNewNotePersisted: vault.loadModifiedFiles })
+  const notes = useNoteActions({ addEntry: vault.addEntry, removeEntry: vault.removeEntry, entries: vault.entries, setToastMessage, updateEntry: vault.updateEntry, vaultPath: resolvedPath, addPendingSave: vault.addPendingSave, removePendingSave: vault.removePendingSave, trackUnsaved: vault.trackUnsaved, clearUnsaved: vault.clearUnsaved, unsavedPaths: vault.unsavedPaths, markContentPending: (path, content) => contentChangeRef.current(path, content), onNewNotePersisted: vault.loadModifiedFiles, replaceEntry: vault.replaceEntry })
 
   // Keep tab entries in sync with vault entries so banners (trash/archive)
   // and read-only state react immediately without reopening the note.
@@ -188,60 +168,27 @@ function App() {
     })
   }, [vault.entries]) // eslint-disable-line react-hooks/exhaustive-deps -- notes.setTabs is stable (useState setter)
 
-  const navHistory = useNavigationHistory()
-
-  // Push to navigation history whenever the active tab changes (user-initiated)
-  const navFromHistoryRef = useRef(false)
-  useEffect(() => {
-    if (notes.activeTabPath && !navFromHistoryRef.current) {
-      navHistory.push(notes.activeTabPath)
-    }
-    navFromHistoryRef.current = false
-  }, [notes.activeTabPath]) // eslint-disable-line react-hooks/exhaustive-deps -- navHistory.push is stable
-
-  const isEntryExists = useCallback((path: string) => vault.entries.some(e => e.path === path), [vault.entries])
-
-  const handleGoBack = useCallback(() => {
-    const target = navHistory.goBack(isEntryExists)
-    if (target) {
-      navFromHistoryRef.current = true
-      if (notes.tabs.some(t => t.entry.path === target)) {
-        notes.handleSwitchTab(target)
-      } else {
-        const entry = vault.entries.find(e => e.path === target)
-        if (entry) notes.handleSelectNote(entry)
-      }
-    }
-  }, [navHistory, isEntryExists, vault.entries, notes])
-
-  const handleGoForward = useCallback(() => {
-    const target = navHistory.goForward(isEntryExists)
-    if (target) {
-      navFromHistoryRef.current = true
-      if (notes.tabs.some(t => t.entry.path === target)) {
-        notes.handleSwitchTab(target)
-      } else {
-        const entry = vault.entries.find(e => e.path === target)
-        if (entry) notes.handleSelectNote(entry)
-      }
-    }
-  }, [navHistory, isEntryExists, vault.entries, notes])
-
-  useNavigationGestures({ onGoBack: handleGoBack, onGoForward: handleGoForward })
+  const { handleGoBack, handleGoForward, canGoBack, canGoForward, entriesByPath } = useAppNavigation({
+    entries: vault.entries,
+    tabs: notes.tabs,
+    activeTabPath: notes.activeTabPath,
+    onSelectNote: notes.handleSelectNote,
+    onSwitchTab: notes.handleSwitchTab,
+  })
 
   // MCP UI bridge: react to AI-driven open/highlight/vault-change events
   const openNoteByPath = useCallback((path: string) => {
-    const entry = vault.entries.find(e => e.path === path || e.path === `${resolvedPath}/${path}`)
+    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.find((e: VaultEntry) => e.path === path || e.path === `${resolvedPath}/${path}`)
+        const fresh = (freshEntries as VaultEntry[]).find(e => e.path === path || e.path === `${resolvedPath}/${path}`)
         if (fresh) notes.handleSelectNote(fresh)
       })
     }
-  }, [vault, notes, resolvedPath])
+  }, [entriesByPath, vault, notes, resolvedPath])
 
   const aiActivity = useAiActivity({
     onOpenNote: openNoteByPath,
@@ -252,10 +199,18 @@ function App() {
     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.find((e: VaultEntry) => e.path === relativePath || e.path === `${resolvedPath}/${relativePath}`)
+      const entry = (freshEntries as VaultEntry[]).find(e => e.path === relativePath || e.path === `${resolvedPath}/${relativePath}`)
       if (entry) notes.handleSelectNote(entry)
     })
   }, [vault, notes, resolvedPath])
@@ -268,39 +223,87 @@ function App() {
     }
   }, [vault, notes, resolvedPath])
 
+  const handleAgentVaultChanged = useCallback(() => {
+    vault.reloadVault()
+  }, [vault])
+
   const { triggerIncrementalIndex } = indexing
   const onAfterSave = useCallback(() => {
     vault.loadModifiedFiles()
     triggerIncrementalIndex()
   }, [vault, triggerIncrementalIndex])
 
+  const { notifyThemeSaved } = themeManager
+  const onNotePersisted = useCallback((path: string, content: string) => {
+    vault.clearUnsaved(path)
+    notifyThemeSaved(path, content)
+  }, [vault, notifyThemeSaved])
+
   const { handleSave: handleSaveRaw, handleContentChange, savePendingForPath, savePending } = useEditorSaveWithLinks({
-    updateContent: vault.updateContent, updateEntry: vault.updateEntry,
+    updateEntry: vault.updateEntry,
     setTabs: notes.setTabs, setToastMessage, onAfterSave,
-    onNotePersisted: vault.clearUnsaved,
+    onNotePersisted,
   })
   useEffect(() => { contentChangeRef.current = handleContentChange }, [handleContentChange])
 
+  // Refs for stable closure in flushBeforeAction (avoids re-creating on every tab/content change)
+  const tabsRef = useRef(notes.tabs)
+  tabsRef.current = notes.tabs // eslint-disable-line react-hooks/refs -- ref sync pattern
+  const unsavedPathsRef = useRef(vault.unsavedPaths)
+  unsavedPathsRef.current = vault.unsavedPaths // eslint-disable-line react-hooks/refs -- ref sync pattern
+
+  /** Auto-save unsaved editor content before a destructive action (trash/archive). */
+  const { clearUnsaved: vaultClearUnsaved } = vault
+  const flushBeforeAction = useCallback(async (path: string) => {
+    try {
+      await flushEditorContent(path, {
+        savePendingForPath,
+        getTabContent: (p) => tabsRef.current.find(t => t.entry.path === p)?.content,
+        isUnsaved: (p) => unsavedPathsRef.current.has(p),
+        onSaved: (p) => { vaultClearUnsaved(p) },
+      })
+    } catch (err) {
+      setToastMessage(`Auto-save failed: ${err}`)
+      throw err
+    }
+  }, [savePendingForPath, vaultClearUnsaved, setToastMessage])
+
   // Wire conflict file opener now that notes is available
   useEffect(() => {
     openConflictFileRef.current = (relativePath: string) => {
       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. settings.json) —
+        // open with system default app so the user can inspect/edit it
+        openLocalFile(fullPath)
       }
     }
   }, [resolvedPath, vault.entries, notes, dialogs])
 
+  const handleRenameTab = useCallback(async (path: string, newTitle: string) => {
+    await savePendingForPath(path)
+    await notes.handleRenameNote(path, newTitle, resolvedPath, vault.replaceEntry).then(vault.loadModifiedFiles)
+  }, [notes, resolvedPath, vault, savePendingForPath])
+
   // Wrap handleSave to also persist unsaved notes that have no pending edits (user pressed Cmd+S without typing)
+  // and trigger file rename when the title slug doesn't match the filename.
   const handleSave = useCallback(async () => {
     const activeTab = notes.tabs.find(t => t.entry.path === notes.activeTabPath)
     const fallback = activeTab && vault.unsavedPaths.has(activeTab.entry.path)
       ? { path: activeTab.entry.path, content: activeTab.content }
       : undefined
     await handleSaveRaw(fallback)
-  }, [handleSaveRaw, notes.tabs, notes.activeTabPath, vault.unsavedPaths])
+
+    // After saving, check if filename needs to match the current title
+    if (activeTab && needsRenameOnSave(activeTab.entry.title, activeTab.entry.filename)) {
+      await handleRenameTab(activeTab.entry.path, activeTab.entry.title)
+    }
+  }, [handleSaveRaw, handleRenameTab, notes.tabs, notes.activeTabPath, vault.unsavedPaths])
 
   const commitFlow = useCommitFlow({ savePending, loadModifiedFiles: vault.loadModifiedFiles, commitAndPush: vault.commitAndPush, setToastMessage })
 
@@ -309,19 +312,17 @@ function App() {
     handleUpdateFrontmatter: notes.handleUpdateFrontmatter,
     handleDeleteProperty: notes.handleDeleteProperty, setToastMessage,
     createTypeEntry: notes.createTypeEntrySilent,
+    onFrontmatterPersisted: vault.loadModifiedFiles,
+    onBeforeAction: flushBeforeAction,
   })
 
-  const handleDeleteNote = useCallback(async (path: string) => {
-    try {
-      if (isTauri()) await invoke('delete_note', { path })
-      else await mockInvoke('delete_note', { path })
-      notes.handleCloseTab(path)
-      vault.removeEntry(path)
-      setToastMessage('Note permanently deleted')
-    } catch (e) {
-      setToastMessage(`Failed to delete note: ${e}`)
-    }
-  }, [notes, vault, setToastMessage])
+  const deleteActions = useDeleteActions({
+    vaultPath: resolvedPath,
+    entries: vault.entries,
+    handleCloseTab: notes.handleCloseTab,
+    removeEntry: vault.removeEntry,
+    setToastMessage,
+  })
 
   const gitHistory = useGitHistory(notes.activeTabPath, vault.loadGitHistory)
 
@@ -330,19 +331,12 @@ function App() {
     setToastMessage(`Type "${name}" created`)
   }, [notes])
 
-  const handleRenameTab = useCallback(async (path: string, newTitle: string) => {
+  /** H1→title sync: save pending content then rename file + update wikilinks. */
+  const handleTitleSync = useCallback(async (path: string, newTitle: string) => {
     await savePendingForPath(path)
     await notes.handleRenameNote(path, newTitle, resolvedPath, vault.replaceEntry).then(vault.loadModifiedFiles)
   }, [notes, resolvedPath, vault, savePendingForPath])
 
-  /** H1→title sync: update VaultEntry.title and tab entry in memory. */
-  const handleTitleSync = useCallback((path: string, newTitle: string) => {
-    vault.updateEntry(path, { title: newTitle })
-    notes.setTabs(prev => prev.map(t =>
-      t.entry.path === path ? { ...t, entry: { ...t.entry, title: newTitle } } : t
-    ))
-  }, [vault, notes])
-
   const bulkActions = useBulkActions(entryActions, setToastMessage)
 
   // Raw-toggle ref: Editor registers its handleToggleRaw here so the command palette can call it
@@ -387,10 +381,23 @@ function App() {
     }
   }, [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,
-    entries: vault.entries, allContent: vault.allContent,
+    entries: vault.entries,
     modifiedCount: vault.modifiedFiles.length,
     activeNoteModified: vault.modifiedFiles.some(f => f.path === notes.activeTabPath),
     selection,
@@ -415,7 +422,7 @@ function App() {
     onSwitchTab: notes.handleSwitchTab, onReplaceActiveTab: notes.handleReplaceActiveTab,
     onSelectNote: notes.handleSelectNote,
     onGoBack: handleGoBack, onGoForward: handleGoForward,
-    canGoBack: navHistory.canGoBack, canGoForward: navHistory.canGoForward,
+    canGoBack: canGoBack, canGoForward: canGoForward,
     themes: themeManager.themes, activeThemeId: themeManager.activeThemeId,
     onSwitchTheme: themeManager.switchTheme,
     onCreateTheme: async () => {
@@ -442,6 +449,12 @@ function App() {
     vaultCount: vaultSwitcher.allVaults.length,
     mcpStatus,
     onInstallMcp: installMcp,
+    onEmptyTrash: deleteActions.handleEmptyTrash,
+    trashedCount: deleteActions.trashedCount,
+    onReopenClosedTab: notes.handleReopenClosedTab,
+    onReindexVault: indexing.triggerFullReindex,
+    onReloadVault: vault.reloadVault,
+    onRepairVault: handleRepairVault,
   })
 
   const activeTab = notes.tabs.find((t) => t.entry.path === notes.activeTabPath) ?? null
@@ -494,7 +507,7 @@ 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} isGitVault={!vault.modifiedFilesError} />
+              <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} />
           </>
@@ -503,13 +516,9 @@ function App() {
           <>
             <div className={`app__note-list${aiActivity.highlightElement === 'notelist' ? ' ai-highlight' : ''}`} style={{ width: layout.noteListWidth }}>
               {selection.kind === 'filter' && selection.filter === 'pulse' ? (
-                <PulseView vaultPath={resolvedPath} onOpenNote={(relativePath) => {
-                  const fullPath = `${resolvedPath}/${relativePath}`
-                  const entry = vault.entries.find(e => e.path === fullPath || e.path === relativePath)
-                  if (entry) notes.handleSelectNote(entry)
-                }} sidebarCollapsed={!sidebarVisible} onExpandSidebar={() => setViewMode('all')} />
+                <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} />
+                <NoteList entries={vault.entries} selection={selection} selectedNote={activeTab?.entry ?? null} 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} onBulkRestore={bulkActions.handleBulkRestore} onBulkDeletePermanently={deleteActions.handleBulkDeletePermanently} onEmptyTrash={deleteActions.handleEmptyTrash} onUpdateTypeSort={notes.handleUpdateFrontmatter} updateEntry={vault.updateEntry} />
               )}
             </div>
             <ResizeHandle onResize={layout.handleNoteListResize} />
@@ -534,11 +543,11 @@ function App() {
             onInspectorResize={layout.handleInspectorResize}
             inspectorEntry={activeTab?.entry ?? null}
             inspectorContent={activeTab?.content ?? null}
-            allContent={vault.allContent}
             gitHistory={gitHistory}
             onUpdateFrontmatter={notes.handleUpdateFrontmatter}
             onDeleteProperty={notes.handleDeleteProperty}
             onAddProperty={notes.handleAddProperty}
+            onCreateAndOpenNote={notes.handleCreateNoteForRelationship}
             showAIChat={dialogs.showAIChat}
             onToggleAIChat={dialogs.toggleAIChat}
             vaultPath={resolvedPath}
@@ -546,7 +555,7 @@ function App() {
             noteListFilter={aiNoteListFilter}
             onTrashNote={entryActions.handleTrashNote}
             onRestoreNote={entryActions.handleRestoreNote}
-            onDeleteNote={handleDeleteNote}
+            onDeleteNote={deleteActions.handleDeleteNote}
             onArchiveNote={entryActions.handleArchiveNote}
             onUnarchiveNote={entryActions.handleUnarchiveNote}
             onRenameTab={handleRenameTab}
@@ -555,19 +564,20 @@ function App() {
             onTitleSync={handleTitleSync}
             rawToggleRef={rawToggleRef}
             diffToggleRef={diffToggleRef}
-            canGoBack={navHistory.canGoBack}
-            canGoForward={navHistory.canGoForward}
+            canGoBack={canGoBack}
+            canGoForward={canGoForward}
             onGoBack={handleGoBack}
             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} mcpStatus={mcpStatus} onInstallMcp={installMcp} />
+      <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} />
@@ -594,6 +604,16 @@ function App() {
         onOpenSettings={() => { dialogs.closeGitHubVault(); dialogs.openSettings() }}
         onGitHubConnected={(token, username) => saveSettings({ ...settings, github_token: token, github_username: username })}
       />
+      {deleteActions.confirmDelete && (
+        <ConfirmDeleteDialog
+          open={true}
+          title={deleteActions.confirmDelete.title}
+          message={deleteActions.confirmDelete.message}
+          confirmLabel={deleteActions.confirmDelete.confirmLabel}
+          onConfirm={deleteActions.confirmDelete.onConfirm}
+          onCancel={() => deleteActions.setConfirmDelete(null)}
+        />
+      )}
     </div>
   )
 }

src/components/AIChatPanel.tsx

@@ -15,9 +15,9 @@ import { MarkdownContent } from './MarkdownContent'
 
 interface AIChatPanelProps {
   entry: VaultEntry | null
-  allContent: Record<string, string>
   entries?: VaultEntry[]
   onClose: () => void
+  onNavigateWikilink?: (target: string) => void
 }
 
 function TypingIndicator() {
@@ -99,10 +99,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 +121,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,17 +176,17 @@ function useContextNotes(entry: VaultEntry | null) {
 
 // --- Main component ---
 
-export function AIChatPanel({ entry, allContent, entries = [], onClose }: AIChatPanelProps) {
+export function AIChatPanel({ entry, entries = [], onClose, onNavigateWikilink }: AIChatPanelProps) {
   const [input, setInput] = useState('')
   const [showSearch, setShowSearch] = useState(false)
   const messagesEndRef = useRef<HTMLDivElement>(null)
 
   const ctx = useContextNotes(entry)
-  const chat = useAIChat(allContent, ctx.contextNotes)
+  const chat = useAIChat(ctx.contextNotes)
 
   const contextInfo = useMemo(
-    () => buildSystemPrompt(ctx.contextNotes, allContent),
-    [ctx.contextNotes, allContent],
+    () => buildSystemPrompt(ctx.contextNotes),
+    [ctx.contextNotes],
   )
 
   useEffect(() => {
@@ -213,7 +213,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 +284,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 +303,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/AiMessage.tsx

@@ -24,6 +24,7 @@ export interface AiMessageProps {
   response?: string
   isStreaming?: boolean
   onOpenNote?: (path: string) => void
+  onNavigateWikilink?: (target: string) => void
 }
 
 function ReferencePill({ reference, onClick }: {
@@ -147,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 }}>
-      <MarkdownContent content={text} />
+      <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 }}
@@ -175,7 +176,7 @@ function StreamingIndicator() {
   )
 }
 
-export function AiMessage({ userMessage, references, reasoning, reasoningDone, actions, response, isStreaming, onOpenNote }: AiMessageProps) {
+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())
@@ -212,7 +213,7 @@ export function AiMessage({ userMessage, references, reasoning, reasoningDone, a
           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()
@@ -74,7 +81,7 @@ describe('AiPanel', () => {
   it('renders contextual empty state when active entry is provided', () => {
     const entry = makeEntry({ title: 'My Note' })
     render(
-      <AiPanel onClose={vi.fn()} vaultPath="/tmp/vault" activeEntry={entry} entries={[entry]} allContent={{}} />
+      <AiPanel onClose={vi.fn()} vaultPath="/tmp/vault" activeEntry={entry} entries={[entry]} />
     )
     expect(screen.getByText('Ask about this note and its linked context')).toBeTruthy()
   })
@@ -82,7 +89,7 @@ describe('AiPanel', () => {
   it('shows context bar with active entry title', () => {
     const entry = makeEntry({ title: 'My Note' })
     render(
-      <AiPanel onClose={vi.fn()} vaultPath="/tmp/vault" activeEntry={entry} entries={[entry]} allContent={{}} />
+      <AiPanel onClose={vi.fn()} vaultPath="/tmp/vault" activeEntry={entry} entries={[entry]} />
     )
     expect(screen.getByTestId('context-bar')).toBeTruthy()
     expect(screen.getByText('My Note')).toBeTruthy()
@@ -95,8 +102,7 @@ describe('AiPanel', () => {
       <AiPanel
         onClose={vi.fn()} vaultPath="/tmp/vault"
         activeEntry={entry} entries={[entry, linked]}
-        allContent={{}}
-      />
+             />
     )
     expect(screen.getByText('+ 1 linked')).toBeTruthy()
   })
@@ -122,7 +128,7 @@ describe('AiPanel', () => {
   it('shows contextual placeholder when active entry exists', () => {
     const entry = makeEntry({ title: 'My Note' })
     render(
-      <AiPanel onClose={vi.fn()} vaultPath="/tmp/vault" activeEntry={entry} entries={[entry]} allContent={{}} />
+      <AiPanel onClose={vi.fn()} vaultPath="/tmp/vault" activeEntry={entry} entries={[entry]} />
     )
     const input = screen.getByTestId('agent-input') as HTMLInputElement
     expect(input.placeholder).toBe('Ask about this note...')
@@ -162,4 +168,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

@@ -13,10 +13,12 @@ interface AiPanelProps {
   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 }
@@ -89,8 +91,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)
 
@@ -102,14 +104,14 @@ 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>
   )
 }
 
-export function AiPanel({ onClose, onOpenNote, onFileCreated, onFileModified, vaultPath, activeEntry, entries, allContent, openTabs, noteList, noteListFilter }: AiPanelProps) {
+export function AiPanel({ onClose, onOpenNote, onFileCreated, onFileModified, onVaultChanged, vaultPath, activeEntry, activeNoteContent, entries, openTabs, noteList, noteListFilter }: AiPanelProps) {
   const [input, setInput] = useState('')
   const [pendingRefs, setPendingRefs] = useState<NoteReference[]>([])
   const inputRef = useRef<HTMLInputElement>(null)
@@ -121,22 +123,23 @@ export function AiPanel({ onClose, onOpenNote, onFileCreated, onFileModified, va
   }, [activeEntry, entries])
 
   const contextPrompt = useMemo(() => {
-    if (!activeEntry || !allContent || !entries) return undefined
+    if (!activeEntry || !entries) return undefined
     return buildContextSnapshot({
       activeEntry,
-      allContent,
+      activeNoteContent: activeNoteContent ?? undefined,
       openTabs,
       noteList,
       noteListFilter,
       entries,
       references: pendingRefs.length > 0 ? pendingRefs : undefined,
     })
-  }, [activeEntry, allContent, openTabs, noteList, noteListFilter, entries, pendingRefs])
+  }, [activeEntry, activeNoteContent, openTabs, noteList, noteListFilter, entries, pendingRefs])
 
   const fileCallbacks = useMemo<AgentFileCallbacks>(() => ({
     onFileCreated,
     onFileModified,
-  }), [onFileCreated, onFileModified])
+    onVaultChanged,
+  }), [onFileCreated, onFileModified, onVaultChanged])
 
   const agent = useAiAgent(vaultPath, contextPrompt, fileCallbacks)
   const hasContext = !!activeEntry
@@ -167,6 +170,10 @@ export function AiPanel({ onClose, onOpenNote, onFileCreated, onFileModified, va
     return () => window.removeEventListener('keydown', handleEscape)
   }, [handleEscape])
 
+  const handleNavigateWikilink = useCallback((target: string) => {
+    onOpenNote?.(target)
+  }, [onOpenNote])
+
   const handleSend = useCallback((text: string, references: NoteReference[]) => {
     if (!text.trim() || isActive) return
     setPendingRefs(references)
@@ -198,6 +205,7 @@ export function AiPanel({ onClose, onOpenNote, onFileCreated, onFileModified, va
         messages={agent.messages}
         isActive={isActive}
         onOpenNote={onOpenNote}
+        onNavigateWikilink={handleNavigateWikilink}
         hasContext={hasContext}
       />
       <div

src/components/BulkActionBar.test.tsx

@@ -0,0 +1,50 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { BulkActionBar } from './BulkActionBar'
+
+describe('BulkActionBar', () => {
+  const defaultProps = {
+    count: 3,
+    onArchive: vi.fn(),
+    onTrash: vi.fn(),
+    onRestore: vi.fn(),
+    onDeletePermanently: vi.fn(),
+    onClear: vi.fn(),
+    isTrashView: false,
+  }
+
+  it('shows Archive and Trash buttons in normal view', () => {
+    render(<BulkActionBar {...defaultProps} />)
+    expect(screen.getByTestId('bulk-archive-btn')).toBeInTheDocument()
+    expect(screen.getByTestId('bulk-trash-btn')).toBeInTheDocument()
+    expect(screen.queryByTestId('bulk-restore-btn')).not.toBeInTheDocument()
+    expect(screen.queryByTestId('bulk-delete-btn')).not.toBeInTheDocument()
+  })
+
+  it('shows Restore and Delete permanently in trash view', () => {
+    render(<BulkActionBar {...defaultProps} isTrashView={true} />)
+    expect(screen.getByTestId('bulk-restore-btn')).toBeInTheDocument()
+    expect(screen.getByTestId('bulk-delete-btn')).toBeInTheDocument()
+    expect(screen.queryByTestId('bulk-archive-btn')).not.toBeInTheDocument()
+    expect(screen.queryByTestId('bulk-trash-btn')).not.toBeInTheDocument()
+  })
+
+  it('calls onRestore when Restore button clicked in trash view', () => {
+    const onRestore = vi.fn()
+    render(<BulkActionBar {...defaultProps} isTrashView={true} onRestore={onRestore} />)
+    fireEvent.click(screen.getByTestId('bulk-restore-btn'))
+    expect(onRestore).toHaveBeenCalledTimes(1)
+  })
+
+  it('calls onDeletePermanently when Delete button clicked in trash view', () => {
+    const onDeletePermanently = vi.fn()
+    render(<BulkActionBar {...defaultProps} isTrashView={true} onDeletePermanently={onDeletePermanently} />)
+    fireEvent.click(screen.getByTestId('bulk-delete-btn'))
+    expect(onDeletePermanently).toHaveBeenCalledTimes(1)
+  })
+
+  it('shows selected count', () => {
+    render(<BulkActionBar {...defaultProps} count={5} />)
+    expect(screen.getByText('5 selected')).toBeInTheDocument()
+  })
+})

src/components/BulkActionBar.tsx

@@ -1,14 +1,20 @@
 import { memo } from 'react'
-import { Archive, Trash, X } from '@phosphor-icons/react'
+import { Archive, ArrowCounterClockwise, Trash, X } from '@phosphor-icons/react'
 
 interface BulkActionBarProps {
   count: number
+  isTrashView: boolean
   onArchive: () => void
   onTrash: () => void
+  onRestore: () => void
+  onDeletePermanently: () => void
   onClear: () => void
 }
 
-function BulkActionBarInner({ count, onArchive, onTrash, onClear }: BulkActionBarProps) {
+const actionBtnStyle = { padding: '5px 10px', borderRadius: 6, background: 'rgba(255,255,255,0.12)', color: 'inherit', fontSize: 12, fontWeight: 500 } as const
+const destructiveBtnStyle = { padding: '5px 10px', borderRadius: 6, background: 'rgba(224,62,62,0.2)', color: 'var(--destructive)', fontSize: 12, fontWeight: 500 } as const
+
+function BulkActionBarInner({ count, isTrashView, onArchive, onTrash, onRestore, onDeletePermanently, onClear }: BulkActionBarProps) {
   return (
     <div
       className="flex shrink-0 items-center justify-between"
@@ -24,26 +30,53 @@ function BulkActionBarInner({ count, onArchive, onTrash, onClear }: BulkActionBa
         {count} selected
       </span>
       <div className="flex items-center gap-1">
-        <button
-          className="flex items-center gap-1.5 border-none bg-transparent cursor-pointer"
-          style={{ padding: '5px 10px', borderRadius: 6, background: 'rgba(255,255,255,0.12)', color: 'inherit', fontSize: 12, fontWeight: 500 }}
-          onClick={onArchive}
-          title="Archive selected notes"
-          data-testid="bulk-archive-btn"
-        >
-          <Archive size={14} />
-          Archive
-        </button>
-        <button
-          className="flex items-center gap-1.5 border-none cursor-pointer"
-          style={{ padding: '5px 10px', borderRadius: 6, background: 'rgba(224,62,62,0.2)', color: 'var(--destructive)', fontSize: 12, fontWeight: 500 }}
-          onClick={onTrash}
-          title="Move selected notes to trash"
-          data-testid="bulk-trash-btn"
-        >
-          <Trash size={14} />
-          Trash
-        </button>
+        {isTrashView ? (
+          <>
+            <button
+              className="flex items-center gap-1.5 border-none bg-transparent cursor-pointer"
+              style={actionBtnStyle}
+              onClick={onRestore}
+              title="Restore selected notes"
+              data-testid="bulk-restore-btn"
+            >
+              <ArrowCounterClockwise size={14} />
+              Restore
+            </button>
+            <button
+              className="flex items-center gap-1.5 border-none cursor-pointer"
+              style={destructiveBtnStyle}
+              onClick={onDeletePermanently}
+              title="Permanently delete selected notes"
+              data-testid="bulk-delete-btn"
+            >
+              <Trash size={14} />
+              Delete permanently
+            </button>
+          </>
+        ) : (
+          <>
+            <button
+              className="flex items-center gap-1.5 border-none bg-transparent cursor-pointer"
+              style={actionBtnStyle}
+              onClick={onArchive}
+              title="Archive selected notes"
+              data-testid="bulk-archive-btn"
+            >
+              <Archive size={14} />
+              Archive
+            </button>
+            <button
+              className="flex items-center gap-1.5 border-none cursor-pointer"
+              style={destructiveBtnStyle}
+              onClick={onTrash}
+              title="Move selected notes to trash"
+              data-testid="bulk-trash-btn"
+            >
+              <Trash size={14} />
+              Trash
+            </button>
+          </>
+        )}
         <button
           className="flex items-center border-none bg-transparent cursor-pointer"
           style={{ padding: '5px 6px', color: 'rgba(255,255,255,0.5)' }}

src/components/ConfirmDeleteDialog.test.tsx

@@ -0,0 +1,81 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { ConfirmDeleteDialog } from './ConfirmDeleteDialog'
+
+describe('ConfirmDeleteDialog', () => {
+  const onConfirm = vi.fn()
+  const onCancel = vi.fn()
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('renders with title and message', () => {
+    render(
+      <ConfirmDeleteDialog
+        open={true}
+        title="Delete permanently?"
+        message="This cannot be undone."
+        onConfirm={onConfirm}
+        onCancel={onCancel}
+      />,
+    )
+    expect(screen.getByText('Delete permanently?')).toBeInTheDocument()
+    expect(screen.getByText('This cannot be undone.')).toBeInTheDocument()
+  })
+
+  it('calls onConfirm when delete button clicked', () => {
+    render(
+      <ConfirmDeleteDialog
+        open={true}
+        title="Delete permanently?"
+        message="This cannot be undone."
+        onConfirm={onConfirm}
+        onCancel={onCancel}
+      />,
+    )
+    fireEvent.click(screen.getByTestId('confirm-delete-btn'))
+    expect(onConfirm).toHaveBeenCalledTimes(1)
+  })
+
+  it('calls onCancel when cancel button clicked', () => {
+    render(
+      <ConfirmDeleteDialog
+        open={true}
+        title="Delete permanently?"
+        message="This cannot be undone."
+        onConfirm={onConfirm}
+        onCancel={onCancel}
+      />,
+    )
+    fireEvent.click(screen.getByText('Cancel'))
+    expect(onCancel).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not render when open is false', () => {
+    render(
+      <ConfirmDeleteDialog
+        open={false}
+        title="Delete permanently?"
+        message="This cannot be undone."
+        onConfirm={onConfirm}
+        onCancel={onCancel}
+      />,
+    )
+    expect(screen.queryByText('Delete permanently?')).not.toBeInTheDocument()
+  })
+
+  it('uses custom confirm label when provided', () => {
+    render(
+      <ConfirmDeleteDialog
+        open={true}
+        title="Empty Trash?"
+        message="Delete all notes?"
+        confirmLabel="Empty Trash"
+        onConfirm={onConfirm}
+        onCancel={onCancel}
+      />,
+    )
+    expect(screen.getByText('Empty Trash')).toBeInTheDocument()
+  })
+})

src/components/ConfirmDeleteDialog.tsx

@@ -0,0 +1,49 @@
+import { memo } from 'react'
+import { Trash } from '@phosphor-icons/react'
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogFooter,
+} from '@/components/ui/dialog'
+import { Button } from '@/components/ui/button'
+
+interface ConfirmDeleteDialogProps {
+  open: boolean
+  title: string
+  message: string
+  confirmLabel?: string
+  onConfirm: () => void
+  onCancel: () => void
+}
+
+export const ConfirmDeleteDialog = memo(function ConfirmDeleteDialog({
+  open,
+  title,
+  message,
+  confirmLabel = 'Delete permanently',
+  onConfirm,
+  onCancel,
+}: ConfirmDeleteDialogProps) {
+  return (
+    <Dialog open={open} onOpenChange={(isOpen) => { if (!isOpen) onCancel() }}>
+      <DialogContent showCloseButton={false} data-testid="confirm-delete-dialog">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Trash size={18} className="text-destructive" />
+            {title}
+          </DialogTitle>
+          <DialogDescription>{message}</DialogDescription>
+        </DialogHeader>
+        <DialogFooter>
+          <Button variant="outline" onClick={onCancel}>Cancel</Button>
+          <Button variant="destructive" onClick={onConfirm} data-testid="confirm-delete-btn">
+            {confirmLabel}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+})

src/components/DynamicPropertiesPanel.test.tsx

@@ -130,7 +130,43 @@ describe('DynamicPropertiesPanel', () => {
     expect(screen.getByText('Luca')).toBeInTheDocument()
   })
 
-  it('skips aliases and relationship keys', () => {
+  it('renders capitalized Owner with plain text value in Properties panel', () => {
+    render(
+      <DynamicPropertiesPanel
+        entry={makeEntry()}
+        content=""
+        frontmatter={{ Owner: 'Luca' }}
+      />
+    )
+    expect(screen.getByText('Owner')).toBeInTheDocument()
+    expect(screen.getByText('Luca')).toBeInTheDocument()
+  })
+
+  it('hides Owner with wikilink value from Properties panel', () => {
+    render(
+      <DynamicPropertiesPanel
+        entry={makeEntry()}
+        content=""
+        frontmatter={{ Owner: '[[person/luca]]' }}
+      />
+    )
+    // Owner with wikilink goes to RelationshipsPanel, not Properties
+    expect(screen.queryByText('Owner')).not.toBeInTheDocument()
+  })
+
+  it('renders notion_id as a visible property', () => {
+    render(
+      <DynamicPropertiesPanel
+        entry={makeEntry()}
+        content=""
+        frontmatter={{ notion_id: 'abc-123-def' }}
+      />
+    )
+    expect(screen.getByText('notion_id')).toBeInTheDocument()
+    expect(screen.getByText('abc-123-def')).toBeInTheDocument()
+  })
+
+  it('skips aliases and fields with wikilink values', () => {
     render(
       <DynamicPropertiesPanel
         entry={makeEntry()}
@@ -138,12 +174,37 @@ describe('DynamicPropertiesPanel', () => {
         frontmatter={{ aliases: ['AL'], 'Belongs to': '[[Something]]', cadence: 'Monthly' }}
       />
     )
-    // aliases and "Belongs to" should be skipped
+    // aliases skipped (in SKIP_KEYS); 'Belongs to' skipped (has wikilinks)
     expect(screen.queryByText('aliases')).not.toBeInTheDocument()
     expect(screen.queryByText('Belongs to')).not.toBeInTheDocument()
     expect(screen.getByText('cadence')).toBeInTheDocument()
   })
 
+  it('shows former relationship key with plain text value in Properties', () => {
+    render(
+      <DynamicPropertiesPanel
+        entry={makeEntry()}
+        content=""
+        frontmatter={{ 'Belongs to': 'some-team', cadence: 'Monthly' }}
+      />
+    )
+    // 'Belongs to' has a plain text value, not a wikilink — should render as property
+    expect(screen.getByText('Belongs to')).toBeInTheDocument()
+    expect(screen.getByText('some-team')).toBeInTheDocument()
+  })
+
+  it('hides custom field with wikilink value from Properties', () => {
+    render(
+      <DynamicPropertiesPanel
+        entry={makeEntry()}
+        content=""
+        frontmatter={{ Mentor: '[[person/luca]]' }}
+      />
+    )
+    // Mentor contains a wikilink → shown in Relationships, not Properties
+    expect(screen.queryByText('Mentor')).not.toBeInTheDocument()
+  })
+
   it('skips is_a, Is A, and type keys (shown via TypeRow instead)', () => {
     render(
       <DynamicPropertiesPanel
@@ -837,7 +898,7 @@ describe('DynamicPropertiesPanel', () => {
     beforeEach(() => {
       resetVaultConfigStore()
       bindVaultConfigStore(
-        { zoom: null, view_mode: null, tag_colors: null, status_colors: null, property_display_modes: null, hidden_sections: null },
+        { zoom: null, view_mode: null, tag_colors: null, status_colors: null, property_display_modes: null },
         vi.fn(),
       )
       initDisplayModeOverrides({})

src/components/DynamicPropertiesPanel.tsx

@@ -27,12 +27,6 @@ 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([
-  'Belongs to', 'Related to', 'Events', 'Has Data', 'Owner',
-  'Advances', 'Parent', 'Children', 'Has', 'Notes',
-])
-
 // 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)
@@ -658,14 +652,13 @@ function NoteInfoSection({ entry, wordCount }: { entry: VaultEntry; wordCount: n
 }
 
 export function DynamicPropertiesPanel({
-  entry, content, frontmatter, entries, allContent,
+  entry, content, frontmatter, entries,
   onUpdateProperty, onDeleteProperty, onAddProperty, onNavigate,
 }: {
   entry: VaultEntry
   content: string | null
   frontmatter: ParsedFrontmatter
   entries?: VaultEntry[]
-  allContent?: Record<string, string>
   onUpdateProperty?: (key: string, value: FrontmatterValue) => void
   onDeleteProperty?: (key: string) => void
   onAddProperty?: (key: string, value: FrontmatterValue) => void
@@ -675,7 +668,7 @@ export function DynamicPropertiesPanel({
     editingKey, setEditingKey, showAddDialog, setShowAddDialog, displayOverrides,
     availableTypes, customColorKey, typeColorKeys, typeIconKeys, vaultStatuses, vaultTagsByKey, propertyEntries,
     handleSaveValue, handleSaveList, handleAdd, handleDisplayModeChange,
-  } = usePropertyPanelState({ entries, entryIsA: entry.isA, frontmatter, allContent, onUpdateProperty, onDeleteProperty, onAddProperty })
+  } = usePropertyPanelState({ entries, entryIsA: entry.isA, frontmatter, onUpdateProperty, onDeleteProperty, onAddProperty })
 
   const wordCount = countWords(content ?? '')
 

src/components/Editor.css

@@ -31,6 +31,7 @@
   display: flex;
   justify-content: center;
   position: relative;
+  cursor: text;
 }
 
 /* Drag-over state: subtle border highlight */