Second-brain 2.0: hybrid retrieval, obsidian bridge, vector watermark, tests

docs/OBSIDIAN.md

@@ -0,0 +1,75 @@
+# Obsidian Coupling (Second-Brain 2.0)
+
+This integrates an Obsidian vault with Second-Brain via two cron tasks:
+
+- `cron_tasks/ingest_obsidian.py` (vault → Second-Brain)
+- `cron_tasks/export_obsidian.py` (Second-Brain → vault)
+
+All settings live in `second-brain/data/obsidian_config.json`.
+
+## 1) Install / Sync the vault to the server
+
+You need a local folder on the server that contains an Obsidian vault (it must contain a `.obsidian/` directory), e.g.:
+
+- `/srv/obsidian/MyVault`
+- `/data/obsidian/MyVault`
+- `/root/Obsidian/MyVault`
+
+How you sync it is up to you (Syncthing, rsync, SMB mount, etc.).
+
+## 2) Set `vault_path` in config (auto or manual)
+
+### Auto-discover (only writes if unambiguous)
+
+```bash
+python3 second-brain/scripts/discover_obsidian_vault.py
+python3 second-brain/scripts/discover_obsidian_vault.py --write
+```
+
+If multiple vaults are detected, it prints them and refuses to write.
+
+### Manual
+
+Edit `second-brain/data/obsidian_config.json` and set:
+
+- `vault_path` to the vault directory (the parent of `.obsidian/`)
+
+## 3) Enable ingest/export
+
+In `second-brain/data/obsidian_config.json`:
+
+- Set `enabled.ingest` to `true` to ingest vault markdown into Second-Brain
+- Set `enabled.export` to `true` to export Second-Brain engrams into the vault
+
+## 4) Enable timers (systemd)
+
+This repo ships unit files in `systemd/`:
+
+- `systemd/openclaw-secondbrain-ingest-obsidian.service`
+- `systemd/openclaw-secondbrain-ingest-obsidian.timer`
+- `systemd/openclaw-secondbrain-export-obsidian.service`
+- `systemd/openclaw-secondbrain-export-obsidian.timer`
+
+Install them (copy or symlink) to `/etc/systemd/system/`, then:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now openclaw-secondbrain-ingest-obsidian.timer
+sudo systemctl enable --now openclaw-secondbrain-export-obsidian.timer
+```
+
+## 5) Verify
+
+Run once manually:
+
+```bash
+python3 openclaw_cron_wrapper.py ingest_obsidian
+python3 openclaw_cron_wrapper.py export_obsidian
+```
+
+What to expect:
+
+- If `vault_path` is missing/invalid, both tasks **skip** safely (no writes to random paths).
+- Ingest creates/updates `second-brain/data/obsidian_ingest_state.json`.
+- Export writes markdown files to `<vault_path>/<export.subdir>/` (default: `SecondBrain/`) and tracks state in `second-brain/data/obsidian_export_state.json`.
+