@vibe-agent-toolkit/cli 0.1.36 → 0.1.38

package/docs/rag.md

@@ -441,6 +441,24 @@ vat rag index docs/
 2. Query too broad/vague → Be more specific
 3. Chunk boundaries split relevant content → Adjust chunk size (future feature)
 
+## Requirements
+
+| Subcommand | `projectRoot` | Config |
+|---|---|---|
+| `vat rag index [path]` | optional (tolerates absence — `--db` supplies the path directly) | required fields (`rag.*`) when `--db` is not supplied; otherwise unused |
+| `vat rag query <text>` | optional (`--db` overrides) | required file with `rag.*` for default db lookup |
+| `vat rag stats` | optional (`--db` overrides) | required file with `rag.*` for default db lookup |
+| `vat rag clear` | optional (`--db` overrides) | required file with `rag.*` for default db lookup |
+
+RAG commands are unusual: they tolerate a missing `projectRoot` because the
+caller can always specify `--db <path>` explicitly. But when `--db` is omitted,
+VAT needs `rag.*` config fields to locate the configured store. The two
+mechanisms are complementary — `--db` is for one-off use, `rag.*` config is for
+project-default behavior.
+
+See [Roots and Config — Canonical Concepts](../../../docs/concepts/roots-and-config.md)
+for terminology.
+
 ## More Information
 
 - **GitHub:** https://github.com/jdutton/vibe-agent-toolkit

package/docs/resources.md

@@ -53,6 +53,20 @@ vat resources scan docs/
 # ---
 ```
 
+**Requirements:**
+
+- **`projectRoot`**: optional with **loud-cwd fallback**. When invoked with an
+  explicit `[path]`, that path is the effective base. Without a path, VAT walks
+  up from `cwd` for `vibe-agent-toolkit.config.yaml` then `.git/`; if neither is
+  found, the command falls back to `cwd` and emits a single stderr warning
+  identifying the fallback. The scan still completes — the warning is the
+  contract that prevents silent surprise.
+- **Config**: optional. Uses built-in include/exclude defaults if no config file
+  is present.
+
+See [Roots and Config — Canonical Concepts](../../../docs/concepts/roots-and-config.md)
+for the loud-cwd fallback policy and the projectRoot discovery ladder.
+
 ### vat resources validate [path]
 
 **Purpose:** Validate markdown resources with strict error reporting
@@ -121,6 +135,30 @@ vat resources validate docs/
 # ---
 ```
 
+**Requirements:**
+
+- **`projectRoot`**: optional with **loud-cwd fallback**. With an explicit
+  `[path]` the path is used as the base directory; without it VAT walks for a
+  `vibe-agent-toolkit.config.yaml` then `.git/` ancestor, and falls back to
+  `cwd` with a stderr warning if neither is found.
+- **Config**: optional. Defaults are applied when no config file is present;
+  `--frontmatter-schema` is independent of config.
+
+**Leading-`/` URI-reference resolution.** Markdown body links and frontmatter
+URI-references whose path component starts with `/` (e.g.
+`[See](/docs/foo.md)`, `parent_spec: /docs/foo.md`) are RFC 3986 §4.2
+absolute-path references and are resolved against the discovered `projectRoot`.
+Once cwd-fallback has fired, the effective `projectRoot` is `cwd` and leading-`/`
+links resolve against `cwd` — consistent with the loud-cwd contract. The
+`absolute_no_root` failure mode fires only when `projectRoot` is genuinely
+undefined (e.g. a programmatic embedder that did not supply one); leading-`/`
+links that escape `projectRoot` via path traversal surface as
+`absolute_escapes_root`. Both surface as `broken_file` issues.
+
+See [Roots and Config — Canonical Concepts](../../../docs/concepts/roots-and-config.md)
+for the projectRoot ladder, the loud-cwd fallback policy, and the rationale
+behind RFC-3986-compliant leading-`/` resolution.
+
 ## Configuration
 
 Place `vibe-agent-toolkit.config.yaml` at project root:

package/docs/skills.md

@@ -128,6 +128,19 @@ vat skills validate --user
 vat skills validate packages/my-agent/resources/skills
 ```
 
+**Requirements:**
+
+- **`projectRoot`**: required. `vat skills validate` refuses to run if no
+  `vibe-agent-toolkit.config.yaml` or `.git/` ancestor is found. Source-mode
+  validation always runs against a real authoring boundary.
+- **Config**: optional. Falls back to built-in defaults if no config file is
+  present, but a `projectRoot` is still required to anchor link resolution and
+  the gitignore-safety gate.
+
+See [Roots and Config — Canonical Concepts](../../../docs/concepts/roots-and-config.md)
+for the discovery ladder, the loud-cwd fallback policy, and the CLI-boundary
+discovery rule that this command participates in.
+
 ---
 
 ### vat skills build
@@ -203,6 +216,18 @@ vat skills build --skill my-skill
 vat skills build --dry-run
 ```
 
+**Requirements:**
+
+- **`projectRoot`**: required. `vat skills build` refuses to run if no
+  `vibe-agent-toolkit.config.yaml` or `.git/` ancestor is found. This guards
+  against accidental builds outside a VAT project.
+- **Config**: required file with `skills.*` fields populated. The build
+  pipeline reads `skills.discovery` and `skills.config.*` directly — there are
+  no useful defaults for these.
+
+See [Roots and Config — Canonical Concepts](../../../docs/concepts/roots-and-config.md)
+for terminology.
+
 ---
 
 ### vat skills package <skill-path>
@@ -270,6 +295,18 @@ vat skills package SKILL.md -o dist --no-rewrite-links
 vat skills package SKILL.md -o dist -b /custom/base
 ```
 
+**Requirements:**
+
+- **`projectRoot`**: required. Packaging is an explicit-adoption operation and
+  is refused outside a discovered VAT project (no `vibe-agent-toolkit.config.yaml`
+  or `.git/` ancestor).
+- **Config**: required file with `skills.*` fields populated. Per-skill packaging
+  options (`skills.config.<name>`) drive link rewriting, bundle inclusion, and
+  validation overrides.
+
+See [Roots and Config — Canonical Concepts](../../../docs/concepts/roots-and-config.md)
+for terminology.
+
 ---
 
 ### vat skills install \<source\>
@@ -378,7 +415,17 @@ vat skills install ./dist/skills/my-skill --target claude --scope project
 **Post-Installation:**
 After installation, you need to:
 1. Restart Claude Code (or the target agent), or
-2. Run `/reload-skills` in Claude Code to load the new skill
+2. Run `/reload-plugins` in Claude Code to load the new skill
+
+**Requirements:**
+
+- **`projectRoot`**: N/A. `vat skills install` is a user-level operation that
+  installs into platform target directories (`~/.claude/skills/`,
+  `.claude/skills/`, etc.) regardless of where it is invoked.
+- **Config**: not used.
+
+See [Roots and Config — Canonical Concepts](../../../docs/concepts/roots-and-config.md)
+for terminology.
 
 ---
 
@@ -453,6 +500,17 @@ vat skills list packages/my-agent
 vat skills list --verbose
 ```
 
+**Requirements:**
+
+- **`projectRoot`**: optional. `vat skills list` tolerates a missing
+  `projectRoot`. With `--user` it scans user installation directories directly
+  and skips project-root discovery entirely.
+- **Config**: optional. Project mode honors config-defined include/exclude
+  patterns when present; defaults are used otherwise.
+
+See [Roots and Config — Canonical Concepts](../../../docs/concepts/roots-and-config.md)
+for terminology.
+
 ---
 
 ## Distribution Workflow
@@ -580,7 +638,7 @@ User: /my-skill
 - Use `--dry-run` to preview what will be installed before committing
 - Use `--force` flag carefully (overwrites existing skills)
 - Verify installation: `vat skills list --user`
-- Remember to restart the target agent or run `/reload-skills` in Claude Code
+- Remember to restart the target agent or run `/reload-plugins` in Claude Code
 
 ---
 
@@ -660,7 +718,7 @@ name: my-help  # Instead of "help"
 **Solution:**
 1. Verify installation: `vat skills list --user`
 2. Check location: Should be in `~/.claude/skills/` not `~/.claude/plugins/`
-3. Restart Claude Code or run `/reload-skills`
+3. Restart Claude Code or run `/reload-plugins`
 
 ### "Windows-style backslashes"
 **Problem:** Links use backslashes: `resources\SKILL.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/cli",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "Command-line interface for vibe-agent-toolkit",
   "type": "module",
   "bin": {
@@ -41,27 +41,26 @@
   "//dependencies-note": "DO NOT add example agent packages or adopter packages here. Adopter packages (like vat-development-agents) depend on the CLI binary at build time — declaring them as deps creates a circular build dependency. They are built in a second turbo pass via package#task overrides in turbo.json.",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.71.2",
-    "@vibe-agent-toolkit/agent-config": "0.1.36",
-    "@vibe-agent-toolkit/agent-schema": "0.1.36",
-    "@vibe-agent-toolkit/agent-skills": "0.1.36",
-    "@vibe-agent-toolkit/claude-marketplace": "0.1.36",
-    "@vibe-agent-toolkit/discovery": "0.1.36",
-    "@vibe-agent-toolkit/gateway-mcp": "0.1.36",
-    "@vibe-agent-toolkit/rag": "0.1.36",
-    "@vibe-agent-toolkit/rag-lancedb": "0.1.36",
-    "@vibe-agent-toolkit/resources": "0.1.36",
-    "@vibe-agent-toolkit/utils": "0.1.36",
+    "@vibe-agent-toolkit/agent-config": "0.1.38",
+    "@vibe-agent-toolkit/agent-schema": "0.1.38",
+    "@vibe-agent-toolkit/agent-skills": "0.1.38",
+    "@vibe-agent-toolkit/claude-marketplace": "0.1.38",
+    "@vibe-agent-toolkit/discovery": "0.1.38",
+    "@vibe-agent-toolkit/gateway-mcp": "0.1.38",
+    "@vibe-agent-toolkit/rag": "0.1.38",
+    "@vibe-agent-toolkit/rag-lancedb": "0.1.38",
+    "@vibe-agent-toolkit/resources": "0.1.38",
+    "@vibe-agent-toolkit/utils": "0.1.38",
     "adm-zip": "^0.5.16",
     "commander": "^12.1.0",
-    "js-yaml": "^4.1.0",
     "picomatch": "^4.0.3",
     "semver": "^7.7.3",
     "tar": "^7.5.7",
+    "yaml": "^2.6.1",
     "zod": "^3.24.1"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.7",
-    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.10.5",
     "@types/picomatch": "^4.0.2",
     "@types/semver": "^7.7.1",

package/dist/utils/project-root.d.ts

@@ -1,30 +0,0 @@
-/**
- * Project root detection utility
- * Walks up directory tree to find .git or vibe-agent-toolkit.config.yaml
- *
- * Environment Variables:
- * - VAT_TEST_ROOT: Override project root for testing (bypasses detection)
- */
-/**
- * Find project root by walking up directory tree
- *
- * @param startDir - Directory to start search from
- * @returns Project root path or null if not found
- *
- * @remarks
- * Can be overridden with VAT_TEST_ROOT environment variable for testing.
- * This allows tests to specify an exact project root without relying on
- * directory structure (.git or config file presence).
- *
- * @example
- * ```typescript
- * // Normal usage
- * const root = findProjectRoot(process.cwd());
- *
- * // Test usage with override
- * process.env.VAT_TEST_ROOT = '/path/to/test/fixtures';
- * const root = findProjectRoot(process.cwd()); // Returns /path/to/test/fixtures
- * ```
- */
-export declare function findProjectRoot(startDir: string): string | null;
-//# sourceMappingURL=project-root.d.ts.map

package/dist/utils/project-root.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"project-root.d.ts","sourceRoot":"","sources":["../../src/utils/project-root.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA+B/D"}

package/dist/utils/project-root.js

@@ -1,59 +0,0 @@
-/**
- * Project root detection utility
- * Walks up directory tree to find .git or vibe-agent-toolkit.config.yaml
- *
- * Environment Variables:
- * - VAT_TEST_ROOT: Override project root for testing (bypasses detection)
- */
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { safePath } from '@vibe-agent-toolkit/utils';
-/**
- * Find project root by walking up directory tree
- *
- * @param startDir - Directory to start search from
- * @returns Project root path or null if not found
- *
- * @remarks
- * Can be overridden with VAT_TEST_ROOT environment variable for testing.
- * This allows tests to specify an exact project root without relying on
- * directory structure (.git or config file presence).
- *
- * @example
- * ```typescript
- * // Normal usage
- * const root = findProjectRoot(process.cwd());
- *
- * // Test usage with override
- * process.env.VAT_TEST_ROOT = '/path/to/test/fixtures';
- * const root = findProjectRoot(process.cwd()); // Returns /path/to/test/fixtures
- * ```
- */
-export function findProjectRoot(startDir) {
-    // Override for testing: VAT_TEST_ROOT bypasses detection
-    if (process.env['VAT_TEST_ROOT']) {
-        return process.env['VAT_TEST_ROOT'];
-    }
-    let current = safePath.resolve(startDir);
-    const root = path.parse(current).root;
-    while (current !== root) {
-        // Check for .git directory
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- path walking is intentional
-        if (fs.existsSync(safePath.join(current, '.git'))) {
-            return current;
-        }
-        // Check for config file
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- path walking is intentional
-        if (fs.existsSync(safePath.join(current, 'vibe-agent-toolkit.config.yaml'))) {
-            return current;
-        }
-        // Move up one directory
-        const parent = path.dirname(current);
-        if (parent === current) {
-            break; // Reached root
-        }
-        current = parent;
-    }
-    return null;
-}
-//# sourceMappingURL=project-root.js.map

package/dist/utils/project-root.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"project-root.js","sourceRoot":"","sources":["../../src/utils/project-root.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,yDAAyD;IACzD,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC;QACjC,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC;IAEtC,OAAO,OAAO,KAAK,IAAI,EAAE,CAAC;QACxB,2BAA2B;QAC3B,kGAAkG;QAClG,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;YAClD,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,wBAAwB;QACxB,kGAAkG;QAClG,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,gCAAgC,CAAC,CAAC,EAAE,CAAC;YAC5E,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,wBAAwB;QACxB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,MAAM,CAAC,eAAe;QACxB,CAAC;QACD,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}