agkit 0.7.0 → 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fair3n
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,42 +1,105 @@
-# agkit
+<div align="center">
 
-> **AG**ent marketplace **KIT**
+# **AG**ent marketplace **KIT**
 
-Scaffold and manage **plugin marketplaces for Claude Code, GitHub Copilot, OpenAI Codex, and Cursor**, distributed through **any Git host** — GitHub, GitLab, Bitbucket, Gitea, or a self-hosted forge.
+**One canonical catalog → every AI coding agent → any Git forge.**
 
-Think `ng` for Angular, but for agent plugin marketplaces: `init` gives you a push-ready repository, and `add`/`build`/`sync`/`bump`/`validate` cover the whole life of the project afterwards.
+Scaffold and manage **plugin marketplaces for Claude Code · GitHub Copilot · OpenAI Codex · Cursor**,
+distributed through **any Git host** — GitHub, GitLab, Bitbucket, Gitea, or a self‑hosted forge.
 
+[![npm version](https://img.shields.io/npm/v/agkit?color=cb3837&logo=npm&label=agkit)](https://www.npmjs.com/package/agkit)
+[![npm downloads](https://img.shields.io/npm/dm/agkit?color=cb3837&logo=npm)](https://www.npmjs.com/package/agkit)
+[![CI](https://github.com/Fairen/agkit/actions/workflows/ci.yml/badge.svg)](https://github.com/Fairen/agkit/actions/workflows/ci.yml)
+[![Node.js](https://img.shields.io/node/v/agkit?color=339933&logo=node.js&logoColor=white)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+*`init` · `add` · `build` · `sync` · `bump` · `validate` · `list`*
+
+</div>
+
+> [!NOTE]
 > Unofficial community tool, not affiliated with Anthropic, GitHub, OpenAI, or Cursor.
 
-## How agents consume your marketplace
+Think **`ng` for Angular, but for agent plugin marketplaces**: `init` gives you a push‑ready repository, and `add` / `build` / `sync` / `bump` / `validate` cover the whole life of the project afterwards.
+
+---
+
+## ✨ Why agkit
+
+- 🧩 **Multi‑agent** — one repository serves Claude Code, GitHub Copilot, OpenAI Codex, and Cursor.
+- 🌐 **Forge‑agnostic** — distribute via GitHub, GitLab, Bitbucket, Gitea, or self‑hosted, with a plain `git push`.
+- 📁 **One source of truth** — a single canonical `.claude-plugin/marketplace.json`; generated registries derive from it and never drift.
+- 🔁 **Full lifecycle** — `init`, `add`, `build`, `sync`, `bump`, `validate`, `list`.
+- 🧬 **Remote & local templates** — pull plugin templates from any git repo (`gh:` / `gl:` / URL) or a local path.
+- ✅ **CI‑ready** — generated GitHub Actions / GitLab CI, with `validate` + `build --check` gates.
 
-agkit always writes one canonical catalog — `.claude-plugin/marketplace.json` — plus your plugins under `plugins/<name>/`. That catalog is the single source of truth. How each agent reads it falls into two groups:
+---
+
+## 📦 Installation
+
+Requires **Node.js ≥ 18**. Run it on demand with `npx` (nothing to install), or install the CLI globally:
+
+```bash
+npx agkit --help          # run without installing
+npm install -g agkit      # or install the `agkit` command globally
+```
 
-- **Native (no build step)** — **Claude Code** and **GitHub Copilot** read `.claude-plugin/marketplace.json` directly. Push the repo and it installs.
-- **Generated registry (`agkit build`)** — **Codex** and **Cursor** install from their own committed registry, which `agkit build` derives from the same canonical catalog. You run `agkit build` once to enable a target; after that `add`/`bump`/`sync` keep it fresh automatically.
+---
 
-You can target several agents from a single repository — the plugin content under `plugins/` is shared.
+## 🚀 Quick start
 
-## Quick start
+Create and distribute your first marketplace in **four steps**:
 
 ```bash
-npx agkit init my-marketplace
+npx agkit init my-marketplace   # 1. scaffold a push-ready repository
 cd my-marketplace
-agkit add skill tdd-coach
-agkit validate
+agkit add skill tdd-coach       # 2. add a plugin from a built-in template
+agkit validate                  # 3. check the catalog is valid
 git remote add origin <your-git-url>
-git add -A && git commit -m "feat: initial marketplace" && git push -u origin main
+git add -A && git commit -m "feat: initial marketplace" && git push -u origin main   # 4. distribute via git
 ```
 
-The default init targets Claude Code and GitHub Copilot (both native). To target Codex or Cursor, see below.
+That's the whole loop — once pushed, anyone can install your plugins straight from the repo (the per‑agent install command is in the **Create a marketplace for your agent** section below). `init` targets **Claude Code** and **GitHub Copilot** by default; add `--agents codex,cursor` to serve more.
+
+---
+
+## 🧩 How agents consume your marketplace
+
+agkit always writes **one canonical catalog** — `.claude-plugin/marketplace.json` — plus your plugins under `plugins/<name>/`. That catalog is the single source of truth. How each agent reads it falls into two groups:
+
+```mermaid
+flowchart TD
+    DEV["agkit init · add · bump · sync"] --> CAT[".claude-plugin/marketplace.json<br/>+ plugins/&lt;name&gt;<br/><b>— canonical catalog —</b>"]
+    CAT -->|read as-is, no build| NATIVE["🟢 Native<br/>Claude Code · GitHub Copilot"]
+    CAT -->|agkit build| GEN["⚙️ Generated registries<br/>OpenAI Codex · Cursor"]
+    NATIVE --> PUSH["git push → any forge"]
+    GEN --> PUSH
+    PUSH --> INSTALL["🎉 consumers install your plugins"]
+```
+
+- 🟢 **Native (no build step)** — **Claude Code** and **GitHub Copilot** read `.claude-plugin/marketplace.json` directly. Push the repo and it installs.
+- ⚙️ **Generated registry (`agkit build`)** — **Codex** and **Cursor** install from their own committed registry, which `agkit build` derives from the same canonical catalog. You run `agkit build` once to enable a target; after that `add` / `bump` / `sync` keep it fresh automatically.
+
+> [!TIP]
+> You can target several agents from a single repository — the plugin content under `plugins/` is shared across all of them.
+
+---
+
+## 🎯 Create a marketplace for your agent
 
-## Create a marketplace for your agent
+Choose targets at init with `--agents`. Every flow ends with a normal `git push`; distribution works from any forge.
 
-Choose targets at init with `--agents`. Every flow ends with a normal git push; distribution works from any forge.
+| Agent | Type | `agkit build`? | Consumers install with |
+| :---- | :--- | :------------: | :--------------------- |
+| **Claude Code** | 🟢 Native | — | `/plugin marketplace add …` |
+| **GitHub Copilot** | 🟢 Native | — | `copilot plugin marketplace add …` |
+| **OpenAI Codex** | ⚙️ Generated | ✅ | `codex plugin marketplace add …` |
+| **Cursor** | ⚙️ Generated | ✅ | add in Cursor, then install by name |
 
-### Claude Code
+<details open>
+<summary><b>🤖 Claude Code</b> — native, nothing to generate</summary>
 
-Native — nothing to generate.
+<br/>
 
 ```bash
 agkit init my-marketplace --agents claude-code
@@ -49,14 +112,19 @@ git add -A && git commit -m "feat: initial marketplace" && git push -u origin ma
 
 Consumers install in a Claude Code session:
 
-```
+```text
 /plugin marketplace add <owner/repo or git URL>
 /plugin install my-skill@my-marketplace
 ```
 
-### GitHub Copilot
+</details>
+
+<details>
+<summary><b>🐙 GitHub Copilot</b> — native, same repo as Claude Code, no build</summary>
+
+<br/>
 
-Native — same repository as Claude Code, no build. The default init already includes Copilot; to target it explicitly use `--agents copilot` (or `--agents claude-code,copilot`).
+The default init already includes Copilot; to target it explicitly use `--agents copilot` (or `--agents claude-code,copilot`).
 
 ```bash
 agkit init my-marketplace --agents claude-code,copilot
@@ -73,7 +141,12 @@ copilot plugin marketplace add <owner/repo or git URL>
 copilot plugin install my-skill@my-marketplace
 ```
 
-### OpenAI Codex
+</details>
+
+<details>
+<summary><b>🧠 OpenAI Codex</b> — installs from a generated registry</summary>
+
+<br/>
 
 Codex installs from its own registry, which `agkit build` generates from the catalog.
 
@@ -94,7 +167,12 @@ codex plugin marketplace add <owner/repo or git URL>
 
 The Codex registry format follows the official Codex plugin docs (`.agents/plugins/marketplace.json` with `source: { source: "local", path }`, `policy`, and `category`). Commit the generated files so consumers can install.
 
-### Cursor
+</details>
+
+<details>
+<summary><b>🖱️ Cursor</b> — installs from a generated registry</summary>
+
+<br/>
 
 Cursor installs from a committed `.cursor-plugin/` registry, also generated by `agkit build`.
 
@@ -109,9 +187,12 @@ git add -A && git commit -m "feat: initial marketplace" && git push -u origin ma
 
 Consumers add the marketplace in Cursor, then install the plugin by name.
 
-### Several agents at once
+</details>
+
+<details>
+<summary><b>🌈 Several agents at once</b> — one repository serves them all</summary>
 
-One repository can serve every supported agent:
+<br/>
 
 ```bash
 agkit init my-marketplace --agents claude-code,copilot,codex,cursor
@@ -122,19 +203,25 @@ agkit validate
 git add -A && git commit -m "feat: initial marketplace" && git push -u origin main
 ```
 
-## Commands
+</details>
+
+---
+
+## 🛠️ Commands
 
 | Command | What it does |
 | :------ | :----------- |
-| `agkit init [dir]` | Scaffolds a git-first marketplace: `.claude-plugin/marketplace.json` (with `$schema`, `pluginRoot`, `targets`), `plugins/`, `AGENTS.md`, a per-agent README, `examples/team-settings.json`, CI (GitHub Actions or GitLab CI), `.gitignore`, `git init`. Pick target agents with `--agents` (see [Target agents](#target-agents)). Non-interactive with `-y`. |
-| `agkit add <template\|spec> <name>` | Scaffolds a plugin from a built-in template (`skill`, `command`, `agent`, `hook`, `mcp`) **or a remote/local one** — `gh:owner/repo/dir#ref`, `gl:owner/repo`, any git URL with `//subdir` and `#ref`, or a local path. Registers it in the catalog and refreshes the README plugin table. |
+| `agkit init [dir]` | Scaffolds a git-first marketplace: `.claude-plugin/marketplace.json` (with `$schema`, `pluginRoot`, `targets`), `plugins/`, `AGENTS.md`, a per-agent README, `examples/team-settings.json`, CI (GitHub Actions or GitLab CI), `.gitignore`, `git init`. Pick target agents with `--agents` (see the **Target agents** section). Non-interactive with `-y`. |
+| `agkit add <template\|spec> <name>` | Scaffolds a plugin from a built-in template (`skill`, `command`, `agent`, `hook`, `mcp`) **or a remote/local one** — `gh:owner/repo/dir#ref`, `gl:owner/repo`, any git URL with `//subdir` and `#ref`, or a local path. Registers it in the catalog and refreshes the README table and `AGENTS.md`. |
 | `agkit build [--target] [--check]` | Generates the registries for **Codex** and **Cursor** from the catalog: their committed `marketplace.json` + per-plugin manifest mirrors. Default targets are the ones in `metadata.targets`; `--target codex,cursor` overrides. `--check` fails on drift (CI). |
-| `agkit bump [plugin] [level]` | Bumps a plugin version from conventional commits scoped to its directory since the last `<plugin>@x.y.z` tag (`feat`→minor, breaking→major, else patch), or an explicit `major\|minor\|patch`. `--tag` commits and tags; `--dry-run` previews. Catalog, README, and any built registries stay in sync. |
-| `agkit sync` | Reconciles the catalog with what's on disk. Source of truth: each plugin's `.claude-plugin/plugin.json`. Adds missing entries, fixes drift, flags orphans, regenerates the README table, and refreshes any already-built Codex/Cursor registry. |
+| `agkit bump [plugin] [level]` | Bumps a plugin version from conventional commits scoped to its directory since the last `<plugin>@x.y.z` tag (`feat`→minor, breaking→major, else patch), or an explicit `major\|minor\|patch`. Prepends a dated entry to `plugins/<name>/CHANGELOG.md` from those commits. `--tag` commits and tags; `--dry-run` previews. Catalog, README, `AGENTS.md`, and any built registries stay in sync. |
+| `agkit sync` | Reconciles the catalog with what's on disk. Source of truth: each plugin's `.claude-plugin/plugin.json`. Adds missing entries, fixes drift, flags orphans, regenerates the README table and the `AGENTS.md` plugin list, and refreshes any already-built Codex/Cursor registry. |
 | `agkit validate [--strict]` | Local checks (JSON validity, kebab-case, reserved names, source resolution, manifest presence, version drift) plus delegation to `claude plugin validate` when the Claude Code CLI is installed (`--strict` forwarded). Non-zero exit on error — CI-ready. |
 | `agkit list` | Lists available plugin templates. |
 
-## Target agents
+---
+
+## 🤖 Target agents
 
 `agkit init --agents <list>` records the agents you want to serve and adapts the scaffold. Default: `claude-code,copilot`.
 
@@ -145,11 +232,26 @@ git add -A && git commit -m "feat: initial marketplace" && git push -u origin ma
 
 Every init also writes a root `AGENTS.md`, read natively by most agents for repository context.
 
-## Keeping registries fresh
+---
+
+## 🔄 Keeping registries fresh
 
 Generation is opt-in: run `agkit build` once to enable Codex/Cursor. From then on, `agkit add`, `agkit bump`, and `agkit sync` refresh the generated registries automatically, so they never drift as plugins change. In CI, run `agkit build --check` to fail the build if a committed registry is out of date (the generated GitHub Actions / GitLab CI workflows already do this).
 
-## Team templates (remote or local)
+---
+
+## 📝 Generated documentation
+
+agkit maintains a small set of human-facing docs derived from the canonical catalog, so they never drift:
+
+- **README plugin table** and **`AGENTS.md` plugin list** — regenerated between `<!-- agkit:plugins:start -->` / `<!-- agkit:plugins:end -->` markers on every mutating command (`add`, `bump`, `sync`). The name links to a plugin's `homepage` when set, and a `Keywords` column appears when any plugin declares keywords. Drop the same markers into any Markdown file to have that list maintained there too.
+- **Per-plugin `CHANGELOG.md`** — `agkit bump` prepends a dated, newest-on-top entry built from the conventional commits it analyses, so each plugin carries its own release history (committed alongside the bump with `--tag`).
+
+Everything derives from `.claude-plugin/marketplace.json` and the per-plugin manifests — edit those (or run `agkit sync`) and the docs follow.
+
+---
+
+## 🧬 Team templates (remote or local)
 
 Version your team's plugin templates in any git repository and consume them from every marketplace:
 
@@ -161,14 +263,24 @@ agkit add ./shared-templates/hook-guard no-secrets
 
 A template is any directory containing `.claude-plugin/plugin.json` (adopted, `name` rewritten) or `plugin.json.tpl`. Files ending in `.tpl` are rendered with `{{pluginName}}`, `{{pluginTitle}}`, `{{description}}`, `{{authorName}}` — in contents **and** in file/directory names. Executable bits are preserved.
 
-## Forge-agnostic by design
+---
+
+## 🌐 Forge-agnostic by design
 
 `init` parses your git remote (https, ssh, scp-style) regardless of host. On github.com it uses the `owner/repo` shorthand and `{"source": "github"}` team settings; everywhere else it emits the git URL form — which every supported agent accepts for any forge.
 
-## Team setup (automatic installation)
+---
+
+## 👥 Team setup (automatic installation)
 
 `init` writes `examples/team-settings.json` with an `extraKnownMarketplaces` block. Drop it into the settings file for each agent so teammates get the marketplace automatically when they trust the repository — `.claude/settings.json` for Claude Code, `.github/copilot/settings.json` for GitHub Copilot.
 
-## License
+---
+
+## 📄 License
+
+[MIT](LICENSE) © fair3n
 
-MIT
+<div align="center">
+<sub>Built for the age of AI coding agents. Ship a marketplace, not a config.</sub>
+</div>

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;
@@ -123,7 +184,7 @@ function parseGitSpec(spec) {
   return void 0;
 }
 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 +194,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 +213,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 +330,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 +353,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 +390,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 +439,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 +513,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 +547,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 +577,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.");
@@ -576,7 +685,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 +700,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 +721,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 +767,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 +790,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 +821,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 +856,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 +889,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 +916,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 +950,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 +1058,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 +1074,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 +1085,7 @@ function isGitAvailable() {
   }
 }
 function isGitRepo(dir) {
-  return fs7.existsSync(path9.join(dir, ".git"));
+  return fs8.existsSync(path9.join(dir, ".git"));
 }
 function gitInit(dir) {
   execFileSync3("git", ["init", "--initial-branch=main"], {
@@ -954,7 +1107,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];
@@ -986,22 +1141,28 @@ 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 initCommand(dirArg, opts) {
   p5.intro(pc4.bgCyan(pc4.black("  agkit init  ")));
   const targetDir = path10.resolve(dirArg ?? ".");
   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 +1252,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 +1263,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 +1282,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 +1299,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 +1397,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 +1422,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 +1441,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 +1453,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 +1466,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 +1524,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 +1534,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 +1545,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 +1563,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 +1573,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,10 +1596,18 @@ 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)").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) => {
   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]",
+  "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) => {
   await addPlugin(process.cwd(), template, name, {
     description: opts.description,
     interactive: opts.description === void 0
@@ -1404,14 +1616,38 @@ program.command("add").argument("[template]", "template name, local path, gh:/gl
 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();

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "agkit",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Scaffold and manage plugin marketplaces for Claude Code and GitHub Copilot, distributed via any Git host (GitHub, GitLab, Bitbucket, Gitea, self-hosted). Init, add plugins from built-in or remote templates, sync, validate, bump.",
   "license": "MIT",
+  "author": "fair3n <fairen.dev@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Fairen/agkit.git"
+  },
+  "homepage": "https://github.com/Fairen/agkit#readme",
+  "bugs": "https://github.com/Fairen/agkit/issues",
   "type": "module",
   "bin": {
     "agkit": "./dist/index.js"
@@ -10,7 +17,8 @@
   "files": [
     "dist",
     "templates",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=18.0.0"
@@ -19,6 +27,11 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -39,8 +52,10 @@
     "picocolors": "^1.1.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.2",
     "@types/node": "^22.0.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.9"
   }
 }