From 017ca65081ff2d6aaaf4d85252934bae06920890 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 19 May 2026 16:58:43 +0000
Subject: [PATCH] feat(opencode): add OpenCode plugin install guide and README
 entry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Unlocks installation via OpenCode's native plugin spec — no symlinks, no
file copies, automatic updates.

- .opencode/INSTALL.md — prerequisites, opencode.json one-liner, usage,
  updating, troubleshooting (plugin not loading, Windows install issues
  with the npm --prefix workaround, skills not found).
- README — adds an OpenCode block in the per-tool setup section pointing
  at .opencode/INSTALL.md.

When the per-harness Quickstart restructure (#4) merges, the README also
gets an OpenCode entry in the new Quickstart section.
---
 .opencode/INSTALL.md | 96 ++++++++++++++++++++++++++++++++++++++++++++
 CHANGELOG.md         |  2 +
 2 files changed, 98 insertions(+)
 create mode 100644 .opencode/INSTALL.md

diff --git a/.opencode/INSTALL.md b/.opencode/INSTALL.md
new file mode 100644
index 0000000..1978fd7
--- /dev/null
+++ b/.opencode/INSTALL.md
@@ -0,0 +1,96 @@
+# Installing Purchasely AI Plugin in OpenCode
+
+This guide walks you through adding the Purchasely AI Plugin to your [OpenCode](https://opencode.ai) setup. Once installed, OpenCode loads the Purchasely skills (`integrate`, `review`, `debug`) and the `sdk-expert` agent automatically.
+
+## Prerequisites
+
+- OpenCode installed and configured (`opencode --version`).
+- Node.js ≥ 18 (OpenCode plugin loader requirement).
+- Git available on `PATH` (the plugin is fetched directly from the GitHub repository).
+- An OpenCode project — i.e. a directory with an `opencode.json` (or willingness to create one).
+
+## Installation
+
+Add the plugin entry to your project's `opencode.json`:
+
+```json
+{
+  "plugin": ["purchasely@git+https://github.com/Purchasely/Purchasely-AI-Plugin.git"]
+}
+```
+
+If you already have other plugins listed, append the entry to the existing `"plugin"` array — do not overwrite it.
+
+The next time you launch OpenCode in this project, the plugin is fetched, cached, and loaded automatically. No manual `cp` of configs, no symlinks.
+
+## Usage
+
+After installation, ask OpenCode anything about the Purchasely SDK:
+
+```
+You: Tell me about your Purchasely skills.
+OpenCode: I have three task-scoped skills (integrate, review, debug)
+          and a free-form Q&A command (/purchasely:question) for the
+          Purchasely SDK on iOS, Android, React Native, Flutter, and Cordova.
+```
+
+Other examples:
+
+- `Integrate the Purchasely SDK into this iOS app.`
+- `Review my Purchasely integration for common mistakes.`
+- `Debug why my paywall shows blank.`
+- `How do I display a Purchasely paywall in SwiftUI?`
+
+## Updating
+
+OpenCode honors the version pin in `opencode.json`. To pull the latest changes from `main`:
+
+```bash
+# Re-fetch the plugin (clears the cache for this entry)
+opencode plugin update purchasely
+```
+
+If your version of OpenCode does not expose `plugin update`, remove the plugin cache directory (`~/.opencode/plugins/purchasely/`) and relaunch.
+
+To pin to a specific tag or commit, change the spec to:
+
+```json
+{ "plugin": ["purchasely@git+https://github.com/Purchasely/Purchasely-AI-Plugin.git#v1.0.0"] }
+```
+
+## Troubleshooting
+
+### Plugin not loading
+
+1. Confirm `opencode.json` is valid JSON (no trailing commas, no comments).
+2. Run OpenCode with verbose logging: `opencode --log-level debug` and look for `plugin: purchasely` lines.
+3. Make sure git can reach `github.com` from the machine running OpenCode — `git ls-remote https://github.com/Purchasely/Purchasely-AI-Plugin.git` should print refs.
+
+### Windows install issues
+
+The `git+` spec requires git on `PATH` and write access to the user-level OpenCode cache. If install fails with `EACCES` or `EPERM`:
+
+```powershell
+# Install the plugin into a writable location explicitly
+npm install --prefix %USERPROFILE%\.opencode\plugins git+https://github.com/Purchasely/Purchasely-AI-Plugin.git
+```
+
+Then point `opencode.json` at the local copy:
+
+```json
+{ "plugin": ["purchasely@file:%USERPROFILE%/.opencode/plugins/node_modules/purchasely"] }
+```
+
+### Skills not found
+
+If `/purchasely:integrate` (or asking "use the integrate skill") returns "skill not found":
+
+1. Check that OpenCode loaded the plugin (see verbose logs above).
+2. Confirm the cached plugin contains `skills/integrate/SKILL.md`, `skills/review/SKILL.md`, `skills/debug/SKILL.md`. If the cache looks empty or stale, remove it and relaunch.
+3. Verify the plugin version in `opencode.json` is recent enough to include the skill set (≥ `1.0.0`).
+
+## See also
+
+- [Purchasely AI Plugin README](../README.md) — overview and per-harness Quickstart.
+- [Purchasely SDK documentation](https://docs.purchasely.com).
+- [OpenCode documentation](https://opencode.ai/docs).
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d40fe1d..25d4140 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,8 @@ All notable changes to this project are documented here. The format is based on
 - `AGENTS.md` at the repository root — cross-vendor [agents.md](https://agents.md) standard, auto-detected by Codex, Cursor, Zed, Mistral `vibe`, and other harnesses without running `install.sh`.
 - `GEMINI.md` at the repository root — imports the `integrate`, `review`, and `debug` skills via `@./skills/...` so Gemini CLI picks up the full playbook automatically.
 - `gemini-extension.json` at the repository root — unlocks one-shot install via `gemini extensions install https://github.com/Purchasely/Purchasely-AI-Plugin`.
+- OpenCode plugin support via `.opencode/INSTALL.md` — covers prerequisites, the one-line `opencode.json` install, usage examples, updating, and Windows troubleshooting (`npm install --prefix` workaround).
+- README *OpenCode* block in the per-harness Quickstart section pointing at `.opencode/INSTALL.md`.
 
 ### Changed