feat: Obsidian Vault — bidirectional live sync

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

Roadmap — follow-up issues

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

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