oribarilan · Oct 2, 2026 · Oct 2, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,14 +8,17 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 
 ## [Unreleased]
 
+## [0.19.0] — 2026-10-02
+
 ### Added
 
-- Experimental OpenCode v2 TUI compatibility POC using a dual v1/v2 entrypoint and a v2 renderer-key interception adapter. Not yet verified as a supported v2 release.
+- Experimental OpenCode v2 TUI support using a dual v1/v2 entrypoint and a renderer-key interception adapter, validated on OpenCode 2.0.15 on macOS.
 - Optional installed-package compatibility harness with exact editor-state checks on pinned v1/v2 binaries; lightweight harness regressions run in CI without downloading hosts.
 - `just dev2` launches local source with a pinned OpenCode v2 release and separate `.dev2/` settings/history.
 
 ### Changed
 
+- Started a gradual transition toward v2-only maintenance. v1 compatibility remains in v0.19.0; existing v1 users can stay pinned to the recommended v0.18.1 release.
 - Document Git installation, options, and custom leader settings separately for OpenCode v1 and experimental v2.
 - Corrected contributor paths for the split Vim engine and documented CI's compatibility-harness checks.
 
@@ -366,7 +369,8 @@ First release. Modal editing for the OpenCode prompt.
 
 > `g` fires immediately as buffer-home instead of waiting for `gg`. The `yy` line tracker drifts on clicks and arrow keys. Visual mode and text objects aren't feasible without cursor position access.
 
-[Unreleased]: https://github.com/oribarilan/vimcode/compare/v0.18.1...HEAD
+[Unreleased]: https://github.com/oribarilan/vimcode/compare/v0.19.0...HEAD
+[0.19.0]: https://github.com/oribarilan/vimcode/compare/v0.18.1...v0.19.0
 [0.18.1]: https://github.com/oribarilan/vimcode/compare/v0.18.0...v0.18.1
 [0.18.0]: https://github.com/oribarilan/vimcode/compare/v0.17.1...v0.18.0
 [0.17.1]: https://github.com/oribarilan/vimcode/compare/v0.17.0...v0.17.1

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -58,6 +58,10 @@ Follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Add your change
 - **MINOR**: New keybindings, new features (backward compatible)
 - **MAJOR**: Breaking changes, removed keybindings
 
+## Host support policy
+
+OpenCode v2 support is rolling out gradually and is experimental in vimcode v0.19.0. Future maintenance will move to v2 only; v1 compatibility remains in this release. The recommended v1 pin stays at `v0.18.1`. Do not automatically advance that legacy recommendation when preparing a v2-focused release.
+
 ## Release process
 
 Releases are manual.
@@ -68,7 +72,7 @@ Releases are manual.
 4. Update link references at the bottom of CHANGELOG.md.
 5. Bump version in `package.json` (`npm version X.Y.Z --no-git-tag-version`).
 6. Bump `VERSION` in `src/version.ts` to match.
-7. Update **all** package refs and unreleased wording in `README.md` and this guide for both host versions, including options and leader examples. For the first v2 release, replace the experimental commit refs with the new tag.
+7. Update the current v2 package refs and release wording in `README.md` and this guide, including options and leader examples. Keep the recommended v1 pin unchanged unless a v1 upgrade is deliberately recommended and verified.
 8. Run `just check`.
 9. Open a PR with the release changes. Title: `Release vX.Y.Z: <one-line summary>`.
 10. After CI passes, squash-merge the PR.
@@ -79,19 +83,19 @@ Releases are manual.
 
 Both host versions load the same `./tui` package entry via a Git URL. Pin a tag or commit so upgrades use a new cache entry.
 
-On OpenCode **v1**, use `tui.json`:
+On OpenCode **v1**, use `tui.json`. The recommended legacy pin is `v0.18.1`; `v0.19.0` still includes v1 compatibility for users who opt in:
 
 ```json
 { "plugin": ["vimcode@git+https://github.com/oribarilan/vimcode.git#v0.18.1"] }
 ```
 
-On OpenCode **v2**, use `cli.json`. v2 support is unreleased; this example pins the tested PR commit, not the v1-only `v0.18.1` release:
+On OpenCode **v2**, use `cli.json` and pin `v0.19.0`. v2 support is experimental; the v1-only `v0.18.1` release does not work on v2:
 
 ```json
 {
   "plugins": [
     {
-      "package": "vimcode@git+https://github.com/oribarilan/vimcode.git#d8050f765b6c2c4e7fdc700d8345c1c5752644cb"
+      "package": "vimcode@git+https://github.com/oribarilan/vimcode.git#v0.19.0"
     }
   ]
 }

diff --git a/README.md b/README.md
@@ -10,6 +10,7 @@
 
 <p align="center">
   <a href="#install">Install</a> ·
+  <a href="#support-policy">Support policy</a> ·
   <a href="#configuration">Configuration</a> ·
   <a href="#what-it-does">What it does</a> ·
   <a href="#keybindings">Keybindings</a> ·
@@ -20,12 +21,25 @@
 
 ---
 
+## Support policy
+
+OpenCode v2 support is rolling out gradually, starting with experimental support in vimcode v0.19.0. Future maintenance will move to v2 only. This release still includes v1 support.
+
+| OpenCode version | Recommended vimcode pin | Status |
+|------------------|-------------------------|--------|
+| v1 | `v0.18.1` | Previous v1-only release. `v0.19.0` also includes v1 compatibility during the transition. |
+| v2 | `v0.19.0` | Experimental; validated on OpenCode 2.0.15 on macOS. |
+
+V1 users can stay on an older pinned release instead of following the v2 rollout. We have not set a date for removing v1 support.
+
 ## Install
 
-Use the instructions for your OpenCode major version. Both versions load the same vimcode package, but their config files and plugin entries differ.
+Use the instructions for your OpenCode major version. Both versions use the same package name, but their config files and recommended pins differ.
 
 ### OpenCode v1
 
+We recommend pinning `v0.18.1` for existing v1 users who want the previous v1-only behavior. To opt into the shared fixes in `v0.19.0`, change the Git ref to `v0.19.0`; revert to the older pin if you encounter a regression.
+
 Add to your `tui.json` (or `.opencode/tui.json`):
 
 ```json
@@ -36,23 +50,23 @@ Add to your `tui.json` (or `.opencode/tui.json`):
 
 > **Why a versioned ref?** OpenCode resolves `@latest` once and caches it forever. Bumping the version in your config is the only reliable way to get updates.
 
-You'll see a toast when a newer version is available (can be turned off).
+By default, you'll see a toast when a newer vimcode version is available. If you stay on the legacy v1 pin, set `updateCheck: false` using the [v1 options example](#opencode-v1-options) to suppress those notifications.
 
 ### OpenCode v2 (experimental)
 
-v2 support is unreleased. The existing `v0.18.1` release does **not** support v2. To try the tested PR code, pin this commit in your global `cli.json`:
+Pin `v0.19.0` in your global `cli.json`. The older `v0.18.1` release does **not** support v2.
 
 ```json
 {
   "plugins": [
     {
-      "package": "vimcode@git+https://github.com/oribarilan/vimcode.git#d8050f765b6c2c4e7fdc700d8345c1c5752644cb"
+      "package": "vimcode@git+https://github.com/oribarilan/vimcode.git#v0.19.0"
     }
   ]
 }
 ```
 
-Cold and warm Git installs were tested on OpenCode 2.0.15 on macOS. Change the pinned ref when updating. See [the v2 POC instructions](docs/opencode-v2-poc.md) for local development, tarball installation, and compatibility limits.
+Validation covers OpenCode 2.0.15 on macOS. Change the pinned ref when updating. See [the v2 POC instructions](docs/opencode-v2-poc.md) for local development, tarball installation, and compatibility limits. To roll back v2, remove the plugin entry; `v0.18.1` cannot be used as a v2 fallback.
 
 ## Configuration
 
@@ -74,7 +88,7 @@ Put `options` alongside `package` in `cli.json`:
 {
   "plugins": [
     {
-      "package": "vimcode@git+https://github.com/oribarilan/vimcode.git#d8050f765b6c2c4e7fdc700d8345c1c5752644cb",
+      "package": "vimcode@git+https://github.com/oribarilan/vimcode.git#v0.19.0",
       "options": { "updateCheck": false }
     }
   ]
@@ -131,7 +145,7 @@ On **v2**, set both the host keybind and the plugin option in `cli.json`:
   "keybinds": { "leader": "space" },
   "plugins": [
     {
-      "package": "vimcode@git+https://github.com/oribarilan/vimcode.git#d8050f765b6c2c4e7fdc700d8345c1c5752644cb",
+      "package": "vimcode@git+https://github.com/oribarilan/vimcode.git#v0.19.0",
       "options": { "experimentalV2Leader": "space" }
     }
   ]

diff --git a/docs/opencode-v2-poc.md b/docs/opencode-v2-poc.md
@@ -1,6 +1,6 @@
 # Experimental OpenCode v2 POC
 
-This branch is a **proof of concept**, not a supported vimcode release. The same `./tui` entry has v1 `tui(api, options)` and v2 `setup(context)` callbacks. v1 still uses its existing API; v2 adapts the host UI, storage, commands and events to the same Vim controller and engine.
+These notes record the v2 proof of concept and compatibility evidence. v2 support is experimental in vimcode v0.19.0; this is not a full-parity or all-versions support declaration. The same `./tui` entry has v1 `tui(api, options)` and v2 `setup(context)` callbacks. v1 still uses its existing API; v2 adapts the host UI, storage, commands and events to the same Vim controller and engine.
 
 ## Local development
 
@@ -21,15 +21,15 @@ The root `tui.ts` re-exports `src/index.ts` for v2's local-directory loader. Thi
 
 The v2 public `keymap` has no key intercept or configured-leader lookup. The POC uses `context.renderer.keyInput.prependListener("keypress", ...)` to intercept prompt keys **before** the host keymap. It calls both `preventDefault()` and `stopPropagation()` on consumed keys. This raw OpenTUI ordering is not a documented OpenCode plugin guarantee; do not rely on it as production compatibility without testing against installed packages and future host releases.
 
-The [README](../README.md#opencode-v2-experimental) shows the tested Git install pinned to commit `d8050f765b6c2c4e7fdc700d8345c1c5752644cb`. Use the global `cli.json` on v2, not v1's `tui.json`.
+The [README](../README.md#opencode-v2-experimental) shows the release Git install pinned to `v0.19.0`. The earlier Git experiment below used commit `d8050f765b6c2c4e7fdc700d8345c1c5752644cb`. Use the global `cli.json` on v2, not v1's `tui.json`.
 
 To test local changes instead, create a fresh artifact directory and build a tarball with `npm pack --ignore-scripts --pack-destination /absolute/path/to/artifacts`. Configure that artifact in `cli.json`:
 
 ```json
 {
   "plugins": [
     {
-      "package": "vimcode@file:/absolute/path/to/artifacts/vimcode-0.18.1.tgz",
+      "package": "vimcode@file:/absolute/path/to/artifacts/vimcode-0.19.0.tgz",
       "options": { "updateCheck": false, "experimentalV2Leader": "ctrl+x" }
     }
   ]

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "vimcode",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "Vim keybindings for the OpenCode prompt",
   "author": "Ori Bar-ilan",
   "license": "MIT",

diff --git a/src/version.ts b/src/version.ts
@@ -1,5 +1,5 @@
 // Keep in sync with package.json on each release.
-export const VERSION = "0.18.1";
+export const VERSION = "0.19.0";
 
 // GitHub API returns fresh content immediately; raw.githubusercontent.com
 // is CDN-cached for up to 5 minutes which delays update detection.