obsidian-zk 0.1.3 → 0.2.1

package/README.md

@@ -6,12 +6,14 @@ Works with [Claude Code](https://claude.ai/code) — exposes tools and prompts v
 
 ## What it does
 
-- **CRUD** for fleeting, literature, and permanent notes with proper frontmatter
+- **CRUD** for fleeting, literature, permanent, MOC, and project notes with proper frontmatter
 - **Luhmann numbering** — auto-generates `zk_id` with alternating numbers/letters (`1 → 1a → 1a1 → 1a1a`)
-- **Connection search** — finds related notes by shared tags, keywords, link proximity
-- **Vault analysis** — unprocessed notes, orphans, emerging theme clusters
-- **MCP prompts** — guided workflows as slash commands (`/zk:capture`, `/zk:promote`, etc.)
-- **SQLite index** — fast metadata queries without scanning files every time
+- **Connection scoring** — finds related notes by shared tags, keywords, Luhmann proximity, MOC overlap
+- **Backlinks** — incoming/outgoing link tracking with path-based resolution
+- **Vault analysis** — unprocessed notes with age warnings, orphans, emerging theme clusters
+- **Quality pipeline** — promote fleeting/literature → permanent, finalize with quality checks
+- **MCP skills** — guided workflows as slash commands (`/zk:capture`, `/zk:promote`, `/zk:moc`, etc.)
+- **SQLite index** — incremental indexing with single-note updates, path-based link storage
 
 No embeddings — Claude judges semantic relevance directly in context.
 
@@ -24,8 +26,9 @@ npx obsidian-zk init
 ```
 
 Interactive wizard:
+
 - Detects or asks for vault path
-- Creates folder structure (`1-Fleeting/`, `2-Literature/`, `3-Permanent/`, etc.)
+- Creates folder structure (`1-Fleeting/`, `2-Literature/`, `3-Permanent/`, `4-MOC/`, `5-Projects/`)
 - Copies note templates, skills, and agents into `.claude/`
 - Creates `CLAUDE.md` with project instructions
 - Sets up SQLite database in `.zk/`
@@ -42,17 +45,22 @@ claude
 
 The MCP server starts automatically. Use prompts:
 
-| Command | What it does |
-|---------|-------------|
-| `/zk:capture` | Quick fleeting note from a thought |
-| `/zk:literature` | Literature note from pasted source |
-| `/zk:permanent` | Atomic permanent note with auto Luhmann ID |
-| `/zk:promote` | Convert fleeting → permanent |
-| `/zk:manage` | Edit/archive/delete by Luhmann number |
-| `/zk:review` | Vault health report |
-| `/zk:daily` | Morning briefing |
-| `/zk:connect` | Find and create connections for a note |
-| `/zk:reflect` | Deep reflection on vault themes |
+
+| Command          | What it does                                         |
+| ---------------- | ---------------------------------------------------- |
+| `/zk:capture`    | Quick fleeting note from a thought                   |
+| `/zk:literature` | Literature note from pasted source                   |
+| `/zk:permanent`  | Atomic permanent note with auto Luhmann ID           |
+| `/zk:promote`    | Convert fleeting/literature → permanent (single/batch) |
+| `/zk:manage`     | Edit/archive/delete by Luhmann number                |
+| `/zk:moc`        | Create Map of Content — auto-pulls notes by tag      |
+| `/zk:project`    | Create project note with tasks and deadlines         |
+| `/zk:finalize`   | Quality-check and finalize permanent notes           |
+| `/zk:review`     | Vault health report                                  |
+| `/zk:daily`      | Morning briefing with age warnings                   |
+| `/zk:connect`    | Find and create connections for a note               |
+| `/zk:reflect`    | Deep reflection on vault themes                      |
+
 
 ### 3. Update
 
@@ -69,42 +77,52 @@ Syncs skills/agents, runs DB migrations.
 ```
 Claude Code ←→ MCP Server (obsidian-zk serve) ←→ SQLite DB + Vault files
                    │
-                   ├── Tools (zk_capture, zk_permanent, zk_find_connections, ...)
-                   └── Prompts (/zk:capture, /zk:promote, /zk:review, ...)
+                   ├── Tools (zk_capture, zk_permanent, zk_moc, zk_backlinks, ...)
+                   └── Skills (/zk:capture, /zk:promote, /zk:finalize, ...)
 ```
 
 ### Architecture
 
-| Component | Choice |
-|-----------|--------|
-| MCP SDK | `@modelcontextprotocol/sdk` (stdio transport) |
-| Database | `better-sqlite3` — single `.zk/zettelkasten.db` file |
-| Semantic search | Claude itself — no embeddings infra needed |
-| Vault I/O | Node.js `fs` — direct file read/write |
+
+| Component       | Choice                                               |
+| --------------- | ---------------------------------------------------- |
+| MCP SDK         | `@modelcontextprotocol/sdk` (stdio transport)        |
+| Database        | `better-sqlite3` — single `.zk/zettelkasten.db` file |
+| Semantic search | Claude itself — no embeddings infra needed           |
+| Vault I/O       | Node.js `fs` — direct file read/write                |
+
 
 ### MCP Tools
 
 **CRUD:**
+
 - `zk_capture` — create fleeting note
 - `zk_literature` — create literature note
 - `zk_permanent` — create permanent note with Luhmann ID
-- `zk_manage` — edit/archive/delete by ID
-- `zk_promote` — mark fleeting as processed
+- `zk_manage` — edit frontmatter + body sections, archive, delete by ID
+- `zk_promote` — mark fleeting/literature as processed, extract key ideas
+- `zk_moc` — create Map of Content, auto-pull notes by tags
+- `zk_project` — create project note with tasks/deadlines
 
 **Search & connections:**
-- `zk_find_connections` — candidates by tags + links + keywords
+
+- `zk_find_connections` — candidates scored by tags, keywords, Luhmann proximity, MOC overlap
+- `zk_backlinks` — incoming/outgoing links for a note (by path, title, or ID)
 - `zk_cluster_detect` — emerging themes without MOCs
 
 **Analysis:**
+
 - `zk_list` — filter notes by type/status/folder
-- `zk_unprocessed` — notes needing processing
+- `zk_unprocessed` — notes needing processing with age and urgency tiers
 - `zk_orphans` — notes with no incoming links
+- `zk_finalize` — quality-check permanent notes (connections, claim, evidence, confidence)
 - `zk_next_id` — next Luhmann ID
 - `zk_find_by_id` — resolve ID → path
 - `zk_list_ids` — all numbered notes
 - `zk_review` — full vault health report
 
 **Index:**
+
 - `zk_reindex` — full vault re-scan
 - `zk_status` — DB stats
 
@@ -124,19 +142,21 @@ CREATE TABLE links (
 );
 ```
 
-Incremental indexing — compares `content_hash`, only updates changed files.
+Links use **path-based resolution** — wikilink titles resolved to file paths during indexing. Incremental indexing via `content_hash`; single-note `indexNote()` for CRUD ops, full `reindex()` for vault scans.
 
 ## Zettelkasten method
 
 ### Note types
 
-| Folder | Type | Atomic? | Lifecycle |
-|--------|------|---------|-----------|
-| `1-Fleeting/` | Raw thoughts | No | unprocessed → processed |
-| `2-Literature/` | Source summaries | Partial | unprocessed → processed |
-| `3-Permanent/` | One idea per note | **Yes** | draft → finalized |
-| `4-MOC/` | Topic indexes | No | — |
-| `5-Projects/` | Active goals | No | active → completed |
+
+| Folder          | Type              | Atomic? | Lifecycle               |
+| --------------- | ----------------- | ------- | ----------------------- |
+| `1-Fleeting/`   | Raw thoughts      | No      | unprocessed → processed |
+| `2-Literature/` | Source summaries  | Partial | unprocessed → processed |
+| `3-Permanent/`  | One idea per note | **Yes** | draft → finalized       |
+| `4-MOC/`        | Topic indexes     | No      | draft → active          |
+| `5-Projects/`   | Active goals      | No      | active → completed      |
+
 
 ### Luhmann numbering
 
@@ -153,19 +173,151 @@ Incremental indexing — compares `content_hash`, only updates changed files.
 - **Розширює** (Extends) — builds upon another idea
 - **Пов'язано** (Related) — topically connected
 
+### Connection scoring
+
+Notes are scored for connection relevance using multiple signals:
+- Shared tags: +2 per tag
+- Keyword overlap: +1 (4+ chars), +2 (6+ chars)
+- Luhmann proximity: +3 (siblings), +1 (cousins)
+- Shared MOC: +2
+- Threshold: score ≥ 2 to appear as candidate
+
 ### Workflow
 
 ```
 Thought → /zk:capture → Fleeting note
 Source  → /zk:literature → Literature note
                 ↓
-         /zk:promote (or /zk:permanent)
+         /zk:promote (fleeting or literature)
                 ↓
          Permanent note (auto zk_id) ←→ connections
                 ↓
+         /zk:finalize (quality check)
+                ↓
          MOC (when 3+ related notes cluster)
 ```
 
+## Use cases
+
+### Research & learning
+
+**Reading a book or paper:**
+
+```
+> /zk:literature
+> Here are my highlights from "Thinking, Fast and Slow" by Kahneman...
+```
+
+1. `/zk:literature` — paste highlights, Claude creates a structured literature note with source metadata
+2. `/zk:promote` — extract atomic ideas into permanent notes, each with its own Luhmann ID
+3. `/zk:connect` — Claude finds related notes in your vault and suggests typed connections
+
+**Exploring a new topic:**
+
+```
+> /zk:capture
+> Just learned that mitochondrial DNA is inherited only from the mother.
+> This might connect to my notes on epigenetics.
+```
+
+1. `/zk:capture` several fleeting notes as you read/watch/listen
+2. `/zk:daily` — review what's accumulated, see age warnings for stale notes
+3. `/zk:promote` in batch — convert the best ideas into permanent notes
+4. `/zk:moc` — once 3+ notes cluster around a theme, create a Map of Content
+
+### Writing & thinking
+
+**Preparing an article or essay:**
+
+```
+> /zk:reflect
+> I'm writing a blog post about decision-making under uncertainty.
+> What themes in my vault are relevant?
+```
+
+1. `/zk:reflect` — Claude analyzes vault themes and surfaces unexpected connections
+2. `/zk:review` — find orphaned notes and weak spots in your knowledge graph
+3. Browse MOCs to build an outline from existing permanent notes
+4. `/zk:connect` — strengthen the argument by finding supporting/contradicting notes
+
+**Developing an argument:**
+
+```
+> /zk:permanent
+> Claim: distributed teams outperform co-located ones when
+> async communication norms are explicit.
+```
+
+1. `/zk:permanent` — write your claim as an atomic note
+2. `/zk:connect` — Claude scores candidates and suggests supporting/contradicting links
+3. Follow the Luhmann tree (1 → 1a → 1a1) to build a chain of reasoning
+4. `/zk:finalize` — quality check: does the note have evidence, confidence level, enough connections?
+
+### Daily knowledge work
+
+**Morning routine:**
+
+```
+> /zk:daily
+```
+
+Claude shows unprocessed notes grouped by urgency, suggests which to promote first.
+
+1. `/zk:daily` — see unprocessed notes with urgency tiers, aging warnings
+2. `/zk:promote` — process the oldest fleeting notes first
+3. `/zk:connect` on newly promoted notes — integrate them into the graph
+
+**After a meeting or conversation:**
+
+```
+> /zk:capture
+> Meeting with Alex: they suggested using event sourcing instead of CRUD
+> for the audit log. Interesting tradeoff — immutability vs query complexity.
+```
+
+1. `/zk:capture` — dump raw thoughts quickly (title + body, no structure needed)
+2. Come back later, `/zk:promote` — Claude helps extract the key insight into a permanent note
+
+### Project management
+
+**Tracking a goal:**
+
+```
+> /zk:project
+> Project: "Q2 API redesign". Deadline: June 30.
+> Key tasks: schema migration, client SDK update, docs rewrite.
+> Link to my notes on REST vs GraphQL tradeoffs.
+```
+
+1. `/zk:project` — create a project note with tasks, deadlines, and linked permanent notes
+2. Link relevant permanent notes as the knowledge base for the project
+3. `/zk:review` — monitor project health alongside vault health
+
+### Vault maintenance
+
+**Weekly cleanup:**
+
+```
+> /zk:review
+```
+
+Claude reports: 12 unprocessed notes (3 urgent), 5 orphans, 2 emerging clusters without MOCs.
+
+1. `/zk:review` — full vault health report (orphans, unprocessed count, connection density)
+2. `/zk:finalize` — batch quality-check draft permanent notes
+3. `/zk:moc` — create MOCs for emerging clusters detected by `/zk:reflect`
+
+**Onboarding to an existing vault:**
+
+```
+> /zk:reflect
+> I just inherited this vault. What are the main themes and how do they connect?
+```
+
+1. `/zk:review` — get a high-level picture of vault state
+2. `/zk:reflect` — understand major themes and how they connect
+3. Browse MOCs and Luhmann trees to navigate the knowledge structure
+
 ## Development
 
 ```bash
@@ -202,14 +354,24 @@ src/
 ├── vault/
 │   ├── parser.ts         # Frontmatter, wikilinks, body
 │   ├── scanner.ts        # File discovery
-│   └── writer.ts         # Note creation/editing
+│   └── writer.ts         # Note creation/editing + section updates
 ├── db/
-│   ├── schema.ts         # SQLite schema
-│   └── index.ts          # DB connection + indexing
+│   ├── schema.ts         # SQLite schema + migrations
+│   └── index.ts          # DB connection, indexing, connection scoring
 ├── tools/                # MCP tool implementations
+│   ├── capture.ts        # Fleeting notes
+│   ├── literature.ts     # Literature notes
+│   ├── permanent.ts      # Permanent notes (from fleeting or literature)
+│   ├── manage.ts         # Edit/archive/delete/finalize
+│   ├── moc.ts            # Map of Content creation
+│   ├── project.ts        # Project notes
+│   ├── backlinks.ts      # Incoming/outgoing link queries
+│   ├── search.ts         # Connection search + cluster detection
+│   ├── analysis.ts       # Unprocessed, orphans, review
+│   └── index-mgmt.ts     # Reindex, status
 └── luhmann.ts            # ID generation + sorting
 templates/                # Copied to user vault on init
-├── claude/skills/        # 9 SKILL.md files
+├── claude/skills/        # 12 SKILL.md files
 ├── claude/agents/        # zk-analyzer agent
 ├── vault-folders/        # Default folder structure + note templates
 └── CLAUDE.md.template    # Project instructions

package/dist/db/index.d.ts

@@ -6,6 +6,9 @@ export declare class ZkDatabase {
     db: Database.Database;
     vaultRoot: string;
     constructor(vaultRoot: string);
+    resolveWikilink(title: string): string | null;
+    indexNote(relPath: string): void;
+    removeNote(relPath: string): void;
     reindex(): {
         added: number;
         updated: number;
@@ -28,7 +31,8 @@ export declare class ZkDatabase {
     getUnprocessed(type?: string): any[];
     getOrphans(folder?: string): any[];
     getLinksFrom(relPath: string): any[];
-    getLinksTo(title: string): any[];
+    getLinksTo(path: string): any[];
+    shareMoc(pathA: string, pathB: string): boolean;
     findConnections(notePath: string): {
         path: string;
         title: string;

package/dist/db/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAQtC,qBAAa,UAAU;IACrB,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;gBAEN,SAAS,EAAE,MAAM;IAY7B,OAAO,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IA8E9D,aAAa,CAAC,OAAO,EAAE,MAAM,GACkD,GAAG;IAGlF,WAAW,CAAC,IAAI,EAAE,MAAM,GACqD,GAAG;IAGhF,cAAc,CAAC,IAAI,EAAE,MAAM,GACiD,GAAG,EAAE;IAGjF,gBAAgB,CAAC,MAAM,EAAE,MAAM,GACiD,GAAG,EAAE;IAGrF,gBAAgB,CAAC,MAAM,EAAE,MAAM,GACiD,GAAG,EAAE;IAGrF,SAAS,CAAC,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAOtB,GAAG,EAAE;IAGrD,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAO3D,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAKoB,GAAG,EAAE;IAGrD,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,GAUsB,GAAG,EAAE;IAGrD,YAAY,CAAC,OAAO,EAAE,MAAM,GACqD,GAAG,EAAE;IAGtF,UAAU,CAAC,KAAK,EAAE,MAAM,GACuD,GAAG,EAAE;IAGpF,eAAe,CAAC,QAAQ,EAAE,MAAM;cAQJ,MAAM;eAAS,MAAM;eAAS,MAAM;iBAAW,MAAM,EAAE;iBAAW,MAAM;cAAQ,MAAM;;IA4BlH,QAAQ;;;;;;;IASR,KAAK;CAGN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAiDtC,qBAAa,UAAU;IACrB,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;gBAEN,SAAS,EAAE,MAAM;IAY7B,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAK7C,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IA4ChC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAMjC,OAAO,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAoF9D,aAAa,CAAC,OAAO,EAAE,MAAM,GACkD,GAAG;IAGlF,WAAW,CAAC,IAAI,EAAE,MAAM,GACqD,GAAG;IAGhF,cAAc,CAAC,IAAI,EAAE,MAAM,GACiD,GAAG,EAAE;IAGjF,gBAAgB,CAAC,MAAM,EAAE,MAAM,GACiD,GAAG,EAAE;IAGrF,gBAAgB,CAAC,MAAM,EAAE,MAAM,GACiD,GAAG,EAAE;IAGrF,SAAS,CAAC,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAOtB,GAAG,EAAE;IAGrD,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAO3D,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAKoB,GAAG,EAAE;IAGrD,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,GASsB,GAAG,EAAE;IAGrD,YAAY,CAAC,OAAO,EAAE,MAAM,GACqD,GAAG,EAAE;IAGtF,UAAU,CAAC,IAAI,EAAE,MAAM,GACuD,GAAG,EAAE;IAGnF,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAU/C,eAAe,CAAC,QAAQ,EAAE,MAAM;cAOJ,MAAM;eAAS,MAAM;eAAS,MAAM;iBAAW,MAAM,EAAE;iBAAW,MAAM;cAAQ,MAAM;;IA4ClH,QAAQ;;;;;;;IASR,KAAK;CAGN"}

package/dist/db/index.js

@@ -8,6 +8,52 @@ import { join, dirname, basename } from "node:path";
 import { CREATE_TABLES, SCHEMA_VERSION } from "./schema.js";
 import { scanVault } from "../vault/scanner.js";
 import { parseFrontmatter, getBody, getTags, getWikilinks } from "../vault/parser.js";
+function extractSummary(fm, body, type) {
+    if (type === "permanent" && fm.claim) {
+        return String(fm.claim);
+    }
+    if (type === "literature") {
+        const lines = body.split("\n");
+        let para = "";
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#")) {
+                if (para)
+                    return para.slice(0, 500);
+                continue;
+            }
+            para += (para ? " " : "") + trimmed;
+        }
+        if (para)
+            return para.slice(0, 500);
+    }
+    if (type === "fleeting") {
+        const match = body.match(/##\s+Thought[^\n]*\n([\s\S]*?)(?=\n##|$)/);
+        if (match)
+            return match[1].trim().slice(0, 500);
+    }
+    return body.trim().slice(0, 500);
+}
+function luhmannProximity(idA, idB) {
+    if (!idA || !idB)
+        return 0;
+    const partsA = idA.match(/(\d+|[a-z]+)/g) ?? [];
+    const partsB = idB.match(/(\d+|[a-z]+)/g) ?? [];
+    let common = 0;
+    for (let i = 0; i < Math.min(partsA.length, partsB.length); i++) {
+        if (partsA[i] === partsB[i])
+            common++;
+        else
+            break;
+    }
+    if (common === 0)
+        return 0;
+    // Siblings: share all but last segment
+    if (common >= Math.max(partsA.length, partsB.length) - 1)
+        return 3;
+    // Cousins: share at least one segment
+    return 1;
+}
 export class ZkDatabase {
     db;
     vaultRoot;
@@ -18,33 +64,71 @@ export class ZkDatabase {
             mkdirSync(dbDir, { recursive: true });
         const dbPath = join(dbDir, "zettelkasten.db");
         this.db = new Database(dbPath);
-        // WAL mode: allows concurrent reads during writes, better for indexing while serving queries
         this.db.pragma("journal_mode = WAL");
         this.db.exec(CREATE_TABLES);
         this.db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)").run("schema_version", String(SCHEMA_VERSION));
     }
+    resolveWikilink(title) {
+        const row = this.db.prepare("SELECT path FROM notes WHERE title = ?").get(title);
+        return row?.path ?? null;
+    }
+    indexNote(relPath) {
+        const fullPath = join(this.vaultRoot, relPath);
+        let content;
+        try {
+            content = readFileSync(fullPath, "utf-8");
+        }
+        catch {
+            return;
+        }
+        const hash = createHash("md5").update(content).digest("hex");
+        const fm = parseFrontmatter(fullPath);
+        const body = getBody(fullPath);
+        const title = basename(relPath, ".md");
+        const folder = dirname(relPath).split("/")[0] || "";
+        const tags = getTags(fm);
+        const type = fm.type;
+        const summary = extractSummary(fm, body, type);
+        this.db.prepare(`
+      INSERT OR REPLACE INTO notes (path, title, zk_id, type, status, folder, tags, summary, created, modified, content_hash)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(relPath, title, fm.zk_id || null, type || null, fm.status || null, folder, JSON.stringify(tags), summary, fm.date || null, fm.last_modified || null, hash);
+        // Rebuild links for this note
+        this.db.prepare("DELETE FROM links WHERE source = ?").run(relPath);
+        const insertLink = this.db.prepare("INSERT OR REPLACE INTO links (source, target, link_type) VALUES (?, ?, ?)");
+        const wikilinks = getWikilinks(fullPath);
+        for (const target of wikilinks) {
+            const targetPath = this.resolveWikilink(target) ?? target;
+            insertLink.run(relPath, targetPath, null);
+        }
+        this.db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)").run("last_index", new Date().toISOString());
+    }
+    removeNote(relPath) {
+        this.db.prepare("DELETE FROM notes WHERE path = ?").run(relPath);
+        this.db.prepare("DELETE FROM links WHERE source = ?").run(relPath);
+        this.db.prepare("DELETE FROM links WHERE target = ?").run(relPath);
+    }
     reindex() {
         const notes = scanVault(this.vaultRoot);
         const currentPaths = new Set(notes.map((n) => n.relPath));
         let added = 0, updated = 0, removed = 0;
-        // Remove deleted notes
+        // Remove deleted notes + their links
         const dbPaths = this.db.prepare("SELECT path FROM notes").all();
-        const removePaths = dbPaths.filter((r) => !currentPaths.has(r.path));
         const deleteNote = this.db.prepare("DELETE FROM notes WHERE path = ?");
         const deleteLinks = this.db.prepare("DELETE FROM links WHERE source = ?");
-        for (const { path } of removePaths) {
+        for (const { path } of dbPaths.filter((r) => !currentPaths.has(r.path))) {
             deleteNote.run(path);
             deleteLinks.run(path);
             removed++;
         }
-        // Upsert notes
+        // Pass 1: upsert all notes
         const getHash = this.db.prepare("SELECT content_hash FROM notes WHERE path = ?");
         const upsert = this.db.prepare(`
       INSERT OR REPLACE INTO notes (path, title, zk_id, type, status, folder, tags, summary, created, modified, content_hash)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
-        const insertLink = this.db.prepare("INSERT OR REPLACE INTO links (source, target, link_type) VALUES (?, ?, ?)");
-        const transaction = this.db.transaction(() => {
+        const changedPaths = new Set();
+        const upsertTx = this.db.transaction(() => {
             for (const note of notes) {
                 const fullPath = join(this.vaultRoot, note.relPath);
                 let content;
@@ -54,31 +138,41 @@ export class ZkDatabase {
                 catch {
                     continue;
                 }
-                // Incremental indexing: skip files whose content hash hasn't changed
                 const hash = createHash("md5").update(content).digest("hex");
                 const existing = getHash.get(note.relPath);
                 if (existing?.content_hash === hash)
                     continue;
+                changedPaths.add(note.relPath);
                 const fm = parseFrontmatter(fullPath);
                 const body = getBody(fullPath);
                 const title = basename(note.relPath, ".md");
                 const folder = dirname(note.relPath).split("/")[0] || "";
                 const tags = getTags(fm);
-                const summary = body.trim().slice(0, 200);
-                upsert.run(note.relPath, title, fm.zk_id || null, fm.type || null, fm.status || null, folder, JSON.stringify(tags), summary, fm.date || null, fm.last_modified || null, hash);
-                // Fully delete+reinsert links — simplest way to handle removed wikilinks
-                deleteLinks.run(note.relPath);
-                const wikilinks = getWikilinks(fullPath);
-                for (const target of wikilinks) {
-                    insertLink.run(note.relPath, target, null);
-                }
+                const type = fm.type;
+                const summary = extractSummary(fm, body, type);
+                upsert.run(note.relPath, title, fm.zk_id || null, type || null, fm.status || null, folder, JSON.stringify(tags), summary, fm.date || null, fm.last_modified || null, hash);
                 if (existing)
                     updated++;
                 else
                     added++;
             }
         });
-        transaction();
+        upsertTx();
+        // Pass 2: rebuild links for changed notes (all notes now in DB for resolution)
+        const insertLink = this.db.prepare("INSERT OR REPLACE INTO links (source, target, link_type) VALUES (?, ?, ?)");
+        const deleteSrcLinks = this.db.prepare("DELETE FROM links WHERE source = ?");
+        const linkTx = this.db.transaction(() => {
+            for (const relPath of changedPaths) {
+                deleteSrcLinks.run(relPath);
+                const fullPath = join(this.vaultRoot, relPath);
+                const wikilinks = getWikilinks(fullPath);
+                for (const target of wikilinks) {
+                    const targetPath = this.resolveWikilink(target) ?? target;
+                    insertLink.run(relPath, targetPath, null);
+                }
+            }
+        });
+        linkTx();
         this.db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)").run("last_index", new Date().toISOString());
         return { added, updated, removed };
     }
@@ -133,10 +227,9 @@ export class ZkDatabase {
         return this.db.prepare(sql).all(...params);
     }
     getOrphans(folder) {
-        // LEFT JOIN + NULL: notes where no link row matched = no incoming links
         let sql = `
       SELECT n.* FROM notes n
-      LEFT JOIN links l ON l.target = n.title
+      LEFT JOIN links l ON l.target = n.path
       WHERE l.target IS NULL
     `;
         const params = [];
@@ -150,34 +243,56 @@ export class ZkDatabase {
     getLinksFrom(relPath) {
         return this.db.prepare("SELECT * FROM links WHERE source = ?").all(relPath);
     }
-    getLinksTo(title) {
-        return this.db.prepare("SELECT * FROM links WHERE target = ?").all(title);
+    getLinksTo(path) {
+        return this.db.prepare("SELECT * FROM links WHERE target = ?").all(path);
+    }
+    shareMoc(pathA, pathB) {
+        const row = this.db.prepare(`
+      SELECT COUNT(*) as c FROM links l1
+      JOIN links l2 ON l1.source = l2.source
+      JOIN notes n ON l1.source = n.path AND n.type = 'moc'
+      WHERE l1.target = ? AND l2.target = ?
+    `).get(pathA, pathB);
+        return row.c > 0;
     }
     findConnections(notePath) {
         const note = this.getNoteByPath(notePath);
         if (!note)
             return [];
         const noteTags = JSON.parse(note.tags || "[]");
-        const noteTitle = note.title;
         const existingLinks = new Set(this.getLinksFrom(notePath).map((l) => l.target));
         const allNotes = this.db.prepare("SELECT * FROM notes WHERE path != ?").all(notePath);
         const candidates = [];
         for (const other of allNotes) {
-            if (existingLinks.has(other.title))
+            if (existingLinks.has(other.path))
                 continue;
             let score = 0;
             const reasons = [];
-            // Scoring: shared tags worth 2pts each, keyword overlap 1pt each.
+            // Shared tags: 2pts each
             const otherTags = JSON.parse(other.tags || "[]");
             const shared = noteTags.filter((t) => otherTags.includes(t));
             score += shared.length * 2;
             reasons.push(...shared.map((t) => `tag:${t}`));
-            // 4-char minimum filters stopwords; Ukrainian+Latin regex covers both languages
+            // Keyword overlap: 6+ chars → +2, shorter → +1
             const noteWords = new Set((note.summary || "").toLowerCase().match(/[а-яієїґa-z]{4,}/g) ?? []);
             const otherWords = (other.summary || "").toLowerCase().match(/[а-яієїґa-z]{4,}/g) ?? [];
-            const kwMatches = otherWords.filter((w) => noteWords.has(w)).length;
-            score += kwMatches;
-            // Threshold ≥2 filters noise (single keyword match alone not enough)
+            for (const w of otherWords) {
+                if (noteWords.has(w)) {
+                    score += w.length >= 6 ? 2 : 1;
+                    reasons.push(`kw:${w}`);
+                }
+            }
+            // Luhmann proximity
+            const proximity = luhmannProximity(note.zk_id, other.zk_id);
+            if (proximity > 0) {
+                score += proximity;
+                reasons.push(proximity >= 3 ? "luhmann:sibling" : "luhmann:cousin");
+            }
+            // MOC boost: both notes referenced by same MOC
+            if (score >= 1 && this.shareMoc(notePath, other.path)) {
+                score += 2;
+                reasons.push("shared-moc");
+            }
             if (score >= 2) {
                 candidates.push({ path: other.path, title: other.title, score, reasons, summary: other.summary || "", type: other.type || "" });
             }