Changeset 0.28.0.1 (#173)

docs/ICD/notes.md

@@ -0,0 +1,105 @@
+# Notes
+
+**Obsidian-style** knowledge graph with `[[wikilinks]]`, backlinks,
+graph visualization, and folder organization. Notes are user-scoped
+(personal notebook). Future: channel-scoped notes for workflow
+artifacts.
+
+### CRUD
+
+```
+GET    /notes                       → paginated list of noteListItem
+POST   /notes                       ← { "title", "content", "folder" }
+GET    /notes/:id                   → full note object
+PUT    /notes/:id                   ← { "title", "content", "folder" }
+DELETE /notes/:id
+```
+
+Note object:
+
+```json
+{
+  "id": "uuid",
+  "user_id": "uuid",
+  "title": "Meeting Notes",
+  "content": "# Meeting Notes\n\nDiscussed [[Project Alpha]]...",
+  "folder": "work",
+  "source_message_id": "uuid|null",
+  "created_at": "...",
+  "updated_at": "..."
+}
+```
+
+`source_message_id` links a note back to the chat message that
+created it (provenance for AI-generated notes).
+
+`noteListItem` is the same but with `content` truncated or omitted.
+
+### Search
+
+**Full-text search:**
+
+```
+GET /notes/search?q=project+alpha
+```
+
+Uses `plainto_tsquery` (Postgres) or `LIKE` fallback (SQLite).
+Returns `{ "data": [searchResult objects] }` with match highlights.
+
+**Title search** (lightweight, for wikilink autocomplete):
+
+```
+GET /notes/search-titles?q=proj
+```
+
+Returns `{ "data": [{ "id", "title" }] }`.
+
+### Graph
+
+**Full graph topology:**
+
+```
+GET /notes/graph
+```
+
+```json
+{
+  "nodes": [{ "id": "uuid", "title": "Note Title" }],
+  "edges": [{ "source": "uuid", "target": "uuid" }],
+  "unresolved": [{ "source": "uuid", "target_title": "Missing Note" }]
+}
+```
+
+Edges are directed: source contains `[[target_title]]`. Unresolved
+edges have a `target_title` but no matching note (dangling wikilink).
+When a note with that title is created, the edge auto-resolves.
+
+**Backlinks** (who links to this note):
+
+```
+GET /notes/:id/backlinks
+```
+
+Returns `{ "data": [note objects] }` — all notes containing
+`[[this note's title]]`.
+
+### Folders
+
+```
+GET /notes/folders
+```
+
+Returns `{ "folders": ["work", "personal", "archive"] }` — distinct
+folder values across all user notes.
+
+### Bulk Operations
+
+```
+POST /notes/bulk-delete
+```
+
+```json
+{ "ids": ["uuid-1", "uuid-2"] }
+```
+
+---