From ef25c0fab108c12b0508fef7fce350c0f5d901fe Mon Sep 17 00:00:00 2001 From: Morgan <232673694+msinclair25@users.noreply.github.com> Date: Tue, 28 Jul 2026 23:07:08 -0700 Subject: [PATCH 1/2] docs: clarify OWD Sync installation --- README.md | 200 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 142 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 8986394..1c22bc3 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,159 @@ # OWD Sync -OWD Sync is the companion Obsidian plugin for -[OWD Platform](https://github.com/msinclair25/owd-platform). It connects the -vault you explicitly opened to an owner-controlled OWD deployment for sync, -search, encrypted snapshots, and recovery. - -> **Invited family test:** OWD Sync `0.1.6` is available through BRAT while its -> Obsidian Community Plugins review is pending. The invited tester first -> deploys the private OWD Platform fork from its -> [trusted-tester start page](https://github.com/msinclair25/owd-platform/blob/main/docs/TRUSTED-TESTER-START.md). - -## Install the invited test candidate - -1. Complete and claim the tester-owned OWD Platform deployment. -2. In **Vault connections**, open **Trusted tester · one temporary step**. -3. Install and enable - [BRAT](https://github.com/TfTHacker/obsidian42-brat) from Obsidian's - Community Plugins. -4. Use the dashboard action to add `msinclair25/owd-sync`, then confirm - Obsidian shows version `0.1.6`. Stop if it differs. -5. Enable **OWD Sync** under **Settings → Community plugins**. - -BRAT installs and updates the published GitHub Release. No terminal or hidden -vault-folder work is required for this invited path. - -BRAT is a testing bridge, not the permanent distribution plan. OWD Sync will -move to Obsidian's official Community Plugin directory after the private-beta -compatibility, security, mobile, update, and clean-install gates pass. - -## Pair one vault safely - -1. In the authenticated OWD dashboard, create a private pairing request. -2. Open the exact vault you intend to connect. -3. Return to OWD and choose **Open Obsidian and pair**. -4. Confirm the displayed current vault name, deployment host, and access - disclosure. - -The protocol handoff never chooses a vault silently: the plugin displays the -currently open vault and waits for approval. Pairing uses a ten-minute -single-use grant and does not expose the stored vault credential in the -dashboard. If the handoff is blocked, use OWD's **Manual fallback**, copy the -request, run **OWD Sync: Pair this vault with OWD**, and paste it. - -## Diagnostic package - -Download `owd-sync-.zip` and `checksums.txt` from the matching -[OWD Sync 0.1.6 GitHub Release](https://github.com/msinclair25/owd-sync/releases/tag/0.1.6). -Verify the checksum, then install the complete `owd-sync` directory as one -version-matched unit. Do not mix `main.js`, `manifest.json`, or `styles.css` -from different releases. If BRAT is blocked, stop the acceptance run. The ZIP -is for separate maintainer diagnosis, not a substitute installation path. +[![Release](https://img.shields.io/badge/release-0.1.6-90a5ff.svg)](https://github.com/msinclair25/owd-sync/releases/tag/0.1.6) +[![License](https://img.shields.io/badge/license-Apache--2.0-d7ff64.svg)](LICENSE) + +**The Obsidian companion for +[OWD Platform](https://github.com/msinclair25/owd-platform).** + +OWD Sync connects only the vault you explicitly open and approve to one +owner-controlled OWD workspace. It provides the sync boundary that lets OWD +publish a searchable library, show current notes, and create encrypted recovery +points while your canonical Markdown files remain ordinary Obsidian files. + +> [!IMPORTANT] +> OWD Sync `0.1.6` is an alpha release. It is not yet listed in Obsidian +> Community Plugins. OWD Platform provides a temporary one-click desktop +> installer for invited testers; BRAT is the fallback. Use synthetic test +> vaults until the Community Plugin publication and personal-vault gates pass. + +## Install from OWD + +The normal alpha path starts in the authenticated OWD **Vaults** folder: + +1. In Obsidian, open **Settings → Community plugins** and choose + **Turn on community plugins**. OWD cannot bypass this Obsidian security + consent. +2. Close Obsidian. +3. In OWD, choose **Install OWD Sync 0.1.6**. +4. In current Chrome or Edge, select the exact vault root in the browser's + folder picker and allow the requested local write access. +5. Reopen Obsidian and confirm **OWD Sync** is enabled in that vault. +6. Return to OWD and create the private pairing request. + +The temporary installer writes the three version-matched OWD Sync files and +queues the plugin as enabled for the selected vault. It reads only existing OWD +Sync files and `.obsidian/community-plugins.json` so it can restore them if +installation fails. + +It does **not** enumerate notes, upload vault data, retain the selected folder, +change general Obsidian settings, or install an updater. + +## Safari, Firefox, or blocked folder picker + +Use [BRAT](https://github.com/TfTHacker/obsidian42-brat) as the disclosed +fallback: + +1. Install and enable BRAT from Obsidian Community Plugins. +2. Add the beta plugin repository `msinclair25/owd-sync`. +3. Confirm Obsidian shows OWD Sync version `0.1.6`. +4. Enable OWD Sync under **Settings → Community plugins**. + +BRAT is a testing bridge, not the permanent install experience. OWD Sync will +move to Obsidian Community Plugins after its compatibility, security, mobile, +update, and clean-install gates pass. + +## Pair one vault + +1. Open the exact vault you intend to connect and confirm OWD Sync `0.1.6` is + enabled. +2. In OWD, choose **I see OWD Sync 0.1.6 — create request**. +3. Choose **Open Obsidian and pair**. +4. In Obsidian, verify the current vault name and OWD workspace. +5. Choose **Pair and start sync**. + +OWD refreshes automatically after the one-time exchange. The pairing request +expires after ten minutes, can be used only once, and never chooses a vault +silently. + +If the direct handoff is blocked, open **Manual fallback** in OWD, copy the +request, run **OWD Sync: Pair this vault with OWD** from Obsidian's command +palette, and paste it. + +## What OWD Sync does + +- Syncs the explicitly paired Obsidian vault with its approved OWD workspace +- Preserves the vault's Markdown/Yjs state across paired devices +- Reports a bounded runtime profile so OWD can avoid exposing private or + infrastructure files +- Provides pairing, reconcile, snapshot, and diagnostics commands +- Keeps pairing credentials inside that vault's plugin settings + +## What OWD Sync does not do + +- It does not connect AI agents or grant MCP access. +- It does not create, authorize, or approve OWD Projects. +- It does not select a vault based on its name or reuse another vault's grant. +- It does not give an agent Obsidian CLI, shell, or filesystem authority. +- It does not silently write arbitrary `.obsidian` settings. +- It does not replace OWD's encrypted snapshot and restore layer. + +Agent connections, Project consent, owner Decisions, and recovery controls live +in OWD Platform. Keeping those responsibilities separate prevents a local sync +plugin from silently expanding an agent's authority. + +## Compatibility + +| Component | Required version | +| ---------------- | ------------------------------------ | +| OWD Sync | `0.1.6` | +| OWD Platform | `1.0.0-alpha.3` | +| Obsidian desktop | Current alpha-tested desktop release | +| Direct installer | Current Chrome or Edge over HTTPS | + +Do not mix `main.js`, `manifest.json`, or `styles.css` from different releases. +The complete versioned package and SHA-256 checksums are available on the +[OWD Sync 0.1.6 release page](https://github.com/msinclair25/owd-sync/releases/tag/0.1.6). +The ZIP is a maintainer diagnostic artifact, not the normal tester installation +path. + +## Troubleshooting + +### Obsidian reports `unrecognized URI action` + +OWD Sync is not loaded at version `0.1.6` in the vault Obsidian opened. Confirm +the plugin version and enabled state in that exact vault, then reopen the +pairing request. Use OWD's manual fallback if the direct handoff remains +blocked. + +### The installer opens a folder picker + +That is expected. Select the vault root—the folder containing `.obsidian`. +OWD cannot choose or inspect a local vault until you explicitly grant the +browser access to that folder. + +### The wrong vault is open + +Cancel the pairing modal without approving it. Open the intended vault and use +the same unexpired request, or create a fresh request in OWD. ## Development -OWD Sync is developed in the OWD Platform monorepo and promoted to this -sanitized public distribution repository. The repository contains the -reviewable adapter, pinned upstream client source and notices, tests, build -configuration, and release assets. +OWD Sync is developed in the OWD Platform monorepo and promoted into this +sanitized distribution repository. This repository contains the reviewable +adapter, pinned upstream source and notices, tests, build configuration, and +release artifacts. ```sh pnpm install +pnpm check +``` + +Individual gates are also available: + +```sh +pnpm format:check +pnpm lint pnpm typecheck pnpm test pnpm build ``` See [UPSTREAM.md](UPSTREAM.md) for pinned YAOS provenance and -[SECURITY.md](SECURITY.md) for vulnerability reporting and the pairing trust -boundary. +[SECURITY.md](SECURITY.md) for vulnerability reporting and the complete pairing +trust boundary. ## License -The OWD adapter is Apache-2.0. Vendored YAOS components retain their 0BSD -notice and provenance. +The OWD adapter is licensed under the [Apache License 2.0](LICENSE). Vendored +YAOS components retain their 0BSD notice and provenance. From 60a595ee7905eedc384515e09c513cb84b92f45f Mon Sep 17 00:00:00 2001 From: Morgan <232673694+msinclair25@users.noreply.github.com> Date: Wed, 29 Jul 2026 15:20:02 -0700 Subject: [PATCH 2/2] docs: strengthen OWD Sync GitHub story --- README.md | 40 +++++++++++++++++++++++++++++++++------- package.json | 2 +- 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 1c22bc3..3c3c49f 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,40 @@ [![Release](https://img.shields.io/badge/release-0.1.6-90a5ff.svg)](https://github.com/msinclair25/owd-sync/releases/tag/0.1.6) [![License](https://img.shields.io/badge/license-Apache--2.0-d7ff64.svg)](LICENSE) +[![Private alpha](https://img.shields.io/badge/OWD-private%20alpha-f0a23a.svg)](https://mdevolved.com/#alpha-access) + +**Keep your Obsidian vault the source. Connect only the workspace you approve.** + +OWD Sync is the deliberately narrow Obsidian companion for +[OWD Platform](https://mdevolved.com). It connects only the vault you +explicitly open and approve to one owner-controlled OWD workspace. Your +canonical Markdown remains ordinary Obsidian files while OWD receives the +durable sync state it needs for searchable context, cited agent work, and +encrypted recovery. + +[Request private alpha access](https://mdevolved.com/#alpha-access) · +[See OWD Platform](https://github.com/msinclair25/owd-platform) · +[Download OWD Sync 0.1.6](https://github.com/msinclair25/owd-sync/releases/tag/0.1.6) + +## The connection boundary + +```mermaid +flowchart LR + V["The vault you open"] --> C["Explicit pairing consent"] + C --> S["OWD Sync"] + S <--> O["Your OWD workspace"] + O --> L["Current searchable library"] + O --> R["Encrypted recovery"] + O --> A["Separately authorized agents"] +``` -**The Obsidian companion for -[OWD Platform](https://github.com/msinclair25/owd-platform).** - -OWD Sync connects only the vault you explicitly open and approve to one -owner-controlled OWD workspace. It provides the sync boundary that lets OWD -publish a searchable library, show current notes, and create encrypted recovery -points while your canonical Markdown files remain ordinary Obsidian files. +| OWD Sync does | OWD Sync never does | +| ---------------------------------------------------------- | --------------------------------------------------------- | +| Pairs the exact open vault after explicit approval | Silently chooses another vault | +| Synchronizes eligible vault state with its OWD destination | Grants an AI agent access | +| Reports the version and safe runtime profile | Creates, joins, or approves an OWD Project | +| Keeps its credential inside that vault's plugin settings | Reads unrelated plugin credentials | +| Supports current-library and recovery workflows | Turns synchronization into an unreviewed agent write path | > [!IMPORTANT] > OWD Sync `0.1.6` is an alpha release. It is not yet listed in Obsidian diff --git a/package.json b/package.json index b66bfc4..5664a7f 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "owd-sync", "version": "0.1.6", "private": true, - "description": "The OWD Sync companion plugin for Obsidian.", + "description": "The explicit vault connection between Obsidian and an owner-controlled OWD workspace.", "license": "Apache-2.0 AND 0BSD", "type": "module", "main": "main.js",