Initial commit

README.md

@@ -0,0 +1,97 @@
+# Obsidian Sync
+
+Obsidian Sync is a self-hosted, end-to-end encrypted vault sync system for Obsidian across Windows, Linux, and Android. It consists of an Obsidian plugin, a sync server, and shared protocol and crypto packages inside a TypeScript monorepo.
+
+## Features
+
+- End-to-end encrypted text note and binary attachment sync
+- Automatic text merge with conflict markers when both sides change
+- Binary conflict copies when attachments diverge
+- Durable server state stored on disk
+- Structured JSON-line diagnostics and client sync log upload
+- Recovery bundle export and import for onboarding new devices
+- Device listing and revocation
+- Vault key rotation with recovery-bundle refresh
+- Paged pull and batched push behavior so interrupted sync runs can resume safely
+
+## Repository Layout
+
+- `apps/obsidian-plugin`: Obsidian plugin entry point, settings UI, and sync orchestration
+- `apps/sync-server`: Express server for encrypted revision exchange and device management
+- `packages/sync-protocol`: Shared request and response schemas
+- `packages/sync-engine`: Shared crypto, hashing, and merge helpers
+- `docs`: Architecture and deployment notes
+- `tests`: Focused contract and store-level integration tests
+
+## Requirements
+
+- Node.js 22 or newer
+- npm 10 or newer
+
+## Install
+
+```bash
+npm install
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+## Test
+
+```bash
+npm test
+```
+
+## Run The Server
+
+```bash
+npm run dev:server
+```
+
+The default server URL is `http://localhost:8787`.
+
+## First-Time Setup
+
+1. Start the sync server.
+2. Load the plugin into an Obsidian vault.
+3. Set the server URL, vault ID, and device name in the plugin settings.
+4. Run a manual sync to register the first device and generate the initial vault key.
+5. Export a recovery bundle from the settings tab and store it securely.
+
+## Add Another Device
+
+1. Install the plugin on the second device.
+2. Open the plugin settings and paste the recovery bundle into the import field.
+3. Run a manual sync to register that device and pull the encrypted vault contents.
+
+## Rotate The Vault Key
+
+1. Open the plugin settings and use `Rotate key`.
+2. Wait for the client to re-encrypt and upload the current vault contents.
+3. Export the fresh recovery bundle.
+4. Import that new bundle on every other device before the next sync.
+
+## Revoke A Device
+
+Use the plugin settings device list to revoke a device that should no longer have access. A revoked device can no longer authenticate to the server.
+
+## Server Data
+
+- `data/sync-state.json`: durable revision, device, tombstone, and key-status state
+- `data/logs/server.jsonl`: structured server and client-sync diagnostics
+
+## Current Limitations
+
+- The server storage backend is file-based rather than SQLite or PostgreSQL.
+- Sync validation is focused on shared libraries and the server store; there is not yet a full Obsidian plugin integration harness.
+- Device onboarding is driven by a copy-and-paste recovery bundle instead of a richer pairing flow.
+
+## Documentation
+
+- `docs/architecture.md`
+- `docs/deployment.md`
+- `Plan.md`