pedrovgp · Oct 13, 2026 · Oct 14, 2026 · Oct 14, 2026 · Oct 14, 2026
diff --git a/README.md b/README.md
@@ -12,29 +12,55 @@ Sync your OpenCode configuration, sessions, and data across multiple machines us
 - **Offline-Friendly** - Works offline, syncs when reconnected
 - **Atomic Updates** - Uses Git's compare-and-swap for safe concurrent access
 
-## Installation
+## Requirements
 
-**Step 1:** Install the package in your OpenCode config directory:
+- **OpenCode v2** (2.0.28 or newer). This release uses the V2 plugin API (`@opencode/plugin`).
+  For OpenCode 1.x, use `oc-sync@0.1.x` and the V1 `"plugin"` (singular) config key.
+- Node.js 18+
+- A GitHub Personal Access Token with `repo` scope
+
+## Installation (OpenCode v2)
+
+**Step 1:** Add the plugin. Either install the published package:
 
 ```bash
-# Linux/macOS
-cd ~/.config/opencode && npm install oc-sync
+opencode plugin add oc-sync@^0.2.0
+```
 
-# Windows (PowerShell)
-cd $HOME\.config\opencode; npm install oc-sync
+Or use a local build/clone (see [Development Setup](docs/DEV-SETUP.md)) and point OpenCode at its
+directory — V2 loads local plugins from a directory or package, not a single file.
+
+**Step 2:** Register the plugin in your global config `~/.config/opencode/opencode.json(c)` using the
+V2 **`plugins`** field:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["oc-sync"]
+}
 ```
 
-**Step 2:** Register the plugin in `opencode.json` (in config directory):
+For a local directory, use an absolute path:
 
-```json
+```jsonc
 {
-  "plugin": ["oc-sync"]
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["/absolute/path/to/oc-sync"]
 }
 ```
 
-**Step 3:** Configure your GitHub token (see [Configuration](#configuration) below)
+Plugin package directories placed directly under `~/.config/opencode/plugins/` are also discovered
+automatically.
+
+**Step 3:** Configure your GitHub token (see [Configuration](#configuration) below).
+
+**Step 4:** Restart OpenCode so the plugin loads:
+
+```bash
+opencode service restart
+```
 
-**Step 4:** Restart OpenCode
+Verify it loaded with `opencode plugin list` — you should see `oc-sync`.
 
 Using an AI coding agent? See [LLM Installation Guide](docs/LLM-INSTALL.md) for step-by-step prompts.
 
@@ -112,6 +138,7 @@ See [Configuration Guide](docs/CONFIG.md) for all options.
 | [Sync Architecture](docs/SYNC.md) | Sync triggers, batching, data categories |
 | [Sync Paths](docs/SYNC-PATHS.md) | OpenCode file locations by platform |
 | [Development Setup](docs/DEV-SETUP.md) | Local development environment |
+| [OpenCode V2 Upgrade](docs/UPGRADE-OPENCODE-V2.md) | V1 → V2 plugin migration notes |
 | [Publishing](docs/PUBLISH.md) | npm release process |
 | [LLM Installation](docs/LLM-INSTALL.md) | Instructions for AI coding agents |
 | [TODO](docs/TODO.md) | Future improvements |

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -21,7 +21,7 @@ OpenCode plugin integration.
 
 | File | Purpose |
 |------|---------|
-| `plugin.ts` | Plugin definition and hooks |
+| `plugin.ts` | Plugin definition (`Plugin.define`, OpenCode V2 API) |
 | `state-manager.ts` | Plugin state management |
 | `sync-handler.ts` | Sync operation handler |
 | `types.ts` | Plugin types |

diff --git a/docs/CONFIG.md b/docs/CONFIG.md
@@ -2,24 +2,36 @@
 
 ## Prerequisites
 
-The plugin must be installed in your OpenCode config directory:
+Requires **OpenCode v2** (2.0.28+). OpenCode 1.x users need `oc-sync@0.1.x` with the V1
+`"plugin"` (singular) config key.
+
+Install the plugin (published package):
 
 ```bash
-# Linux/macOS
-cd ~/.config/opencode && npm install oc-sync
+opencode plugin add oc-sync@^0.2.0
+```
 
-# Windows (PowerShell)
-cd $HOME\.config\opencode; npm install oc-sync
+Or use a local build directory (see [Development Setup](DEV-SETUP.md)). Register it in the global
+config `~/.config/opencode/opencode.json(c)` under the V2 **`plugins`** field:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["oc-sync"]
+}
 ```
 
-And registered in `opencode.json` (in config directory):
+For a local build, use an absolute directory path:
 
-```json
+```jsonc
 {
-  "plugin": ["oc-sync"]
+  "plugins": ["/absolute/path/to/oc-sync"]
 }
 ```
 
+Plugin package directories under `~/.config/opencode/plugins/` are discovered automatically.
+After changing config or plugins, restart OpenCode (`opencode service restart`).
+
 See [Sync Paths](SYNC-PATHS.md) for platform-specific directory locations.
 
 ## Quick Start

diff --git a/docs/DEV-SETUP.md b/docs/DEV-SETUP.md
@@ -22,17 +22,22 @@ npm run build
 
 ### 2. Register Plugin with OpenCode
 
-Create or edit `~/.config/opencode/opencode.json`:
+Requires OpenCode v2. Point the global config `~/.config/opencode/opencode.json(c)` at the plugin
+**directory** using the V2 `plugins` field:
 
-```json
+```jsonc
 {
-  "plugin": [
-    "file:///absolute/path/to/opencode-sync/dist/index.js"
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    "/absolute/path/to/opencode-sync"
   ]
 }
 ```
 
-Replace `/absolute/path/to/opencode-sync` with the actual path to your cloned repo.
+Replace `/absolute/path/to/opencode-sync` with the actual path to your cloned repo. V2 loads local
+plugins from a directory/package (its `package.json`/`index.js`), not from `dist/index.js`
+directly. Alternatively, copy/symlink the built directory under `~/.config/opencode/plugins/` and
+it will be discovered automatically.
 
 ### 3. Set GitHub Token
 
@@ -45,7 +50,8 @@ The token needs `repo` scope to create and access the private sync repository.
 ### 4. Start OpenCode
 
 ```bash
-opencode
+opencode service restart
+opencode plugin list   # should list oc-sync
 ```
 
 ### 5. Verify Plugin Loaded
@@ -172,9 +178,10 @@ To rotate encryption keys without losing access to credentials:
 
 ### Plugin not loading
 
-1. Check `opencode.json` has correct absolute path to `dist/index.js`
+1. Confirm OpenCode v2 and that the global config uses `plugins` (plural) with an absolute path to the plugin directory
 2. Ensure `npm run build` completed successfully
-3. Check OpenCode logs: `~/.local/share/opencode/log/*.log`
+3. Run `opencode plugin list`; if `oc-sync` is missing, restart with `opencode service restart`
+4. Check OpenCode logs: `~/.local/share/opencode/log/*.log`
 
 ### "No configuration found"
 
@@ -188,4 +195,4 @@ Set `GITHUB_TOKEN` environment variable or create config file manually.
 ### Changes not reflecting
 
 1. Run `npm run build`
-2. Restart OpenCode completely (not just the TUI)
+2. Restart the OpenCode service: `opencode service restart` (the TUI is not enough)
diff --git a/docs/LLM-INSTALL.md b/docs/LLM-INSTALL.md
@@ -11,44 +11,47 @@ You are helping the user install oc-sync, which syncs OpenCode data across machi
 
 ### Prerequisites Check
 Ask the user:
-1. "Do you have Node.js 18 or higher installed?" - If no, guide them to install from https://nodejs.org
-2. "Do you have a GitHub account?" - If no, guide them to create one at https://github.com
+1. "Do you have OpenCode v2 (2.0.28 or newer) installed?" - If no, guide them to install/upgrade; V1 users need oc-sync 0.1.x
+2. "Do you have Node.js 18 or higher installed?" - If no, guide them to install from https://nodejs.org
+3. "Do you have a GitHub account?" - If no, guide them to create one at https://github.com
 
-### Step 1: Install the Package
-IMPORTANT: The package must be installed in the OpenCode config directory, NOT globally.
+### Step 1: Install the Package (OpenCode v2)
+IMPORTANT: This release uses the OpenCode V2 plugin API and requires OpenCode v2 (2.0.28+).
+If the user runs OpenCode 1.x, they must use oc-sync 0.1.x instead.
 
-Determine the user's OS and run the appropriate command:
+Install the published package globally with the V2 CLI:
 
-**Linux/macOS:**
-cd ~/.config/opencode && npm install oc-sync
+opencode plugin add oc-sync@^0.2.0
 
-**Windows (PowerShell):**
-cd $HOME\.config\opencode; npm install oc-sync
+Alternatively, for a local build, point OpenCode at the built plugin directory
+(see docs/DEV-SETUP.md). V2 loads local plugins from a directory/package, not a single file.
 
-**Windows (Command Prompt):**
-cd %USERPROFILE%\.config\opencode && npm install oc-sync
-
-This installs the plugin where OpenCode can find it (in the config directory's node_modules/).
+### Step 2: Register the Plugin
+IMPORTANT: Installing the package may register it automatically; verify and, if needed, add it
+to the global config.
 
-NOTE: OpenCode uses XDG paths on ALL platforms. On Windows, this is NOT %APPDATA% - it's %USERPROFILE%\.config\opencode\.
+Edit the global config file:
 
-### Step 2: Register the Plugin
-IMPORTANT: Installing the package is NOT enough. You must also register it.
+**Linux/macOS:** ~/.config/opencode/opencode.json(c)
+**Windows:** %USERPROFILE%\.config\opencode\opencode.json(c)
 
-Edit the opencode.json file in the config directory:
+Use the V2 "plugins" (plural) field:
 
-**Linux/macOS:** ~/.config/opencode/opencode.json
-**Windows:** %USERPROFILE%\.config\opencode\opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["oc-sync"]
+}
 
-Add the plugin array:
+For a local build, use an absolute directory path:
 
 {
-  "plugin": ["oc-sync"]
+  "plugins": ["/absolute/path/to/oc-sync"]
 }
 
-NOTE: The key is "plugin" (singular), NOT "plugins" (plural).
+NOTE: In OpenCode V2 the key is "plugins" (plural). The V1 key "plugin" (singular) is NOT used by
+OpenCode v2. Plugin package directories placed directly under ~/.config/opencode/plugins/ are
+discovered automatically and do not need an explicit entry.
 
-If opencode.json already exists with other settings, just add "oc-sync" to the existing plugin array.
 
 ### Step 3: Generate GitHub Personal Access Token
 Guide the user step by step:
@@ -77,7 +80,15 @@ That's it! The plugin will automatically:
 - Detect the default branch (main/master)
 
 ### Step 5: Verify Installation
-Tell user to restart OpenCode. The plugin will:
+Tell user to restart OpenCode so the plugin loads:
+
+opencode service restart
+
+Then confirm it is active:
+
+opencode plugin list
+
+The plugin will:
 - Auto-create the sync repository if needed
 - Sync on startup
 - Watch for file changes
@@ -97,11 +108,11 @@ Expected output:
 ### Troubleshooting
 
 #### Plugin not loading (no log output)
-- Check plugin is installed in correct location:
-  - Linux/macOS: ls ~/.config/opencode/node_modules/oc-sync
-  - Windows: dir %USERPROFILE%\.config\opencode\node_modules\oc-sync
-- Check plugin is registered in opencode.json with "plugin" (singular) key
-- Check opencode.json is valid JSON (no trailing commas, etc.)
+- Check OpenCode is v2 and the plugin is listed: `opencode plugin list` (should show `oc-sync`)
+- Check the global config registers it under `plugins` (plural), not `plugin` (singular)
+- For a local build, confirm the config path is an absolute path to the plugin directory and that `npm run build` succeeded
+- Check the config file is valid JSON/JSONC (no stray commas, etc.)
+- Restart the service after changes: `opencode service restart`
 
 #### API Errors
 - "401 Unauthorized": Token is invalid or expired. Generate a new one.

diff --git a/docs/PUBLISH.md b/docs/PUBLISH.md
@@ -1,5 +1,14 @@
 # Publishing to npm
 
+## Release lines
+
+- **`0.2.x`** targets **OpenCode v2** (V2 plugin API via `@opencode/plugin`, `{ id, setup }`).
+- **`0.1.x`** targets **OpenCode 1.x** (V1 plugin API, function export). Keep these installable for
+  older setups.
+
+V1 and V2 export different module shapes, so `0.2.0` is a **breaking** release for V1 users.
+Consider publishing `0.2.0` under a `next` dist-tag first, then promoting to `latest` once verified.
+
 ## Quick Command
 
 ```bash