agkit 0.7.0 → 0.9.0

package/dist/index.js

@@ -24,7 +24,13 @@ var RESERVED_MARKETPLACE_NAMES = [
   "anthropic-plugins"
 ];
 var KEBAB_CASE_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-var PLUGIN_TEMPLATES = ["skill", "command", "agent", "hook", "mcp"];
+var PLUGIN_TEMPLATES = [
+  "skill",
+  "command",
+  "agent",
+  "hook",
+  "mcp"
+];
 var TEMPLATE_DESCRIPTIONS = {
   skill: "Plugin exposing an Agent Skill (SKILL.md): reference knowledge or a repeatable procedure Claude loads on demand.",
   command: "Plugin exposing a slash command (commands/<name>.md): a prompt shortcut invoked as /<plugin>:<name>.",
@@ -84,14 +90,69 @@ function readJson(filePath) {
 }
 function writeJson(filePath, data) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}
+`);
+}
+
+// src/lib/marketplace.ts
+import fs2 from "fs";
+import path2 from "path";
+function marketplacePath(root) {
+  return path2.join(root, MARKETPLACE_DIR, MARKETPLACE_FILE);
+}
+function findMarketplaceRoot(startDir) {
+  let dir = path2.resolve(startDir);
+  for (; ; ) {
+    if (fs2.existsSync(marketplacePath(dir))) return dir;
+    const parent = path2.dirname(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+function readMarketplace(root) {
+  return readJson(marketplacePath(root));
+}
+function writeMarketplace(root, data) {
+  writeJson(marketplacePath(root), data);
+}
+function pluginRootDir(root, mp) {
+  const rel = mp.metadata?.pluginRoot ?? DEFAULT_PLUGIN_ROOT;
+  return path2.resolve(root, rel);
+}
+function resolveLocalPluginDir(root, mp, entry) {
+  if (typeof entry.source !== "string") return void 0;
+  if (entry.source.startsWith("./") || entry.source.startsWith("../")) {
+    return path2.resolve(root, entry.source);
+  }
+  return path2.join(pluginRootDir(root, mp), entry.source);
+}
+function scanLocalPlugins(root, mp) {
+  const base = pluginRootDir(root, mp);
+  if (!fs2.existsSync(base)) return [];
+  const result = [];
+  for (const entry of fs2.readdirSync(base, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const manifestPath = path2.join(
+      base,
+      entry.name,
+      MARKETPLACE_DIR,
+      PLUGIN_MANIFEST_FILE
+    );
+    if (!fs2.existsSync(manifestPath)) continue;
+    result.push({
+      dir: path2.join(base, entry.name),
+      dirName: entry.name,
+      manifest: readJson(manifestPath)
+    });
+  }
+  return result;
 }
 
 // src/lib/templates.ts
 import { execFileSync } from "child_process";
-import fs2 from "fs";
+import fs3 from "fs";
 import os from "os";
-import path2 from "path";
+import path3 from "path";
 function parseGitSpec(spec) {
   let ref;
   let body = spec;
@@ -122,8 +183,75 @@ function parseGitSpec(spec) {
   }
   return void 0;
 }
+function isRemoteSpec(spec) {
+  if (PLUGIN_TEMPLATES.includes(spec)) return false;
+  return !(spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("path:") || path3.isAbsolute(spec));
+}
+function resolveRemoteSource(spec, opts = {}) {
+  if (spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("path:") || path3.isAbsolute(spec)) {
+    throw new Error(
+      `--link needs a remote git source, but "${spec}" is a local path. Drop --link to scaffold from a local template.`
+    );
+  }
+  if (PLUGIN_TEMPLATES.includes(spec)) {
+    throw new Error(
+      `--link needs a remote git source, but "${spec}" is a built-in template. Drop --link to scaffold it locally.`
+    );
+  }
+  if (opts.sha && !/^[0-9a-f]{40}$/i.test(opts.sha)) {
+    throw new Error(
+      `--sha must be a full 40-character commit hash: "${opts.sha}"`
+    );
+  }
+  let body = spec;
+  let hashRef;
+  const hash = body.lastIndexOf("#");
+  if (hash > 0) {
+    hashRef = body.slice(hash + 1) || void 0;
+    body = body.slice(0, hash);
+  }
+  const git2 = parseGitSpec(spec);
+  const ref = opts.ref ?? git2?.ref ?? hashRef;
+  const pin = (base) => {
+    if (ref) base.ref = ref;
+    if (opts.sha) base.sha = opts.sha;
+    return base;
+  };
+  if (git2) {
+    if (git2.subdir) {
+      return {
+        source: pin({
+          source: "git-subdir",
+          url: git2.cloneUrl,
+          path: git2.subdir
+        }),
+        label: spec
+      };
+    }
+    const gh = git2.cloneUrl.match(
+      /^https:\/\/github\.com\/([^/]+)\/(.+?)(?:\.git)?$/
+    );
+    if (gh) {
+      return {
+        source: pin({ source: "github", repo: `${gh[1]}/${gh[2]}` }),
+        label: spec
+      };
+    }
+    return { source: pin({ source: "url", url: git2.cloneUrl }), label: spec };
+  }
+  const bare = body.match(/^([\w][\w.-]*)\/([\w][\w.-]*)$/);
+  if (bare) {
+    return {
+      source: pin({ source: "github", repo: `${bare[1]}/${bare[2]}` }),
+      label: spec
+    };
+  }
+  throw new Error(
+    `Unrecognized remote source "${spec}". Use owner/repo, gh:owner/repo[/dir], gl:owner/repo[/dir], or a git URL[//dir][#ref].`
+  );
+}
 function assertTemplateDir(dir, label) {
-  const hasManifest = fs2.existsSync(path2.join(dir, ".claude-plugin", "plugin.json.tpl")) || fs2.existsSync(path2.join(dir, ".claude-plugin", "plugin.json"));
+  const hasManifest = fs3.existsSync(path3.join(dir, ".claude-plugin", "plugin.json.tpl")) || fs3.existsSync(path3.join(dir, ".claude-plugin", "plugin.json"));
   if (!hasManifest) {
     throw new Error(
       `"${label}" is not a plugin template: expected .claude-plugin/plugin.json(.tpl) in ${dir}`
@@ -133,15 +261,16 @@ function assertTemplateDir(dir, label) {
 function resolveTemplate(spec) {
   if (PLUGIN_TEMPLATES.includes(spec)) {
     return {
-      dir: path2.join(templatesDir(), "plugins", spec),
+      dir: path3.join(templatesDir(), "plugins", spec),
       label: `built-in:${spec}`,
       builtin: true
     };
   }
-  const localPath = spec.startsWith("path:") ? spec.slice(5) : spec.startsWith("./") || spec.startsWith("../") || path2.isAbsolute(spec) ? spec : void 0;
+  const localPath = spec.startsWith("path:") ? spec.slice(5) : spec.startsWith("./") || spec.startsWith("../") || path3.isAbsolute(spec) ? spec : void 0;
   if (localPath !== void 0) {
-    const dir2 = path2.resolve(localPath);
-    if (!fs2.existsSync(dir2)) throw new Error(`Template directory not found: ${dir2}`);
+    const dir2 = path3.resolve(localPath);
+    if (!fs3.existsSync(dir2))
+      throw new Error(`Template directory not found: ${dir2}`);
     assertTemplateDir(dir2, spec);
     return { dir: dir2, label: spec, builtin: false };
   }
@@ -151,91 +280,106 @@ function resolveTemplate(spec) {
       `Unrecognized template "${spec}". Use a built-in name (${PLUGIN_TEMPLATES.join(", ")}), a local path, gh:owner/repo[/dir][#ref], gl:owner/repo[/dir][#ref], or a git URL.`
     );
   }
-  const tmp = fs2.mkdtempSync(path2.join(os.tmpdir(), "agkit-tpl-"));
+  const tmp = fs3.mkdtempSync(path3.join(os.tmpdir(), "agkit-tpl-"));
   const args = ["clone", "--depth", "1"];
   if (git2.ref) args.push("--branch", git2.ref);
   args.push(git2.cloneUrl, tmp);
   try {
     execFileSync("git", args, { stdio: "pipe" });
   } catch (err) {
-    fs2.rmSync(tmp, { recursive: true, force: true });
+    fs3.rmSync(tmp, { recursive: true, force: true });
     const msg = err.stderr?.toString().trim();
-    throw new Error(`git clone failed for ${git2.cloneUrl}${msg ? `:
-${msg}` : ""}`);
+    throw new Error(
+      `git clone failed for ${git2.cloneUrl}${msg ? `:
+${msg}` : ""}`
+    );
   }
-  const dir = git2.subdir ? path2.join(tmp, git2.subdir) : tmp;
-  if (!fs2.existsSync(dir)) {
-    fs2.rmSync(tmp, { recursive: true, force: true });
-    throw new Error(`Subdirectory "${git2.subdir}" not found in ${git2.cloneUrl}`);
+  const dir = git2.subdir ? path3.join(tmp, git2.subdir) : tmp;
+  if (!fs3.existsSync(dir)) {
+    fs3.rmSync(tmp, { recursive: true, force: true });
+    throw new Error(
+      `Subdirectory "${git2.subdir}" not found in ${git2.cloneUrl}`
+    );
   }
-  fs2.rmSync(path2.join(tmp, ".git"), { recursive: true, force: true });
+  fs3.rmSync(path3.join(tmp, ".git"), { recursive: true, force: true });
   try {
     assertTemplateDir(dir, spec);
   } catch (err) {
-    fs2.rmSync(tmp, { recursive: true, force: true });
+    fs3.rmSync(tmp, { recursive: true, force: true });
     throw err;
   }
   return { dir, label: spec, cleanup: tmp, builtin: false };
 }
 
-// src/lib/marketplace.ts
-import fs3 from "fs";
-import path3 from "path";
-function marketplacePath(root) {
-  return path3.join(root, MARKETPLACE_DIR, MARKETPLACE_FILE);
-}
-function findMarketplaceRoot(startDir) {
-  let dir = path3.resolve(startDir);
-  for (; ; ) {
-    if (fs3.existsSync(marketplacePath(dir))) return dir;
-    const parent = path3.dirname(dir);
-    if (parent === dir) return void 0;
-    dir = parent;
-  }
-}
-function readMarketplace(root) {
-  return readJson(marketplacePath(root));
+// src/commands/sync.ts
+import fs5 from "fs";
+import path6 from "path";
+import * as p2 from "@clack/prompts";
+
+// src/lib/docs.ts
+var PLUGINS_START = "<!-- agkit:plugins:start -->";
+var PLUGINS_END = "<!-- agkit:plugins:end -->";
+var CHANGELOG_HEADER = "# Changelog";
+function replaceBetweenMarkers(content, start, end, body) {
+  const s = content.indexOf(start);
+  const e = content.indexOf(end);
+  if (s === -1 || e === -1 || e < s) return void 0;
+  return `${content.slice(0, s + start.length)}
+${body}
+${content.slice(e)}`;
 }
-function writeMarketplace(root, data) {
-  writeJson(marketplacePath(root), data);
+var EMPTY_HINT = "_No plugins yet. Add one with `agkit add <template> <name>`._";
+function renderPluginTable(plugins) {
+  if (plugins.length === 0) return EMPTY_HINT;
+  const withKeywords = plugins.some((p8) => (p8.keywords?.length ?? 0) > 0);
+  const header = withKeywords ? [
+    "| Plugin | Version | Description | Keywords |",
+    "| :----- | :------ | :---------- | :------- |"
+  ] : [
+    "| Plugin | Version | Description |",
+    "| :----- | :------ | :---------- |"
+  ];
+  const rows = plugins.map((e) => {
+    const name = e.homepage ? `[\`${e.name}\`](${e.homepage})` : `\`${e.name}\``;
+    const cells = [name, e.version ?? "\u2014", e.description ?? ""];
+    if (withKeywords) {
+      cells.push((e.keywords ?? []).map((k) => `\`${k}\``).join(" "));
+    }
+    return `| ${cells.join(" | ")} |`;
+  });
+  return [...header, ...rows].join("\n");
 }
-function pluginRootDir(root, mp) {
-  const rel = mp.metadata?.pluginRoot ?? DEFAULT_PLUGIN_ROOT;
-  return path3.resolve(root, rel);
+function renderAgentsPluginList(plugins) {
+  if (plugins.length === 0) return "_No plugins yet._";
+  return plugins.map((e) => {
+    const version2 = e.version ? ` (${e.version})` : "";
+    const desc = e.description ? ` \u2014 ${e.description}` : "";
+    return `- \`${e.name}\`${version2}${desc}`;
+  }).join("\n");
 }
-function resolveLocalPluginDir(root, mp, entry) {
-  if (typeof entry.source !== "string") return void 0;
-  if (entry.source.startsWith("./") || entry.source.startsWith("../")) {
-    return path3.resolve(root, entry.source);
-  }
-  return path3.join(pluginRootDir(root, mp), entry.source);
+function renderChangelogEntry(version2, subjects, date) {
+  const bullets = subjects.length > 0 ? subjects.map((s) => `- ${s}`).join("\n") : `- Release ${version2}`;
+  return `## ${version2} \u2014 ${date}
+
+${bullets}`;
 }
-function scanLocalPlugins(root, mp) {
-  const base = pluginRootDir(root, mp);
-  if (!fs3.existsSync(base)) return [];
-  const result = [];
-  for (const entry of fs3.readdirSync(base, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const manifestPath = path3.join(
-      base,
-      entry.name,
-      MARKETPLACE_DIR,
-      PLUGIN_MANIFEST_FILE
-    );
-    if (!fs3.existsSync(manifestPath)) continue;
-    result.push({
-      dir: path3.join(base, entry.name),
-      dirName: entry.name,
-      manifest: readJson(manifestPath)
-    });
+function prependChangelogEntry(existing, entry) {
+  if (!existing?.includes(CHANGELOG_HEADER)) {
+    return `${CHANGELOG_HEADER}
+
+${entry}
+`;
   }
-  return result;
-}
+  const idx = existing.indexOf(CHANGELOG_HEADER) + CHANGELOG_HEADER.length;
+  const before = existing.slice(0, idx);
+  const after = existing.slice(idx).replace(/^\n+/, "");
+  return `${`${before}
 
-// src/commands/sync.ts
-import fs5 from "fs";
-import path6 from "path";
-import * as p2 from "@clack/prompts";
+${entry}
+
+${after}`.trimEnd()}
+`;
+}
 
 // src/commands/build.ts
 import fs4 from "fs";
@@ -253,7 +397,8 @@ function sourcePath(mp, dirName) {
   return `./${path4.posix.join(pluginRootRel(mp), dirName)}`;
 }
 function json(value) {
-  return JSON.stringify(value, null, 2) + "\n";
+  return `${JSON.stringify(value, null, 2)}
+`;
 }
 function manifestCopy(local) {
   return json(local.manifest);
@@ -275,11 +420,19 @@ function generateCursor(ctx) {
     }))
   };
   const files = [
-    { relPath: path4.posix.join(".cursor-plugin", "marketplace.json"), content: json(registry) }
+    {
+      relPath: path4.posix.join(".cursor-plugin", "marketplace.json"),
+      content: json(registry)
+    }
   ];
   for (const p8 of plugins) {
     files.push({
-      relPath: path4.posix.join(pluginRootRel(mp), p8.dirName, ".cursor-plugin", "plugin.json"),
+      relPath: path4.posix.join(
+        pluginRootRel(mp),
+        p8.dirName,
+        ".cursor-plugin",
+        "plugin.json"
+      ),
       content: manifestCopy(p8)
     });
   }
@@ -304,7 +457,12 @@ function generateCodex(ctx) {
   ];
   for (const p8 of plugins) {
     files.push({
-      relPath: path4.posix.join(pluginRootRel(mp), p8.dirName, ".codex-plugin", "plugin.json"),
+      relPath: path4.posix.join(
+        pluginRootRel(mp),
+        p8.dirName,
+        ".codex-plugin",
+        "plugin.json"
+      ),
       content: manifestCopy(p8)
     });
   }
@@ -348,7 +506,9 @@ function computeFiles(root, mp, ids) {
 async function buildCommand(startDir, opts = {}) {
   const root = findMarketplaceRoot(startDir);
   if (!root) {
-    p.log.error("No .claude-plugin/marketplace.json found. Run `agkit init` first.");
+    p.log.error(
+      "No .claude-plugin/marketplace.json found. Run `agkit init` first."
+    );
     process.exitCode = 1;
     return;
   }
@@ -420,12 +580,27 @@ function refreshBuiltTargets(root, mp) {
 }
 
 // src/commands/sync.ts
-var README_START = "<!-- agkit:plugins:start -->";
-var README_END = "<!-- agkit:plugins:end -->";
+function refreshMarkedDoc(root, relPath, body, label, changes) {
+  const abs = path6.join(root, relPath);
+  if (!fs5.existsSync(abs)) return;
+  const content = fs5.readFileSync(abs, "utf8");
+  const updated = replaceBetweenMarkers(
+    content,
+    PLUGINS_START,
+    PLUGINS_END,
+    body
+  );
+  if (updated !== void 0 && updated !== content) {
+    fs5.writeFileSync(abs, updated);
+    changes.push(`~ refreshed ${label}`);
+  }
+}
 async function syncCommand(startDir, opts = {}) {
   const root = findMarketplaceRoot(startDir);
   if (!root) {
-    p2.log.error("No .claude-plugin/marketplace.json found. Run `agkit init` first.");
+    p2.log.error(
+      "No .claude-plugin/marketplace.json found. Run `agkit init` first."
+    );
     process.exitCode = 1;
     return;
   }
@@ -439,12 +614,18 @@ async function syncCommand(startDir, opts = {}) {
     if (!entry) {
       entry = {
         name: entryName,
-        source: mp.metadata?.pluginRoot ? local.dirName : `./${path6.relative(root, local.dir).split(path6.sep).join("/")}`
+        source: `./${path6.relative(root, local.dir).split(path6.sep).join("/")}`
       };
       mp.plugins.push(entry);
       changes.push(`+ added "${entryName}" to the catalog`);
     }
-    for (const field of ["version", "description", "author", "keywords", "homepage"]) {
+    for (const field of [
+      "version",
+      "description",
+      "author",
+      "keywords",
+      "homepage"
+    ]) {
       const value = manifest[field];
       if (value !== void 0 && JSON.stringify(entry[field]) !== JSON.stringify(value)) {
         entry[field] = value;
@@ -463,27 +644,22 @@ async function syncCommand(startDir, opts = {}) {
   mp.plugins.sort((a, b) => a.name.localeCompare(b.name));
   writeMarketplace(root, mp);
   const refreshed = refreshBuiltTargets(root, mp);
-  for (const id of refreshed) changes.push(`~ refreshed ${id} tier-2 artifacts`);
-  const readmePath = path6.join(root, "README.md");
-  if (fs5.existsSync(readmePath)) {
-    const readme = fs5.readFileSync(readmePath, "utf8");
-    const start = readme.indexOf(README_START);
-    const end = readme.indexOf(README_END);
-    if (start !== -1 && end !== -1 && end > start) {
-      const table = mp.plugins.length === 0 ? "_No plugins yet. Add one with `agkit add <template> <name>`._" : [
-        "| Plugin | Version | Description |",
-        "| :----- | :------ | :---------- |",
-        ...mp.plugins.map(
-          (e) => `| \`${e.name}\` | ${e.version ?? "\u2014"} | ${e.description ?? ""} |`
-        )
-      ].join("\n");
-      const updated = readme.slice(0, start + README_START.length) + "\n" + table + "\n" + readme.slice(end);
-      if (updated !== readme) {
-        fs5.writeFileSync(readmePath, updated);
-        changes.push("~ refreshed plugin list in README.md");
-      }
-    }
-  }
+  for (const id of refreshed)
+    changes.push(`~ refreshed ${id} tier-2 artifacts`);
+  refreshMarkedDoc(
+    root,
+    "README.md",
+    renderPluginTable(mp.plugins),
+    "plugin list in README.md",
+    changes
+  );
+  refreshMarkedDoc(
+    root,
+    "AGENTS.md",
+    renderAgentsPluginList(mp.plugins),
+    "plugin list in AGENTS.md",
+    changes
+  );
   if (!opts.quiet) {
     if (changes.length === 0) {
       p2.log.success("Catalog already in sync.");
@@ -521,6 +697,7 @@ async function addPlugin(startDir, templateArg, nameArg, opts = {}) {
     if (p3.isCancel(answer)) return cancel2();
     templateSpec = answer;
   }
+  const reference = isRemoteSpec(templateSpec) && opts.vendor !== true;
   let name = nameArg;
   if (!name) {
     const answer = await p3.text({
@@ -542,12 +719,6 @@ async function addPlugin(startDir, templateArg, nameArg, opts = {}) {
     process.exitCode = 1;
     return;
   }
-  const destDir = path7.join(pluginRootDir(root, mp), name);
-  if (fs6.existsSync(destDir)) {
-    p3.log.error(`Directory already exists: ${destDir}`);
-    process.exitCode = 1;
-    return;
-  }
   let description = opts.description;
   if (description === void 0 && opts.interactive !== false) {
     const answer = await p3.text({
@@ -559,6 +730,39 @@ async function addPlugin(startDir, templateArg, nameArg, opts = {}) {
     description = answer;
   }
   description = description || `TODO: describe what ${name} does.`;
+  if (reference) {
+    let remote;
+    try {
+      remote = resolveRemoteSource(templateSpec, {
+        ref: opts.ref,
+        sha: opts.sha
+      });
+    } catch (err) {
+      p3.log.error(err.message);
+      process.exitCode = 1;
+      return;
+    }
+    mp.plugins.push({ name, source: remote.source, description });
+    writeMarketplace(root, mp);
+    await syncCommand(root, { quiet: true });
+    p3.log.success(
+      `Registered ${pc2.cyan(name)} as a remote plugin (${remote.label}) in marketplace.json \u2014 nothing was cloned.`
+    );
+    p3.log.info(
+      `Claude Code fetches it from the source at install time:
+  claude
+  /plugin marketplace add ${root}
+  /plugin install ${name}@${mp.name}
+(pass --vendor to clone it into ${mp.metadata?.pluginRoot ?? "./plugins"} instead)`
+    );
+    return;
+  }
+  const destDir = path7.join(pluginRootDir(root, mp), name);
+  if (fs6.existsSync(destDir)) {
+    p3.log.error(`Directory already exists: ${destDir}`);
+    process.exitCode = 1;
+    return;
+  }
   const vars = {
     pluginName: name,
     pluginTitle: titleCase(name),
@@ -576,7 +780,8 @@ async function addPlugin(startDir, templateArg, nameArg, opts = {}) {
   try {
     copyTemplateDir(resolved.dir, destDir, vars);
   } finally {
-    if (resolved.cleanup) fs6.rmSync(resolved.cleanup, { recursive: true, force: true });
+    if (resolved.cleanup)
+      fs6.rmSync(resolved.cleanup, { recursive: true, force: true });
   }
   const manifestPath = path7.join(destDir, ".claude-plugin", "plugin.json");
   if (!resolved.builtin && fs6.existsSync(manifestPath)) {
@@ -590,7 +795,7 @@ async function addPlugin(startDir, templateArg, nameArg, opts = {}) {
     }
   }
   const template = resolved.label;
-  const source = mp.metadata?.pluginRoot ? name : `./${path7.relative(root, destDir).split(path7.sep).join("/")}`;
+  const source = `./${path7.relative(root, destDir).split(path7.sep).join("/")}`;
   mp.plugins.push({ name, source, description, version: "0.1.0" });
   writeMarketplace(root, mp);
   await syncCommand(root, { quiet: true });
@@ -611,6 +816,7 @@ function cancel2() {
 
 // src/commands/bump.ts
 import { execFileSync as execFileSync2 } from "child_process";
+import fs7 from "fs";
 import path8 from "path";
 import * as p4 from "@clack/prompts";
 import pc3 from "picocolors";
@@ -656,7 +862,8 @@ function analyzeCommits(root, pluginDir, since) {
     return { level: void 0, commits: 0, reasons: ["not a git repository"] };
   }
   const commits = raw.split("").map((c) => c.trim()).filter(Boolean);
-  if (commits.length === 0) return { level: void 0, commits: 0, reasons: [] };
+  if (commits.length === 0)
+    return { level: void 0, commits: 0, reasons: [] };
   let level = "patch";
   const reasons = [];
   for (const c of commits) {
@@ -678,7 +885,9 @@ function analyzeCommits(root, pluginDir, since) {
 async function bumpCommand(startDir, pluginName, levelArg, opts = {}) {
   const root = findMarketplaceRoot(startDir);
   if (!root) {
-    p4.log.error("No .claude-plugin/marketplace.json found. Run `agkit init` first.");
+    p4.log.error(
+      "No .claude-plugin/marketplace.json found. Run `agkit init` first."
+    );
     process.exitCode = 1;
     return;
   }
@@ -707,20 +916,24 @@ async function bumpCommand(startDir, pluginName, levelArg, opts = {}) {
   }
   const local = locals.find((l) => (l.manifest.name || l.dirName) === name);
   if (!local) {
-    p4.log.error(`No local plugin named "${name}". Known: ${locals.map((l) => l.manifest.name || l.dirName).join(", ")}`);
+    p4.log.error(
+      `No local plugin named "${name}". Known: ${locals.map((l) => l.manifest.name || l.dirName).join(", ")}`
+    );
     process.exitCode = 1;
     return;
   }
   if (levelArg && !["major", "minor", "patch", "auto"].includes(levelArg)) {
-    p4.log.error(`Invalid level "${levelArg}". Use major, minor, patch, or auto.`);
+    p4.log.error(
+      `Invalid level "${levelArg}". Use major, minor, patch, or auto.`
+    );
     process.exitCode = 1;
     return;
   }
   const current = local.manifest.version ?? "0.1.0";
+  const sinceTag = lastReleaseTag(root, name);
+  const analysis = analyzeCommits(root, local.dir, sinceTag);
   let level;
   if (!levelArg || levelArg === "auto") {
-    const sinceTag = lastReleaseTag(root, name);
-    const analysis = analyzeCommits(root, local.dir, sinceTag);
     if (!analysis.level) {
       p4.log.info(
         `No commits touching ${path8.relative(root, local.dir)}${sinceTag ? ` since ${sinceTag}` : ""} \u2014 nothing to bump.`
@@ -738,14 +951,32 @@ async function bumpCommand(startDir, pluginName, levelArg, opts = {}) {
   }
   const next = incrementSemver(current, level);
   const tagName = `${name}@${next}`;
+  const subjects = analysis.commits > 0 ? analysis.reasons.map((r) => r.replace(/^(?:major|minor|patch)\s+/, "")) : [];
   if (opts.dryRun) {
-    p4.log.info(`[dry-run] ${name}: ${current} -> ${pc3.green(next)} (${level})${opts.tag ? ` + tag ${tagName}` : ""}`);
+    p4.log.info(
+      `[dry-run] ${name}: ${current} -> ${pc3.green(next)} (${level})${opts.tag ? ` + tag ${tagName}` : ""} + CHANGELOG.md entry`
+    );
     return;
   }
-  const manifestPath = path8.join(local.dir, MARKETPLACE_DIR, PLUGIN_MANIFEST_FILE);
+  const manifestPath = path8.join(
+    local.dir,
+    MARKETPLACE_DIR,
+    PLUGIN_MANIFEST_FILE
+  );
   const manifest = readJson(manifestPath);
   manifest.version = next;
   writeJson(manifestPath, manifest);
+  const changelogPath = path8.join(local.dir, "CHANGELOG.md");
+  const existingChangelog = fs7.existsSync(changelogPath) ? fs7.readFileSync(changelogPath, "utf8") : void 0;
+  const entry = renderChangelogEntry(
+    next,
+    subjects,
+    (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+  );
+  fs7.writeFileSync(
+    changelogPath,
+    prependChangelogEntry(existingChangelog, entry)
+  );
   await syncCommand(root, { quiet: true });
   p4.log.success(`${name}: ${current} -> ${pc3.green(next)} (${level})`);
   if (opts.tag) {
@@ -753,17 +984,23 @@ async function bumpCommand(startDir, pluginName, levelArg, opts = {}) {
       git(root, ["add", "-A"]);
       git(root, ["commit", "-m", `chore(release): ${tagName}`]);
       git(root, ["tag", tagName]);
-      p4.log.success(`Committed and tagged ${pc3.cyan(tagName)} \u2014 push with: git push --follow-tags`);
+      p4.log.success(
+        `Committed and tagged ${pc3.cyan(tagName)} \u2014 push with: git push --follow-tags`
+      );
     } catch (err) {
-      p4.log.warn(`Version bumped but commit/tag failed: ${err.message}`);
+      p4.log.warn(
+        `Version bumped but commit/tag failed: ${err.message}`
+      );
     }
   } else {
-    p4.log.info("Commit the change, then push. Use --tag to commit and tag in one step.");
+    p4.log.info(
+      "Commit the change, then push. Use --tag to commit and tag in one step."
+    );
   }
 }
 
 // src/commands/init.ts
-import fs8 from "fs";
+import fs9 from "fs";
 import path10 from "path";
 import * as p5 from "@clack/prompts";
 import pc4 from "picocolors";
@@ -774,7 +1011,10 @@ var claudeCode = {
   label: "Claude Code",
   tier: 1,
   install: (arg, name) => ({
-    lines: [`/plugin marketplace add ${arg}`, `/plugin install <plugin-name>@${name}`]
+    lines: [
+      `/plugin marketplace add ${arg}`,
+      `/plugin install <plugin-name>@${name}`
+    ]
   }),
   teamSettings: { path: ".claude/settings.json" }
 };
@@ -805,7 +1045,9 @@ var cursor = {
   label: "Cursor",
   tier: 2,
   install: () => ({
-    lines: ["# add the marketplace in Cursor, then: /plugin install <plugin-name>"],
+    lines: [
+      "# add the marketplace in Cursor, then: /plugin install <plugin-name>"
+    ],
     note: "Requires a committed Cursor registry (.cursor-plugin/). Generate it with `agkit build --target cursor` (planned)."
   })
 };
@@ -911,6 +1153,12 @@ The catalog lives in \`.claude-plugin/marketplace.json\`; each plugin lives unde
 
 Target agents: ${labels}.
 
+## Plugins
+
+${PLUGINS_START}
+${renderAgentsPluginList([])}
+${PLUGINS_END}
+
 ## For agents working in this repo
 
 - Plugins are self-contained under \`plugins/<name>/\` with a \`.claude-plugin/plugin.json\` manifest and \`skills/\`, \`commands/\`, \`agents/\`, \`hooks/\` as needed.
@@ -921,7 +1169,7 @@ Target agents: ${labels}.
 
 // src/lib/git.ts
 import { execFileSync as execFileSync3 } from "child_process";
-import fs7 from "fs";
+import fs8 from "fs";
 import path9 from "path";
 function isGitAvailable() {
   try {
@@ -932,7 +1180,16 @@ function isGitAvailable() {
   }
 }
 function isGitRepo(dir) {
-  return fs7.existsSync(path9.join(dir, ".git"));
+  return fs8.existsSync(path9.join(dir, ".git"));
+}
+function isInsideGitRepo(dir) {
+  let d = path9.resolve(dir);
+  for (; ; ) {
+    if (fs8.existsSync(path9.join(d, ".git"))) return true;
+    const parent = path9.dirname(d);
+    if (parent === d) return false;
+    d = parent;
+  }
 }
 function gitInit(dir) {
   execFileSync3("git", ["init", "--initial-branch=main"], {
@@ -954,7 +1211,9 @@ function parseRemoteUrl(raw) {
   let host;
   let repoPath;
   const scp = raw.match(/^(?:[\w.-]+)@([\w.-]+):(.+?)(?:\.git)?\/?$/);
-  const url = raw.match(/^(?:https?|ssh|git):\/\/(?:[\w.-]+@)?([\w.-]+(?::\d+)?)\/(.+?)(?:\.git)?\/?$/);
+  const url = raw.match(
+    /^(?:https?|ssh|git):\/\/(?:[\w.-]+@)?([\w.-]+(?::\d+)?)\/(.+?)(?:\.git)?\/?$/
+  );
   if (scp) {
     host = scp[1];
     repoPath = scp[2];
@@ -976,6 +1235,9 @@ function parseRemoteUrl(raw) {
 }
 
 // src/commands/init.ts
+function titleCase2(kebab) {
+  return kebab.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
 function validateName(name) {
   if (!KEBAB_CASE_RE.test(name)) {
     return "Name must be kebab-case (lowercase letters, digits, hyphens)";
@@ -986,22 +1248,151 @@ function validateName(name) {
   return void 0;
 }
 function marketplaceTpl(file) {
-  return fs8.readFileSync(path10.join(templatesDir(), "marketplace", file), "utf8");
+  return fs9.readFileSync(
+    path10.join(templatesDir(), "marketplace", file),
+    "utf8"
+  );
 }
 function addArgument(remote) {
   if (!remote) return "<git-url-or-owner/repo>";
   return remote.isGitHub && remote.slug ? remote.slug : remote.httpsUrl;
 }
 function teamSource(remote) {
-  const source = remote?.isGitHub && remote.slug ? { source: "github", repo: remote.slug } : { source: "url", url: remote?.httpsUrl ?? "https://<git-host>/<owner>/<repo>.git" };
-  return JSON.stringify(source, null, 2).split("\n").map((line, i) => i === 0 ? line : "      " + line).join("\n");
+  const source = remote?.isGitHub && remote.slug ? { source: "github", repo: remote.slug } : {
+    source: "url",
+    url: remote?.httpsUrl ?? "https://<git-host>/<owner>/<repo>.git"
+  };
+  return JSON.stringify(source, null, 2).split("\n").map((line, i) => i === 0 ? line : `      ${line}`).join("\n");
+}
+async function initPlugin(targetDir, templateSpec, opts) {
+  p5.intro(pc4.bgCyan(pc4.black("  agkit init --plugin  ")));
+  const defaultName = path10.basename(targetDir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  let spec = typeof templateSpec === "string" ? templateSpec : void 0;
+  if (!spec) {
+    if (opts.yes) {
+      spec = "skill";
+    } else {
+      const answer = await p5.select({
+        message: "Plugin template",
+        options: PLUGIN_TEMPLATES.map((t) => ({
+          value: t,
+          label: t,
+          hint: TEMPLATE_DESCRIPTIONS[t]
+        }))
+      });
+      if (p5.isCancel(answer)) return cancel5();
+      spec = answer;
+    }
+  }
+  let name = opts.name;
+  if (!name && !opts.yes) {
+    const answer = await p5.text({
+      message: "Plugin name (kebab-case)",
+      initialValue: defaultName,
+      validate: (v) => KEBAB_CASE_RE.test(v) ? void 0 : "Must be kebab-case (lowercase, digits, hyphens)"
+    });
+    if (p5.isCancel(answer)) return cancel5();
+    name = answer;
+  }
+  name = name || defaultName;
+  if (!KEBAB_CASE_RE.test(name)) {
+    p5.log.error(`Plugin name "${name}" must be kebab-case.`);
+    process.exitCode = 1;
+    return;
+  }
+  let description = opts.description;
+  if (description === void 0 && !opts.yes) {
+    const answer = await p5.text({
+      message: "One-line description",
+      defaultValue: "",
+      placeholder: `What does ${name} do?`
+    });
+    if (p5.isCancel(answer)) return cancel5();
+    description = answer;
+  }
+  description = description || `TODO: describe what ${name} does.`;
+  const manifestPath = path10.join(targetDir, ".claude-plugin", "plugin.json");
+  if (fs9.existsSync(manifestPath)) {
+    p5.log.error(`A plugin already exists here: ${manifestPath}`);
+    process.exitCode = 1;
+    return;
+  }
+  const s = p5.spinner();
+  s.start("Scaffolding plugin");
+  fs9.mkdirSync(targetDir, { recursive: true });
+  const vars = {
+    pluginName: name,
+    pluginTitle: titleCase2(name),
+    description,
+    authorName: opts.owner || "Unknown"
+  };
+  let resolved;
+  try {
+    resolved = resolveTemplate(spec);
+  } catch (err) {
+    s.stop("Scaffolding failed");
+    p5.log.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    copyTemplateDir(resolved.dir, targetDir, vars);
+  } finally {
+    if (resolved.cleanup)
+      fs9.rmSync(resolved.cleanup, { recursive: true, force: true });
+  }
+  if (!resolved.builtin && fs9.existsSync(manifestPath)) {
+    try {
+      const manifest = readJson(manifestPath);
+      manifest.name = name;
+      if (opts.description) manifest.description = description;
+      writeJson(manifestPath, manifest);
+    } catch {
+      p5.log.warn("Template plugin.json could not be parsed; left as-is.");
+    }
+  }
+  const standalone = !isInsideGitRepo(targetDir);
+  if (standalone) {
+    const gitignore = path10.join(targetDir, ".gitignore");
+    if (!fs9.existsSync(gitignore)) {
+      fs9.writeFileSync(
+        gitignore,
+        ["node_modules/", ".DS_Store", "*.log", ""].join("\n")
+      );
+    }
+    if (isGitAvailable()) {
+      try {
+        gitInit(targetDir);
+      } catch {
+        p5.log.warn("git init failed; initialize the repository manually.");
+      }
+    }
+  }
+  s.stop("Plugin scaffolded");
+  const rel = path10.relative(process.cwd(), targetDir) || ".";
+  p5.note(
+    [
+      `Standalone plugin "${name}" (${resolved.label}) \u2014 no marketplace was created.`,
+      "",
+      "Distribute it either way:",
+      "  \u2022 Push this folder to its own git repo, then reference it from a",
+      `    marketplace:  agkit add <owner/repo> ${name}`,
+      "  \u2022 Or drop it into an existing marketplace's plugins/ and run:",
+      "    agkit sync"
+    ].join("\n"),
+    `Next steps  (cd ${rel})`
+  );
+  p5.outro("Done \u2714");
 }
 async function initCommand(dirArg, opts) {
-  p5.intro(pc4.bgCyan(pc4.black("  agkit init  ")));
   const targetDir = path10.resolve(dirArg ?? ".");
+  if (opts.plugin) {
+    return initPlugin(targetDir, opts.plugin, opts);
+  }
+  p5.intro(pc4.bgCyan(pc4.black("  agkit init  ")));
   const defaultName = path10.basename(targetDir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   const gitAvailable = isGitAvailable();
-  const existingRemote = gitAvailable && fs8.existsSync(targetDir) ? getOriginUrl(targetDir) : void 0;
+  const existingRemote = gitAvailable && fs9.existsSync(targetDir) ? getOriginUrl(targetDir) : void 0;
   let name = opts.name;
   let owner = opts.owner;
   let email = opts.email;
@@ -1091,7 +1482,9 @@ async function initCommand(dirArg, opts) {
   }
   owner = owner || "Unknown Owner";
   ci = ci ?? "github";
-  const { ids: agentIds, unknown } = parseAgentList(agentsRaw ?? DEFAULT_AGENTS.join(","));
+  const { ids: agentIds, unknown } = parseAgentList(
+    agentsRaw ?? DEFAULT_AGENTS.join(",")
+  );
   if (unknown.length > 0) {
     p5.log.warn(
       `Unknown agent(s) ignored: ${unknown.join(", ")}. Known: ${AGENT_ADAPTERS.map((a) => a.id).join(", ")}.`
@@ -1100,11 +1493,13 @@ async function initCommand(dirArg, opts) {
   const targets = agentIds.length > 0 ? agentIds : [...DEFAULT_AGENTS];
   const remote = repoUrl ? parseRemoteUrl(repoUrl) : void 0;
   if (repoUrl && !remote) {
-    p5.log.warn(`Could not parse remote URL "${repoUrl}"; install instructions will use placeholders.`);
+    p5.log.warn(
+      `Could not parse remote URL "${repoUrl}"; install instructions will use placeholders.`
+    );
   }
   const s = p5.spinner();
   s.start("Scaffolding marketplace");
-  fs8.mkdirSync(targetDir, { recursive: true });
+  fs9.mkdirSync(targetDir, { recursive: true });
   const marketplace = {
     $schema: MARKETPLACE_SCHEMA_URL,
     name,
@@ -1117,9 +1512,12 @@ async function initCommand(dirArg, opts) {
     },
     plugins: []
   };
-  writeJson(path10.join(targetDir, ".claude-plugin", "marketplace.json"), marketplace);
-  fs8.mkdirSync(path10.join(targetDir, "plugins"), { recursive: true });
-  fs8.writeFileSync(path10.join(targetDir, "plugins", ".gitkeep"), "");
+  writeJson(
+    path10.join(targetDir, ".claude-plugin", "marketplace.json"),
+    marketplace
+  );
+  fs9.mkdirSync(path10.join(targetDir, "plugins"), { recursive: true });
+  fs9.writeFileSync(path10.join(targetDir, "plugins", ".gitkeep"), "");
   const desc = description || "A curated collection of agent plugins.";
   const mktArg = addArgument(remote);
   const teamBlock = teamSource(remote);
@@ -1131,34 +1529,34 @@ async function initCommand(dirArg, opts) {
     installSections: renderInstallSections(targets, mktArg, name),
     teamSections: renderTeamSections(targets, teamBlock, name)
   };
-  fs8.writeFileSync(
+  fs9.writeFileSync(
     path10.join(targetDir, "README.md"),
     renderTemplate(marketplaceTpl("README.md.tpl"), vars)
   );
-  fs8.writeFileSync(
+  fs9.writeFileSync(
     path10.join(targetDir, "AGENTS.md"),
     renderAgentsMd(name, desc, targets)
   );
   const exampleDir = path10.join(targetDir, "examples");
-  fs8.mkdirSync(exampleDir, { recursive: true });
-  fs8.writeFileSync(
+  fs9.mkdirSync(exampleDir, { recursive: true });
+  fs9.writeFileSync(
     path10.join(exampleDir, "team-settings.json"),
     renderTemplate(marketplaceTpl("team-settings.json.tpl"), vars)
   );
   if (ci === "github") {
     const wfDir = path10.join(targetDir, ".github", "workflows");
-    fs8.mkdirSync(wfDir, { recursive: true });
-    fs8.writeFileSync(
+    fs9.mkdirSync(wfDir, { recursive: true });
+    fs9.writeFileSync(
       path10.join(wfDir, "validate.yml"),
       renderTemplate(marketplaceTpl("github-validate.yml.tpl"), vars)
     );
   } else if (ci === "gitlab") {
-    fs8.writeFileSync(
+    fs9.writeFileSync(
       path10.join(targetDir, ".gitlab-ci.yml"),
       renderTemplate(marketplaceTpl("gitlab-ci.yml.tpl"), vars)
     );
   }
-  fs8.writeFileSync(
+  fs9.writeFileSync(
     path10.join(targetDir, ".gitignore"),
     ["node_modules/", ".DS_Store", "*.log", ""].join("\n")
   );
@@ -1229,14 +1627,16 @@ async function listCommand() {
 
 // src/commands/validate.ts
 import { execFileSync as execFileSync4 } from "child_process";
-import fs9 from "fs";
+import fs10 from "fs";
 import path11 from "path";
 import * as p7 from "@clack/prompts";
 import pc6 from "picocolors";
 async function validateCommand(startDir, opts = {}) {
   const root = findMarketplaceRoot(startDir);
   if (!root) {
-    p7.log.error("No .claude-plugin/marketplace.json found. Run `agkit init` first.");
+    p7.log.error(
+      "No .claude-plugin/marketplace.json found. Run `agkit init` first."
+    );
     process.exitCode = 1;
     return;
   }
@@ -1252,7 +1652,10 @@ async function validateCommand(startDir, opts = {}) {
   }
   if (mp) {
     if (!mp.name) {
-      findings.push({ level: "error", message: "Missing required field: name" });
+      findings.push({
+        level: "error",
+        message: "Missing required field: name"
+      });
     } else {
       if (!KEBAB_CASE_RE.test(mp.name)) {
         findings.push({
@@ -1268,7 +1671,10 @@ async function validateCommand(startDir, opts = {}) {
       }
     }
     if (!mp.owner?.name) {
-      findings.push({ level: "error", message: "Missing required field: owner.name" });
+      findings.push({
+        level: "error",
+        message: "Missing required field: owner.name"
+      });
     }
     if (!Array.isArray(mp.plugins)) {
       findings.push({ level: "error", message: "plugins must be an array" });
@@ -1277,7 +1683,10 @@ async function validateCommand(startDir, opts = {}) {
     for (const entry of mp.plugins ?? []) {
       const label = entry.name ?? "<unnamed>";
       if (!entry.name) {
-        findings.push({ level: "error", message: "A plugin entry is missing its name" });
+        findings.push({
+          level: "error",
+          message: "A plugin entry is missing its name"
+        });
         continue;
       }
       if (!KEBAB_CASE_RE.test(entry.name)) {
@@ -1287,30 +1696,42 @@ async function validateCommand(startDir, opts = {}) {
         });
       }
       if (seen.has(entry.name)) {
-        findings.push({ level: "error", message: `Duplicate plugin name "${label}"` });
+        findings.push({
+          level: "error",
+          message: `Duplicate plugin name "${label}"`
+        });
       }
       seen.add(entry.name);
       if (entry.source === void 0) {
-        findings.push({ level: "error", message: `Plugin "${label}" is missing source` });
+        findings.push({
+          level: "error",
+          message: `Plugin "${label}" is missing source`
+        });
         continue;
       }
       const localDir = resolveLocalPluginDir(root, mp, entry);
       if (localDir) {
-        if (!fs9.existsSync(localDir)) {
+        if (!fs10.existsSync(localDir)) {
           findings.push({
             level: "error",
             message: `Plugin "${label}" source resolves to missing directory ${path11.relative(root, localDir)}`
           });
         } else {
-          const manifestPath = path11.join(localDir, MARKETPLACE_DIR, PLUGIN_MANIFEST_FILE);
-          if (!fs9.existsSync(manifestPath)) {
+          const manifestPath = path11.join(
+            localDir,
+            MARKETPLACE_DIR,
+            PLUGIN_MANIFEST_FILE
+          );
+          if (!fs10.existsSync(manifestPath)) {
             findings.push({
               level: "error",
               message: `Plugin "${label}" has no ${MARKETPLACE_DIR}/${PLUGIN_MANIFEST_FILE}`
             });
           } else {
             try {
-              const manifest = JSON.parse(fs9.readFileSync(manifestPath, "utf8"));
+              const manifest = JSON.parse(
+                fs10.readFileSync(manifestPath, "utf8")
+              );
               if (manifest.name && manifest.name !== entry.name) {
                 findings.push({
                   level: "warn",
@@ -1333,7 +1754,9 @@ async function validateCommand(startDir, opts = {}) {
         }
       }
     }
-    const hasRelative = (mp.plugins ?? []).some((e) => typeof e.source === "string");
+    const hasRelative = (mp.plugins ?? []).some(
+      (e) => typeof e.source === "string"
+    );
     if (hasRelative) {
       p7.log.info(
         "Note: relative plugin sources resolve only when the marketplace is added via Git (any forge), not via a direct URL to marketplace.json."
@@ -1341,7 +1764,9 @@ async function validateCommand(startDir, opts = {}) {
     }
   }
   if (mp?.metadata?.targets) {
-    const needBuild = mp.metadata.targets.filter((id) => (getAdapter(id)?.tier ?? 1) > 1);
+    const needBuild = mp.metadata.targets.filter(
+      (id) => (getAdapter(id)?.tier ?? 1) > 1
+    );
     if (needBuild.length > 0) {
       p7.log.info(
         `metadata.targets includes tier 2/3 agent(s): ${needBuild.join(", ")}. The Claude catalog validates here; run \`agkit build\` to (re)generate their registries and \`agkit build --check\` in CI.`
@@ -1350,7 +1775,11 @@ async function validateCommand(startDir, opts = {}) {
   }
   let officialRan = false;
   try {
-    execFileSync4("claude", ["plugin", "validate", root, ...opts.strict ? ["--strict"] : []], { stdio: "pipe" });
+    execFileSync4(
+      "claude",
+      ["plugin", "validate", root, ...opts.strict ? ["--strict"] : []],
+      { stdio: "pipe" }
+    );
     officialRan = true;
     p7.log.success("claude plugin validate: passed");
   } catch (err) {
@@ -1364,7 +1793,8 @@ async function validateCommand(startDir, opts = {}) {
       const out = [e.stdout?.toString(), e.stderr?.toString()].filter(Boolean).join("\n").trim();
       findings.push({
         level: "error",
-        message: `claude plugin validate failed${out ? ":\n" + out : ""}`
+        message: `claude plugin validate failed${out ? `:
+${out}` : ""}`
       });
     }
   }
@@ -1373,7 +1803,11 @@ async function validateCommand(startDir, opts = {}) {
   for (const f of warns) p7.log.warn(f.message);
   for (const f of errors) p7.log.error(f.message);
   if (errors.length > 0) {
-    p7.log.error(pc6.red(`Validation failed: ${errors.length} error(s), ${warns.length} warning(s).`));
+    p7.log.error(
+      pc6.red(
+        `Validation failed: ${errors.length} error(s), ${warns.length} warning(s).`
+      )
+    );
     process.exitCode = 1;
   } else {
     p7.log.success(
@@ -1392,26 +1826,78 @@ var program = new Command();
 program.name("agkit").description(
   "Scaffold and manage plugin marketplaces for Claude Code and GitHub Copilot, distributed via any Git host."
 ).version(version);
-program.command("init").argument("[dir]", "target directory (default: current directory)").description("Scaffold a new plugin marketplace (git-first)").option("-n, --name <name>", "marketplace name (kebab-case)").option("-o, --owner <owner>", "owner name").option("-e, --email <email>", "owner email").option("-d, --description <text>", "marketplace description").option("-r, --repo <url>", "git remote URL (any forge)").option("--ci <ci>", "CI workflow: github | gitlab | none").option("--agents <list>", "comma-separated target agents (e.g. claude-code,copilot,codex)").option("-y, --yes", "non-interactive, accept defaults").action(async (dir, opts) => {
+program.command("init").argument("[dir]", "target directory (default: current directory)").description(
+  "Scaffold a new plugin marketplace (git-first), or a standalone plugin with --plugin"
+).option(
+  "-n, --name <name>",
+  "marketplace (or plugin, with --plugin) name (kebab-case)"
+).option("-o, --owner <owner>", "owner / plugin author name").option("-e, --email <email>", "owner email").option(
+  "-d, --description <text>",
+  "marketplace (or plugin, with --plugin) description"
+).option("-r, --repo <url>", "git remote URL (any forge)").option("--ci <ci>", "CI workflow: github | gitlab | none").option(
+  "--agents <list>",
+  "comma-separated target agents (e.g. claude-code,copilot,codex)"
+).option(
+  "--plugin [template]",
+  "scaffold a standalone plugin (skill|command|agent|hook|mcp, or a template spec) in [dir] instead of a marketplace"
+).option("-y, --yes", "non-interactive, accept defaults").action(async (dir, opts) => {
   await initCommand(dir, opts);
 });
-program.command("add").argument("[template]", "template name, local path, gh:/gl: shorthand, or git URL (see `agkit list`)").argument("[name]", "plugin name (kebab-case)").description("Scaffold a plugin from a template and register it in the catalog").option("-d, --description <text>", "one-line plugin description").action(async (template, name, opts) => {
+program.command("add").argument(
+  "[template]",
+  "built-in template name, local path, or remote git source (owner/repo, gh:/gl: shorthand, git URL). Remote sources are referenced, not cloned (see --vendor)."
+).argument("[name]", "plugin name (kebab-case)").description(
+  "Register a plugin in the catalog: reference a remote git repo, or scaffold from a built-in/local template"
+).option("-d, --description <text>", "one-line plugin description").option(
+  "--vendor",
+  "clone the remote repo and scaffold from its files into the marketplace, instead of referencing it"
+).option("--ref <ref>", "branch or tag to pin a referenced remote source to").option(
+  "--sha <sha>",
+  "commit hash (40 hex) to pin a referenced remote source to"
+).action(async (template, name, opts) => {
   await addPlugin(process.cwd(), template, name, {
     description: opts.description,
-    interactive: opts.description === void 0
+    interactive: opts.description === void 0,
+    vendor: opts.vendor,
+    ref: opts.ref,
+    sha: opts.sha
   });
 });
 program.command("sync").description("Reconcile marketplace.json and README with the plugins on disk").action(async () => {
   await syncCommand(process.cwd());
 });
-program.command("validate").description("Validate the catalog (local checks + `claude plugin validate` if available)").option("--strict", "treat warnings as errors in the official validator").action(async (opts) => {
+program.command("validate").description(
+  "Validate the catalog (local checks + `claude plugin validate` if available)"
+).option("--strict", "treat warnings as errors in the official validator").action(async (opts) => {
   await validateCommand(process.cwd(), { strict: opts.strict });
 });
-program.command("bump").argument("[plugin]", "plugin name (prompted if omitted)").argument("[level]", "major | minor | patch | auto (default: auto, from conventional commits)").description("Bump a plugin version (conventional-commit aware) and sync the catalog").option("-t, --tag", "commit the bump and create a release tag <plugin>@<version>").option("--dry-run", "show what would change without writing").action(async (plugin, level, opts) => {
-  await bumpCommand(process.cwd(), plugin, level, { tag: opts.tag, dryRun: opts.dryRun });
+program.command("bump").argument("[plugin]", "plugin name (prompted if omitted)").argument(
+  "[level]",
+  "major | minor | patch | auto (default: auto, from conventional commits)"
+).description(
+  "Bump a plugin version (conventional-commit aware) and sync the catalog"
+).option(
+  "-t, --tag",
+  "commit the bump and create a release tag <plugin>@<version>"
+).option("--dry-run", "show what would change without writing").action(async (plugin, level, opts) => {
+  await bumpCommand(process.cwd(), plugin, level, {
+    tag: opts.tag,
+    dryRun: opts.dryRun
+  });
 });
-program.command("build").description("Generate tier-2 agent artifacts (codex, cursor) from the catalog").option("--target <list>", "comma-separated tier-2 targets (default: those in metadata.targets)").option("--check", "verify generated artifacts are up to date (CI); non-zero exit on drift").action(async (opts) => {
-  await buildCommand(process.cwd(), { targets: opts.target, check: opts.check });
+program.command("build").description(
+  "Generate tier-2 agent artifacts (codex, cursor) from the catalog"
+).option(
+  "--target <list>",
+  "comma-separated tier-2 targets (default: those in metadata.targets)"
+).option(
+  "--check",
+  "verify generated artifacts are up to date (CI); non-zero exit on drift"
+).action(async (opts) => {
+  await buildCommand(process.cwd(), {
+    targets: opts.target,
+    check: opts.check
+  });
 });
 program.command("list").description("List available plugin templates").action(async () => {
   await listCommand();