# EVC Local Sync


**Keep your project `/docs` and Obsidian notes always in sync — bidirectional, local-first, no copy/paste.**

> Built for AI-assisted coding workflows (Cursor / Claude Code / Copilot):
> let AI update repo docs while your Obsidian specs stay fresh automatically.

![Demo](./assets/demo.gif)

---

## The Problem

You code with AI. Your AI writes and updates docs in `/docs`. But your Obsidian specs go stale.
Or you update specs in Obsidian, and the repo doesn't know.

**Result:** AI hallucinates from outdated context. Teammates read wrong docs. You copy-paste manually.

Local Sync fixes this: **bidirectional, automatic, local-first.**

---

## Install

1. *Settings → Community plugins → Browse* → search **"EVC Local Sync"**
2. **Install**, then **Enable**

Or open directly: `obsidian://show-plugin?id=evc-local-sync`  
Plugin page: https://obsidian.md/plugins?id=evc-local-sync

<details>
<summary>Manual install</summary>

1. Download `main.js`, `manifest.json`, and `styles.css` from the [latest release](https://github.com/entire-vc/evc-local-sync-plugin/releases)
2. Create folder `.obsidian/plugins/evc-local-sync/` in your vault
3. Copy downloaded files to this folder
4. Enable in *Settings → Community plugins*

</details>

---

## Quickstart (3 minutes)

1. Open plugin settings → **Add mapping**
   - Vault path: `Specs/`
   - Local path: `/path/to/project/docs/`
2. Click **Sync Now**
3. *(Optional)* Enable **Auto sync** and choose a conflict strategy

✅ Changes now mirror in both directions.

---

## Workflows

### 1 — AI writes docs → Obsidian stays fresh
AI updates `/docs` while you code → Local Sync keeps your Obsidian notes current.
No more "AI hallucinated because the spec was outdated."

### 2 — You edit in Obsidian → repo docs update for teammates and CI
Edit spec in Obsidian → sync → teammates and CI pipelines always read the latest docs.

### 3 — Dev team docs that never go stale
Connect your team's project docs to a shared vault. When any dev updates `/docs` (or AI does), the vault stays current. End the cycle of stale documentation.

---

## Key Features

- **Bidirectional sync** (vault ↔ local folders)
- **Multiple mappings** (multiple projects / subfolders)
- **Configurable conflict handling** (keep both / overwrite / prompt)
- **Auto sync** (on-change, on-startup, scheduled)
- **File deletion sync** — deleted files sync across locations
- **Per-mapping settings** — override conflict resolution and file types per project
- **Dry-run preview** — see changes before syncing
- **File watching** with configurable debounce
- **Symlink support** for complex project structures
- **Detailed logging** with filtering and CSV export
- **Backup creation** before overwriting files
- **Import/Export** configuration for portability
- Supports **.md**, **.canvas**, **.excalidraw.md** files
- **Fully local** — works offline, nothing sent to external servers

---

## Conflict Handling

Sync conflicts happen when both sides change before a sync runs.

**Recommended starting point:**
- Start with **manual sync** while testing your mapping
- Use **Keep both copies** until you're confident
- Check [`docs/Troubleshooting.md`](./docs/Troubleshooting.md) for common edge cases

---

## Comparison

| | Copy/paste | Manual export | Git submodule | **Local Sync** |
|---|---|---|---|---|
| Always current | ❌ | ❌ | partial | ✅ |
| Bidirectional | ❌ | ❌ | ❌ | ✅ |
| Conflict handling | manual | none | merge conflicts | configurable |
| Offline / private | ✅ | ✅ | ✅ | ✅ |
| Setup complexity | none | none | high | 3 steps |
| AI IDE workflow | ❌ | ❌ | partial | ✅ |

---

## Working with a Team?

Local Sync is designed for solo workflows. If you need **team collaboration** or want to **publish your vault** as a website (private, protected, or public):

→ [**EVC Team Relay**](https://github.com/entire-vc/evc-team-relay-obsidian-plugin) — self-hosted collaborative editing for Obsidian teams.

---

## Feedback

Edge cases and integration requests help make this solid:

- [Report a bug →](https://github.com/entire-vc/evc-local-sync-plugin/issues/new?template=bug-report.yml)
- [Report a conflict case →](https://github.com/entire-vc/evc-local-sync-plugin/issues/new?template=conflict-case.yml)
- [Request a feature →](https://github.com/entire-vc/evc-local-sync-plugin/issues/new?template=feature-request.yml)

---

## Troubleshooting

See [`docs/Troubleshooting.md`](./docs/Troubleshooting.md)

Common topics: renames/moves · case sensitivity (Windows/macOS) · watcher missed events · rapid edits

---

## Community

- 💬 [Discussions](https://github.com/entire-vc/.github/discussions)
- 📧 in@entire.vc

## License

MIT