lavish-axi 0.1.45 → 0.1.46

package/README.md

@@ -95,6 +95,32 @@ This installs a `SessionStart` hook for **Claude Code**, **Codex**, **OpenCode**
 Unlike the skill, the hook also shows your live open sessions, so a fresh agent session can resume an in-flight review.
 **Restart your agent session after running this** so the new hook takes effect.
 
+### Agent Plugin
+
+Lavish also ships as an [Agent Plugin](https://agent-plugins.org) - the vendor-neutral packaging standard for skills and MCP servers - so clients that speak that format can load it directly.
+
+**No marketplace is involved.** The installed npm package _is_ the plugin: `plugin.json` sits at the package root next to the `skills/` directory, so whatever `npm install` already put on disk is a complete, conformant plugin. Install the CLI, then register it:
+
+```sh
+npm install -g lavish-axi
+lavish-axi setup plugin
+```
+
+That registers the installed package with every supported client it finds - **VS Code**, **Cursor**, and **GitHub Copilot CLI** - and reports which ones were absent. It is opt-in and idempotent, and it repairs the registered path after a reinstall or relocation. Reload each client afterward.
+
+Each client is registered independently: one that cannot be registered is reported with what to do about it, and never blocks the others or fails the command.
+
+To register by hand instead, point any client at the package directory (`npm root -g`/`lavish-axi`):
+
+| Client             | Register with                                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| VS Code            | `"chat.pluginLocations": { "<package-dir>": true }` in user settings                                               |
+| Cursor             | link the package dir at `~/.cursor/plugins/local/lavish-axi` (`setup plugin` handles Windows link compatibility)   |
+| GitHub Copilot CLI | `copilot plugin install <package-dir>` (or `copilot plugin install kunchenguid/lavish-axi` straight from the repo) |
+
+Codex and ChatGPT install plugins only from marketplace sources, so Codex users should use the session hook above instead.
+Lavish declares no MCP server - the CLI itself is the agent interface - so a plugin install brings the same `lavish` skill, and the skill and plugin are alternatives rather than a stack.
+
 ### From source
 
 ```sh
@@ -207,6 +233,7 @@ pnpm link
 | `lavish-axi playbook [id]`      | List focused artifact guidance or show one playbook; agents must open each matching playbook before writing HTML.                                                                                                                                                                                                                            |
 | `lavish-axi design`             | Show agent-facing design guidance, including optional CDN and Mermaid snippets.                                                                                                                                                                                                                                                              |
 | `lavish-axi setup hooks`        | Install or repair optional SessionStart hooks for Claude Code, Codex, OpenCode, and GitHub Copilot CLI; restart the agent session afterward.                                                                                                                                                                                                 |
+| `lavish-axi setup plugin`       | Register the installed package as an [Agent Plugin](https://agent-plugins.org) in VS Code, Cursor, and GitHub Copilot CLI; opt-in, idempotent, no marketplace involved. Reload each client afterward.                                                                                                                                        |
 | `lavish-axi server`             | Run the local Lavish Editor server.                                                                                                                                                                                                                                                                                                          |
 
 Known playbook IDs: `diagram`, `table`, `comparison`, `plan`, `code`, `input`, `slides`.

package/dist/cli.mjs

@@ -7,11 +7,11 @@ var __export = (target, all) => {
 
 // src/cli.js
 import { spawn, spawnSync } from "node:child_process";
-import { closeSync, existsSync as existsSync2, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync as existsSync3, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync2, realpathSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { access, readFile as readFile5, writeFile as writeFile3 } from "node:fs/promises";
-import os2 from "node:os";
-import path6 from "node:path";
-import { fileURLToPath as fileURLToPath3 } from "node:url";
+import os3 from "node:os";
+import path7 from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
 import { AxiError, installSessionStartHooks, RESERVED_COMMANDS, runAxiCli } from "axi-sdk-js";
 
 // src/playbooks.js
@@ -4285,14 +4285,179 @@ function defaultPort() {
   return Number(process.env.LAVISH_AXI_PORT || 4387);
 }
 
+// src/plugin.js
+import { randomUUID } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync
+} from "node:fs";
+import { createRequire } from "node:module";
+import os2 from "node:os";
+import path3 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+var crossSpawn = createRequire(import.meta.url)("cross-spawn");
+var PLUGIN_AUTHOR = Object.freeze({ name: "Kun Chen", url: "https://github.com/kunchenguid" });
+function spawnPluginClientSync(command, args) {
+  return crossSpawn.sync(command, args, { encoding: "utf8" });
+}
+function resolvePluginRoot() {
+  return path3.resolve(fileURLToPath2(new URL("../", import.meta.url)));
+}
+function readPluginManifest(root) {
+  try {
+    return JSON.parse(readFileSync(path3.join(root, "plugin.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function isStalePluginLocation(candidate, pluginName) {
+  const manifest = readPluginManifest(candidate);
+  if (manifest) return manifest.name === pluginName;
+  return !existsSync(candidate) && path3.basename(candidate) === pluginName;
+}
+function computeVsCodePluginLocationsUpdate(settings, pluginRoot, pluginName) {
+  const updated = structuredClone(settings && typeof settings === "object" ? settings : {});
+  const existing = updated["chat.pluginLocations"];
+  const locations = existing && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
+  let changed = false;
+  for (const key of Object.keys(locations)) {
+    if (key !== pluginRoot && isStalePluginLocation(key, pluginName)) {
+      delete locations[key];
+      changed = true;
+    }
+  }
+  if (locations[pluginRoot] !== true) {
+    locations[pluginRoot] = true;
+    changed = true;
+  }
+  updated["chat.pluginLocations"] = locations;
+  return [updated, changed];
+}
+function resolveVsCodeSettingsFile(env = process.env, homeDir = os2.homedir(), platform = process.platform) {
+  const platformPath = platform === "win32" ? path3.win32 : path3.posix;
+  if (platform === "win32") {
+    return platformPath.join(
+      env.APPDATA || platformPath.join(homeDir, "AppData", "Roaming"),
+      "Code",
+      "User",
+      "settings.json"
+    );
+  }
+  if (platform === "darwin") {
+    return platformPath.join(homeDir, "Library", "Application Support", "Code", "User", "settings.json");
+  }
+  return platformPath.join(
+    env.XDG_CONFIG_HOME || platformPath.join(homeDir, ".config"),
+    "Code",
+    "User",
+    "settings.json"
+  );
+}
+function resolveCursorLocalPluginsDir(homeDir = os2.homedir()) {
+  return path3.join(homeDir, ".cursor", "plugins", "local");
+}
+function writeTextFileAtomically(file, content, operations = {}) {
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  const write = operations.writeFileSync || writeFileSync;
+  const rename2 = operations.renameSync || renameSync;
+  const remove = operations.rmSync || rmSync;
+  const chmod = operations.chmodSync || chmodSync;
+  const stat2 = operations.statSync || statSync;
+  let mode;
+  try {
+    mode = stat2(file).mode & 511;
+  } catch {
+  }
+  try {
+    write(temporary, content, mode === void 0 ? "utf8" : { encoding: "utf8", mode });
+    if (mode !== void 0) chmod(temporary, mode);
+    rename2(temporary, file);
+  } catch (error) {
+    try {
+      remove(temporary, { force: true });
+    } catch {
+    }
+    throw error;
+  }
+}
+function createDirectoryLink(createSymlink, pluginRoot, linkPath, platform) {
+  if (platform === "win32") {
+    try {
+      createSymlink(pluginRoot, linkPath, "junction");
+      return;
+    } catch {
+    }
+  }
+  createSymlink(pluginRoot, linkPath);
+}
+function linkCursorLocalPlugin(localPluginsDir, pluginRoot, pluginName, operations = {}) {
+  const target = path3.join(localPluginsDir, pluginName);
+  const platform = operations.platform || process.platform;
+  const createSymlink = (linkTarget, linkPath) => createDirectoryLink(operations.symlinkSync || symlinkSync, linkTarget, linkPath, platform);
+  const rename2 = operations.renameSync || renameSync;
+  const remove = operations.rmSync || rmSync;
+  let existing = null;
+  try {
+    existing = lstatSync(target);
+  } catch {
+  }
+  if (existing && !existing.isSymbolicLink()) {
+    return { status: "occupied", target };
+  }
+  if (existing) {
+    if (path3.resolve(readlinkSync(target)) === pluginRoot) return { status: "current", target };
+    mkdirSync(localPluginsDir, { recursive: true });
+    const replacement = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    const previous = `${target}.${process.pid}.${randomUUID()}.old`;
+    let movedPrevious = false;
+    try {
+      createSymlink(pluginRoot, replacement);
+      if (platform === "win32") {
+        rename2(target, previous);
+        movedPrevious = true;
+      }
+      rename2(replacement, target);
+      if (movedPrevious) remove(previous, { force: true });
+    } catch (error) {
+      try {
+        remove(replacement, { force: true });
+        if (movedPrevious) rename2(previous, target);
+      } catch {
+      }
+      return { status: "unsupported", target, reason: linkFailureReason(error) };
+    }
+    return { status: "repaired", target };
+  }
+  mkdirSync(localPluginsDir, { recursive: true });
+  try {
+    createSymlink(pluginRoot, target);
+  } catch (error) {
+    return { status: "unsupported", target, reason: linkFailureReason(error) };
+  }
+  return { status: "linked", target };
+}
+function linkFailureReason(error) {
+  const message = String(error instanceof Error ? error.message : error).split("\n")[0];
+  return message || "link creation failed";
+}
+
 // src/server.js
 import crypto4 from "node:crypto";
 import { EventEmitter } from "node:events";
-import { existsSync } from "node:fs";
+import { existsSync as existsSync2 } from "node:fs";
 import { readFile as readFile4 } from "node:fs/promises";
 import { homedir } from "node:os";
-import path5 from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import path6 from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 import chokidar from "chokidar";
 import express from "express";
 
@@ -4792,15 +4957,15 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
     return node.parentElement || document.body;
   }
   function nodePath(node, root) {
-    const path7 = [];
+    const path8 = [];
     let current = node;
     while (current && current !== root) {
       const parentNode = current.parentNode;
       if (!parentNode) break;
-      path7.unshift([...parentNode.childNodes].indexOf(current));
+      path8.unshift([...parentNode.childNodes].indexOf(current));
       current = parentNode;
     }
-    return path7;
+    return path8;
   }
   function rangeBoundary(node, offset) {
     const el = closestElement(node);
@@ -6358,7 +6523,7 @@ function mermaidSourceHash(source) {
 
 // src/whiteboard-store.js
 import { mkdir as mkdir2, readFile as readFile2, rename, rm, writeFile } from "node:fs/promises";
-import path3 from "node:path";
+import path4 from "node:path";
 
 // src/whiteboard-core.js
 var EXCALIDRAW_SCENE_TARGET_TYPE = "excalidraw-scene";
@@ -6410,13 +6575,13 @@ function assertValidRef(key, index) {
   if (!isValidDiagramIndex(index)) throw new Error(`invalid whiteboard diagram index: ${index}`);
 }
 function whiteboardDir(stateDir2, key) {
-  return path3.join(stateDir2, "whiteboards", String(key));
+  return path4.join(stateDir2, "whiteboards", String(key));
 }
 function workingFile(stateDir2, key, index) {
-  return path3.join(whiteboardDir(stateDir2, key), `${Number(index)}.json`);
+  return path4.join(whiteboardDir(stateDir2, key), `${Number(index)}.json`);
 }
 function writeQueueKey(stateDir2, key, index) {
-  return `${path3.resolve(stateDir2)}\0${key}\0${Number(index)}`;
+  return `${path4.resolve(stateDir2)}\0${key}\0${Number(index)}`;
 }
 function queueWhiteboardWrite(stateDir2, key, index, operation) {
   const queueKey = writeQueueKey(stateDir2, key, index);
@@ -6446,8 +6611,8 @@ function whiteboardFeedbackPaths(stateDir2, key, index) {
   assertValidRef(key, index);
   const dir = whiteboardDir(stateDir2, key);
   return {
-    scenePath: path3.join(dir, `${Number(index)}.excalidraw`),
-    previewPath: path3.join(dir, `${Number(index)}.png`)
+    scenePath: path4.join(dir, `${Number(index)}.excalidraw`),
+    previewPath: path4.join(dir, `${Number(index)}.png`)
   };
 }
 async function saveWhiteboard(stateDir2, key, index, { sourceHash, textMetricsVersion = 0, scene, baseline = null }) {
@@ -6536,7 +6701,7 @@ ${script}`;
 // src/session-store.js
 import crypto3 from "node:crypto";
 import { readFile as readFile3, realpath as realpath2, writeFile as writeFile2 } from "node:fs/promises";
-import path4 from "node:path";
+import path5 from "node:path";
 var LAYOUT_WARNINGS_TARGET_TYPE = "layout-warnings";
 var MAX_ARTIFACT_FAILURES = 20;
 var SessionStore = class {
@@ -6995,7 +7160,7 @@ var SessionStore = class {
   }
 };
 async function canonicalFile(file) {
-  const absolute = path4.resolve(file);
+  const absolute = path5.resolve(file);
   return realpath2(absolute);
 }
 function sessionKey(file) {
@@ -7101,9 +7266,9 @@ var WHITEBOARD_CHANNEL_TOKEN_TTL_MS = 5 * 6e4;
 var RELOAD_DEBOUNCE_MS = 100;
 var BATCH_RELOAD_DEBOUNCE_MS = 900;
 function defaultWhiteboardAssetsDir() {
-  const packaged = fileURLToPath2(new URL("./whiteboard", import.meta.url));
-  if (existsSync(packaged)) return packaged;
-  return fileURLToPath2(new URL("../dist/whiteboard", import.meta.url));
+  const packaged = fileURLToPath3(new URL("./whiteboard", import.meta.url));
+  if (existsSync2(packaged)) return packaged;
+  return fileURLToPath3(new URL("../dist/whiteboard", import.meta.url));
 }
 function isWhiteboardWriteApiPath(pathname) {
   return /^\/api\/[0-9a-f]{16}\/whiteboard\/\d{1,3}(\/feedback-files)?$/.test(String(pathname || ""));
@@ -7160,7 +7325,7 @@ async function serve({
 `);
   const logEvent = verbose ? (line) => writeLog(`[lavish] ${line}`) : null;
   let publicPort = port;
-  const whiteboardStateRoot = path5.dirname(stateFile2);
+  const whiteboardStateRoot = path6.dirname(stateFile2);
   const allowedHostnames = buildAllowedHostnames({ host, linkHost: linkHostName, allowedHosts });
   if (!allowsAllHosts(allowedHosts)) {
     app.use((req, res, next) => {
@@ -7430,7 +7595,7 @@ async function serve({
         return;
       }
       const source = await readFile4(session.file, "utf8");
-      const root = path5.dirname(session.file);
+      const root = path6.dirname(session.file);
       const { html, warnings } = await buildSelfContainedHtml(source, {
         baseDir: root,
         confineDir: root,
@@ -7458,7 +7623,7 @@ async function serve({
       }
       const body = req.body || {};
       const source = await readFile4(session.file, "utf8");
-      const root = path5.dirname(session.file);
+      const root = path6.dirname(session.file);
       const { html, warnings } = await buildSelfContainedHtml(source, {
         baseDir: root,
         confineDir: root,
@@ -7603,7 +7768,7 @@ async function serve({
         res.status(404).send("Session not found");
         return;
       }
-      const root = path5.dirname(session.file);
+      const root = path6.dirname(session.file);
       const file = resolveArtifactAsset(root, assetPath);
       if (!file) {
         res.status(403).send("Forbidden");
@@ -7736,8 +7901,8 @@ data: ${JSON.stringify({ state: computePresence(req.params.key, activePolls, del
         res.status(403).send("Forbidden");
         return;
       }
-      if (!existsSync(file)) {
-        res.status(404).send(existsSync(whiteboardAssetsDir) ? "Not found" : "Whiteboard bundle missing - run `pnpm run build`");
+      if (!existsSync2(file)) {
+        res.status(404).send(existsSync2(whiteboardAssetsDir) ? "Not found" : "Whiteboard bundle missing - run `pnpm run build`");
         return;
       }
       res.setHeader("access-control-allow-origin", "*");
@@ -7945,10 +8110,10 @@ function resolveDesignAssetPath(refPath) {
   if (!match) return null;
   const asset = designAssetUrls[match[1]];
   if (!asset) return null;
-  const packaged = fileURLToPath2(asset.packaged);
-  if (existsSync(packaged)) return packaged;
-  const source = fileURLToPath2(asset.source);
-  return existsSync(source) ? source : null;
+  const packaged = fileURLToPath3(asset.packaged);
+  if (existsSync2(packaged)) return packaged;
+  const source = fileURLToPath3(asset.source);
+  return existsSync2(source) ? source : null;
 }
 function exportContentDisposition(file) {
   const filename = exportFileName(file);
@@ -8028,9 +8193,9 @@ function optionalBodyString(value) {
   return trimmed || void 0;
 }
 function resolveArtifactAsset(root, assetPath) {
-  const file = path5.resolve(root, assetPath);
-  const relative = path5.relative(root, file);
-  if (relative.startsWith("..") || path5.isAbsolute(relative)) {
+  const file = path6.resolve(root, assetPath);
+  const relative = path6.relative(root, file);
+  if (relative.startsWith("..") || path6.isAbsolute(relative)) {
     return null;
   }
   return file;
@@ -8066,7 +8231,7 @@ async function resolveWatchTarget(session) {
     const html = await readFile4(session.file, "utf8");
     if (hasLiveReloadRootOptIn(html)) {
       return {
-        path: path5.dirname(session.file),
+        path: path6.dirname(session.file),
         scope: "directory",
         options: {
           ...baseOptions,
@@ -8412,9 +8577,9 @@ var HttpTelemetryClient = class {
     if (!trimmed) return;
     this.send(trimmed, eventURL(this.app, trimmed), fields);
   }
-  pageview(path7, fields = {}) {
+  pageview(path8, fields = {}) {
     if (this.closed) return;
-    this.send("", normalizePagePath(path7), fields);
+    this.send("", normalizePagePath(path8), fields);
   }
   async close(timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
     this.closed = true;
@@ -8489,8 +8654,8 @@ function eventURL(app, name) {
   if (!name) return `app://${app}`;
   return `app://${app}/${name.replace(/\./g, "/")}`;
 }
-function normalizePagePath(path7) {
-  const trimmed = String(path7 || "").trim();
+function normalizePagePath(path8) {
+  const trimmed = String(path8 || "").trim();
   if (!trimmed) return "/";
   return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
 }
@@ -8509,7 +8674,7 @@ var POLL_WAKE_PATH_RULES = Object.freeze([
 ]);
 var POLL_SEND_AND_END_RULE = "`Send & End` ends the session. Its final feedback is still delivered once. After that response, polling stops, and the agent must not reopen the session uninvited.";
 var CODEX_POLL_WAKE_PATH_GUIDANCE = "Codex detected: completed background tasks may not resume Codex automatically, so keep the poll attached to the active turn.";
-var VERSION = "0.1.45";
+var VERSION = "0.1.46";
 function detectInvokingAgent(env = process.env) {
   return ["CODEX_SANDBOX", "CODEX_THREAD_ID"].some((key) => Object.hasOwn(env, key)) ? "codex" : "generic";
 }
@@ -8521,7 +8686,15 @@ function pollExecutionGuidance({ agent = "generic" } = {}) {
   const agentGuidance = agent === "codex" ? ` ${CODEX_POLL_WAKE_PATH_GUIDANCE}` : "";
   return `${sharedGuidance}${agentGuidance}`;
 }
+function isVersionOnlyArgv(argv) {
+  return argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "-V");
+}
 async function run(argv) {
+  if (isVersionOnlyArgv(argv)) {
+    process.stdout.write(`${VERSION}
+`);
+    return;
+  }
   await ensureStateDir();
   const normalizedArgv = normalizeArgv(argv);
   const agent = detectInvokingAgent(process.env);
@@ -8595,7 +8768,7 @@ function telemetryCommandName(argv) {
 }
 function createHomeOutput({ bin, sessions, includeSessions = true, agent = "generic" }) {
   return {
-    bin: collapseHomeDirectory(bin, os2.homedir()),
+    bin: collapseHomeDirectory(bin, os3.homedir()),
     description: DESCRIPTION,
     ...includeSessions ? {
       sessions: sessions.map((session) => ({
@@ -8838,8 +9011,8 @@ async function exportCommand(args) {
   }
   await assertHtmlFile(file);
   const absolute = await canonicalFile(file);
-  const root = path6.dirname(absolute);
-  const output = path6.resolve(flagValue(args, "--out") || path6.join(root, exportFileName(absolute)));
+  const root = path7.dirname(absolute);
+  const output = path7.resolve(flagValue(args, "--out") || path7.join(root, exportFileName(absolute)));
   const source = await readFile5(absolute, "utf8");
   const { html, warnings } = await buildSelfContainedHtml(source, {
     baseDir: root,
@@ -8885,7 +9058,7 @@ async function shareCommand(args) {
   const absolute = await canonicalFile(file);
   const password = optionalFlagString(flagValue(args, "--password"));
   const token = optionalFlagString(flagValue(args, "--token"));
-  const root = path6.dirname(absolute);
+  const root = path7.dirname(absolute);
   const source = await readFile5(absolute, "utf8");
   const { html, warnings } = await buildSelfContainedHtml(source, {
     baseDir: root,
@@ -8964,9 +9137,13 @@ async function designCommand() {
   return createDesignOutput();
 }
 async function setupCommand(args) {
-  if (args.length !== 1 || args[0] !== "hooks") {
-    throw new AxiError("Unknown setup action", "VALIDATION_ERROR", ["Run `lavish-axi setup hooks`"]);
+  if (args.length !== 1 || args[0] !== "hooks" && args[0] !== "plugin") {
+    throw new AxiError("Unknown setup action", "VALIDATION_ERROR", [
+      "Run `lavish-axi setup hooks`",
+      "Run `lavish-axi setup plugin`"
+    ]);
   }
+  if (args[0] === "plugin") return setupPluginCommand();
   const errors = [];
   installSessionStartHooks({
     marker: "lavish-axi",
@@ -8984,14 +9161,186 @@ async function setupCommand(args) {
   }
   return {
     hooks: { status: "installed", integrations: "Claude Code, Codex, OpenCode, GitHub Copilot CLI" },
-    help: ["Restart your agent session to receive lavish-axi ambient context"]
+    help: [
+      "Restart your agent session to receive lavish-axi ambient context",
+      "Run `lavish-axi setup plugin` to also register the Agent Plugin in VS Code, Cursor, and GitHub Copilot CLI"
+    ]
   };
 }
-function resolveHookHomeDir(env = process.env, fallback = os2.homedir()) {
+async function setupPluginCommand() {
+  const pluginRoot = resolvePluginRoot();
+  const manifest = readPluginManifest(pluginRoot);
+  if (!manifest) {
+    throw new AxiError("No plugin.json found in the lavish-axi package", "SERVER_ERROR", [
+      `Expected a manifest at ${path7.join(pluginRoot, "plugin.json")}`,
+      "Reinstall lavish-axi, or run `npm run build:plugin` when working from a source checkout"
+    ]);
+  }
+  const clients = [
+    registerVsCodePlugin(pluginRoot, manifest.name),
+    registerCursorPlugin(pluginRoot, manifest.name),
+    registerCopilotPlugin(pluginRoot, manifest.name)
+  ];
+  const help = ["Restart or reload each client so it discovers the plugin"];
+  if (clients.some((client) => client.status === "absent")) {
+    help.push("Absent clients are skipped; re-run `lavish-axi setup plugin` after installing one");
+  }
+  if (clients.some((client) => client.status === "manual")) {
+    help.push(`Register the plugin root manually where noted: ${pluginRoot}`);
+  }
+  return { plugin: { name: manifest.name, root: collapseHome(pluginRoot) }, clients, help };
+}
+function collapseHome(target) {
+  const home = resolveHookHomeDir();
+  return home && target.startsWith(home) ? `~${target.slice(home.length)}` : target;
+}
+function registerVsCodePlugin(pluginRoot, pluginName) {
+  const settingsFile = resolveVsCodeSettingsFile(process.env, resolveHookHomeDir());
+  const settingsDir = path7.dirname(settingsFile);
+  const hasSettingsFile = existsSync3(settingsFile);
+  if (!hasSettingsFile && !existsSync3(settingsDir)) {
+    return { client: "vscode", status: "absent", detail: "no VS Code user configuration found" };
+  }
+  let settings = {};
+  if (hasSettingsFile) {
+    try {
+      settings = JSON.parse(readFileSync2(settingsFile, "utf8"));
+    } catch {
+      return {
+        client: "vscode",
+        status: "manual",
+        detail: `add "chat.pluginLocations": {"${pluginRoot}": true} to ${collapseHome(settingsFile)}`
+      };
+    }
+  }
+  const [updated, changed] = computeVsCodePluginLocationsUpdate(settings, pluginRoot, pluginName);
+  if (!changed) return { client: "vscode", status: "current", detail: collapseHome(settingsFile) };
+  try {
+    const writeTarget = hasSettingsFile ? realpathSync(settingsFile) : settingsFile;
+    writeTextFileAtomically(writeTarget, `${JSON.stringify(updated, null, 2)}
+`);
+  } catch (error) {
+    return { client: "vscode", status: "failed", detail: String(error instanceof Error ? error.message : error) };
+  }
+  return { client: "vscode", status: "registered", detail: collapseHome(settingsFile) };
+}
+function registerCursorPlugin(pluginRoot, pluginName) {
+  const cursorDir = path7.join(resolveHookHomeDir(), ".cursor");
+  if (!existsSync3(cursorDir)) {
+    return { client: "cursor", status: "absent", detail: "no ~/.cursor directory found" };
+  }
+  try {
+    const { status, target, reason } = linkCursorLocalPlugin(
+      resolveCursorLocalPluginsDir(resolveHookHomeDir()),
+      pluginRoot,
+      pluginName
+    );
+    if (status === "occupied") {
+      return { client: "cursor", status: "manual", detail: `${collapseHome(target)} exists and is not a symlink` };
+    }
+    if (status === "unsupported") {
+      return {
+        client: "cursor",
+        status: "manual",
+        detail: `cannot link ${collapseHome(target)} (${reason}); link it to ${pluginRoot} manually, or enable Developer Mode on Windows`
+      };
+    }
+    return {
+      client: "cursor",
+      status: status === "current" ? "current" : "registered",
+      detail: collapseHome(target)
+    };
+  } catch (error) {
+    return { client: "cursor", status: "failed", detail: String(error instanceof Error ? error.message : error) };
+  }
+}
+function registerCopilotPlugin(pluginRoot, pluginName) {
+  const listed = spawnPluginClientSync("copilot", ["plugins", "list", "--scope", "user", "--kind", "plugin", "--json"]);
+  if (listed.error) {
+    return { client: "copilot", status: "absent", detail: "copilot CLI not found on PATH" };
+  }
+  if (listed.status !== 0) {
+    const detail = String(listed.stderr || listed.stdout || `exit ${listed.status}`).trim();
+    return {
+      client: "copilot",
+      status: "manual",
+      detail: `could not verify installed plugins: ${detail.split("\n")[0]}`
+    };
+  }
+  const records = parseCopilotPluginRecords(listed.stdout);
+  if (!records) {
+    return { client: "copilot", status: "manual", detail: "could not parse installed plugin records" };
+  }
+  const existing = records.find((record) => record.name === pluginName && (!record.kind || record.kind === "plugin"));
+  if (existing) {
+    const source = copilotPluginSourcePath(existing) || installedCopilotPluginSourcePath(pluginName);
+    if (!source) {
+      return { client: "copilot", status: "manual", detail: "could not verify the installed plugin source" };
+    }
+    if (sameResolvedPath(source, pluginRoot)) {
+      return { client: "copilot", status: "current", detail: collapseHome(pluginRoot) };
+    }
+  }
+  const installed = spawnPluginClientSync("copilot", ["plugin", "install", pluginRoot]);
+  if (installed.status !== 0) {
+    const detail = String(installed.stderr || installed.stdout || `exit ${installed.status}`).trim();
+    return { client: "copilot", status: "failed", detail: detail.split("\n")[0] };
+  }
+  return { client: "copilot", status: "registered", detail: "copilot plugin install" };
+}
+function parseCopilotPluginRecords(output) {
+  try {
+    const parsed = JSON.parse(String(output));
+    const records = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.plugins) ? parsed.plugins : parsed?.items;
+    return Array.isArray(records) && records.every((record) => record && typeof record === "object") ? records : null;
+  } catch {
+    return null;
+  }
+}
+function installedCopilotPluginSourcePath(pluginName) {
+  const configDir = process.env.COPILOT_HOME || path7.join(resolveHookHomeDir(), ".copilot");
+  try {
+    const config = JSON.parse(readFileSync2(path7.join(configDir, "config.json"), "utf8"));
+    const record = Array.isArray(config.installedPlugins) ? config.installedPlugins.find((candidate) => candidate?.name === pluginName) : null;
+    return record ? copilotPluginSourcePath(record) : null;
+  } catch {
+    return null;
+  }
+}
+function copilotPluginSourcePath(record) {
+  const candidates = [
+    record.sourcePath,
+    record.source_path,
+    record.pluginRoot,
+    record.plugin_root,
+    record.path,
+    record.source?.path
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate !== "string") continue;
+    if (candidate.startsWith("file:")) {
+      try {
+        return fileURLToPath4(candidate);
+      } catch {
+        continue;
+      }
+    }
+    if (path7.isAbsolute(candidate)) return candidate;
+  }
+  return null;
+}
+function sameResolvedPath(left, right) {
+  try {
+    return realpathSync(left) === realpathSync(right);
+  } catch {
+    return path7.resolve(left) === path7.resolve(right);
+  }
+}
+function resolveHookHomeDir(env = process.env, fallback = os3.homedir()) {
   return env.HOME || fallback;
 }
 function resolveCopilotHookDir(env = process.env, homeDir = resolveHookHomeDir(env)) {
-  return path6.join(env.COPILOT_HOME || path6.join(homeDir, ".copilot"), "hooks");
+  return path7.join(env.COPILOT_HOME || path7.join(homeDir, ".copilot"), "hooks");
 }
 function createCopilotCliAmbientContextScript(command = "lavish-axi") {
   return [
@@ -9040,16 +9389,16 @@ function installCopilotCliSessionStartHook({
   timeoutSec = 10,
   onError = void 0
 } = {}) {
-  const target = path6.join(hookDir, "lavish-axi.json");
+  const target = path7.join(hookDir, "lavish-axi.json");
   try {
-    mkdirSync(path6.dirname(target), { recursive: true });
-    const current = existsSync2(target) ? JSON.parse(readFileSync(target, "utf8")) : {};
+    mkdirSync2(path7.dirname(target), { recursive: true });
+    const current = existsSync3(target) ? JSON.parse(readFileSync2(target, "utf8")) : {};
     const [updated, changed] = computeCopilotCliHookUpdate(
       current,
       createCopilotCliSessionStartHook(command, timeoutSec)
     );
     if (changed) {
-      writeFileSync(target, `${JSON.stringify(updated, null, 2)}
+      writeFileSync2(target, `${JSON.stringify(updated, null, 2)}
 `, "utf8");
     }
   } catch (error) {
@@ -9139,11 +9488,11 @@ function shouldRestartServer(currentVersion, healthBody, forceRestart = false) {
   return healthBody.version !== currentVersion;
 }
 function shouldForceRestartForLocalBuild(executablePath, sourceServerExists = localSourceServerExists()) {
-  const localBuildEntry = fileURLToPath3(new URL("../dist/cli.mjs", import.meta.url));
-  return sourceServerExists && path6.resolve(executablePath) === path6.resolve(localBuildEntry);
+  const localBuildEntry = fileURLToPath4(new URL("../dist/cli.mjs", import.meta.url));
+  return sourceServerExists && path7.resolve(executablePath) === path7.resolve(localBuildEntry);
 }
 function localSourceServerExists() {
-  return existsSync2(fileURLToPath3(new URL("../src/server.js", import.meta.url)));
+  return existsSync3(fileURLToPath4(new URL("../src/server.js", import.meta.url)));
 }
 function shouldKillProcessOnPort(currentVersion, healthBody) {
   if (!healthBody || typeof healthBody !== "object") return false;
@@ -9229,9 +9578,9 @@ async function startServer(port) {
   }
 }
 function resolveServerEntry() {
-  const binEntry = fileURLToPath3(new URL("../bin/lavish-axi.js", import.meta.url));
-  if (existsSync2(binEntry)) return binEntry;
-  return fileURLToPath3(import.meta.url);
+  const binEntry = fileURLToPath4(new URL("../bin/lavish-axi.js", import.meta.url));
+  if (existsSync3(binEntry)) return binEntry;
+  return fileURLToPath4(import.meta.url);
 }
 function createServerSpawnOptions(logFd = null) {
   const stdio = (
@@ -9353,6 +9702,7 @@ Usage:
   lavish-axi playbook [playbook_id]
   lavish-axi design
   lavish-axi setup hooks
+  lavish-axi setup plugin
 
 ${DESIGN_SYSTEM_HINT}
 
@@ -9402,8 +9752,13 @@ Examples:
 Show a copy-pasteable CDN snippet for Tailwind CSS browser runtime v4 + DaisyUI v5 + themes, Mermaid diagram tooling, a content-to-playbook router, an optional layout safety CSS snippet, plus technical reference for DaisyUI components. ${PLAYBOOK_ROUTER_HELP} Lavish artifacts stay portable HTML. This CDN snippet is the design fallback, not the default: inspect the subject project before falling back, and paste the layout safety CSS only when useful for dense nested grid/flex layouts, badges, wide fonts, or local media. ${DESIGN_PRIORITY_RULE}
 `,
     setup: `Usage: lavish-axi setup hooks
+       lavish-axi setup plugin
+
+hooks: install or repair agent SessionStart hooks for lavish-axi ambient context in Claude Code, Codex, OpenCode, and GitHub Copilot CLI. Restart your agent session afterward to receive the context. This is the primary integration - it carries live session state.
+
+plugin: register the installed lavish-axi package as an Agent Plugin (agent-plugins.org) in VS Code, Cursor, and GitHub Copilot CLI. The installed package directory is itself the plugin root, so nothing is downloaded and no marketplace is involved. Reload each client afterward. Codex users should use \`setup hooks\` instead.
 
-Install or repair agent SessionStart hooks for lavish-axi ambient context in Claude Code, Codex, OpenCode, and GitHub Copilot CLI. Restart your agent session afterward to receive the context.
+Both actions are explicit opt-in, idempotent, and repair a stale path after a reinstall.
 `,
     server: `Usage: lavish-axi server [--port 4387] [--verbose]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lavish-axi",
-  "version": "0.1.45",
+  "version": "0.1.46",
   "packageManager": "pnpm@11.1.1",
   "description": "HTML is the new markdown. Lavish is the new editor for your HTML artifacts.",
   "type": "module",
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist",
+    "plugin.json",
     "skills/lavish",
     "lavish-editor-marketing/renders/lavish-editor-marketing.gif",
     "LICENSE",
@@ -18,7 +19,8 @@
   "scripts": {
     "build": "node scripts/build.js",
     "build:skill": "node scripts/build-skill.js",
-    "check": "npm run build && npm run lint && npm run format:check && npm run typecheck && npm test && node scripts/build-skill.js --check",
+    "build:plugin": "node scripts/build-plugin.js",
+    "check": "npm run build && npm run lint && npm run format:check && npm run typecheck && npm test && node scripts/build-skill.js --check && node scripts/build-plugin.js --check",
     "start": "node dist/cli.mjs",
     "lint": "eslint bin src test scripts",
     "format": "prettier --write .",
@@ -32,6 +34,7 @@
     "@tailwindcss/browser": "4.2.4",
     "axi-sdk-js": "^0.1.8",
     "chokidar": "^4.0.3",
+    "cross-spawn": "7.0.6",
     "daisyui": "^5.5.19",
     "express": "^5.2.1",
     "open": "^10.2.0",

package/plugin.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "lavish-axi",
+  "version": "0.1.46",
+  "description": "HTML is the new markdown. Lavish is the new editor for your HTML artifacts.",
+  "author": {
+    "name": "Kun Chen",
+    "url": "https://github.com/kunchenguid"
+  },
+  "homepage": "https://github.com/kunchenguid/lavish-axi#readme",
+  "repository": "https://github.com/kunchenguid/lavish-axi",
+  "license": "MIT",
+  "keywords": [
+    "axi",
+    "agent",
+    "cli",
+    "html",
+    "review",
+    "collaboration"
+  ]
+}

package/skills/lavish/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: lavish
 description: Turn complex or visual agent responses into rich, reviewable HTML artifacts the user can annotate and send feedback on, using the lavish-axi CLI. Use when about to give a plan, comparison, diagram, table, code diff, report, or anything easier to grasp visually than as prose.
-argument-hint: <what the artifact should show>
-author: Kun Chen (kunchenguid)
+license: MIT
 metadata:
-  hermes:
-    tags: [html, review, artifacts, visualization]
-    category: productivity
+  author: Kun Chen (kunchenguid)
+  argument-hint: <what the artifact should show>
+  hermes-tags: html, review, artifacts, visualization
+  hermes-category: productivity
 ---
 
 # Lavish Editor