@vibe-agent-toolkit/vat-development-agents 0.1.33-rc.3 → 0.1.34-rc.2

package/dist/.claude/plugins/marketplaces/vat-skills/CHANGELOG.md

@@ -8,6 +8,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **Skill-claude-plugin recognition in `vat audit`.** Introduces the **skill-claude-plugin** artifact shape — a skill that self-publishes as a Claude plugin by co-locating `.claude-plugin/plugin.json` alongside its root `SKILL.md`. Audit now emits independent `ValidationResult` entries for each surface (one `agent-skill`, one `claude-plugin`) instead of reporting only the plugin and silently ignoring the skill. The skill remains platform-agnostic; the graduation to skill-claude-plugin adds Claude-specific packaging only. See [`docs/architecture/skill-packaging.md`](docs/architecture/skill-packaging.md) for the full packaging-shape terminology (standalone skill / skill-claude-plugin / claude-plugin / claude-marketplace).
+- **`SKILL_CLAUDE_PLUGIN_NAME_MISMATCH`** validation code (default `warning`). Fires on the plugin result when a skill-claude-plugin's `plugin.json.name` disagrees with the co-located `SKILL.md` frontmatter `name`. The skill is authoritative; the plugin manifest is a distribution wrapper and should match unless the plugin is intentionally namespaced (in which case use `validation.severity` or `validation.allow`).
+- **Self-contained Claude Code plugin support in `vat claude plugin build`.**
+  Adopters can now bundle commands, hooks, agents, MCP servers, scripts, raw
+  plugin-local `SKILL.md` files, and author-supplied `plugin.json` metadata from a
+  per-plugin `plugins/<name>/` directory. The entire directory is tree-copied
+  verbatim (respecting `.gitignore`). Pre-existing pool-to-plugin skill selectors
+  (`marketplace.plugins[].skills`) are preserved — a plugin can still declare
+  `skills: "*"` or `skills: [names]` to import pool skills (built by
+  `vat skills build`) into its bundle. The skills stream is unchanged: `vat skills
+  build` continues to produce `dist/skills/<name>/` only. New schema fields on
+  marketplace plugin entries: `source` (path override, default `plugins/<name>`)
+  and `files[]` (compiled-artifact mappings). The 5-phase plugin build pipeline
+  is deterministically ordered (discovery → tree-copy → pool-skill import →
+  `files[]` → merged `plugin.json`). YAML summary adds `commandsCopied`,
+  `hooksCopied`, `agentsCopied`, `mcpCopied`, `treeFilesCopied`,
+  `explicitFilesCopied` per plugin. Case-sensitivity mismatches between declared
+  plugin names and on-disk dirs now fail the build to catch Linux-CI drift.
+
+### Changed
+- `vat audit` directory-entry detection uses a new `enumerateSurfaces()` helper that returns every manifest present at the directory root, replacing single-result detection in the multi-surface case. Single-surface directories retain their legacy single-validator dispatch, including the marketplace-with-co-located-plugin collapse.
+- `packages/cli/src/commands/audit/hierarchical-output.ts` comments standardized on the new terminology: the pattern previously documented as "standalone plugin skill (no skills subdir)" is now called **skill-claude-plugin**.
+- Upgraded `vibe-validate` and `@vibe-validate/cli` dev dependencies from `^0.19.1` to `^0.19.4`.
+
+### Documentation
+- New reference doc `docs/architecture/skill-packaging.md` enumerates the four packaging shapes with layouts and applicable validation.
+- `docs/README.md` gains a "Validation & Quality Framework" section indexing the three stance docs (`skill-quality-and-compatibility.md`, `validation-codes.md`, `skill-smell-philosophy.md`).
+- New `docs/CLAUDE.md` and `docs/architecture/CLAUDE.md` agent navigators pull in each directory's README via `@README.md` and add agent-only guidance for audit/validation work.
+- Root `/CLAUDE.md` "Questions?" section now links to directories rather than README files — child CLAUDE.md files auto-trigger and pull in their README once, avoiding the previous double-read pattern.
+- `packages/cli/CLAUDE.md` gains a "Validation Framework References" section.
+
+## [0.1.33] - 2026-04-21
+
+### Added
+- **Cross-platform ESM helpers in `@vibe-agent-toolkit/utils`.** Two new exports address Windows path footguns that can bite adopters once their code runs on Windows CI:
+  - `resolveFromImportMeta(importMetaUrl, ...segments)`: OS-native absolute path from a module's `import.meta.url` and optional relative segments. Use instead of `new URL(rel, import.meta.url).pathname`, which returns `/D:/...` on Windows and breaks `fs` operations.
+  - `dynamicImportPath<T>(absPath)`: wraps `await import(pathToFileURL(absPath).href)`. Use instead of `await import(absPath)` on an OS-native filesystem path — the bare form throws on Windows (ESM dynamic import requires a `file://` URL there).
+- **Two new local ESLint rules** (registered in `@vibe-agent-toolkit/dev-tools/eslint-local-rules` and wired as `error` in the root `eslint.config.js`):
+  - `local/no-url-pathname-for-fs`: flags `.pathname` access on `new URL(..., import.meta.url)`. Message points at the new `resolveFromImportMeta()` helper or `fileURLToPath()`.
+  - `local/no-bare-dynamic-import-path`: flags `await import(expr)` where `expr` is a computed filesystem path (absolute literal, `path.join/resolve` result, path-shaped identifier). Message points at the new `dynamicImportPath()` helper or `pathToFileURL(p).href`. Intentionally narrow heuristic with one documented false-positive escape hatch (suppress per-line with `eslint-disable-next-line local/no-bare-dynamic-import-path` when the identifier already holds a `file://` URL).
+  - RuleTester-based unit tests land alongside the rules via a shared harness (`packages/dev-tools/test/eslint-rule-test-harness.ts`). Adding a new local rule is now one row in `local-eslint-rules.test.ts`, not a new test file.
 - Three new skill-smell validation codes (all default `warning`, per skill-smell philosophy):
   - `SKILL_FRONTMATTER_EXTRA_FIELDS`: frontmatter contains keys beyond the standard agentskills.io + Claude Code set. Allowed keys derive from `AgentSkillFrontmatterSchema` at module load, so the rule tracks the schema. Actionable when adopters put project-specific fields (`version:`, `tools:`, `permissions:`) at top level — `metadata.*` is the right home for custom data.
   - `SKILL_CROSS_SKILL_AUTH_UNDECLARED`: body prose declares a sibling-skill or `ANTHROPIC_*_KEY` dependency (e.g., "Requires `vibe-agent-toolkit:vat-enterprise-org`", "Requires `ANTHROPIC_ADMIN_API_KEY`") but the description omits it. Narrow heuristic to keep false-positive rate low; bare `ANTHROPIC_API_KEY` (the universal Claude-API default) is explicitly excluded.
@@ -18,17 +59,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `actions/checkout` and `actions/setup-node` bumped from `@v4` to `@v6` across `.github/workflows/*.yml`. Runs on Node 24; removes the Sept-2026 deprecation warning on `v4` runners.
 
 ### Fixed
-- `packages/cli/test/system/audit-dogfooding.system.test.ts` test 1 (`should successfully audit vibe-agent-toolkit project root`) now runs on Windows. The `skipIf(process.platform === 'win32')` was added in 0.1.32 when the test timed out at 120s; the narrow `gitCheckIgnoredBatch` fallback fix that landed alongside it dropped audit wall time ~4x, so the smoke test fits in budget again. Windows CI will confirm.
+- **Windows path-normalization regression in `GitTracker.isIgnored()`.** The cache was populated at init with `safePath.resolve(projectRoot, relPath)` (which drive-prefixes on Windows, e.g. `C:/project/README.md`), but `isIgnored()` queried the cache with the raw caller-supplied path. Every lookup missed on Windows and fell through to spawn `git check-ignore`, triggering three `packages/utils/test/git-tracker.test.ts` performance-assertion failures on every Windows CI run since rc.2. Fix normalizes the lookup key to match population. Sibling methods `hasActiveDescendant` and `isIgnoredByActiveSet` already normalized correctly; `isIgnored` was the outlier. Added a POSIX-visible regression test using a non-canonical path (containing `..`) so the invariant is guarded against future changes that might reintroduce raw-path lookups.
+- **Windows infinite loop in `findConfigPath()` when scanning paths outside a VAT-configured project.** The root-detection used a hardcoded `/`, which never matches Windows drive roots (`C:\`, `D:\`), causing the walk-up loop to spin indefinitely. Fixed via `path.parse(dir).root` + `dirname()` with a `parent === currentDir` safety break so traversal halts at the filesystem root on every OS. Manifested as `vat audit` hangs on Windows whenever the scan target (or the caller's cwd for a `.` scan) had no `vibe-agent-toolkit.config.yaml` ancestor — common for temp-directory test fixtures and any audit run outside a project.
 - Stale JSDoc examples referencing `vibe-agent-toolkit:resources` (renamed to `vibe-agent-toolkit:vat-knowledge-resources` during the 0.1.32 plugin restructure) replaced with `vibe-agent-toolkit:vat-audit` in `packages/cli/src/commands/claude/plugin/build.ts`, `packages/cli/src/commands/skills/build.ts`, `packages/agent-schema/src/package-metadata.ts`, and the companion test constant.
+- **`duplication-check` now runs on Windows.** Previously it was skipped because `@jscpd/finder` calls `realpathSync()` on the input patterns, which on Windows fails when paths contain `..`/glob patterns and prevents the report from being generated (upstream issue [jscpd#143](https://github.com/kucherenko/jscpd/issues/143), unfixed since 2020). The fix ships as a Bun `patchedDependencies` entry at `patches/@jscpd%2Ffinder@4.0.4.patch` — Bun applies it automatically on `bun install`. The patch is a two-line removal of the `realpathSync()` call; jscpd doesn't depend on the resolved path for anything downstream. Cross-platform baseline portability is ensured by a companion change: `jscpd-check-new.ts` and `jscpd-update-baseline.ts` now normalize clone paths to forward slashes via `toForwardSlash()`, so a baseline captured on Linux/CI matches when `duplication-check` runs on Windows (where jscpd reports backslashes).
+- **`safeExecSync` / `safeExecResult` in `@vibe-agent-toolkit/utils` no longer silently fail on Windows under Node 24+.** When the resolved command was a shell wrapper (`.cmd`/`.bat`) — e.g. `npx.cmd`, `bunx.cmd`, `npm.cmd` — the previous code passed args through `shell:true` as a separate array, which Node 24 rejects with `EINVAL` per [DEP0190](https://nodejs.org/api/deprecations.html#DEP0190) whenever any arg contains a shell metacharacter (`*`, `?`, `(`, `)` …). Symptom: the spawned process would fail immediately and produce no output, leaving callers to misattribute the crash to the downstream tool. Fix joins the command and args into a single string when the shell path is needed, keeping `shell:false` + absolute-path spawning as the default for all non-wrapper commands (the secure path). Was the actual reason `bun run duplication-check` failed on Windows CI even after the jscpd patch landed.
+- **Windows `bun install` postinstall failures from `link-workspace-packages.ts`.** The postinstall script created workspace symlinks with `symlinkSync(target, link, 'dir')`, which requires the `SeCreateSymbolicLinkPrivilege` admin right on Windows and fails with `EPERM` in non-elevated shells. Fix uses directory **junctions** on Windows (`symlinkSync(absoluteTarget, link, 'junction')`) — junctions don't require elevation and are transparent to both Node's ESM resolver and Bun's workspace linking. POSIX platforms continue to use relative-path `'dir'` symlinks as before. Windows developers can now `bun install` in a standard (non-admin) shell.
 
 ### Performance
-- **Walker unification on `GitTracker`.** Every `vat audit` / `vat skills validate` / `vat verify` scan now shares one pre-populated `GitTracker` per repo. The tracker pre-loads the full active file set (tracked + untracked-not-ignored) via `git ls-files --cached --others --exclude-standard`, precomputes the ancestor directory set, and answers every ignore check from an in-memory `Set` instead of spawning `git check-ignore`. Per-directory `gitCheckIgnoredBatch` calls and per-link `isGitIgnored` calls are gone from the hot paths in `packages/cli/src/commands/audit.ts`, `packages/agent-skills/src/walk-link-graph.ts`, `packages/agent-skills/src/validators/packaging-validator.ts`, and `packages/discovery/src/scanners/local-scanner.ts`. The legacy `isGitIgnored` / `gitCheckIgnoredBatch` exports on `@vibe-agent-toolkit/utils` are preserved for one-off and cross-repo consumers.
+- **Walker unification on `GitTracker`.** Every `vat audit` / `vat skills validate` / `vat verify` scan now shares one pre-populated `GitTracker` per repo. The tracker pre-loads the full active file set (tracked + untracked-not-ignored) via `git ls-files --cached --others --exclude-standard`, precomputes the ancestor directory set, and answers every ignore check from an in-memory `Set` instead of spawning `git check-ignore`. Per-directory `gitCheckIgnoredBatch` calls and per-link `isGitIgnored` calls are gone from the hot paths in `packages/cli/src/commands/audit.ts`, `packages/agent-skills/src/walk-link-graph.ts`, `packages/agent-skills/src/validators/packaging-validator.ts`, and `packages/discovery/src/scanners/local-scanner.ts`. `@vibe-agent-toolkit/utils` **removes the `gitCheckIgnoredBatch` export** (no remaining in-tree or external callers); `isGitIgnored` is kept as the single-spawn fallback for code paths that don't have a tracker threaded in (e.g. one-off callers in `link-validator.ts` and `walk-link-graph.ts`).
 - **Shared `ResourceRegistry` across skills in `vat skills validate`.** When a single `vat skills validate` invocation covers multiple skills that share one project root, the command now builds one crawled/link-resolved `ResourceRegistry` once and reuses it for every skill's validation instead of re-parsing the same markdown per skill. Heterogeneous scans (mixed project roots) transparently fall back to per-skill registries.
 - **Measured wall-time (median of 3 runs on the VAT monorepo, M-series laptop):**
   - `vat audit .`: 6.85s → 2.50s (~2.7x, under the 3s target set in the rc.1 plan)
   - `vat verify --cwd packages/vat-development-agents`: 12.68s → 2.85s (~4.4x)
   - `vat skills validate packages/vat-development-agents`: 10.05s → 1.44s (~7x)
-- Pure perf — no behavior changes. YAML output diffs clean pre/post across all three commands except wall-time fields. New `GitTracker` APIs (`hasActiveDescendant`, `isIgnoredByActiveSet`) are non-breaking additions; `initialize()` accepts an options bag with `includeUntracked` defaulting to `true`.
+- No observable output changes for `vat audit` / `vat skills validate` / `vat verify` — YAML output diffs clean pre/post across all three commands except wall-time fields. One internal shift worth noting: `@vibe-agent-toolkit/discovery`'s `LocalScanner.scan()` now instantiates and eagerly `initialize()`s a `GitTracker` on every call so in-project gitignore checks are O(1); this adds a single `git ls-files` spawn per scan invocation (was effectively a no-op when only one file was scanned). New `GitTracker` APIs (`hasActiveDescendant`, `isIgnoredByActiveSet`) are non-breaking additions; `initialize()` accepts an options bag with `includeUntracked` defaulting to `true`.
+- **Final spawn sweep (post-rc.3).** Two independent spawn-eliminations that together recover the rc.2 baseline and beat it for single-config projects. (1) `vat audit` now caches `discoverSkillsFromConfig` by governing-config root, so per-skill walk-up resolution no longer re-expands the same config's globs N times for an N-skill package. (2) `packages/resources/src/link-validator.ts` switched both `gitTracker.isIgnored()` call sites (source + target) to `isIgnoredByActiveSet`, which answers O(1) against the pre-populated active set for in-project paths. Link validation fires per link and skills typically have dozens of links, so this was the largest remaining spawn source in the audit hot path. Post-fix medians (M-series Mac, 3 runs): VAT self `vat audit .` ~2.5s (recovered rc.2 baseline after rc.3's ~12% regression); vibe-validate `vat audit .` 0.96s → ~0.20s (~5x faster); avonrisk-sdlc `vat audit .` 5.43s → ~4.0s. Windows sees roughly 2x these wins since process-spawn overhead there is ~10x higher than on Linux.
 
 ## [0.1.32] - 2026-04-19
 

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "vibe-agent-toolkit",
-  "description": "Development agents and skills for building with vibe-agent-toolkit",
-  "version": "0.1.33-rc.3",
+  "version": "0.1.34-rc.2",
   "author": {
     "name": "vibe-agent-toolkit contributors"
-  }
+  },
+  "description": "Development agents and skills for building with vibe-agent-toolkit"
 }

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-adoption-and-configuration/SKILL.md

@@ -84,7 +84,6 @@ claude:
       plugins:
         - name: my-plugin
           description: "What this plugin does"
-          skills: "*"
 
 rag:
   stores:

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-skill-distribution/SKILL.md

@@ -182,15 +182,14 @@ claude:
       plugins:
         - name: my-plugin             # installable unit
           description: My plugin description
-          skills: "*"                  # all discovered skills
 ```
 
-The `skills:` section discovers SKILL.md files via include/exclude globs. The `claude:` section defines how skills are packaged into plugins. Each marketplace has `owner` and `plugins` fields (strict schema — no extra fields).
+The top-level `skills:` section drives standalone skill builds (output: `dist/skills/`). The `claude:` section defines plugins, which are assembled from their own `plugins/<name>/` directories (plugin-local skills under `plugins/<name>/skills/**/SKILL.md`). Each marketplace has `owner` and `plugins` fields (strict schema — no extra fields).
 
 **Naming convention:** marketplace = org identity (e.g. `acme`), plugin = this package
 (e.g. `acme-tools`). Registers as `my-plugin@my-marketplace` in Claude's plugin registry.
 
-### Multiple skills in one package
+### Multiple skills in one plugin
 
 List all skills in `vat.skills` for npm discoverability:
 
@@ -201,18 +200,16 @@ List all skills in `vat.skills` for npm discoverability:
 }
 ```
 
-Use a selector in the plugin config to include matching skills:
+Each skill lives as a subdirectory of the plugin under `plugins/<name>/skills/<skill>/SKILL.md`:
 
-```yaml
-plugins:
-  - name: my-plugin
-    description: Linting and testing skills
-    skills:
-      - "my-linting"
-      - "my-testing"
+```
+plugins/my-plugin/
+  skills/
+    my-linting/SKILL.md
+    my-testing/SKILL.md
 ```
 
-Or use `"*"` to include all discovered skills in the plugin.
+All plugin-local skills found under `plugins/<name>/skills/` are packaged into the plugin automatically — no per-plugin selector is needed or supported. Skill names must be globally unique across all plugins.
 
 ## Step 3: Build
 
@@ -264,7 +261,6 @@ claude:
       plugins:
         - name: my-plugin
           description: My plugin description
-          skills: "*"
       publish:
         github:
           repo: owner/repo          # GitHub repo to publish to
@@ -406,3 +402,13 @@ All `vat` commands in this skill work with these alternatives.
 ## Future: Zero-Dependency Postinstall (Option B)
 
 A planned improvement: `vat build` would bundle the plugin install logic into `dist/postinstall.js` — a fully self-contained script with no npm dependencies. The postinstall script would become simply `node ./dist/postinstall.js`. This eliminates `vibe-agent-toolkit` as a runtime dependency entirely, reducing install footprint for end users. Until then, Option C (runtime `vibe-agent-toolkit` dep) is the correct approach.
+
+## Full-plugin authoring (commands, hooks, agents, MCP)
+
+VAT supports bundling any Claude Code plugin asset — not just skills. Drop the plugin
+under `plugins/<name>/` in the same native layout Claude expects. VAT tree-copies
+everything (minus `skills/` and `.claude-plugin/`), merges author `plugin.json` with
+VAT-owned identity fields, and applies any `files[]` mappings for artifacts built
+outside the plugin dir.
+
+See [docs/guides/marketplace-distribution.md](resources/marketplace-distribution.md) section "Full-plugin authoring".

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-skill-distribution/resources/marketplace-distribution.md

@@ -0,0 +1,427 @@
+# Marketplace Distribution
+
+**Guide for building, validating, and publishing Claude plugin marketplaces.**
+
+## Overview
+
+A Claude plugin marketplace is a Git repository containing `.claude-plugin/marketplace.json` and plugin directories. Marketplaces are the distribution unit for Claude Code (via `/plugin marketplace add`) and Cowork (via GitHub App sync). VAT supports three modes of marketplace management.
+
+## Three Marketplace Modes
+
+| Mode | Description | VAT commands |
+|------|-------------|-------------|
+| **Built** | Source repo with skills → `vat build` → publish to `claude-marketplace` branch | `vat build`, `vat validate`, `vat claude marketplace publish` |
+| **Separate repo** | Source repo → `vat build` → publish to a different Git repo | Same as Built (remote configured in YAML) |
+| **Manual/native** | The repo IS the marketplace — no build step | `vat validate` (with config) or `vat claude marketplace validate` (without config) |
+
+## Distribution Surfaces
+
+Custom skills and plugins **do not sync across Claude surfaces**. Each surface is independent:
+
+| Surface | Source | Scope | Marketplace format? |
+|---------|--------|-------|---------------------|
+| **Claude Code** | Git repo with `marketplace.json` | Self-service install | Yes |
+| **Cowork (claude.ai)** | Admin UI → GitHub App sync from private repo | Org-wide, admin-controlled | Yes (same format) |
+| **Skills API** | `POST /v1/skills` multipart upload | Workspace-wide | No (direct API upload) |
+| **Claude Code (managed)** | `managed-settings.json` via MDM | Per-machine, IT-managed | Yes (marketplace ref in settings) |
+
+Public and private GitHub marketplaces use the **same format**. The only difference is authentication (private repos require `GITHUB_TOKEN` or `GH_TOKEN` for auto-updates).
+
+## Marketplace Structure
+
+```
+marketplace-repo/           # or claude-marketplace branch
+├── .claude-plugin/
+│   └── marketplace.json    # marketplace manifest (required)
+├── plugins/
+│   └── plugin-name/
+│       ├── .claude-plugin/
+│       │   └── plugin.json # plugin manifest (required)
+│       ├── skills/
+│       │   └── skill-name/
+│       │       ├── SKILL.md
+│       │       └── references/
+│       ├── commands/       # slash commands (*.md)
+│       ├── agents/         # agent definitions (*.md)
+│       └── hooks/          # hooks.json
+├── CHANGELOG.md            # marketplace changelog
+├── README.md               # marketplace "storefront" for GitHub
+└── LICENSE                  # required for distribution
+```
+
+## Versioning Strategy
+
+**Marketplace version is the distribution version.** One version for the whole marketplace.
+
+| Artifact | Versioned? | Required? | Source |
+|----------|-----------|-----------|--------|
+| Marketplace | Yes | Yes (error if missing) | `package.json` or config |
+| Plugin | Yes | Yes (error if missing) | Defaults to marketplace version |
+| Skill | No | N/A | Tracked by marketplace version |
+
+Skills are not independently versioned by VAT. The SKILL.md frontmatter spec has no version field. Skill changes are tracked at the marketplace level.
+
+Plugin version defaults to the marketplace version when not explicitly set. The top-level version defaults to `package.json` when available.
+
+## Branch Convention
+
+**Default publish branch: `claude-marketplace`** — analogous to GitHub Pages' `gh-pages`.
+
+- Source code and SDLC on `main` (tests, lint, CI, PRs)
+- Built marketplace artifacts on `claude-marketplace` (clean, generated)
+- Extensible: `claude-marketplace-beta`, `claude-marketplace-next` for staging channels
+- Configurable via `publish.branch` in config or `--branch` flag
+
+**Default-branch-only surfaces:** Both Cowork (claude.ai) and Claude Enterprise GitHub sync read from the repository's **default branch only** — they cannot target a specific branch. This means the branch-based publish pattern (`claude-marketplace` / `claude-marketplace-next`) does not work for these surfaces.
+
+**Workaround: dedicated marketplace repo.** Create a separate repository where the default branch (`main`) IS the marketplace. Configure `publish.remote` to point to this repo:
+
+```yaml
+publish:
+  remote: https://github.com/org/my-marketplace-repo.git
+  branch: main
+```
+
+This keeps your source code and SDLC on the original repo while the marketplace repo contains only the published artifacts.
+
+**Enterprise lockdown:** `managed-settings.json` supports `ref` on marketplace sources:
+
+```json
+{
+  "strictKnownMarketplaces": [
+    { "source": "github", "repo": "acme/plugins", "ref": "claude-marketplace" }
+  ]
+}
+```
+
+## Configuration
+
+In `vibe-agent-toolkit.config.yaml`:
+
+```yaml
+version: 1
+
+claude:
+  marketplaces:
+    my-marketplace:
+      owner:
+        name: Your Name or Org
+      publish:
+        branch: claude-marketplace          # default
+        remote: origin                      # git remote name, or full URL for cross-repo publish
+        changelog: docs/marketplace-changelog.md
+        readme: docs/marketplace-readme.md
+        license: mit                        # SPDX identifier or file path
+        sourceRepo: false                   # optional linkback in commit metadata
+      plugins:
+        - name: my-plugin
+          description: What this plugin does
+          skills: "*"                       # or list: ["skill-a", "skill-b"]
+```
+
+### License field
+
+The `license` field accepts:
+- **SPDX identifier string** (e.g., `mit`, `apache-2.0`, `gpl-3.0`) — generates standard license text with owner name and current year
+- **File path** (e.g., `./LICENSE` or `docs/LICENSE-ENTERPRISE`) — copies the file as-is
+
+Strings are validated against known SPDX identifiers. Paths are distinguished by containing `/` or `.` characters.
+
+## Changelog
+
+Each marketplace maintains its own `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/) format. The marketplace release cadence may differ from source package releases.
+
+- Author maintains the changelog source file in the repo (path configured in YAML)
+- On publish, it's copied to `CHANGELOG.md` in the published tree
+- The `[Unreleased]` section is required for publish — the command refuses if empty
+- On publish, `[Unreleased]` is stamped with version + date
+- The changelog delta becomes the Git commit message body
+
+Categories: `Added`, `Changed`, `Removed`, `Fixed`, `Security`.
+
+## Publish Flow
+
+```bash
+# 1. Build marketplace artifacts
+vat build
+
+# 2. Validate everything
+vat validate
+
+# 3. Publish to claude-marketplace branch
+vat claude marketplace publish
+
+# Or dry-run first
+vat claude marketplace publish --dry-run
+```
+
+**What publish does:**
+
+1. Verifies `vat build` output exists
+2. Checks marketplace changelog has `[Unreleased]` content
+3. Composes the publish tree (marketplace artifacts + CHANGELOG.md + README.md + LICENSE)
+4. Creates a single squashed commit: `publish v{version}` with changelog delta as body
+5. Pushes to the configured branch/remote
+
+**Flags:**
+- `--dry-run` — compose and show diff, don't push
+- `--branch <name>` — override configured branch
+- `--force` — force-push (first publish or recovery only)
+
+**Commit history:** Each publish adds one commit. The `claude-marketplace` branch accumulates a clean release timeline — `git log` shows the version history of the marketplace.
+
+## CI/CD: Cross-Repo Publishing
+
+When publishing to a **separate repository** (via `publish.remote`), the default `GITHUB_TOKEN` in GitHub Actions is scoped to the source repo and cannot push to the target. You need a Personal Access Token (PAT) or fine-grained token with write access to the marketplace repo.
+
+**Setup:**
+
+1. Create a PAT with `contents: write` permission on the marketplace repo
+2. Store it as a repository secret (e.g., `MARKETPLACE_GITHUB_PUSH_TOKEN`)
+3. Expose it as `GH_TOKEN` in your workflow — `vat claude marketplace publish` uses `GH_TOKEN` (or `GITHUB_TOKEN`) to authenticate pushes
+
+```yaml
+# .github/workflows/marketplace-publish.yml
+- name: Publish marketplace
+  env:
+    GH_TOKEN: ${{ secrets.MARKETPLACE_GITHUB_PUSH_TOKEN }}
+  run: |
+    vat build
+    vat claude marketplace publish --branch main
+```
+
+**Why a separate token?** GitHub Actions' built-in `GITHUB_TOKEN` has repo-scoped permissions and cannot push to other repositories. This is a standard pattern for any cross-repo CI operation.
+
+## Validation
+
+### With config (`vat validate`)
+
+When marketplace config exists, `vat validate` orchestrates in dependency order:
+
+1. `resources validate` — links, frontmatter, schemas
+2. `skills validate` — SKILL.md structure, frontmatter
+3. `marketplace validate` — marketplace.json, plugin.json, structure
+
+Each layer fails fast — bad links block skill validation, bad skills block marketplace validation.
+
+### Without config (`vat claude marketplace validate`)
+
+Standalone validation for manual/native marketplaces. Uses the same discovery logic as `vat audit` but with **strict expectations** — this must be a valid marketplace:
+
+| Check | `vat audit` (liberal) | `marketplace validate` (strict) |
+|-------|----------------------|--------------------------------|
+| Missing version | Warning | Error |
+| Missing LICENSE | Ignored | Error |
+| Bad plugin.json | Warning | Error |
+| Missing README | Ignored | Warning |
+| Missing CHANGELOG | Ignored | Warning |
+| Bad SKILL.md | Warning | Error |
+
+```bash
+# Validate a marketplace directory or repo
+vat claude marketplace validate .
+vat claude marketplace validate path/to/marketplace
+```
+
+## Examples
+
+### Built mode: monorepo publishes to same repo
+
+```yaml
+# vibe-agent-toolkit.config.yaml
+claude:
+  marketplaces:
+    vat-skills:
+      owner:
+        name: vibe-agent-toolkit contributors
+      publish:
+        changelog: docs/marketplace-changelog.md
+        readme: docs/marketplace-readme.md
+        license: mit
+      plugins:
+        - name: vibe-agent-toolkit
+          description: Development agents and skills
+          skills: "*"
+```
+
+```bash
+vat build && vat validate && vat claude marketplace publish
+```
+
+Consumers install via:
+```
+/plugin marketplace add owner/repo#claude-marketplace
+```
+
+### Separate repo: private source, public marketplace
+
+```yaml
+# vibe-agent-toolkit.config.yaml in private source repo
+claude:
+  marketplaces:
+    acme-skills:
+      owner:
+        name: Acme Corp
+      publish:
+        remote: git@github.com:acme/acme-skills-marketplace.git
+        changelog: docs/marketplace-changelog.md
+        readme: docs/marketplace-readme.md
+        license: apache-2.0
+      plugins:
+        - name: acme-tools
+          description: Acme engineering tools
+          skills: "*"
+```
+
+### Manual/native: repo IS the marketplace
+
+No `vat build`, no publish. Author maintains `marketplace.json` and plugin directories directly. Validate with:
+
+```bash
+# With vibe-agent-toolkit.config.yaml
+vat validate
+
+# Without config
+vat claude marketplace validate .
+```
+
+## Testing Your Marketplace
+
+After publishing, test the marketplace locally before sharing with users. This flow validates the full consumer experience — clone, install, and skill loading.
+
+### Test flow
+
+```bash
+# 1. Add the marketplace (uses the published branch)
+claude plugin marketplace add owner/repo#claude-marketplace
+
+# 2. Install the plugin from the marketplace
+claude plugin install my-plugin@my-marketplace
+
+# 3. Validate the installed plugin
+claude plugin validate ~/.claude/plugins/cache/my-marketplace/my-plugin/<version>
+
+# 4. List plugins and verify status
+claude plugin list
+
+# 5. Start a new Claude Code session — skills should appear in /skill-name
+```
+
+### What to verify
+
+- **Marketplace add** succeeds and `known_marketplaces.json` shows the correct source
+- **Plugin install** resolves the correct version from plugin.json
+- **All skills** are present in the cache directory
+- **`claude plugin validate`** passes on the installed plugin
+- **`claude plugin list`** shows the plugin as enabled
+- **Skills load** in a new session (check the system reminder for skill names)
+
+### Updating after changes
+
+After publishing a new version:
+
+```bash
+# Update the marketplace cache
+claude plugin marketplace update my-marketplace
+
+# Update the installed plugin
+claude plugin update my-plugin@my-marketplace
+```
+
+### Known issues
+
+**Name collision on marketplace add (Claude Code v2.1.81):** If a marketplace with the same `name` field already exists (e.g., previously registered via npm), `claude plugin marketplace add` reports success but silently reuses the old source in `known_marketplaces.json`. The workaround is to remove the old marketplace first, then add:
+
+```bash
+claude plugin marketplace remove my-marketplace
+claude plugin marketplace add owner/repo#branch
+```
+
+Verify by checking `~/.claude/plugins/known_marketplaces.json` to confirm the source switched to `github`.
+
+**`claude plugin validate` rejects `$schema` key (Claude Code v2.1.81):** The marketplace validator treats `$schema` as an unrecognized key, even though Anthropic's own official marketplace uses it. This does not affect runtime behavior — the marketplace installs and works correctly. This is a Claude Code validation bug, not a marketplace authoring issue.
+
+
+## Full-plugin authoring
+
+`vat claude plugin build` ships any Claude Code plugin asset — not just skills. Drop the plugin under `plugins/<name>/` in the same native layout Claude Code expects, declare it in `vibe-agent-toolkit.config.yaml`, and `vat claude plugin build` assembles the output from that plugin's own directory. Pool skills (from the top-level `skills:` discovery) are still imported into the plugin via the `skills:` selector — the plugin directory and the pool skills are both sources, composed into one bundle.
+
+### Layout
+
+```
+plugins/<name>/
+  .claude-plugin/
+    plugin.json       # author-supplied metadata; VAT merges on top
+  commands/           # slash commands (*.md)
+  hooks/
+    hooks.json        # hook registry (JSON; parse-only validated)
+  agents/             # subagent definitions (*.md)
+  .mcp.json           # MCP server config (JSON; parse-only validated)
+  scripts/            # arbitrary scripts (tree-copied verbatim)
+  skills/             # plugin-local SKILL.md files — tree-copied verbatim
+```
+
+Everything under `plugins/<name>/` is tree-copied to `dist/.claude/plugins/marketplaces/<mp>/plugins/<name>/`, except:
+
+- `.claude-plugin/` — owned by the `plugin.json` merge-write (see "plugin.json merge")
+
+Tree-copy respects `.gitignore` (safe: `node_modules/`, build detritus never ship). `plugins/<name>/skills/` is just a regular tree-copied directory — drop raw `SKILL.md` files there and they ship as-is.
+
+### Minimum content — empty-plugin guard
+
+Every declared plugin must supply at least one of:
+
+- a `plugins/<name>/` directory on disk (or an alternate `source:` override pointing at one), **or**
+- a non-empty `files: [{ source, dest }, ...]` mapping, **or**
+- a non-empty `skills:` selector that matches at least one pool skill.
+
+A plugin with none of these is rejected with the empty-plugin guard.
+
+### `source` override
+
+```yaml
+claude:
+  marketplaces:
+    mp1:
+      owner: { name: Example }
+      plugins:
+        - name: my-plugin
+          skills: []
+          source: custom/path/to/my-plugin   # default: plugins/my-plugin
+```
+
+### `files[]` — compiled artifacts outside the plugin dir
+
+Use `files: [{ source, dest }]` to inject build artifacts (compiled hooks, generated configs) into the plugin output:
+
+```yaml
+plugins:
+  - name: my-plugin
+    skills: []
+    files:
+      - source: dist/hooks/compiled-hook.mjs   # relative to project root
+        dest: hooks/compiled-hook.mjs         # relative to plugin output dir
+```
+
+`dest` cannot escape the plugin output dir and cannot target `.claude-plugin/plugin.json` (owned by merge-write). Overwrites are allowed and logged at info level.
+
+### `plugin.json` merge rules
+
+VAT writes `.claude-plugin/plugin.json` last, merging the author's `.claude-plugin/plugin.json` (if present) with VAT-owned identity fields:
+
+- **VAT wins** on `name`, `version`, `author` (shallow replace — mismatches produce warnings, never errors).
+- **Author wins** on all other keys (`keywords`, `repository`, `homepage`, `license`, …).
+- **Description chain:** `config.description ?? author.description ?? "${name} plugin"`.
+- `version` falls back to the author's value when VAT has no version (no `package.json`).
+
+### Ordering contract
+
+`vat claude plugin build` runs per plugin in this order:
+
+1. Discovery + validators (case-match, `hooks.json`/`.mcp.json` parse, empty-plugin guard)
+2. Tree-copy `plugins/<name>/` verbatim (skips `.claude-plugin/`, respects `.gitignore`)
+3. Pool-skill import via the plugin's `skills:` selector (from `dist/skills/`)
+4. `files[]` mapping (may overwrite tree-copied files; logged at info)
+5. `.claude-plugin/plugin.json` merge-write (always last, always wins)
+
+**Run order:** `vat skills build && vat claude plugin build`. The plugin build reads pre-built pool skills from `dist/skills/` and raw plugin-local skills directly from `plugins/<name>/skills/`.