feat: Obsidian Vault — bidirectional live sync

[diebugger-tech]

Obsidian Vault Integration — Issue Roadmap

Companion issues to #124 (architecture/vision).
Each issue is self-contained and can be picked up independently.

---

Issue A — feat: obsidian_vault_collector.py (READ)

Depends on: nothing — standalone, PR-ready

Adds a collector that recursively reads an Obsidian vault and produces
the same output structure as feishu_auto_collector:

knowledge/{slug}/
├── messages.txt   ← Daily / Journal / Meeting Notes
├── docs/*.md      ← Projects / MOC / Evergreen
└── collection_summary.json

What it handles:

• YAML frontmatter stripping
• [[wikilink]] resolution
• .obsidian/ and .trash/ excluded
• Optional --author filter for shared vaults
• No new dependencies (stdlib only)

I can submit this PR immediately if there's interest.

---

Issue B — feat: --watch flag (live sync via inotify/fsevents)

Depends on: Issue A

Adds a --watch flag to obsidian_vault_collector.py that monitors
the vault for file changes and re-runs the collector automatically:

python3 tools/obsidian_vault_collector.py --vault ~/Notes --name "Alice" --watch

Implementation:

• Linux: inotifywait (inotify-tools)
• macOS: fsevents via watchdog (one new optional dep)
• Debounce: 2s after last change to avoid partial-write triggers

Turns the one-shot collector into a living skill —
vault changes, skill updates automatically, no manual step.

---

Issue C — feat: obsidian_vault_writer.py (WRITE)

Depends on: Issue A

New script that writes dot-skill output back into the vault as .md files:

Vault/
└── .colleague-skill/
    ├── 2024-03-15 Code Review.md
    ├── Decision Log — API redesign.md
    └── ...

Why a separate folder (.colleague-skill/):

• Keeps generated notes separate from hand-written notes
• Easy to exclude from collector (skip dot-folders)
• No conflict with existing vault structure

Conflict resolution deliberately out of scope for v1 —
last-write-wins is sufficient since the skill is the only writer
to .colleague-skill/.

---

Issue D — feat: AGENTS.md as context bridge

Depends on: nothing — docs + convention only

An AGENTS.md file in the vault root that describes the person's
stack, projects, and preferences. All agents that follow the standard
read it automatically on startup — no repeated setup per tool.

# AGENTS.md

## Stack
- OS: NixOS + Cosmic
- Editor: Helix
- Languages: Rust, Python, Nix

## Active projects
- 3DNTerminal: 3D flip terminal emulator (egui + vte)
- colleague-skill: Obsidian connector

## AI agents
- Claude Code: ~/.claude/
- Goose: ~/.config/goose/
- OpenClaw: ~/.openclaw/

Supported agents today: Claude Code, Goose, OpenClaw, IronClaw.

This makes the vault the single source of truth across the entire
agent ecosystem — write once, all agents know.

---

Issue E — docs: Nix cross-platform deployment example

Depends on: nothing — docs only, no code

Adds a docs/deployment/nix.md showing how to deploy the full
Obsidian sync setup reproducibly on any platform:

• Windows (WSL2) + Nix
• macOS + Nix
• Linux (any distro) + Nix

# home.nix
home.packages = with pkgs; [ gh python3 ];

home.file.".config/colleague-skill/vault-path".text =
  "/home/user/Obsidian";

systemd.user.services.obsidian-sync = {
  description = "Obsidian → dot-skill live sync";
  wantedBy = [ "default.target" ];
  serviceConfig.ExecStart =
    "python3 ~/.claude/skills/create-colleague/tools/obsidian_vault_collector.py --watch";
};

Without Nix: manual install on every machine.
With Nix: home-manager switch — done.

Target audience: the Obsidian community heavily overlaps with
Nix/NixOS users — this doc will be found and used.

---

Suggested order for titanwings

Priority	Issue	Effort	Value
1	A — collector	low	immediate
2	E — nix docs	very low	community reach
3	D — AGENTS.md	low	ecosystem
4	B — watch flag	medium	living skill
5	C — writer	medium	full loop

Roadmap — follow-up issues

To keep this manageable, I'll submit each piece separately:

	Issue	Depends on
A	obsidian_vault_collector.py — READ, PR-ready	nothing
B	--watch flag — live sync via inotify/fsevents	A
C	obsidian_vault_writer.py — WRITE back to vault	A + B
D	AGENTS.md as context bridge for all agents	nothing
E	Nix cross-platform deployment docs	nothing

Happy to start with A immediately if the architecture looks right.

[diebugger-tech]

SKILL.md Patch — Obsidian Vault als Datenquelle

Ergänzung in der Collector-Auswahl (nach dem Email-Block):

[G] Obsidian Vault
    Vault-Pfad angeben — alle .md-Dateien werden rekursiv eingelesen.
    Wikilinks werden aufgelöst, Frontmatter geparst, .obsidian/ übersprungen.
    Optional: SurrealDB für Graph-Queries (--surreal http://localhost:8000)

    python3 ${SKILL_DIR}/tools/obsidian_vault_collector.py \
        --vault {vault_path} \
        --name "{name}" \
        --output-dir ./knowledge/{slug}

    Mit SurrealDB:
    python3 ${SKILL_DIR}/tools/obsidian_vault_collector.py \
        --vault {vault_path} \
        --name "{name}" \
        --output-dir ./knowledge/{slug} \
        --surreal http://127.0.0.1:8000

    Output: knowledge/{slug}/messages.txt + docs/*.md + collection_summary.json
    (Identisch mit feishu_auto_collector — keine Downstream-Änderungen nötig)