docs: Add setup and usage instructions to README

2026-04-29 09:51:49 +02:00
parent c0c634ac92
commit 11d9c0556a
1 changed files with 150 additions and 1 deletions
@@ -4,7 +4,7 @@ A personal knowledge base and system for capturing, organizing, and synthesizing

 **Synced with:** Extended thinking passes (on-idle or nightly)  
 **Backed by:** Git for version control and history  
-**Indexed in:** MEMORY.md for fast access
+**Indexed in:** MEMORY.md for fast access  

 ## Structure

@@ -37,3 +37,152 @@ A personal knowledge base and system for capturing, organizing, and synthesizing
 ---

 Created 2026-04-26
+
+---
+
+## Quick Start (Setup)
+
+### 1. Clone the repo
+
+```bash
+cd /workspace
+git clone http://localhost:3002/clawd/second-brain.git
+cd second-brain
+```
+
+### 2. Start the vault server (headless)
+
+The vault server provides a REST API for reading and writing notes without needing Obsidian Desktop.
+
+```bash
+# Start the vault server
+OBSIDIAN_API_KEY=c3b35c9ff948d127ba46acad226ad3ab4b5992da0a53b4ffc1aae6d4c8cbb771 \
+VAULT_PATH=/workspace/second-brain \
+node vault-server.js &
+```
+
+The server runs on port **27123**.
+
+### 3. Start the MCP bridge (optional)
+
+For connecting to Bumblebee or other MCP clients:
+
+```bash
+./start-mcp.sh
+```
+
+### 4. Enable systemd auto-start (optional)
+
+```bash
+sudo cp vault-server.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now vault-server
+```
+
+---
+
+## Daily Usage
+
+### Capture a note
+
+```bash
+# Quick capture to inbox
+echo "- $(date +%Y-%m-%d): Idea about X" >> 00-inbox/capture.md
+```
+
+### Read or write via API
+
+```bash
+# Read a note
+curl -s \
+  -H "Authorization: Bearer c3b35c9ff948d127ba46acad226ad3ab4b5992da0a53b4ffc1aae6d4c8cbb771" \
+  "http://localhost:27123/vault/read?path=02-projects/gravl/status.md"
+
+# List all notes
+curl -s \
+  -H "Authorization: Bearer c3b35c9ff948d127ba46acad226ad3ab4b5992da0a53b4ffc1aae6d4c8cbb771" \
+  "http://localhost:27123/vault/list"
+```
+
+### Run dream sync manually
+
+```bash
+./dream-sync.sh
+```
+
+Or wait for the nightly cron job at 23:00.
+
+### Git sync
+
+```bash
+# Pull changes from other devices
+git pull origin master
+
+# Commit and push
+git add .
+git commit -m "Update notes"
+git push origin master
+```
+
+---
+
+## Vault Server API
+
+**Base URL:** `http://localhost:27123`  
+**Auth:** Bearer token (`OBSIDIAN_API_KEY`)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/vault/read` | GET | Read a note by `path` query param |
+| `/vault/list` | GET | List all notes in the vault |
+| `/vault/search` | GET | Search notes by `q` query param |
+
+Example:
+
+```bash
+curl -s \
+  -H "Authorization: Bearer <API_KEY>" \
+  "http://localhost:27123/vault/search?q=gravl"
+```
+
+---
+
+## Architecture
+
+```
+/workspace/second-brain/ (vault files)
+        ↓
+vault-server.js (Node.js REST API on port 27123)
+Reads vault directly from disk
+        ↓
+obsidian-mcp-server (MCP Protocol bridge)
+Provides tools for reading/writing vault
+        ↓
+Bumblebee (can read/write vault headless!)
+```
+
+---
+
+## Tips
+
+- **Capture fast, organize later.** Dump everything into 00-inbox/ first.
+- **Use templates.** Copy from 07-templates/ for consistent structure.
+- **Link notes.** Use `[[note-name]]` or `[text](path/to/note.md)` for connections.
+- **Tag for discovery.** Add `#tag` anywhere for searchability.
+- **Review weekly.** Move inbox items to proper folders during cleanup.
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| Vault server won't start | Check port 27123 is free: `lsof -i :27123` |
+| Auth failed | Verify `OBSIDIAN_API_KEY` matches |
+| MCP not connecting | Ensure vault-server is running first |
+| Git conflicts | Pull before push: `git pull origin master` |
+
+---
+
+Created 2026-04-26
+Updated 2026-04-29