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

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

@@ -7,27 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
   - `SKILL_DESCRIPTION_STYLE_MIXED_IN_PACKAGE`: detects mixed YAML scalar styles across sibling skills' `description` frontmatter in the same package. Detector registered and documented; pipeline wiring deferred to a follow-up RC (requires a package-level aggregation pass that the current single-file validator pipeline does not provide).
 
 ### Changed
+- **Config model clarified: one `vibe-agent-toolkit.config.yaml` per VAT project; no composition across projects.** `vat audit` no longer walks the filesystem looking for every nested config under the scan path. Instead, for each SKILL.md it discovers, it walks up to the skill's nearest-ancestor config (if any) and applies only that skill's `skills.config.<name>` packaging rules to the finding. This removes the federated-skill-discovery behavior that was never a documented or intended feature. Lifecycle commands (`vat build`, `vat verify`, `vat skills validate`, `vat skills build`) continue to use exactly one config — the one at their cwd — as they have all along. Adopters who ran `vat audit <ancestor-path>` against monorepos with multiple per-package configs should now run `vat audit` inside each project directory (or use `--cwd`) for per-project validation. When audit encounters a non-scan-root `vibe-agent-toolkit.config.yaml`, it emits a one-time info breadcrumb so operators see which configs were observed. Performance: `vat audit .` on the VAT monorepo drops into the sub-second range because the tree walk is bounded to skill discovery, not to config discovery.
 - `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,7 +1,7 @@
 {
   "name": "vibe-agent-toolkit",
   "description": "Development agents and skills for building with vibe-agent-toolkit",
-  "version": "0.1.33-rc.2",
+  "version": "0.1.33",
   "author": {
     "name": "vibe-agent-toolkit contributors"
   }

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

@@ -47,7 +47,7 @@ my-skills-project/
 
 Three conventions are load-bearing:
 
-1. **`vibe-agent-toolkit.config.yaml` at the project root** — VAT walks upward from the invocation directory to find it.
+1. **`vibe-agent-toolkit.config.yaml` at the project root** — VAT commands pick up this file when run from the project root or a subdirectory.
 2. **SKILL.md files live under `resources/skills/`** — any path works, but this one is what `vat build` and `vat audit` expect by default.
 3. **`dist/` is the only write target** — everything VAT generates goes there, and it's gitignored.
 
@@ -105,6 +105,25 @@ Sections and the skills that own their details:
 
 When adding to a section, load the owning skill rather than re-deriving the shape from this file.
 
+## Config lives at the VAT project root
+
+A VAT project is a directory that contains a `vibe-agent-toolkit.config.yaml`. That file is authoritative for the project: it defines `resources`, `skills`, `claude`, and (optionally) `rag`. Nothing outside the config contributes to its behavior — there is no ambient configuration, no inheritance from parent directories, and no merge with sibling configs.
+
+VAT commands (`vat build`, `vat verify`, `vat skills validate`, `vat skills build`) read the config at the directory they are invoked from. Run them from the project root or from a subdirectory, or pass `--cwd <path>` to point them at a specific project. If you run a lifecycle command from somewhere that has no config, it will not find one — there is no upward walk here.
+
+**Multiple `vibe-agent-toolkit.config.yaml` files in one git repository mean multiple distinct VAT projects.** Each project is independent: configs do not compose, do not merge, and do not inherit from one another. Running VAT from outside any project directory operates on a union of whatever projects it discovers, but each project's rules are applied only to its own skills — per-skill packaging overrides in `project-a/vibe-agent-toolkit.config.yaml` never affect skills under `project-b/`.
+
+`vat audit` is the one command that knowingly spans projects, and even there it does not compose: audit is a general-purpose read-only scan that you may point at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill's nearest-ancestor `vibe-agent-toolkit.config.yaml` and applies **only** that skill's packaging rules (from its own project's `skills.config.<name>`) to the finding. This is display sanity, not federation — audit never merges config data across project boundaries.
+
+In practice, prefer one `vibe-agent-toolkit.config.yaml` per git repository. Multiple configs in a single repo are reasonable only for:
+
+- Committed test harnesses or fixtures that define their own toy VAT projects (for VAT's own tests, or for an adopter's integration tests).
+- Genuinely unrelated projects that happen to share a monorepo and each ship their own skills.
+
+If you are tempted to use nested configs to "share" or "override" settings across related skills, fold everything into one project-level config instead — that's what `skills.defaults` and `skills.config.<name>` are for.
+
+(Note: `agent.yaml`, the manifest for TypeScript portable agents, is a separate surface with its own rules and is out of scope for this guidance — see `vibe-agent-toolkit:vat-agent-authoring`.)
+
 ## `package.json` Wiring
 
 For projects that publish skills via npm, three fields tie VAT into the npm lifecycle:

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

@@ -41,6 +41,10 @@ Running `vat audit <path>` recursively walks the directory and auto-detects:
 
 Recursion is the default — you do not need `--recursive`.
 
+## Audit vs configured VAT projects
+
+Audit is the general-purpose command — you may point it at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill's nearest-ancestor `vibe-agent-toolkit.config.yaml` and respects the skill's per-skill packaging rules (`excludeReferencesFromBundle`, `linkFollowDepth`, `files`) to avoid false flags — but it never composes configs across project boundaries. Per-skill rules from one project do not bleed into skills in another project. For gated, configured-project-level validation, use the lifecycle commands (`vat skills validate`, `vat verify`) and run them from within the project directory.
+
 ## Compatibility Analysis (`--compat`)
 
 ```bash

package/dist/generated/resources/skills/vat-adoption-and-configuration.d.ts

@@ -19,6 +19,7 @@ export const fragments: {
   readonly installingVat: Fragment;
   readonly recommendedRepoStructure: Fragment;
   readonly vibeAgentToolkitconfigyamlShape: Fragment;
+  readonly configLivesAtTheVatProjectRoot: Fragment;
   readonly packagejsonWiring: Fragment;
   readonly vibeValidateIntegration: Fragment;
   readonly firstTimeSetupChecklist: Fragment;

package/dist/generated/resources/skills/vat-adoption-and-configuration.js

@@ -7,7 +7,7 @@ export const meta = {
   description: "Use when starting a new VAT project, adding VAT to an existing repo, or orienting to \`vibe-agent-toolkit.config.yaml\`. Covers project setup, repo structure, package.json wiring, vibe-validate integration, and the npm postinstall hook."
 };
 
-export const text = "\n# VAT Adoption and Configuration\n\nThis skill covers the top-level orientation for adopting VAT in a project: installing the CLI, the overall shape of \`vibe-agent-toolkit.config.yaml\`, repo structure conventions, vibe-validate integration, and how npm postinstall wires plugin registration. Per-section deep-dives live in the sibling skills listed below.\n\n## Installing VAT\n\nVAT ships as the \`vibe-agent-toolkit\` npm package with a \`vat\` CLI:\n\n\`\`\`bash\n# Global install (most common during development)\nnpm install -g vibe-agent-toolkit\n\n# Or run without installing\nnpx vibe-agent-toolkit <command>\nbunx vibe-agent-toolkit <command>\n\n# As a runtime dependency (recommended for published packages that ship skills)\nnpm install --save vibe-agent-toolkit\n\`\`\`\n\nOnce installed, \`vat --help\` lists the top-level command groups. \`vat <group> --help\` and \`vat <group> <cmd> --help --verbose\` cover the rest.\n\n## Recommended Repo Structure\n\n\`\`\`\nmy-skills-project/\n├── package.json                        # includes \"vat\" block (see below)\n├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT\n├── resources/\n│   ├── skills/                         # SKILL.md sources\n│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)\n│   │   └── my-skill.md\n│   └── content/                        # non-skill markdown (RAG, collections)\n├── agents/                             # TypeScript portable agents (optional)\n│   └── my-agent/\n│       ├── agent.yaml\n│       └── src/\n├── schemas/                            # JSON Schemas for resource collections\n├── docs/                               # project documentation\n└── dist/                               # generated (gitignored): vat build output\n\`\`\`\n\nThree conventions are load-bearing:\n\n1. **\`vibe-agent-toolkit.config.yaml\` at the project root** — VAT walks upward from the invocation directory to find it.\n2. **SKILL.md files live under \`resources/skills/\`** — any path works, but this one is what \`vat build\` and \`vat audit\` expect by default.\n3. **\`dist/\` is the only write target** — everything VAT generates goes there, and it\'s gitignored.\n\n## \`vibe-agent-toolkit.config.yaml\` Shape\n\n\`\`\`yaml\nversion: 1\n\nskills:\n  include: [\"resources/skills/SKILL.md\", \"resources/skills/*.md\"]\n  defaults:\n    linkFollowDepth: 2\n    excludeNavigationFiles: true\n    targets: [\'claude-code\']\n  config:\n    my-skill:\n      linkFollowDepth: 1\n\nresources:\n  collections:\n    docs:\n      include: [\"docs/**/*.md\"]\n      validation:\n        frontmatterSchema: \"schemas/doc.schema.json\"\n        mode: permissive\n\nclaude:\n  marketplaces:\n    my-marketplace:\n      owner: { name: \"my-org\" }\n      publish:\n        changelog: CHANGELOG.md\n        readme: README.md\n      plugins:\n        - name: my-plugin\n          description: \"What this plugin does\"\n          skills: \"*\"\n\nrag:\n  stores:\n    default:\n      db: .rag-db/\n      include: [\"docs/**/*.md\"]\n\`\`\`\n\nSections and the skills that own their details:\n\n| Section | Owning skill |\n|---|---|\n| Top-level structure, \`version\`, section orientation | this skill (\`vat-adoption-and-configuration\`) |\n| \`skills:\` (include, defaults, per-skill config, packagingOptions) | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| \`resources:\` (collections, schemas, validation modes) | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`claude:\` (marketplaces, plugins, publish, owner) | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`rag:\` (stores, embedding providers) | \`vibe-agent-toolkit:vat-rag\` |\n\nWhen adding to a section, load the owning skill rather than re-deriving the shape from this file.\n\n## \`package.json\` Wiring\n\nFor projects that publish skills via npm, three fields tie VAT into the npm lifecycle:\n\n\`\`\`json\n{\n  \"name\": \"@myorg/my-skills\",\n  \"dependencies\": {\n    \"vibe-agent-toolkit\": \"latest\"\n  },\n  \"scripts\": {\n    \"build\": \"vat build\",\n    \"postinstall\": \"vat claude plugin install --npm-postinstall || exit 0\"\n  },\n  \"vat\": {\n    \"skills\": [\"my-skill-one\", \"my-skill-two\"]\n  }\n}\n\`\`\`\n\n- **\`dependencies.vibe-agent-toolkit\`** — runtime dep, not dev. Needed so the postinstall hook can find \`vat\`.\n- **\`scripts.postinstall\`** — registers the built plugin into the user\'s \`~/.claude/plugins/\` tree after \`npm install -g\` or any install that runs lifecycle scripts. The \`|| exit 0\` keeps \`npm install\` from aborting if the hook can\'t run (unusual but defensive).\n- **\`vat.skills\`** — declares which skill names this package ships. \`vat verify\` cross-checks this list against \`skills.include\` in \`vibe-agent-toolkit.config.yaml\`; mismatches fire \`PACKAGE_JSON_LISTS_UNKNOWN_SKILL\` / \`PACKAGE_JSON_MISSING_SKILL\`. The list is a packaging contract with npm, not a build input — \`vat build\` discovers skills from the config globs.\n\nThe full distribution pipeline (build, verify, npm publish, marketplace layout, managed settings) lives in \`vibe-agent-toolkit:vat-skill-distribution\`.\n\n## vibe-validate Integration\n\nIf the project uses vibe-validate (recommended), wire VAT into the validation config:\n\n\`\`\`yaml\n# vibe-validate.config.yaml (or relevant section)\nphases:\n  - name: vat-build-and-verify\n    parallel: false\n    commands:\n      - name: vat build\n        run: vat build\n      - name: vat verify\n        run: vat verify\n\`\`\`\n\n\`vat verify\` runs the full artifact check (resources → skills → marketplace → consistency); it\'s the authoritative gate before \`npm publish\`. In this repo\'s own config, \`bun run validate\` already does this — adopters typically mirror the pattern.\n\n## First-Time Setup Checklist\n\n1. \`npm install -g vibe-agent-toolkit\` (or add to local deps)\n2. \`vat --help\` — confirm the CLI resolves\n3. Create \`vibe-agent-toolkit.config.yaml\` with the minimal \`version: 1\` plus the sections you need\n4. Add \`resources/skills/SKILL.md\` or a kebab-case SKILL.md file and stage it in git (the skill discovery crawler uses \`git ls-files\` by default — untracked new files are skipped)\n5. \`vat skills validate\` — report any issues before building\n6. \`vat build\` — produces \`dist/\` artifacts\n7. \`vat verify\` — full consistency check; should be a no-op when clean\n8. If publishing: add the \`vat.skills\`, \`scripts.postinstall\`, and \`dependencies.vibe-agent-toolkit\` entries in \`package.json\` before \`npm publish\`\n\n## When Things Are Off\n\n- **\"No skills section in config yaml\"** — either the file isn\'t at the project root, or \`skills.include\` is missing.\n- **\"Found 0 skills\"** — glob doesn\'t match any SKILL.md files. Confirm the path and that the files are tracked by git (VAT\'s discovery respects \`.gitignore\` and \`git ls-files\`).\n- **\`PACKAGE_JSON_LISTS_UNKNOWN_SKILL\`** — \`vat.skills\` mentions a name not produced by \`skills.include\` discovery. Either add the file or remove the name.\n- **\`vat audit\` fires unexpected warnings** — load \`vibe-agent-toolkit:vat-audit\` for the full audit surface, including \`--compat\` and \`--exclude\` flags.\n\n## References\n\n- \`vibe-agent-toolkit:vat-skill-authoring\` — SKILL.md frontmatter, body structure, references, packagingOptions\n- \`vibe-agent-toolkit:vat-agent-authoring\` — TypeScript agent archetypes and runtime adapters\n- \`vibe-agent-toolkit:vat-skill-distribution\` — \`vat build\` / \`vat verify\` / marketplace / npm publish\n- \`vibe-agent-toolkit:vat-knowledge-resources\` — \`resources:\` collections and frontmatter schemas\n- \`vibe-agent-toolkit:vat-rag\` — \`rag:\` stores, embedding providers, \`vat rag index/query\`\n- \`vibe-agent-toolkit:vat-audit\` — \`vat audit\` for plugins, marketplaces, and installed skills\n- \`vibe-agent-toolkit:vat-skill-review\` — pre-publication quality checklist\n- [Getting Started Guide](../../../../docs/getting-started.md) — full setup walkthrough\n";
+export const text = "\n# VAT Adoption and Configuration\n\nThis skill covers the top-level orientation for adopting VAT in a project: installing the CLI, the overall shape of \`vibe-agent-toolkit.config.yaml\`, repo structure conventions, vibe-validate integration, and how npm postinstall wires plugin registration. Per-section deep-dives live in the sibling skills listed below.\n\n## Installing VAT\n\nVAT ships as the \`vibe-agent-toolkit\` npm package with a \`vat\` CLI:\n\n\`\`\`bash\n# Global install (most common during development)\nnpm install -g vibe-agent-toolkit\n\n# Or run without installing\nnpx vibe-agent-toolkit <command>\nbunx vibe-agent-toolkit <command>\n\n# As a runtime dependency (recommended for published packages that ship skills)\nnpm install --save vibe-agent-toolkit\n\`\`\`\n\nOnce installed, \`vat --help\` lists the top-level command groups. \`vat <group> --help\` and \`vat <group> <cmd> --help --verbose\` cover the rest.\n\n## Recommended Repo Structure\n\n\`\`\`\nmy-skills-project/\n├── package.json                        # includes \"vat\" block (see below)\n├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT\n├── resources/\n│   ├── skills/                         # SKILL.md sources\n│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)\n│   │   └── my-skill.md\n│   └── content/                        # non-skill markdown (RAG, collections)\n├── agents/                             # TypeScript portable agents (optional)\n│   └── my-agent/\n│       ├── agent.yaml\n│       └── src/\n├── schemas/                            # JSON Schemas for resource collections\n├── docs/                               # project documentation\n└── dist/                               # generated (gitignored): vat build output\n\`\`\`\n\nThree conventions are load-bearing:\n\n1. **\`vibe-agent-toolkit.config.yaml\` at the project root** — VAT commands pick up this file when run from the project root or a subdirectory.\n2. **SKILL.md files live under \`resources/skills/\`** — any path works, but this one is what \`vat build\` and \`vat audit\` expect by default.\n3. **\`dist/\` is the only write target** — everything VAT generates goes there, and it\'s gitignored.\n\n## \`vibe-agent-toolkit.config.yaml\` Shape\n\n\`\`\`yaml\nversion: 1\n\nskills:\n  include: [\"resources/skills/SKILL.md\", \"resources/skills/*.md\"]\n  defaults:\n    linkFollowDepth: 2\n    excludeNavigationFiles: true\n    targets: [\'claude-code\']\n  config:\n    my-skill:\n      linkFollowDepth: 1\n\nresources:\n  collections:\n    docs:\n      include: [\"docs/**/*.md\"]\n      validation:\n        frontmatterSchema: \"schemas/doc.schema.json\"\n        mode: permissive\n\nclaude:\n  marketplaces:\n    my-marketplace:\n      owner: { name: \"my-org\" }\n      publish:\n        changelog: CHANGELOG.md\n        readme: README.md\n      plugins:\n        - name: my-plugin\n          description: \"What this plugin does\"\n          skills: \"*\"\n\nrag:\n  stores:\n    default:\n      db: .rag-db/\n      include: [\"docs/**/*.md\"]\n\`\`\`\n\nSections and the skills that own their details:\n\n| Section | Owning skill |\n|---|---|\n| Top-level structure, \`version\`, section orientation | this skill (\`vat-adoption-and-configuration\`) |\n| \`skills:\` (include, defaults, per-skill config, packagingOptions) | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| \`resources:\` (collections, schemas, validation modes) | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`claude:\` (marketplaces, plugins, publish, owner) | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`rag:\` (stores, embedding providers) | \`vibe-agent-toolkit:vat-rag\` |\n\nWhen adding to a section, load the owning skill rather than re-deriving the shape from this file.\n\n## Config lives at the VAT project root\n\nA VAT project is a directory that contains a \`vibe-agent-toolkit.config.yaml\`. That file is authoritative for the project: it defines \`resources\`, \`skills\`, \`claude\`, and (optionally) \`rag\`. Nothing outside the config contributes to its behavior — there is no ambient configuration, no inheritance from parent directories, and no merge with sibling configs.\n\nVAT commands (\`vat build\`, \`vat verify\`, \`vat skills validate\`, \`vat skills build\`) read the config at the directory they are invoked from. Run them from the project root or from a subdirectory, or pass \`--cwd <path>\` to point them at a specific project. If you run a lifecycle command from somewhere that has no config, it will not find one — there is no upward walk here.\n\n**Multiple \`vibe-agent-toolkit.config.yaml\` files in one git repository mean multiple distinct VAT projects.** Each project is independent: configs do not compose, do not merge, and do not inherit from one another. Running VAT from outside any project directory operates on a union of whatever projects it discovers, but each project\'s rules are applied only to its own skills — per-skill packaging overrides in \`project-a/vibe-agent-toolkit.config.yaml\` never affect skills under \`project-b/\`.\n\n\`vat audit\` is the one command that knowingly spans projects, and even there it does not compose: audit is a general-purpose read-only scan that you may point at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill\'s nearest-ancestor \`vibe-agent-toolkit.config.yaml\` and applies **only** that skill\'s packaging rules (from its own project\'s \`skills.config.<name>\`) to the finding. This is display sanity, not federation — audit never merges config data across project boundaries.\n\nIn practice, prefer one \`vibe-agent-toolkit.config.yaml\` per git repository. Multiple configs in a single repo are reasonable only for:\n\n- Committed test harnesses or fixtures that define their own toy VAT projects (for VAT\'s own tests, or for an adopter\'s integration tests).\n- Genuinely unrelated projects that happen to share a monorepo and each ship their own skills.\n\nIf you are tempted to use nested configs to \"share\" or \"override\" settings across related skills, fold everything into one project-level config instead — that\'s what \`skills.defaults\` and \`skills.config.<name>\` are for.\n\n(Note: \`agent.yaml\`, the manifest for TypeScript portable agents, is a separate surface with its own rules and is out of scope for this guidance — see \`vibe-agent-toolkit:vat-agent-authoring\`.)\n\n## \`package.json\` Wiring\n\nFor projects that publish skills via npm, three fields tie VAT into the npm lifecycle:\n\n\`\`\`json\n{\n  \"name\": \"@myorg/my-skills\",\n  \"dependencies\": {\n    \"vibe-agent-toolkit\": \"latest\"\n  },\n  \"scripts\": {\n    \"build\": \"vat build\",\n    \"postinstall\": \"vat claude plugin install --npm-postinstall || exit 0\"\n  },\n  \"vat\": {\n    \"skills\": [\"my-skill-one\", \"my-skill-two\"]\n  }\n}\n\`\`\`\n\n- **\`dependencies.vibe-agent-toolkit\`** — runtime dep, not dev. Needed so the postinstall hook can find \`vat\`.\n- **\`scripts.postinstall\`** — registers the built plugin into the user\'s \`~/.claude/plugins/\` tree after \`npm install -g\` or any install that runs lifecycle scripts. The \`|| exit 0\` keeps \`npm install\` from aborting if the hook can\'t run (unusual but defensive).\n- **\`vat.skills\`** — declares which skill names this package ships. \`vat verify\` cross-checks this list against \`skills.include\` in \`vibe-agent-toolkit.config.yaml\`; mismatches fire \`PACKAGE_JSON_LISTS_UNKNOWN_SKILL\` / \`PACKAGE_JSON_MISSING_SKILL\`. The list is a packaging contract with npm, not a build input — \`vat build\` discovers skills from the config globs.\n\nThe full distribution pipeline (build, verify, npm publish, marketplace layout, managed settings) lives in \`vibe-agent-toolkit:vat-skill-distribution\`.\n\n## vibe-validate Integration\n\nIf the project uses vibe-validate (recommended), wire VAT into the validation config:\n\n\`\`\`yaml\n# vibe-validate.config.yaml (or relevant section)\nphases:\n  - name: vat-build-and-verify\n    parallel: false\n    commands:\n      - name: vat build\n        run: vat build\n      - name: vat verify\n        run: vat verify\n\`\`\`\n\n\`vat verify\` runs the full artifact check (resources → skills → marketplace → consistency); it\'s the authoritative gate before \`npm publish\`. In this repo\'s own config, \`bun run validate\` already does this — adopters typically mirror the pattern.\n\n## First-Time Setup Checklist\n\n1. \`npm install -g vibe-agent-toolkit\` (or add to local deps)\n2. \`vat --help\` — confirm the CLI resolves\n3. Create \`vibe-agent-toolkit.config.yaml\` with the minimal \`version: 1\` plus the sections you need\n4. Add \`resources/skills/SKILL.md\` or a kebab-case SKILL.md file and stage it in git (the skill discovery crawler uses \`git ls-files\` by default — untracked new files are skipped)\n5. \`vat skills validate\` — report any issues before building\n6. \`vat build\` — produces \`dist/\` artifacts\n7. \`vat verify\` — full consistency check; should be a no-op when clean\n8. If publishing: add the \`vat.skills\`, \`scripts.postinstall\`, and \`dependencies.vibe-agent-toolkit\` entries in \`package.json\` before \`npm publish\`\n\n## When Things Are Off\n\n- **\"No skills section in config yaml\"** — either the file isn\'t at the project root, or \`skills.include\` is missing.\n- **\"Found 0 skills\"** — glob doesn\'t match any SKILL.md files. Confirm the path and that the files are tracked by git (VAT\'s discovery respects \`.gitignore\` and \`git ls-files\`).\n- **\`PACKAGE_JSON_LISTS_UNKNOWN_SKILL\`** — \`vat.skills\` mentions a name not produced by \`skills.include\` discovery. Either add the file or remove the name.\n- **\`vat audit\` fires unexpected warnings** — load \`vibe-agent-toolkit:vat-audit\` for the full audit surface, including \`--compat\` and \`--exclude\` flags.\n\n## References\n\n- \`vibe-agent-toolkit:vat-skill-authoring\` — SKILL.md frontmatter, body structure, references, packagingOptions\n- \`vibe-agent-toolkit:vat-agent-authoring\` — TypeScript agent archetypes and runtime adapters\n- \`vibe-agent-toolkit:vat-skill-distribution\` — \`vat build\` / \`vat verify\` / marketplace / npm publish\n- \`vibe-agent-toolkit:vat-knowledge-resources\` — \`resources:\` collections and frontmatter schemas\n- \`vibe-agent-toolkit:vat-rag\` — \`rag:\` stores, embedding providers, \`vat rag index/query\`\n- \`vibe-agent-toolkit:vat-audit\` — \`vat audit\` for plugins, marketplaces, and installed skills\n- \`vibe-agent-toolkit:vat-skill-review\` — pre-publication quality checklist\n- [Getting Started Guide](../../../../docs/getting-started.md) — full setup walkthrough\n";
 
 export const fragments = {
   installingVat: {
@@ -17,14 +17,19 @@ export const fragments = {
   },
   recommendedRepoStructure: {
     header: "## Recommended Repo Structure",
-    body: "\`\`\`\nmy-skills-project/\n├── package.json                        # includes \"vat\" block (see below)\n├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT\n├── resources/\n│   ├── skills/                         # SKILL.md sources\n│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)\n│   │   └── my-skill.md\n│   └── content/                        # non-skill markdown (RAG, collections)\n├── agents/                             # TypeScript portable agents (optional)\n│   └── my-agent/\n│       ├── agent.yaml\n│       └── src/\n├── schemas/                            # JSON Schemas for resource collections\n├── docs/                               # project documentation\n└── dist/                               # generated (gitignored): vat build output\n\`\`\`\n\nThree conventions are load-bearing:\n\n1. **\`vibe-agent-toolkit.config.yaml\` at the project root** — VAT walks upward from the invocation directory to find it.\n2. **SKILL.md files live under \`resources/skills/\`** — any path works, but this one is what \`vat build\` and \`vat audit\` expect by default.\n3. **\`dist/\` is the only write target** — everything VAT generates goes there, and it\'s gitignored.",
-    text: "## Recommended Repo Structure\n\n\`\`\`\nmy-skills-project/\n├── package.json                        # includes \"vat\" block (see below)\n├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT\n├── resources/\n│   ├── skills/                         # SKILL.md sources\n│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)\n│   │   └── my-skill.md\n│   └── content/                        # non-skill markdown (RAG, collections)\n├── agents/                             # TypeScript portable agents (optional)\n│   └── my-agent/\n│       ├── agent.yaml\n│       └── src/\n├── schemas/                            # JSON Schemas for resource collections\n├── docs/                               # project documentation\n└── dist/                               # generated (gitignored): vat build output\n\`\`\`\n\nThree conventions are load-bearing:\n\n1. **\`vibe-agent-toolkit.config.yaml\` at the project root** — VAT walks upward from the invocation directory to find it.\n2. **SKILL.md files live under \`resources/skills/\`** — any path works, but this one is what \`vat build\` and \`vat audit\` expect by default.\n3. **\`dist/\` is the only write target** — everything VAT generates goes there, and it\'s gitignored."
+    body: "\`\`\`\nmy-skills-project/\n├── package.json                        # includes \"vat\" block (see below)\n├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT\n├── resources/\n│   ├── skills/                         # SKILL.md sources\n│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)\n│   │   └── my-skill.md\n│   └── content/                        # non-skill markdown (RAG, collections)\n├── agents/                             # TypeScript portable agents (optional)\n│   └── my-agent/\n│       ├── agent.yaml\n│       └── src/\n├── schemas/                            # JSON Schemas for resource collections\n├── docs/                               # project documentation\n└── dist/                               # generated (gitignored): vat build output\n\`\`\`\n\nThree conventions are load-bearing:\n\n1. **\`vibe-agent-toolkit.config.yaml\` at the project root** — VAT commands pick up this file when run from the project root or a subdirectory.\n2. **SKILL.md files live under \`resources/skills/\`** — any path works, but this one is what \`vat build\` and \`vat audit\` expect by default.\n3. **\`dist/\` is the only write target** — everything VAT generates goes there, and it\'s gitignored.",
+    text: "## Recommended Repo Structure\n\n\`\`\`\nmy-skills-project/\n├── package.json                        # includes \"vat\" block (see below)\n├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT\n├── resources/\n│   ├── skills/                         # SKILL.md sources\n│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)\n│   │   └── my-skill.md\n│   └── content/                        # non-skill markdown (RAG, collections)\n├── agents/                             # TypeScript portable agents (optional)\n│   └── my-agent/\n│       ├── agent.yaml\n│       └── src/\n├── schemas/                            # JSON Schemas for resource collections\n├── docs/                               # project documentation\n└── dist/                               # generated (gitignored): vat build output\n\`\`\`\n\nThree conventions are load-bearing:\n\n1. **\`vibe-agent-toolkit.config.yaml\` at the project root** — VAT commands pick up this file when run from the project root or a subdirectory.\n2. **SKILL.md files live under \`resources/skills/\`** — any path works, but this one is what \`vat build\` and \`vat audit\` expect by default.\n3. **\`dist/\` is the only write target** — everything VAT generates goes there, and it\'s gitignored."
   },
   vibeAgentToolkitconfigyamlShape: {
     header: "## \`vibe-agent-toolkit.config.yaml\` Shape",
     body: "\`\`\`yaml\nversion: 1\n\nskills:\n  include: [\"resources/skills/SKILL.md\", \"resources/skills/*.md\"]\n  defaults:\n    linkFollowDepth: 2\n    excludeNavigationFiles: true\n    targets: [\'claude-code\']\n  config:\n    my-skill:\n      linkFollowDepth: 1\n\nresources:\n  collections:\n    docs:\n      include: [\"docs/**/*.md\"]\n      validation:\n        frontmatterSchema: \"schemas/doc.schema.json\"\n        mode: permissive\n\nclaude:\n  marketplaces:\n    my-marketplace:\n      owner: { name: \"my-org\" }\n      publish:\n        changelog: CHANGELOG.md\n        readme: README.md\n      plugins:\n        - name: my-plugin\n          description: \"What this plugin does\"\n          skills: \"*\"\n\nrag:\n  stores:\n    default:\n      db: .rag-db/\n      include: [\"docs/**/*.md\"]\n\`\`\`\n\nSections and the skills that own their details:\n\n| Section | Owning skill |\n|---|---|\n| Top-level structure, \`version\`, section orientation | this skill (\`vat-adoption-and-configuration\`) |\n| \`skills:\` (include, defaults, per-skill config, packagingOptions) | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| \`resources:\` (collections, schemas, validation modes) | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`claude:\` (marketplaces, plugins, publish, owner) | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`rag:\` (stores, embedding providers) | \`vibe-agent-toolkit:vat-rag\` |\n\nWhen adding to a section, load the owning skill rather than re-deriving the shape from this file.",
     text: "## \`vibe-agent-toolkit.config.yaml\` Shape\n\n\`\`\`yaml\nversion: 1\n\nskills:\n  include: [\"resources/skills/SKILL.md\", \"resources/skills/*.md\"]\n  defaults:\n    linkFollowDepth: 2\n    excludeNavigationFiles: true\n    targets: [\'claude-code\']\n  config:\n    my-skill:\n      linkFollowDepth: 1\n\nresources:\n  collections:\n    docs:\n      include: [\"docs/**/*.md\"]\n      validation:\n        frontmatterSchema: \"schemas/doc.schema.json\"\n        mode: permissive\n\nclaude:\n  marketplaces:\n    my-marketplace:\n      owner: { name: \"my-org\" }\n      publish:\n        changelog: CHANGELOG.md\n        readme: README.md\n      plugins:\n        - name: my-plugin\n          description: \"What this plugin does\"\n          skills: \"*\"\n\nrag:\n  stores:\n    default:\n      db: .rag-db/\n      include: [\"docs/**/*.md\"]\n\`\`\`\n\nSections and the skills that own their details:\n\n| Section | Owning skill |\n|---|---|\n| Top-level structure, \`version\`, section orientation | this skill (\`vat-adoption-and-configuration\`) |\n| \`skills:\` (include, defaults, per-skill config, packagingOptions) | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| \`resources:\` (collections, schemas, validation modes) | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`claude:\` (marketplaces, plugins, publish, owner) | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`rag:\` (stores, embedding providers) | \`vibe-agent-toolkit:vat-rag\` |\n\nWhen adding to a section, load the owning skill rather than re-deriving the shape from this file."
   },
+  configLivesAtTheVatProjectRoot: {
+    header: "## Config lives at the VAT project root",
+    body: "A VAT project is a directory that contains a \`vibe-agent-toolkit.config.yaml\`. That file is authoritative for the project: it defines \`resources\`, \`skills\`, \`claude\`, and (optionally) \`rag\`. Nothing outside the config contributes to its behavior — there is no ambient configuration, no inheritance from parent directories, and no merge with sibling configs.\n\nVAT commands (\`vat build\`, \`vat verify\`, \`vat skills validate\`, \`vat skills build\`) read the config at the directory they are invoked from. Run them from the project root or from a subdirectory, or pass \`--cwd <path>\` to point them at a specific project. If you run a lifecycle command from somewhere that has no config, it will not find one — there is no upward walk here.\n\n**Multiple \`vibe-agent-toolkit.config.yaml\` files in one git repository mean multiple distinct VAT projects.** Each project is independent: configs do not compose, do not merge, and do not inherit from one another. Running VAT from outside any project directory operates on a union of whatever projects it discovers, but each project\'s rules are applied only to its own skills — per-skill packaging overrides in \`project-a/vibe-agent-toolkit.config.yaml\` never affect skills under \`project-b/\`.\n\n\`vat audit\` is the one command that knowingly spans projects, and even there it does not compose: audit is a general-purpose read-only scan that you may point at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill\'s nearest-ancestor \`vibe-agent-toolkit.config.yaml\` and applies **only** that skill\'s packaging rules (from its own project\'s \`skills.config.<name>\`) to the finding. This is display sanity, not federation — audit never merges config data across project boundaries.\n\nIn practice, prefer one \`vibe-agent-toolkit.config.yaml\` per git repository. Multiple configs in a single repo are reasonable only for:\n\n- Committed test harnesses or fixtures that define their own toy VAT projects (for VAT\'s own tests, or for an adopter\'s integration tests).\n- Genuinely unrelated projects that happen to share a monorepo and each ship their own skills.\n\nIf you are tempted to use nested configs to \"share\" or \"override\" settings across related skills, fold everything into one project-level config instead — that\'s what \`skills.defaults\` and \`skills.config.<name>\` are for.\n\n(Note: \`agent.yaml\`, the manifest for TypeScript portable agents, is a separate surface with its own rules and is out of scope for this guidance — see \`vibe-agent-toolkit:vat-agent-authoring\`.)",
+    text: "## Config lives at the VAT project root\n\nA VAT project is a directory that contains a \`vibe-agent-toolkit.config.yaml\`. That file is authoritative for the project: it defines \`resources\`, \`skills\`, \`claude\`, and (optionally) \`rag\`. Nothing outside the config contributes to its behavior — there is no ambient configuration, no inheritance from parent directories, and no merge with sibling configs.\n\nVAT commands (\`vat build\`, \`vat verify\`, \`vat skills validate\`, \`vat skills build\`) read the config at the directory they are invoked from. Run them from the project root or from a subdirectory, or pass \`--cwd <path>\` to point them at a specific project. If you run a lifecycle command from somewhere that has no config, it will not find one — there is no upward walk here.\n\n**Multiple \`vibe-agent-toolkit.config.yaml\` files in one git repository mean multiple distinct VAT projects.** Each project is independent: configs do not compose, do not merge, and do not inherit from one another. Running VAT from outside any project directory operates on a union of whatever projects it discovers, but each project\'s rules are applied only to its own skills — per-skill packaging overrides in \`project-a/vibe-agent-toolkit.config.yaml\` never affect skills under \`project-b/\`.\n\n\`vat audit\` is the one command that knowingly spans projects, and even there it does not compose: audit is a general-purpose read-only scan that you may point at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill\'s nearest-ancestor \`vibe-agent-toolkit.config.yaml\` and applies **only** that skill\'s packaging rules (from its own project\'s \`skills.config.<name>\`) to the finding. This is display sanity, not federation — audit never merges config data across project boundaries.\n\nIn practice, prefer one \`vibe-agent-toolkit.config.yaml\` per git repository. Multiple configs in a single repo are reasonable only for:\n\n- Committed test harnesses or fixtures that define their own toy VAT projects (for VAT\'s own tests, or for an adopter\'s integration tests).\n- Genuinely unrelated projects that happen to share a monorepo and each ship their own skills.\n\nIf you are tempted to use nested configs to \"share\" or \"override\" settings across related skills, fold everything into one project-level config instead — that\'s what \`skills.defaults\` and \`skills.config.<name>\` are for.\n\n(Note: \`agent.yaml\`, the manifest for TypeScript portable agents, is a separate surface with its own rules and is out of scope for this guidance — see \`vibe-agent-toolkit:vat-agent-authoring\`.)"
+  },
   packagejsonWiring: {
     header: "## \`package.json\` Wiring",
     body: "For projects that publish skills via npm, three fields tie VAT into the npm lifecycle:\n\n\`\`\`json\n{\n  \"name\": \"@myorg/my-skills\",\n  \"dependencies\": {\n    \"vibe-agent-toolkit\": \"latest\"\n  },\n  \"scripts\": {\n    \"build\": \"vat build\",\n    \"postinstall\": \"vat claude plugin install --npm-postinstall || exit 0\"\n  },\n  \"vat\": {\n    \"skills\": [\"my-skill-one\", \"my-skill-two\"]\n  }\n}\n\`\`\`\n\n- **\`dependencies.vibe-agent-toolkit\`** — runtime dep, not dev. Needed so the postinstall hook can find \`vat\`.\n- **\`scripts.postinstall\`** — registers the built plugin into the user\'s \`~/.claude/plugins/\` tree after \`npm install -g\` or any install that runs lifecycle scripts. The \`|| exit 0\` keeps \`npm install\` from aborting if the hook can\'t run (unusual but defensive).\n- **\`vat.skills\`** — declares which skill names this package ships. \`vat verify\` cross-checks this list against \`skills.include\` in \`vibe-agent-toolkit.config.yaml\`; mismatches fire \`PACKAGE_JSON_LISTS_UNKNOWN_SKILL\` / \`PACKAGE_JSON_MISSING_SKILL\`. The list is a packaging contract with npm, not a build input — \`vat build\` discovers skills from the config globs.\n\nThe full distribution pipeline (build, verify, npm publish, marketplace layout, managed settings) lives in \`vibe-agent-toolkit:vat-skill-distribution\`.",

package/dist/generated/resources/skills/vat-audit.d.ts

@@ -18,6 +18,7 @@ export const text: string;
 export const fragments: {
   readonly runningTheAudit: Fragment;
   readonly whatGetsDetectedAutomatic: Fragment;
+  readonly auditVsConfiguredVatProjects: Fragment;
   readonly compatibilityAnalysis--Compat: Fragment;
   readonly exitCodes: Fragment;
   readonly ciUsage: Fragment;

package/dist/generated/resources/skills/vat-audit.js

@@ -7,7 +7,7 @@ export const meta = {
   description: "Use when running vat audit to validate Claude plugins, agent skills, or marketplaces. Covers the audit command, --compat flag for surface compatibility analysis, --exclude for noise filtering, and interpreting audit output."
 };
 
-export const text = "\n# VAT Audit: Validating Plugins, Skills & Marketplaces\n\n## Running the Audit\n\n\`\`\`bash\n# Audit current directory (recursive by default)\nvat audit\n\n# Audit a specific directory\nvat audit ./plugins/\n\n# Audit your entire Claude installation\nvat audit --user\n\n# Exclude noisy directories\nvat audit --exclude \"dist/**\" --exclude \"node_modules/**\"\n\n# Verbose: show all resources, not just those with issues\nvat audit --verbose\n\n# Compatibility analysis: which Claude surfaces each plugin supports\nvat audit ./plugins/ --compat\n\`\`\`\n\n## What Gets Detected (Automatic)\n\nRunning \`vat audit <path>\` recursively walks the directory and auto-detects:\n\n| Found | Detected as |\n|---|---|\n| \`.claude-plugin/plugin.json\` in a dir | Claude Plugin |\n| \`.claude-plugin/marketplace.json\` in a dir | Claude Marketplace |\n| \`SKILL.md\` file | Agent Skill |\n| \`agent.yaml\` + \`SKILL.md\` | VAT Agent |\n| \`installed_plugins.json\` | Registry file |\n\nRecursion is the default — you do not need \`--recursive\`.\n\n## Compatibility Analysis (\`--compat\`)\n\n\`\`\`bash\nvat audit ./plugins/ --compat\n\`\`\`\n\nOutput per plugin:\n\`\`\`yaml\nplugin: mission-control\ncompatibility:\n  claude-code:\n    compatible: true\n    evidence: []\n  cowork:\n    compatible: true\n    evidence: []\n  claude-desktop:\n    compatible: false\n    evidence:\n      - type: python-script\n        file: hooks-handlers/handler.py\n        detail: Python execution not available in claude-desktop\n\`\`\`\n\nUse this before a release to determine which surfaces each plugin supports.\n\n## Exit Codes\n\n\`vat audit\` is **advisory** — it reports every issue it detects but never blocks on validation severity:\n\n- \`0\` — always, when the audit completes, regardless of errors or warnings in the report.\n- \`2\` — system error (path not found, permission denied, etc.) — the audit could not run.\n\nFor gated checks that exit \`1\` on validation errors, use \`vat skills validate\` or \`vat skills build\` instead. Those commands apply \`validation.severity\` and honor \`validation.allow\` from config.\n\n## CI Usage\n\n\`\`\`yaml\n# vibe-validate.config.yaml\nsteps:\n  - name: Plugin and skill validation\n    command: vat audit plugins/ --exclude \"**/__pycache__/**\"\n\`\`\`\n\n## Interpreting Output\n\n\`\`\`yaml\nstatus: warning\nsummary:\n  filesScanned: 23\n  success: 21\n  warnings: 2\n  errors: 0\n\`\`\`\n\nSeverity taxonomy in audit output:\n- **Errors:** Missing required frontmatter, broken links, invalid plugin.json schema, link integrity violations\n- **Warnings:** Skill too long, description too short, best practice violations\n\nAudit always exits \`0\` regardless — surface-level severity drives display grouping only.\n\n**Hiding codes from audit output.** Audit ignores \`validation.allow\` by design (it is the read-only report), but it does honor \`validation.severity\`. Set a code to \`ignore\` in \`vibe-agent-toolkit.config.yaml\` to suppress it from the audit output:\n\n\`\`\`yaml\nskills:\n  config:\n    my-skill:\n      validation:\n        severity:\n          LINK_TO_NAVIGATION_FILE: ignore   # hidden from audit output\n\`\`\`\n\n**Per-instance allow entries.** For per-path suppression with an audit trail, use \`validation.allow\` and run \`vat skills validate\` or \`vat skills build\` — those commands apply \`allow\` and gate the build. See \`docs/validation-codes.md\` for the full code reference and the VAT agent-authoring skill for configuration patterns.\n";
+export const text = "\n# VAT Audit: Validating Plugins, Skills & Marketplaces\n\n## Running the Audit\n\n\`\`\`bash\n# Audit current directory (recursive by default)\nvat audit\n\n# Audit a specific directory\nvat audit ./plugins/\n\n# Audit your entire Claude installation\nvat audit --user\n\n# Exclude noisy directories\nvat audit --exclude \"dist/**\" --exclude \"node_modules/**\"\n\n# Verbose: show all resources, not just those with issues\nvat audit --verbose\n\n# Compatibility analysis: which Claude surfaces each plugin supports\nvat audit ./plugins/ --compat\n\`\`\`\n\n## What Gets Detected (Automatic)\n\nRunning \`vat audit <path>\` recursively walks the directory and auto-detects:\n\n| Found | Detected as |\n|---|---|\n| \`.claude-plugin/plugin.json\` in a dir | Claude Plugin |\n| \`.claude-plugin/marketplace.json\` in a dir | Claude Marketplace |\n| \`SKILL.md\` file | Agent Skill |\n| \`agent.yaml\` + \`SKILL.md\` | VAT Agent |\n| \`installed_plugins.json\` | Registry file |\n\nRecursion is the default — you do not need \`--recursive\`.\n\n## Audit vs configured VAT projects\n\nAudit is the general-purpose command — you may point it at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill\'s nearest-ancestor \`vibe-agent-toolkit.config.yaml\` and respects the skill\'s per-skill packaging rules (\`excludeReferencesFromBundle\`, \`linkFollowDepth\`, \`files\`) to avoid false flags — but it never composes configs across project boundaries. Per-skill rules from one project do not bleed into skills in another project. For gated, configured-project-level validation, use the lifecycle commands (\`vat skills validate\`, \`vat verify\`) and run them from within the project directory.\n\n## Compatibility Analysis (\`--compat\`)\n\n\`\`\`bash\nvat audit ./plugins/ --compat\n\`\`\`\n\nOutput per plugin:\n\`\`\`yaml\nplugin: mission-control\ncompatibility:\n  claude-code:\n    compatible: true\n    evidence: []\n  cowork:\n    compatible: true\n    evidence: []\n  claude-desktop:\n    compatible: false\n    evidence:\n      - type: python-script\n        file: hooks-handlers/handler.py\n        detail: Python execution not available in claude-desktop\n\`\`\`\n\nUse this before a release to determine which surfaces each plugin supports.\n\n## Exit Codes\n\n\`vat audit\` is **advisory** — it reports every issue it detects but never blocks on validation severity:\n\n- \`0\` — always, when the audit completes, regardless of errors or warnings in the report.\n- \`2\` — system error (path not found, permission denied, etc.) — the audit could not run.\n\nFor gated checks that exit \`1\` on validation errors, use \`vat skills validate\` or \`vat skills build\` instead. Those commands apply \`validation.severity\` and honor \`validation.allow\` from config.\n\n## CI Usage\n\n\`\`\`yaml\n# vibe-validate.config.yaml\nsteps:\n  - name: Plugin and skill validation\n    command: vat audit plugins/ --exclude \"**/__pycache__/**\"\n\`\`\`\n\n## Interpreting Output\n\n\`\`\`yaml\nstatus: warning\nsummary:\n  filesScanned: 23\n  success: 21\n  warnings: 2\n  errors: 0\n\`\`\`\n\nSeverity taxonomy in audit output:\n- **Errors:** Missing required frontmatter, broken links, invalid plugin.json schema, link integrity violations\n- **Warnings:** Skill too long, description too short, best practice violations\n\nAudit always exits \`0\` regardless — surface-level severity drives display grouping only.\n\n**Hiding codes from audit output.** Audit ignores \`validation.allow\` by design (it is the read-only report), but it does honor \`validation.severity\`. Set a code to \`ignore\` in \`vibe-agent-toolkit.config.yaml\` to suppress it from the audit output:\n\n\`\`\`yaml\nskills:\n  config:\n    my-skill:\n      validation:\n        severity:\n          LINK_TO_NAVIGATION_FILE: ignore   # hidden from audit output\n\`\`\`\n\n**Per-instance allow entries.** For per-path suppression with an audit trail, use \`validation.allow\` and run \`vat skills validate\` or \`vat skills build\` — those commands apply \`allow\` and gate the build. See \`docs/validation-codes.md\` for the full code reference and the VAT agent-authoring skill for configuration patterns.\n";
 
 export const fragments = {
   runningTheAudit: {
@@ -20,6 +20,11 @@ export const fragments = {
     body: "Running \`vat audit <path>\` recursively walks the directory and auto-detects:\n\n| Found | Detected as |\n|---|---|\n| \`.claude-plugin/plugin.json\` in a dir | Claude Plugin |\n| \`.claude-plugin/marketplace.json\` in a dir | Claude Marketplace |\n| \`SKILL.md\` file | Agent Skill |\n| \`agent.yaml\` + \`SKILL.md\` | VAT Agent |\n| \`installed_plugins.json\` | Registry file |\n\nRecursion is the default — you do not need \`--recursive\`.",
     text: "## What Gets Detected (Automatic)\n\nRunning \`vat audit <path>\` recursively walks the directory and auto-detects:\n\n| Found | Detected as |\n|---|---|\n| \`.claude-plugin/plugin.json\` in a dir | Claude Plugin |\n| \`.claude-plugin/marketplace.json\` in a dir | Claude Marketplace |\n| \`SKILL.md\` file | Agent Skill |\n| \`agent.yaml\` + \`SKILL.md\` | VAT Agent |\n| \`installed_plugins.json\` | Registry file |\n\nRecursion is the default — you do not need \`--recursive\`."
   },
+  auditVsConfiguredVatProjects: {
+    header: "## Audit vs configured VAT projects",
+    body: "Audit is the general-purpose command — you may point it at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill\'s nearest-ancestor \`vibe-agent-toolkit.config.yaml\` and respects the skill\'s per-skill packaging rules (\`excludeReferencesFromBundle\`, \`linkFollowDepth\`, \`files\`) to avoid false flags — but it never composes configs across project boundaries. Per-skill rules from one project do not bleed into skills in another project. For gated, configured-project-level validation, use the lifecycle commands (\`vat skills validate\`, \`vat verify\`) and run them from within the project directory.",
+    text: "## Audit vs configured VAT projects\n\nAudit is the general-purpose command — you may point it at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill\'s nearest-ancestor \`vibe-agent-toolkit.config.yaml\` and respects the skill\'s per-skill packaging rules (\`excludeReferencesFromBundle\`, \`linkFollowDepth\`, \`files\`) to avoid false flags — but it never composes configs across project boundaries. Per-skill rules from one project do not bleed into skills in another project. For gated, configured-project-level validation, use the lifecycle commands (\`vat skills validate\`, \`vat verify\`) and run them from within the project directory."
+  },
   compatibilityAnalysis--Compat: {
     header: "## Compatibility Analysis (\`--compat\`)",
     body: "\`\`\`bash\nvat audit ./plugins/ --compat\n\`\`\`\n\nOutput per plugin:\n\`\`\`yaml\nplugin: mission-control\ncompatibility:\n  claude-code:\n    compatible: true\n    evidence: []\n  cowork:\n    compatible: true\n    evidence: []\n  claude-desktop:\n    compatible: false\n    evidence:\n      - type: python-script\n        file: hooks-handlers/handler.py\n        detail: Python execution not available in claude-desktop\n\`\`\`\n\nUse this before a release to determine which surfaces each plugin supports.",

package/dist/skills/vat-adoption-and-configuration/SKILL.md

@@ -47,7 +47,7 @@ my-skills-project/
 
 Three conventions are load-bearing:
 
-1. **`vibe-agent-toolkit.config.yaml` at the project root** — VAT walks upward from the invocation directory to find it.
+1. **`vibe-agent-toolkit.config.yaml` at the project root** — VAT commands pick up this file when run from the project root or a subdirectory.
 2. **SKILL.md files live under `resources/skills/`** — any path works, but this one is what `vat build` and `vat audit` expect by default.
 3. **`dist/` is the only write target** — everything VAT generates goes there, and it's gitignored.
 
@@ -105,6 +105,25 @@ Sections and the skills that own their details:
 
 When adding to a section, load the owning skill rather than re-deriving the shape from this file.
 
+## Config lives at the VAT project root
+
+A VAT project is a directory that contains a `vibe-agent-toolkit.config.yaml`. That file is authoritative for the project: it defines `resources`, `skills`, `claude`, and (optionally) `rag`. Nothing outside the config contributes to its behavior — there is no ambient configuration, no inheritance from parent directories, and no merge with sibling configs.
+
+VAT commands (`vat build`, `vat verify`, `vat skills validate`, `vat skills build`) read the config at the directory they are invoked from. Run them from the project root or from a subdirectory, or pass `--cwd <path>` to point them at a specific project. If you run a lifecycle command from somewhere that has no config, it will not find one — there is no upward walk here.
+
+**Multiple `vibe-agent-toolkit.config.yaml` files in one git repository mean multiple distinct VAT projects.** Each project is independent: configs do not compose, do not merge, and do not inherit from one another. Running VAT from outside any project directory operates on a union of whatever projects it discovers, but each project's rules are applied only to its own skills — per-skill packaging overrides in `project-a/vibe-agent-toolkit.config.yaml` never affect skills under `project-b/`.
+
+`vat audit` is the one command that knowingly spans projects, and even there it does not compose: audit is a general-purpose read-only scan that you may point at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill's nearest-ancestor `vibe-agent-toolkit.config.yaml` and applies **only** that skill's packaging rules (from its own project's `skills.config.<name>`) to the finding. This is display sanity, not federation — audit never merges config data across project boundaries.
+
+In practice, prefer one `vibe-agent-toolkit.config.yaml` per git repository. Multiple configs in a single repo are reasonable only for:
+
+- Committed test harnesses or fixtures that define their own toy VAT projects (for VAT's own tests, or for an adopter's integration tests).
+- Genuinely unrelated projects that happen to share a monorepo and each ship their own skills.
+
+If you are tempted to use nested configs to "share" or "override" settings across related skills, fold everything into one project-level config instead — that's what `skills.defaults` and `skills.config.<name>` are for.
+
+(Note: `agent.yaml`, the manifest for TypeScript portable agents, is a separate surface with its own rules and is out of scope for this guidance — see `vibe-agent-toolkit:vat-agent-authoring`.)
+
 ## `package.json` Wiring
 
 For projects that publish skills via npm, three fields tie VAT into the npm lifecycle:

package/dist/skills/vat-audit/SKILL.md

@@ -41,6 +41,10 @@ Running `vat audit <path>` recursively walks the directory and auto-detects:
 
 Recursion is the default — you do not need `--recursive`.
 
+## Audit vs configured VAT projects
+
+Audit is the general-purpose command — you may point it at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill's nearest-ancestor `vibe-agent-toolkit.config.yaml` and respects the skill's per-skill packaging rules (`excludeReferencesFromBundle`, `linkFollowDepth`, `files`) to avoid false flags — but it never composes configs across project boundaries. Per-skill rules from one project do not bleed into skills in another project. For gated, configured-project-level validation, use the lifecycle commands (`vat skills validate`, `vat verify`) and run them from within the project directory.
+
 ## Compatibility Analysis (`--compat`)
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/vat-development-agents",
-  "version": "0.1.33-rc.2",
+  "version": "0.1.33",
   "description": "VAT development agents - dogfooding the vibe-agent-toolkit",
   "type": "module",
   "keywords": [
@@ -67,13 +67,13 @@
     "postinstall": "vat claude plugin install --npm-postinstall || exit 0"
   },
   "dependencies": {
-    "@vibe-agent-toolkit/agent-schema": "0.1.33-rc.2",
-    "@vibe-agent-toolkit/cli": "0.1.33-rc.2",
+    "@vibe-agent-toolkit/agent-schema": "0.1.33",
+    "@vibe-agent-toolkit/cli": "0.1.33",
     "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
-    "@vibe-agent-toolkit/resource-compiler": "0.1.33-rc.2",
+    "@vibe-agent-toolkit/resource-compiler": "0.1.33",
     "ts-patch": "^3.2.1",
     "typescript": "^5.7.3"
   },