docs(opencode): document the supported plugin install flow

Author: iceteaSA

ARCHITECTURE.md

@@ -42,7 +42,7 @@ graph LR
   E2E --> Core
 ```
 
-`packages/opencode/package.json:32-45` declares two `oc-plugin` entry points: `server` (the fetch interceptor / OAuth / quota controller) and `tui` (the OpenTUI sidebar) — the host loads them as separate plugin registrations. The Pi package's `pi.extensions` field (`packages/pi/package.json:34-38`) is the analogue. The core package has no peer dependencies on any host runtime; it only depends on Node built-ins and `@openauthjs/openauth`.
+`packages/opencode/package.json` exposes two `exports` subpaths that the host installer reads: `exports["."]` (the fetch interceptor / OAuth / quota controller) and `exports["./tui"]` (the OpenTUI sidebar). The host's `opencode plugin` installer writes a server entry to `opencode.json` and a TUI entry to `tui.json`; the host loads the two registrations independently. The Pi package's `pi.extensions` field (`packages/pi/package.json:34-38`) is the analogue. The core package has no peer dependencies on any host runtime; it only depends on Node built-ins and `@openauthjs/openauth`.
 
 ### Process topology at runtime
 
@@ -206,7 +206,7 @@ The `RetryState` at `packages/opencode/src/plugin/fetch/retry-state.ts` and `War
 
 ### Two halves of the contract
 
-The OpenTUI plugin is declared in `packages/opencode/package.json:32-45` as `"oc-plugin": ["server", "tui"]`. The host loads the TUI entry point separately; the entry dispatches to either the precompiled Solid bundle or the raw `tui.tsx` based on the host runtime module's availability (`packages/opencode/src/tui/entry.mjs:30-66`).
+The OpenTUI plugin is wired through the package's `exports["./tui"]` subpath (`packages/opencode/package.json`). The host's `opencode plugin` installer reads that subpath and writes the registration into `tui.json`; the host loads the TUI entry point separately from the server entry, and the entry dispatches to either the precompiled Solid bundle or the raw `tui.tsx` based on the host runtime module's availability (`packages/opencode/src/tui/entry.mjs:30-66`).
 
 The two halves share a small amount of code through `packages/opencode/src/tui-compiled/` (the precompiled mirror) and the slim contract modules:
 

README.md

@@ -22,31 +22,55 @@ The shipped headers, project IDs, and OAuth client identifiers match the publicl
 
 | Host | Package version | Host requirement | Install path |
 | --- | --- | --- | --- |
-| OpenCode (server + TUI) | `2.0.0` | `@opencode-ai/plugin >=1.17.13 <2` · `@opentui/core`, `@opentui/keymap`, `@opentui/solid` all `^0.4.5` | `plugin` array (server) + `oc-plugin` field (`["server","tui"]`) |
+| OpenCode (server + TUI) | `2.0.0` | `@opencode-ai/plugin >=1.17.13 <2` · `@opentui/core`, `@opentui/keymap`, `@opentui/solid` all `^0.4.5` | `opencode plugin @cortexkit/opencode-antigravity-auth@latest` (writes the server entry to `opencode.json` and the TUI entry to `tui.json`) |
 | Pi coding agent | `2.0.0` | `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui` (peer) | `pi install npm:@cortexkit/pi-antigravity-auth` then `/login google-antigravity` |
 | Standalone CLI | shipped inside the OpenCode package as the `antigravity-auth` bin | Node 20+ | `npx @cortexkit/opencode-antigravity-auth` |
 | Node libraries (harness builders) | `2.0.0` core | Node 20+ | `npm install @cortexkit/antigravity-auth-core` |
 
-The OpenCode package's `oc-plugin` field publishes two subpaths:
+The OpenCode package exposes two `exports` subpaths the host installer reads:
 
-- `oc-plugin: "server"` — the default `@opencode-ai/plugin` entry; OpenCode loads it via the `plugin` array.
-- `oc-plugin: "tui"` — exports the TUI sidebar through the `"./tui"` subpath. OpenCode 1.17.13+ resolves this automatically; legacy hosts declare it explicitly through the package's `oc-plugin` declaration in `package.json` (`["server","tui"]`). The precompiled JSX tree ships under `dist/src/tui-compiled/` and is regenerated by `bun run build:tui`; the host's loader also accepts the raw `src/tui.tsx` source path for development installs.
+- `exports["."]` — the bundled `dist/index.js` server root; `opencode plugin` writes this entry into `opencode.json`'s `plugin` array.
+- `exports["./tui"]` — `src/tui/entry.mjs`, the OpenTUI sidebar loader; `opencode plugin` writes this entry into `tui.json` so the TUI process picks it up on the next host start. The precompiled JSX tree ships under `dist/src/tui-compiled/` and is regenerated by `bun run build:tui`; the host's loader also accepts the raw `src/tui.tsx` source path for development installs.
 
-Both core and opencode packages are dual-target: the OpenCode package bundles a CommonJS-free ESM artifact via `esbuild`, while the core package ships `tsc`-emitted ESM. Runtime requirements match the `engines.node` field (`>=20`).
+The host enforces the minimum OpenCode version through the package's `engines.opencode` field (`>=1.17.13 <2`); `opencode plugin` refuses to install a plugin that asks for an unsupported range. Both core and opencode packages are dual-target: the OpenCode package bundles a CommonJS-free ESM artifact via `esbuild`, while the core package ships `tsc`-emitted ESM. Runtime requirements match the `engines.node` field (`>=20`).
 
 ## Installation matrix
 
 ### OpenCode (npm — the only end-user install path)
 
-Edit `~/.config/opencode/opencode.json` (or the path `OPENCODE_CONFIG_DIR` points at):
+The supported installer writes both registrations in one step:
+
+```bash
+opencode plugin @cortexkit/opencode-antigravity-auth@latest
+```
+
+What this does:
+
+- Reads the package's `exports["."]` (the server root) and writes it into `~/.config/opencode/opencode.json` under the `plugin` array — that is the `auth.loader` and `fetch` interceptor the host calls on every model dispatch.
+- Reads the package's `exports["./tui"]` (the OpenTUI sidebar loader) and writes it into `~/.config/opencode/tui.json` so the TUI process picks the sidebar up on the next host start.
+- Refuses to install when the host's OpenCode version falls outside the package's `engines.opencode` range (`>=1.17.13 <2`).
+
+#### Manual config (hand-edited configs)
+
+If you cannot use `opencode plugin`, write both files by hand. The server entry lives in `opencode.json`:
 
 ```jsonc
+// ~/.config/opencode/opencode.json
 {
   "plugin": ["@cortexkit/opencode-antigravity-auth@latest"]
 }
 ```
 
-The plugin field is the **server** subpath. The TUI sidebar is loaded automatically through the `oc-plugin` declaration in the npm package; no extra config is required on a 1.17.13+ host. On older hosts, explicitly add the `./tui` exports subpath through the host plugin loader.
+The TUI entry lives in a separate `tui.json` file under the same config dir:
+
+```jsonc
+// ~/.config/opencode/tui.json
+{
+  "plugins": ["@cortexkit/opencode-antigravity-auth"]
+}
+```
+
+The two files are independent — the host reads the server registration from `opencode.json` and the TUI registration from `tui.json`. Dropping one side disables that half of the plugin without touching the other.
 
 ### OpenCode from this checkout (contributors)
 

STRUCTURE.md

@@ -99,7 +99,7 @@ Every production file has a corresponding `*.test.ts` sibling. The dense transfo
 
 ## `packages/opencode` inventory
 
-`@cortexkit/opencode-antigravity-auth`. Has two `oc-plugin` entry points (`server`, `tui`) declared in `package.json:32-45`. Production layout:
+`@cortexkit/opencode-antigravity-auth`. Exposes two `exports` subpaths (`"."` and `"./tui"`) and pins the supported host range through `engines.opencode` (`>=1.17.13 <2`); the host installer (`opencode plugin`) reads the subpaths and writes a server entry to `opencode.json` and a TUI entry to `tui.json`. Production layout:
 
 ```
 packages/opencode/
@@ -343,7 +343,7 @@ Project-wide tsconfig used by `bun run typecheck` (root script `typecheck`) for
 | `@cortexkit/opencode-antigravity-auth` (`server` — fallback) | `packages/opencode/src/plugin-entry.test.ts` | test entry | Verifies the public barrel exports the two stable plugin names. |
 | `@cortexkit/pi-antigravity-auth` | `packages/pi/src/index.ts` | `default function` | Pi extension. Resolves as `pi.extensions: ['./dist/index.js']` per `packages/pi/package.json:34-38`. |
 
-The `oc-plugin` manifest at `packages/opencode/package.json:32-45` declares the `server` and `tui` entry points and the `exports` map declares both `.` (the bundled server root) and `./tui` (the loader). The host resolves them as separate plugin registrations.
+The `exports` map at `packages/opencode/package.json` declares both `.` (the bundled server root) and `./tui` (the OpenTUI loader). The host's `opencode plugin` installer reads the subpaths and writes a server entry to `opencode.json` plus a TUI entry to `tui.json`; the host then resolves them as two independent plugin registrations.
 
 ## Generated and ignored artifacts
 

packages/opencode/README.md

@@ -32,28 +32,49 @@ This package is part of the `@cortexkit/antigravity-auth@2.0.0` monorepo. See th
 | `@opentui/core`, `@opentui/keymap`, `@opentui/solid` (peer) | `^0.4.5` each |
 | Node | `>=20` |
 
-The package declares both `oc-plugin` subpaths in its `package.json`:
+The package pins the supported host range through `engines.opencode` (`>=1.17.13 <2`); `opencode plugin` refuses to install a plugin that asks for an unsupported range.
 
-```jsonc
-{
-  "oc-plugin": ["server", "tui"]
-}
-```
+The package exposes two `exports` subpaths the host installer reads:
 
-OpenCode 1.17.13+ resolves the **server** subpath through the `plugin` array and the **tui** subpath through `oc-plugin` automatically. Legacy hosts can declare the `./tui` exports subpath explicitly through their own plugin loader.
+- `exports["."]` — the bundled `dist/index.js` server root. `opencode plugin` writes this entry into `opencode.json`'s `plugin` array.
+- `exports["./tui"]` — `src/tui/entry.mjs`, the OpenTUI sidebar loader. `opencode plugin` writes this entry into `tui.json` so the TUI process picks it up on the next host start.
 
 ## Installation
 
 ### End-user (npm) — the supported path
 
-Add to `~/.config/opencode/opencode.json`:
+The supported installer writes both registrations in one step:
 
-```json
+```bash
+opencode plugin @cortexkit/opencode-antigravity-auth@latest
+```
+
+What this does:
+
+- Reads the package's `exports["."]` and writes it into `~/.config/opencode/opencode.json` under the `plugin` array — the `auth.loader` and `fetch` interceptor the host calls on every model dispatch.
+- Reads the package's `exports["./tui"]` and writes it into `~/.config/opencode/tui.json` so the TUI process picks the sidebar up on the next host start.
+- Refuses to install when the host's OpenCode version falls outside the package's `engines.opencode` range.
+
+#### Manual config (hand-edited configs)
+
+If you cannot use `opencode plugin`, write both files by hand:
+
+```jsonc
+// ~/.config/opencode/opencode.json
 {
   "plugin": ["@cortexkit/opencode-antigravity-auth@latest"]
 }
 ```
 
+```jsonc
+// ~/.config/opencode/tui.json
+{
+  "plugins": ["@cortexkit/opencode-antigravity-auth"]
+}
+```
+
+The two files are independent — the server registration is read from `opencode.json` and the TUI registration from `tui.json`.
+
 Then start OpenCode and run `opencode auth login`, pick **Antigravity (Google OAuth)** in the menu (or `/antigravity-account add`). Verify with `npx -y @cortexkit/opencode-antigravity-auth quota`.
 
 ### Contributor (Bun)
@@ -80,7 +101,7 @@ A precompiled JSX tree ships under `dist/src/tui-compiled/` and is regenerated b
   import { authorizeAntigravity, exchangeAntigravity } from "@cortexkit/antigravity-auth-core"
   ```
 
-- **`@opencode-ai/plugin` peer dependency** moved from `^0.15.30` to `^1.17.13`. Hosts on 1.17.13+ get the automatic `oc-plugin: tui` discovery for free.
+- **`@opencode-ai/plugin` peer dependency** moved from `^0.15.30` to `^1.17.13`. Hosts on 1.17.13+ get the TUI registration through `opencode plugin` (the host reads `exports["./tui"]` and writes it into `tui.json`).
 - **New peer dependencies** (`@opentui/core`, `@opentui/keymap`, `@opentui/solid` at `^0.4.5`) — required by the sidebar.
 - No account-storage changes: the on-disk format is unchanged from the v1.4+ storage schema (`AccountStorageV4`).
 - Missing accounts now return **HTTP 401 `UNAUTHENTICATED`** from the fetch interceptor instead of a synthetic 200 with assistant text.

packages/opencode/package.json

@@ -27,12 +27,9 @@
     "claude"
   ],
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.0.0",
+    "opencode": ">=1.17.13 <2"
   },
-  "oc-plugin": [
-    "server",
-    "tui"
-  ],
   "exports": {
     ".": {
       "import": "./dist/index.js",

packages/opencode/scripts/smoke-tui-pack-install.ts

@@ -3,8 +3,11 @@
  * directory through `bun add ./pack.tgz` (so the package export map is
  * actually exercised), and assert the tarball + install shape:
  *
- *   - `package.json` exposes `oc-plugin: ["server", "tui"]`.
- *   - `package.json` exports `./tui` pointing at `src/tui/entry.mjs`.
+ *   - `package.json` `engines.opencode` pins the host-version range
+ *     that `opencode plugin` enforces.
+ *   - `package.json` exports `./tui` pointing at `src/tui/entry.mjs`
+ *     (the host installer reads this subpath when wiring the TUI
+ *     registration into `tui.json`).
  *   - The compiled tree lands at `src/tui-compiled/tui.tsx` (where the
  *     host entry module expects it after a successful virtual runtime
  *     probe).
@@ -13,7 +16,7 @@
  *     real package export map (`import('@cortexkit/opencode-antigravity-auth/tui')`).
  *
  * Runs only via `bun run smoke:tui`. Use this on every package change
- * that touches `package.json` `exports`, `files`, or `oc-plugin` — a
+ * that touches `package.json` `exports`, `files`, or `engines` — a
  * broken pack is a broken ship.
  */
 
@@ -30,9 +33,9 @@ const CORE_ROOT = resolve(REPO_ROOT, 'packages/core')
 interface PackageJson {
   name: string
   version: string
+  engines?: Record<string, string>
   exports?: Record<string, unknown>
   files?: string[]
-  'oc-plugin'?: string[]
 }
 
 async function run(): Promise<void> {
@@ -61,17 +64,16 @@ async function run(): Promise<void> {
   const pkgRaw = readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf-8')
   const pkg = JSON.parse(pkgRaw) as PackageJson
 
-  // 1) `oc-plugin` must list `tui`.
-  const ocPlugin = pkg['oc-plugin']
-  if (!Array.isArray(ocPlugin) || ocPlugin.length === 0) {
-    throw new Error('package.json is missing oc-plugin metadata')
-  }
-  if (!ocPlugin.includes('tui')) {
-    throw new Error('package.json oc-plugin does not list "tui"')
+  // 1) `engines.opencode` must pin the host-version range that
+  //    `opencode plugin` enforces at install time.
+  const opencodeEngine = pkg.engines?.opencode
+  if (typeof opencodeEngine !== 'string' || opencodeEngine.length === 0) {
+    throw new Error('package.json is missing engines.opencode metadata')
   }
 
   // 2) `./tui` must be exposed in the exports map and point at
-  //    `tui/entry.mjs`.
+  //    `tui/entry.mjs` — the host installer reads this subpath to
+  //    wire the TUI registration into `tui.json`.
   const tuiExport = pkg.exports?.['./tui']
   if (!tuiExport || typeof tuiExport !== 'object') {
     throw new Error('package.json exports must include "./tui" entry')