@elliotsystems/eai 0.1.1 → 0.1.3

package/README.md

@@ -31,9 +31,16 @@ In precedence order (`lib/resolve.js`):
 | # | Source | Path |
 |---|---|---|
 | 1 | `ELLIOT_OPENCODE_BIN` | the binary itself |
-| 2 | bundled runtime | `vendor/opencode-<platform>-<arch>/bin/opencode[.exe]` |
-| 3 | `ELLIOT_OPENCODE_HOME` | `<home>/packages/opencode/dist/…` or `<home>/opencode-<platform>-<arch>/…` |
-| 4 | sibling fork checkout | **development only**, last resort |
+| 2 | **stock upstream runtime** | `opencode-ai/bin/opencode.exe`, resolved via `require.resolve` — **this is production** |
+| 3 | Elliot platform package | `@elliotsystems/eai-<os>-<arch>/bin/…` — fork builds, legacy, no longer a dependency |
+| 4 | bundled runtime | `vendor/opencode-<platform>-<arch>/bin/…` |
+| 5 | `ELLIOT_OPENCODE_HOME` | `<home>/packages/opencode/dist/…` or `<home>/opencode-<platform>-<arch>/…` |
+| 6 | in-repo fork checkout | `../opencode/…` — **development only** |
+| 7 | sibling fork checkout | `../../opencode/…` — **development only**, last resort |
+
+Stock sits ahead of the Elliot platform packages deliberately. Those are fork
+builds, and preferring them would quietly reintroduce the patched OpenCode this
+architecture exists to remove.
 
 Two deliberate rules:
 
@@ -58,8 +65,7 @@ stays clean for piping).
 (`@elliotsystems/elliot-ai`, currently on PATH). Both can coexist, so the legacy
 CLI keeps working untouched and its retirement stays a separate, later decision.
 
-The package is still `private: true` — packaging, publishing and global install
-are out of scope until approved. Run it locally with `node bin/eai`.
+Run it locally, without installing, with `node bin/eai`.
 
 ## Install
 
@@ -99,3 +105,43 @@ To publish a new release to npm:
 ```
 npm test        # node --test, no dependencies
 ```
+
+## Architecture
+
+```
+stock upstream OpenCode  (opencode-ai, an npm dependency)
+          |
+   Elliot launcher  (this package)
+     |-- config/            OPENCODE_CONFIG_DIR: theme + plugin registration
+     |-- config/themes/     the Elliot palette
+     |-- plugin/            the bundled Elliot plugin (wordmark, chrome)
+     +-- bin/eai            OSC 0 terminal title
+          |
+        eai  ->  Elliot-branded TUI
+```
+
+**OpenCode core modifications: 0.** Elliot ships no compiled OpenCode. An
+upstream upgrade is a version bump of `opencode-ai` in `package.json`.
+
+Three mechanisms carry the branding, none of which touch OpenCode source:
+
+| Surface | Mechanism |
+|---|---|
+| Wordmark, palette, accent, chrome | the bundled plugin, via `home_logo` (`mode="replace"`) and theme discovery |
+| Theme selection + plugin registration | `OPENCODE_CONFIG_DIR` -> this package's `config/` |
+| Terminal title | `OPENCODE_DISABLE_TERMINAL_TITLE=1`, then the launcher writes OSC 0 |
+
+### Why the plugin is bundled rather than depended on
+
+`@elliotsystems/opencode-plugin` is not published to npm. A config that named it
+by package name would install cleanly and then render as plain OpenCode, which
+is the worst failure mode available -- it looks like it worked. `scripts/bundle.js`
+copies it in from `opencode-plugin/` (the single source of truth) and runs from
+`prepack`, so `npm pack` and `npm publish` cannot forget it.
+
+### Why the theme file is shipped as well
+
+The plugin can install the palette itself via `api.theme.install()`, but that
+WRITES into the config directory, and a global npm install directory is not
+reliably writable. Shipping `config/themes/elliot.json` means the theme resolves
+read-only.

package/bin/eai

@@ -25,6 +25,7 @@ const {
   resolveOpencodeBin,
 } = require("../lib/resolve.js")
 const { injectToken } = require("../lib/token-env.js")
+const { stageOverlay } = require("../lib/stage.js")
 
 /**
  * Resolve symlinks before deriving the package root.
@@ -50,6 +51,11 @@ function packageRoot() {
 }
 
 const PACKAGE_ROOT = packageRoot()
+const PACKAGE_VERSION = require("../package.json").version
+// OSC 0 (set icon name and window title), BEL-terminated: every terminal that
+// supports OSC accepts BEL, while some older ones reject ST.
+const ELLIOT_TITLE = String.fromCharCode(27) + "]0;Elliot-AI" + String.fromCharCode(7)
+
 const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"]
 
 function fail(message) {
@@ -87,10 +93,33 @@ if (process.env.ELLIOT_LAUNCHER_DEBUG) {
 // the child inherits process.env, so setting it here is enough.
 injectToken(process.env)
 
+// Elliot's identity travels WITH this package, not with the directory the user
+// happens to be standing in. Before this, branding came from a `tui.json` in the
+// Elliot repository root, so an installed `eai` outside that repo rendered as
+// plain OpenCode. `config/` is packaged (see package.json `files`) and holds the
+// theme, the palette and the plugin registration.
+const env = { ...process.env }
+if (!env.OPENCODE_CONFIG_DIR) {
+  // Staged OUTSIDE node_modules, which is not optional: a plugin under
+  // node_modules does not load (its tsconfig, and so its jsxImportSource, is
+  // not applied there), and the TUI comes up as plain OpenCode with nothing
+  // logged. See lib/stage.js.
+  const staged = stageOverlay({ packageRoot: PACKAGE_ROOT, version: PACKAGE_VERSION })
+  if (staged) env.OPENCODE_CONFIG_DIR = staged
+}
+
+// The one branding surface no plugin slot can reach. Upstream sets the terminal
+// title itself from a `createEffect` with no slot and no config key, but it does
+// honour this flag (`core/src/flag/flag.ts`), so we turn its title off and write
+// our own below. This is what lets OpenCode stay stock.
+env.OPENCODE_DISABLE_TERMINAL_TITLE = "1"
+
+// Claim the title before the child paints anything.
+if (process.stdout.isTTY) process.stdout.write(ELLIOT_TITLE)
+
 // argv passes through untouched and WITHOUT a shell, so quoting, spaces and
-// shell metacharacters in a prompt reach the runtime as the user typed them and
-// are never re-interpreted by an intermediate shell.
-const child = childProcess.spawn(resolved.path, process.argv.slice(2), { stdio: "inherit" })
+// shell metacharacters in a prompt reach the runtime as the user typed them.
+const child = childProcess.spawn(resolved.path, process.argv.slice(2), { stdio: "inherit", env })
 
 child.on("error", (error) => fail(error.message))
 

package/config/opencode.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["../plugin/opencode-plugin"]
+}

package/config/themes/elliot.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://opencode.ai/theme.json",
+  "defs": {
+    "brandOrange": "#FF6600",
+    "accentOrange": "#FF7A2E",
+    "accentOrangeLit": "#FF9354",
+    "accentOrangeSoft": "#FFB07A",
+    "accentOrangeDeep": "#C2410C",
+    "accentOrangeInk": "#7C2D12",
+
+    "ground": "#0B0C0E",
+    "panel": "#121315",
+    "elevated": "#191B1D",
+    "elevated2": "#212325",
+    "border": "#262829",
+    "borderSoft": "#1C1E20",
+
+    "text": "#F5F6F8",
+    "textFaint": "#A0A3A8",
+    "textDim": "#8E9297",
+    "textGhost": "#3A3D3F",
+
+    "success": "#5DD89B",
+    "warning": "#E8C33A",
+    "error": "#F7768E",
+    "teal": "#5EEAD4",
+
+    "lightGround": "#FFFFFF",
+    "lightPanel": "#FAFAFA",
+    "lightElevated": "#F2F2F4",
+    "lightElevated2": "#E9E9EC",
+    "lightBorder": "#D9D9DE",
+    "lightBorderSoft": "#EDEDF0",
+    "lightText": "#0B0C0E",
+    "lightTextDim": "#6B6E73",
+    "lightTextFaint": "#8E9297",
+    "lightTextGhost": "#C4C6CA",
+    "lightSuccess": "#1B7F4F",
+    "lightWarning": "#8A6D0B",
+    "lightError": "#C2334C",
+    "lightTeal": "#0F766E"
+  },
+  "theme": {
+    "primary": { "dark": "brandOrange", "light": "brandOrange" },
+    "accent": { "dark": "accentOrange", "light": "accentOrangeDeep" },
+    "secondary": { "dark": "teal", "light": "lightTeal" },
+    "info": { "dark": "accentOrangeSoft", "light": "accentOrangeDeep" },
+
+    "error": { "dark": "error", "light": "lightError" },
+    "warning": { "dark": "warning", "light": "lightWarning" },
+    "success": { "dark": "success", "light": "lightSuccess" },
+
+    "text": { "dark": "text", "light": "lightText" },
+    "textMuted": { "dark": "textDim", "light": "lightTextDim" },
+
+    "selectedListItemText": { "dark": "ground", "light": "lightGround" },
+
+    "background": { "dark": "ground", "light": "lightGround" },
+    "backgroundPanel": { "dark": "panel", "light": "lightPanel" },
+    "backgroundElement": { "dark": "elevated", "light": "lightElevated" },
+    "backgroundMenu": { "dark": "elevated2", "light": "lightElevated2" },
+
+    "border": { "dark": "border", "light": "lightBorder" },
+    "borderActive": { "dark": "accentOrange", "light": "accentOrangeDeep" },
+    "borderSubtle": { "dark": "borderSoft", "light": "lightBorderSoft" },
+
+    "diffAdded": { "dark": "success", "light": "lightSuccess" },
+    "diffRemoved": { "dark": "error", "light": "lightError" },
+    "diffContext": { "dark": "textDim", "light": "lightTextDim" },
+    "diffHunkHeader": { "dark": "textFaint", "light": "lightTextFaint" },
+    "diffHighlightAdded": { "dark": "#8DE8B8", "light": "#12603B" },
+    "diffHighlightRemoved": { "dark": "#FF9BAC", "light": "#A62740" },
+    "diffAddedBg": { "dark": "#0F2018", "light": "#E4F5EB" },
+    "diffRemovedBg": { "dark": "#241318", "light": "#FBE4E9" },
+    "diffContextBg": { "dark": "panel", "light": "lightPanel" },
+    "diffLineNumber": { "dark": "textGhost", "light": "lightTextGhost" },
+    "diffAddedLineNumberBg": { "dark": "#0C1913", "light": "#D6EDDF" },
+    "diffRemovedLineNumberBg": { "dark": "#1D0F13", "light": "#F6D8DF" },
+
+    "markdownText": { "dark": "text", "light": "lightText" },
+    "markdownHeading": { "dark": "brandOrange", "light": "accentOrangeDeep" },
+    "markdownLink": { "dark": "accentOrange", "light": "accentOrangeDeep" },
+    "markdownLinkText": { "dark": "accentOrangeSoft", "light": "accentOrangeDeep" },
+    "markdownCode": { "dark": "accentOrangeSoft", "light": "accentOrangeDeep" },
+    "markdownBlockQuote": { "dark": "textFaint", "light": "lightTextFaint" },
+    "markdownEmph": { "dark": "accentOrangeLit", "light": "accentOrangeDeep" },
+    "markdownStrong": { "dark": "accentOrange", "light": "accentOrangeDeep" },
+    "markdownHorizontalRule": { "dark": "borderSoft", "light": "lightBorderSoft" },
+    "markdownListItem": { "dark": "accentOrange", "light": "accentOrangeDeep" },
+    "markdownListEnumeration": { "dark": "accentOrangeLit", "light": "accentOrangeDeep" },
+    "markdownImage": { "dark": "accentOrange", "light": "accentOrangeDeep" },
+    "markdownImageText": { "dark": "textFaint", "light": "lightTextFaint" },
+    "markdownCodeBlock": { "dark": "text", "light": "lightText" },
+
+    "syntaxComment": { "dark": "textGhost", "light": "lightTextGhost" },
+    "syntaxKeyword": { "dark": "accentOrange", "light": "accentOrangeDeep" },
+    "syntaxFunction": { "dark": "accentOrangeLit", "light": "accentOrangeInk" },
+    "syntaxVariable": { "dark": "text", "light": "lightText" },
+    "syntaxString": { "dark": "success", "light": "lightSuccess" },
+    "syntaxNumber": { "dark": "accentOrangeSoft", "light": "accentOrangeDeep" },
+    "syntaxType": { "dark": "teal", "light": "lightTeal" },
+    "syntaxOperator": { "dark": "textFaint", "light": "lightTextFaint" },
+    "syntaxPunctuation": { "dark": "textDim", "light": "lightTextDim" }
+  }
+}

package/config/tui.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "theme": "elliot",
+  "mouse": true,
+  "plugin": ["../plugin/opencode-plugin"],
+  "plugin_enabled": {
+    "internal:home-tips": false
+  }
+}

package/lib/resolve.js

@@ -15,6 +15,7 @@ const path = require("path")
 const os = require("os")
 
 const DEV_FALLBACK = "in-repo fork checkout (dev)"
+const STOCK_RUNTIME = "stock upstream runtime"
 const SIBLING_FALLBACK = "sibling fork checkout (dev)"
 
 const PLATFORM_MAP = { darwin: "darwin", linux: "linux", win32: "windows" }
@@ -50,7 +51,43 @@ function candidates(opts) {
     out.push({ source: "ELLIOT_OPENCODE_BIN", path: env.ELLIOT_OPENCODE_BIN })
   }
 
-  // 2. Per-platform npm optionalDependency package — the shape a published,
+  // 2. Stock upstream OpenCode, from upstream's OWN per-platform npm package.
+  //
+  //    Resolved DIRECTLY rather than through `opencode-ai/bin/opencode.exe`,
+  //    and that distinction is the difference between working and not. The path
+  //    inside `opencode-ai` is a 479-byte placeholder shell script until its
+  //    postinstall replaces it with the real binary -- and postinstall does not
+  //    always run: `--ignore-scripts`, pnpm's defaults, and npm's newer
+  //    script-gating all skip it. Observed on a clean install here: the platform
+  //    package unpacked its 146MB binary fine while the stub was still in place.
+  //    The platform package needs no script at all, so this path is the reliable
+  //    one.
+  //
+  //    Baseline variant second: upstream ships `-baseline` for x64 CPUs without
+  //    AVX2, so it is the correct fallback rather than an error.
+  for (const suffix of ['', '-baseline']) {
+    try {
+      const spec = `opencode-${platform}-${arch}${suffix}/package.json`
+      const p = requireResolve(spec)
+      out.push({
+        source: suffix ? STOCK_RUNTIME + ' (baseline)' : STOCK_RUNTIME,
+        path: path.join(path.dirname(p), 'bin', binary),
+      })
+    } catch {
+      // Not installed for this platform/arch; try the next shape.
+    }
+  }
+
+  //    Last stock shape: `opencode-ai`'s own bin, valid once its postinstall HAS
+  //    run. Kept so an install that did run scripts still resolves.
+  try {
+    const p = requireResolve('opencode-ai/package.json')
+    out.push({ source: STOCK_RUNTIME + ' (via opencode-ai postinstall)', path: path.join(path.dirname(p), 'bin', 'opencode.exe') })
+  } catch {
+    // opencode-ai not installed.
+  }
+
+  // 3. Per-platform npm optionalDependency package — the shape a published,
   //    `npm install`-ed `@elliotsystems/eai` gets its runtime from. Resolved via
   //    `require.resolve` so it works no matter where npm hoisted node_modules.
   try {
@@ -60,11 +97,11 @@ function candidates(opts) {
     // Platform package not installed (e.g. running from a dev checkout).
   }
 
-  // 3. Bundled runtime — the shape a published/installed Elliot package will
+  // 4. Bundled runtime — the shape a published/installed Elliot package will
   //    have. Nothing populates this yet; packaging is a later, approved phase.
   out.push({ source: "bundled vendor runtime", path: path.join(root, "vendor", dir, "bin", binary) })
 
-  // 4. A configured fork location. Accepts either a checkout root or a dist
+  // 5. A configured fork location. Accepts either a checkout root or a dist
   //    root, because both are things a person reasonably points this at.
   if (env.ELLIOT_OPENCODE_HOME) {
     const home = env.ELLIOT_OPENCODE_HOME
@@ -129,4 +166,5 @@ function resolveOpencodeBin(opts) {
   return null
 }
 
-module.exports = { DEV_FALLBACK, SIBLING_FALLBACK, candidates, isExplicitlyConfigured, platformTriple, resolveOpencodeBin }
+module.exports = {
+  STOCK_RUNTIME, DEV_FALLBACK, SIBLING_FALLBACK, candidates, isExplicitlyConfigured, platformTriple, resolveOpencodeBin }

package/lib/stage.js

@@ -0,0 +1,116 @@
+"use strict"
+
+/**
+ * Stage the Elliot overlay outside `node_modules` before launching.
+ *
+ * This exists because of a hard runtime constraint, found by installing the
+ * tarball and watching it fail: a plugin that lives under `node_modules` does
+ * not load. The same files, byte for byte, load fine one directory outside it.
+ * The runtime does not apply the plugin's own `tsconfig.json` — and therefore
+ * its `jsxImportSource` — to anything under `node_modules`, so the plugin's JSX
+ * never compiles. Nothing is logged: the TUI simply comes up as plain OpenCode,
+ * which is the failure mode that looks like success.
+ *
+ * So the tarball ships the overlay (it must be self-contained, since
+ * `@elliotsystems/opencode-plugin` is not published), and this copies it to a
+ * writable location outside `node_modules` on first run. That location doubles
+ * as `OPENCODE_CONFIG_DIR`, which also solves a second problem: the plugin's
+ * `api.theme.install()` writes into the config dir, and a global npm install
+ * directory is not reliably writable.
+ *
+ * The generated `tui.json` names the plugin by ABSOLUTE path. A relative one
+ * would resolve against the staged config file and work, but an absolute path
+ * is what makes a broken stage obvious instead of silently falling back to
+ * upstream's own chrome.
+ */
+
+const fs = require("fs")
+const os = require("os")
+const path = require("path")
+
+/**
+ * Where the staged overlay lives.
+ *
+ * Keyed by version so an upgrade stages fresh rather than reusing a stale tree,
+ * and so two installed versions cannot fight over one directory.
+ */
+function stageRoot(version, env = process.env) {
+  const base =
+    env.ELLIOT_STAGE_DIR ||
+    (process.platform === "win32" && env.LOCALAPPDATA
+      ? path.join(env.LOCALAPPDATA, "elliot", "eai")
+      : path.join(os.homedir(), ".elliot", "eai"))
+  return path.join(base, version)
+}
+
+function copyDir(from, to) {
+  fs.mkdirSync(to, { recursive: true })
+  for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+    // node_modules is deliberately not copied: the host supplies solid-js and
+    // @opentui/* to runtime-loaded plugins, and a second copy of solid-js in the
+    // TUI process would break reactivity across the slot boundary.
+    if (entry.name === "node_modules") continue
+    const src = path.join(from, entry.name)
+    const dst = path.join(to, entry.name)
+    if (entry.isDirectory()) copyDir(src, dst)
+    else fs.copyFileSync(src, dst)
+  }
+}
+
+/**
+ * Ensure the overlay is staged, and return the directory to use as
+ * OPENCODE_CONFIG_DIR. Returns undefined if staging is not possible, so the
+ * caller can still launch — an unbranded TUI beats no TUI.
+ */
+function stageOverlay(opts) {
+  const packageRoot = opts.packageRoot
+  const version = opts.version
+  const env = opts.env || process.env
+
+  const pluginSource = path.join(packageRoot, "plugin", "opencode-plugin")
+  const themeSource = path.join(packageRoot, "config", "themes")
+  if (!fs.existsSync(pluginSource)) return undefined
+
+  const root = stageRoot(version, env)
+  const marker = path.join(root, ".staged")
+  const pluginDir = path.join(root, "plugin", "opencode-plugin")
+
+  try {
+    // `.staged` records the version this tree was built from. Re-staging on
+    // every launch would add hundreds of file copies to startup.
+    const done = fs.existsSync(marker) && fs.readFileSync(marker, "utf8").trim() === version
+    if (!done) {
+      fs.rmSync(root, { recursive: true, force: true })
+      copyDir(pluginSource, pluginDir)
+      if (fs.existsSync(themeSource)) copyDir(themeSource, path.join(root, "themes"))
+
+      const plugin = [pluginDir]
+      fs.writeFileSync(
+        path.join(root, "tui.json"),
+        JSON.stringify(
+          {
+            $schema: "https://opencode.ai/tui.json",
+            theme: "elliot",
+            mouse: true,
+            plugin,
+            plugin_enabled: { "internal:home-tips": false },
+          },
+          null,
+          2,
+        ),
+      )
+      fs.writeFileSync(
+        path.join(root, "opencode.json"),
+        JSON.stringify({ $schema: "https://opencode.ai/config.json", plugin }, null, 2),
+      )
+      fs.writeFileSync(marker, version)
+    }
+    return root
+  } catch {
+    // Read-only home, exotic permissions, a racing install. Branding is worth
+    // less than starting up, so this is not fatal.
+    return undefined
+  }
+}
+
+module.exports = { stageOverlay, stageRoot }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elliotsystems/eai",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Elliot AI CLI entry point (eai) - launches the Elliot runtime with arguments forwarded verbatim.",
   "bin": {
     "eai": "./bin/eai"
@@ -8,6 +8,8 @@
   "files": [
     "bin",
     "lib",
+    "config",
+    "plugin",
     "README.md"
   ],
   "scripts": {
@@ -15,7 +17,10 @@
     "vendor": "node scripts/vendor.js",
     "assemble": "node scripts/assemble.js",
     "publish:npm": "node scripts/publish.js",
-    "build:runtime": "bun run --cwd ../opencode/packages/opencode script/build.ts --skip-embed-web-ui"
+    "build:runtime": "bun run --cwd ../opencode/packages/opencode script/build.ts --skip-embed-web-ui",
+    "bundle": "node scripts/bundle.js",
+    "prepack": "node scripts/bundle.js",
+    "verify": "node scripts/verify-package.js"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -23,11 +28,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "optionalDependencies": {
-    "@elliotsystems/eai-darwin-arm64": "0.1.0",
-    "@elliotsystems/eai-darwin-x64": "0.1.0",
-    "@elliotsystems/eai-linux-x64": "0.1.0",
-    "@elliotsystems/eai-linux-arm64": "0.1.0",
-    "@elliotsystems/eai-windows-x64": "0.1.0"
+  "dependencies": {
+    "opencode-ai": "1.18.30"
   }
 }

package/plugin/opencode-plugin/README.md

@@ -0,0 +1,64 @@
+# @elliotsystems/opencode-plugin
+
+Elliot AI's OpenCode integration. Phase C2 scope: repository-scope injection for
+`elliot_knowledge_search`.
+
+## What it does — and pointedly does not
+
+The Elliot backend serves `knowledge_search` as an MCP tool on `/mcp/v1`; through the MCP
+server name `elliot`, the agent sees **`elliot_knowledge_search`**. This plugin's single
+job is to inject the session's repository (`owner/name`, derived from the worktree's git
+remote) into that tool's arguments, so retrieval can be repo-focused **while the model
+never names a repository**. The backend's `resolve_repo_scope` remains the only
+authorizer — a wrong or forged hint can select nothing the tenant wasn't already granted.
+
+No tokens (login/refresh/storage is OpenCode's native MCP OAuth — `opencode mcp auth
+elliot`), no transport, no prompt injection.
+
+## Setup
+
+`opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "elliot": {
+      "type": "remote",
+      "url": "https://backend.elliotsystemsonline.com/mcp/v1",
+      "oauth": { "clientId": "elliot-opencode" }
+    }
+  },
+  "plugin": [["@elliotsystems/opencode-plugin@0.1.0", { "serverNames": ["elliot"] }]]
+}
+```
+
+Then `opencode mcp auth elliot` once. Pin the plugin version — never `@latest`.
+
+`serverNames` must match your `mcp` key(s); the plugin recognises the composed tool key
+`<server>_knowledge_search` exactly (OpenCode composes MCP tool keys as
+`sanitize(client) + "_" + sanitize(tool)`).
+
+## Development
+
+```bash
+npm install
+npm test          # vitest — includes the security cases (scope overwrite/delete)
+npm run typecheck
+```
+
+Load the working copy into OpenCode with a path spec:
+`"plugin": [["file:///abs/path/to/opencode-plugin/src/index.ts", {}]]`.
+
+Windows note: if `bun`/OpenCode installs hit `EPERM (NtSetInformationFile())` on native
+packages, that's AV interference during cache renames — use
+`bun install --backend=copyfile` and/or add an AV exclusion (see Phase B findings).
+
+## Security invariants (tested)
+
+- Session truth **overwrites** any pre-existing `repo_scope_hint` in tool args.
+- With no derivable scope, a smuggled hint is **deleted**; search degrades to
+  tenant-wide (authorized, just unfocused) — never an error, never a forged scope.
+- Only the exact composed key on configured servers is touched; every other tool's
+  args pass through byte-identical.
+- Options are zod-`strict()`: unknown keys fail the plugin at load, loudly.

package/plugin/opencode-plugin/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@elliotsystems/opencode-plugin",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Elliot AI integration for OpenCode: tenant-aware knowledge tools, repository scope, and policy.",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./tui": "./src/tui/index.tsx"
+  },
+  "files": [
+    "src",
+    "themes",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@opentui/core": ">=0.4.5 <0.5",
+    "@opentui/solid": ">=0.4.5 <0.5",
+    "solid-js": ">=1.9.10 <2",
+    "zod": ">=3.23"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "elliot": {
+    "opencodeRange": ">=1.18.19 <1.19.0"
+  },
+  "oc-themes": [
+    "themes/elliot.json"
+  ]
+}