From aef79a02857cdce9620c254b4df9d44bbadcfa0b Mon Sep 17 00:00:00 2001
From: Gamosoft <gamosoft@users.noreply.github.com>
Date: Tue, 24 Mar 2026 11:45:57 +0100
Subject: [PATCH] updated main docs

---
 documentation/API.md      | 51 ++++++++++++++++++++++++++++++++++++++-
 documentation/FEATURES.md |  9 +++++++
 2 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/documentation/API.md b/documentation/API.md
index 6719dae..01aecf8 100644
--- a/documentation/API.md
+++ b/documentation/API.md
@@ -35,13 +35,62 @@ curl "http://localhost:8000/api/notes?limit=20&offset=20"
 ```http
 GET /api/notes/{note_path}
 ```
-Retrieve the content of a specific note.
+Retrieve the content of a specific note, including metadata and backlinks.
+
+**Query Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `include_backlinks` | boolean | `true` | Include backlinks (notes that link to this note) |
 
 **Example:**
 ```bash
 curl http://localhost:8000/api/notes/folder/mynote.md
 ```
 
+**Response:**
+```json
+{
+  "path": "folder/mynote.md",
+  "content": "# My Note\n\nNote content here...",
+  "metadata": {
+    "created": "2026-03-15T10:00:00+01:00",
+    "modified": "2026-03-17T14:30:00+01:00",
+    "size": 1234,
+    "lines": 42
+  },
+  "backlinks": [
+    {
+      "path": "meetings/standup.md",
+      "name": "standup",
+      "references": [
+        {
+          "line_number": 15,
+          "context": "...discussed [[mynote]]...",
+          "type": "wikilink"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Backlinks Response Fields:**
+
+| Field | Description |
+|-------|-------------|
+| `path` | Path of the note that links to this note |
+| `name` | Display name of the linking note |
+| `references` | Array of link occurrences (max 3 per note) |
+| `references[].line_number` | Line number where the link appears |
+| `references[].context` | Text snippet around the link |
+| `references[].type` | Link type: `wikilink` or `markdown` |
+
+**Without Backlinks:**
+```bash
+curl "http://localhost:8000/api/notes/folder/mynote.md?include_backlinks=false"
+```
+
 ### Create/Update Note
 ```http
 POST /api/notes/{note_path}
diff --git a/documentation/FEATURES.md b/documentation/FEATURES.md
index 9d831f4..613f420 100644
--- a/documentation/FEATURES.md
+++ b/documentation/FEATURES.md
@@ -60,6 +60,14 @@
 - **Hierarchical view** - Indentation shows heading structure
 - **Heading count badge** - Quick indicator of document structure
 
+### Backlinks
+- **Reverse link discovery** - See which notes link TO the current note
+- **Context snippets** - Preview the surrounding text where links appear
+- **Line numbers** - Know exactly where each reference is located
+- **Link type detection** - Distinguishes wikilinks from markdown links
+- **API access** - Query backlinks programmatically via REST API
+- **MCP integration** - AI assistants can discover note relationships
+
 ### Section Link Syntax
 To link to a heading, convert the heading text to a slug: **lowercase, spaces → dashes, remove special chars**.
 
@@ -365,6 +373,7 @@ Built-in **Model Context Protocol (MCP)** server for AI assistant integration:
 - **Browse tags** - AI understands your organization
 - **Create notes** - AI can save summaries and insights
 - **Knowledge graph** - AI can explore note relationships
+- **Discover backlinks** - AI can find what notes reference a specific note
 - **Zero setup** - Works with Docker or Python, just add config to Cursor/Claude
 
 ### Quick Setup (Docker)