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

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

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `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

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-rc.3",
   "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-rc.3",
   "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-rc.3",
+    "@vibe-agent-toolkit/cli": "0.1.33-rc.3",
     "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-rc.3",
     "ts-patch": "^3.2.1",
     "typescript": "^5.7.3"
   },