@vibe-agent-toolkit/cli 0.2.0-rc.10 → 0.2.0-rc.12

package/docs/mcp.md

@@ -24,13 +24,31 @@ vat mcp list-collections [options]
 **Options:**
 - `--debug` - Enable debug logging
 
-**Output:**
-Lists all known packages that export MCP agent collections.
+**Output:** the report envelope as YAML on stdout (schema
+`packages/cli/schemas/mcp-list-collections.json`): `status: ok`, `examined: 1` (the built-in
+package list read), and `data.packages`, each package's `name` and `description`. A human listing
+with usage examples goes to stderr.
+
+**Exit Codes:**
+- `0` - Listed
+- `2` - `error` (`INTERNAL_ERROR`: a VAT defect — the command takes no argument to mistake)
 
 **Example:**
 ```bash
 $ vat mcp list-collections
 
+# stdout:
+# ---
+# status: ok
+# examined: 1
+# findings: []
+# ...
+# data:
+#   packages:
+#     - name: "@vibe-agent-toolkit/vat-example-cat-agents"
+#       description: Example cat breeding agents (haiku validator, photo analyzer)
+
+# stderr:
 Available MCP agent packages:
 
   @vibe-agent-toolkit/vat-example-cat-agents
@@ -64,6 +82,15 @@ vat mcp serve <package> [options]
 - Runs until terminated (Ctrl+C)
 - Writes MCP protocol messages to stdout
 - Writes logs to stderr (does not interfere with protocol)
+- A failure (a package that does not resolve, a gateway that will not start)
+  writes its message to stderr — the stack too under `--debug` — and exits 2,
+  with nothing on stdout: stdout belongs to the protocol, so there is no
+  report document
+- `--print-config` writes the Claude Desktop config as JSON on stdout and
+  nothing else, so it can be redirected straight into a file; the
+  instructions around it go to stderr. Exits 0. The package is resolved
+  first, so one that does not load is the same failure as without the flag
+  (exit 2, nothing on stdout) — never a config for a server that cannot start
 
 **Example - Production:**
 ```bash
@@ -77,24 +104,24 @@ vat mcp serve ./packages/vat-example-cat-agents
 
 **Example - Show Configuration:**
 ```bash
-$ vat mcp serve @vibe-agent-toolkit/vat-example-cat-agents --print-config
-
-Claude Desktop configuration for '@vibe-agent-toolkit/vat-example-cat-agents':
-
-Add this to ~/.claude/config.json:
-
+$ vat mcp serve @vibe-agent-toolkit/vat-example-cat-agents --print-config 2>/dev/null
 {
   "mcpServers": {
-    "vat-example-cat-agents": {
+    "vat-vat-example-cat-agents": {
       "command": "vat",
-      "args": ["mcp", "serve", "@vibe-agent-toolkit/vat-example-cat-agents"]
+      "args": [
+        "mcp",
+        "serve",
+        "@vibe-agent-toolkit/vat-example-cat-agents"
+      ]
     }
   }
 }
-
-Then restart Claude Desktop to load the MCP server.
 ```
 
+Without the `2>/dev/null`, the terminal also shows the stderr instructions
+(which file to add it to, and to restart Claude Desktop).
+
 ## Claude Desktop Integration
 
 ### Configuration File
@@ -331,3 +358,28 @@ for terminology.
 - [MCP Gateway README](../../gateway-mcp/README.md)
 - [Example Cat Agents](../../vat-example-cat-agents/README.md)
 - [VAT Architecture](../../../docs/architecture/README.md)
+
+## Example reports
+
+Each block below is a real document from the built CLI, trimmed where noted; `packages/cli/test/integration/tagged-report-examples.integration.test.ts` validates every `vat-report=<verb>` block against that verb's registered schema.
+
+### `mcp list-collections`
+
+The MCP agent packages available. Produced by `vat mcp list-collections`.
+
+```yaml vat-report=mcp list-collections
+status: ok
+examined: 1
+findings: []
+summary:
+  errors: 0
+  warnings: 0
+  info: 0
+gate:
+  strict: false
+durationMs: 0
+data:
+  packages:
+    - name: "@vibe-agent-toolkit/vat-example-cat-agents"
+      description: Example cat breeding agents (haiku validator, photo analyzer)
+```

package/docs/rag.md

@@ -51,12 +51,12 @@ vat rag clear
 - `--db <path>` - Database path (default: `.rag-db` in project root)
 - `--debug` - Enable debug logging
 
-**Exit Codes:**
-- `0` - Indexing completed successfully
-- `1` - Indexed with errors: the run finished, `status: partial`, and `errors` names each resource whose content is NOT in the index — one the provider failed to chunk or embed, or one the crawl enumerated but could not read (a permission-denied file is reported here, never silently dropped)
-- `2` - System error (config invalid, database error, a `rag_documents` table whose columns an earlier build typed differently — the message names the columns and `vat rag clear` is the remedy, etc.)
+**Exit Codes:** derived from the published report (`status: ok | findings | error`)
+- `0` - `ok`: every submitted file is indexed, or skipped as unchanged
+- `1` - `findings`: the run finished and at least one file is NOT in the index — each is a `RAG_DOCUMENT_INDEX_FAILED` error finding located at its path, whether the provider failed to chunk or embed it or the crawl enumerated it and could not read it (a permission-denied file is reported here, never silently dropped). A run that found no file at all is a `RESOURCE_CHECK_BROKEN` finding: it examined nothing
+- `2` - `error`: the run could not do its job; `error.code` says why — `USAGE_INVALID` (a path argument that names nothing, or no `--db` and no project root), `INPUT_UNREADABLE` (a project `.rag-db` that is a file or a directory holding anything but a RAG database — a `--db` that is, or lies under, a file, or a `--db` directory holding anything but the tables `vat rag index` writes, is `USAGE_INVALID` naming the path and its entries; an empty directory, an existing RAG database, one holding only operating-system litter such as `.DS_Store`, and a path that does not exist yet are indexed into; on a refusal nothing is indexed or written; an existing database whose chunk table cannot be read is `INPUT_UNREADABLE` too, refused once rather than one finding per file, and the message names the cause — files the OS refuses, named with the errno (fix their permissions: clearing would fail on the same files), a table another tool or build wrote (its missing columns or vector size named), or damaged files; `vat rag clear` removes either of the last two), `RUN_INCOMPLETE` (the database directory cannot be examined, listed, created or written — a read-only parent, say: the database is what the verb writes), `CONFIG_INVALID`, `BACKEND_UNAVAILABLE` (the optional RAG backend is not installed; the message names the package), or `INTERNAL_ERROR` (a database error such as a `rag_documents` table whose columns an earlier build typed differently — the message names the columns and `vat rag clear` is the remedy)
 
-**Output:** YAML on stdout with indexing statistics
+**Output:** the report envelope as YAML on stdout (schema `packages/cli/schemas/rag-index.json`). `examined` counts the files submitted, read or not; `data` holds the counters.
 
 **Example:**
 ```bash
@@ -66,15 +66,19 @@ vat rag index docs/
 
 # Output:
 # ---
-# status: success
-# resourcesIndexed: 12
-# resourcesSkipped: 0
-# resourcesEmpty: 0      # frontmatter-only or blank files: counted, not stored
-# resourcesUpdated: 0
-# chunksCreated: 48
-# chunksDeleted: 0
-# duration: 2.4s
-# ---
+# status: ok
+# examined: 12
+# findings: []
+# summary: { errors: 0, warnings: 0, info: 0 }
+# gate: { strict: false }
+# durationMs: 2400
+# data:
+#   resourcesIndexed: 12
+#   resourcesSkipped: 0
+#   resourcesEmpty: 0      # frontmatter-only or blank files: counted, not stored
+#   resourcesUpdated: 0
+#   chunksCreated: 48
+#   chunksDeleted: 0
 ```
 
 **Incremental Updates:**
@@ -115,10 +119,10 @@ vat rag index docs/
 - `--debug` - Enable debug logging
 
 **Exit Codes:**
-- `0` - Query completed successfully
-- `2` - System error (no database, embedding error, etc.)
+- `0` - `ok`: the index was searched — a query matching nothing is `ok` with `chunks: []`
+- `2` - `error`: `INPUT_UNREADABLE` when nothing is indexed yet — no project database, no chunk table, or a table of zero chunks, one outcome every way (run `vat rag index`) — or when the database directory cannot be read; `USAGE_INVALID` with no `--db` and no project root, or a `--db` that is not a RAG database — nothing there, a file, or a directory holding anything but the tables `vat rag index` writes, operating-system litter such as `.DS_Store` aside (nothing is read, created or removed; the project's own `.rag-db` holding anything else is `INPUT_UNREADABLE`); `BACKEND_UNAVAILABLE`; or `INTERNAL_ERROR` (an embedding failure). A chunk table that cannot be read is `INPUT_UNREADABLE`, the message naming the cause: files the OS refuses (named with the errno — fix their permissions), a table another tool or build wrote, or damaged files — a table manifest that will not open, or data files that will not read; `vat rag clear` removes either of the last two
 
-**Output:** YAML on stdout with query results
+**Output:** the report envelope as YAML on stdout (schema `packages/cli/schemas/rag-query.json`). `examined` counts the chunks in the index searched; `data` holds `root` (the directory every `filePath` is relative to), `query`, `stats` and `chunks`.
 
 **Example:**
 ```bash
@@ -126,15 +130,19 @@ vat rag query "error handling patterns" --limit 5
 
 # Output:
 # ---
-# status: success
-# query: error handling patterns
-# stats:
-#   totalMatches: 5
-#   searchDurationMs: 62
-#   embedding:
-#     model: Xenova/all-MiniLM-L6-v2
-# duration: 65ms
-# chunks:
+# status: ok
+# examined: 48
+# findings: []
+# ...
+# data:
+#   root: /path/to/project
+#   query: error handling patterns
+#   stats:
+#     totalMatches: 5
+#     searchDurationMs: 62
+#     embedding:
+#       model: Xenova/all-MiniLM-L6-v2
+#   chunks:
 #   - chunkId: doc1-chunk2
 #     resourceId: doc1-hash
 #     filePath: docs/guide.md
@@ -166,7 +174,7 @@ Each chunk includes comprehensive metadata:
 - `resourceId` - ID of source document (content-based hash)
 
 **Location:**
-- `filePath` - Path to source markdown file
+- `filePath` - Path to source markdown file, relative to `data.root`
 - `headingPath` - Full heading hierarchy (e.g., "Guide > Setup > Installation")
 - `headingLevel` - Markdown heading level (1-6)
 - `startLine` / `endLine` - Line numbers in source file
@@ -180,7 +188,7 @@ Each chunk includes comprehensive metadata:
 - `contentHash` - Hash of chunk content (for change detection)
 - `tokenCount` - Approximate token count for this chunk
 - `embeddingModel` - Model used to generate embedding
-- `embeddedAt` - Timestamp when embedding was created
+- `embeddedAt` - ISO 8601 timestamp when the embedding was created
 
 **Context:**
 - `previousChunkId` - ID of previous chunk in same document (if exists)
@@ -204,10 +212,12 @@ Each chunk includes comprehensive metadata:
 - `--debug` - Enable debug logging
 
 **Exit Codes:**
-- `0` - Stats retrieved successfully
-- `2` - System error (no database exists)
+- `0` - `ok`: the database was read — an existing database that holds nothing reports zeros
+- `2` - `error`: `USAGE_INVALID` with no `--db` and no project root, or a `--db` that is not a RAG database — nothing there, a file, or a directory holding anything but the tables `vat rag index` writes, operating-system litter such as `.DS_Store` aside (nothing is read, created or removed); `INPUT_UNREADABLE` when the project has no database yet (run `vat rag index`), its `.rag-db` is a file or holds anything else, or the database cannot be read (a directory the OS will not list; a chunk table whose files the OS refuses, named with the errno — fix their permissions; or one another tool or build wrote, or whose manifests or data files are damaged — `vat rag clear` removes those); `BACKEND_UNAVAILABLE`; or `INTERNAL_ERROR`
 
-**Output:** YAML on stdout with database statistics
+`vat rag stats` only reads: it never creates the database it is asked about.
+
+**Output:** the report envelope as YAML on stdout (schema `packages/cli/schemas/rag-stats.json`); `examined` is 1, the database opened.
 
 **Example:**
 ```bash
@@ -215,14 +225,16 @@ vat rag stats
 
 # Output:
 # ---
-# status: success
-# totalChunks: 48
-# totalResources: 12
-# dbSizeBytes: 0
-# embeddingModel: Xenova/all-MiniLM-L6-v2
-# lastIndexed: 2025-12-29T10:30:45.123Z
-# duration: 15ms
-# ---
+# status: ok
+# examined: 1
+# findings: []
+# ...
+# data:
+#   totalChunks: 48
+#   totalResources: 12
+#   dbSizeBytes: 0
+#   embeddingModel: Xenova/all-MiniLM-L6-v2
+#   lastIndexed: 2025-12-29T10:30:45.123Z
 ```
 
 **Field Descriptions:**
@@ -237,8 +249,8 @@ vat rag stats
 **Purpose:** Delete entire RAG database directory
 
 **What it does:**
-1. Closes database connection
-2. Deletes entire database directory (`.rag-db/` by default)
+1. Checks the path is a RAG database (refuses anything else)
+2. Deletes entire database directory (`.rag-db/` by default), without opening it
 3. Removes all indexed data and embeddings
 4. Cannot be undone - use with caution
 
@@ -253,10 +265,12 @@ vat rag stats
 - `--debug` - Enable debug logging
 
 **Exit Codes:**
-- `0` - Database cleared successfully
-- `2` - System error
+- `0` - `ok`: the database was cleared
+- `2` - `error`: `USAGE_INVALID` with no `--db` and no project root, or a `--db` that is not a RAG database — nothing there, a file, a symbolic link (the refusal names the real path to clear), or a directory holding anything but the tables `vat rag index` writes (nothing is read, created or removed); `INPUT_UNREADABLE` when the project has no database to clear, or its `.rag-db` is a file, a link or holds anything else; `RUN_INCOMPLETE` when the database directory cannot be examined or listed (it is what the verb removes), or the OS stopped the removal partway (part of the database may be gone — make it writable and clear again); `BACKEND_UNAVAILABLE`; or `INTERNAL_ERROR`
 
-**Output:** YAML on stdout with confirmation
+`vat rag clear` removes a database without opening it, so a database whose files are damaged can still be cleared. It removes only a directory holding nothing but the tables `vat rag index` writes (or nothing at all), operating-system litter such as `.DS_Store`, `Thumbs.db`, `desktop.ini` and `._*` files aside (regular files only, and each must start with the bytes the OS writes into it — the AppleDouble header for `._*`, Finder's `Bud1` header for `.DS_Store`, an OLE compound-file header for `Thumbs.db`; `desktop.ini` has none, so its name decides. A `._notes` file of your own, or a directory or symbolic link carrying one of those names, is the user's, and makes the directory not a database); any other directory is refused and left as it is, and so is a symbolic link to a database — removing the link would leave the database in place.
+
+**Output:** the report envelope as YAML on stdout (schema `packages/cli/schemas/rag-clear.json`); `examined` is 1, the database removed, and `data` is `{ cleared: true }`.
 
 **Example:**
 ```bash
@@ -264,10 +278,12 @@ vat rag clear
 
 # Output:
 # ---
-# status: success
-# message: Database cleared
-# duration: 12ms
-# ---
+# status: ok
+# examined: 1
+# findings: []
+# ...
+# data:
+#   cleared: true
 ```
 
 **Warning:** This operation is **permanent and cannot be undone**. The entire
@@ -471,3 +487,115 @@ for terminology.
 - **Issues:** https://github.com/jdutton/vibe-agent-toolkit/issues
 - **Embedding Model:** https://huggingface.co/Xenova/all-MiniLM-L6-v2
 - **LanceDB:** https://lancedb.com
+
+## Example reports
+
+Each block below is a real document from the built CLI, trimmed where noted; `packages/cli/test/integration/tagged-report-examples.integration.test.ts` validates every `vat-report=<verb>` block against that verb's registered schema.
+
+### `rag index`
+
+Two markdown files indexed. Produced by `vat rag index knowledge --db .rag-db`.
+
+```yaml vat-report=rag index
+status: ok
+examined: 2
+findings: []
+summary:
+  errors: 0
+  warnings: 0
+  info: 0
+gate:
+  strict: false
+durationMs: 14560
+data:
+  resourcesIndexed: 2
+  resourcesSkipped: 0
+  resourcesEmpty: 0
+  resourcesUpdated: 0
+  chunksCreated: 2
+  chunksDeleted: 0
+```
+
+### `rag stats`
+
+The index just built. Produced by `vat rag stats --db .rag-db`.
+
+```yaml vat-report=rag stats
+status: ok
+examined: 1
+findings: []
+summary:
+  errors: 0
+  warnings: 0
+  info: 0
+gate:
+  strict: false
+durationMs: 246
+data:
+  totalChunks: 2
+  totalResources: 2
+  dbSizeBytes: 16318
+  embeddingModel: Xenova/all-MiniLM-L6-v2
+  lastIndexed: 2026-10-04T00:30:54.226Z
+```
+
+### `rag query`
+
+One match; each hit is under `data.chunks`. Produced by `vat rag query "when do I file an expense report" --db .rag-db --limit 1`.
+
+```yaml vat-report=rag query
+status: ok
+examined: 2
+findings: []
+summary:
+  errors: 0
+  warnings: 0
+  info: 0
+gate:
+  strict: false
+durationMs: 996
+data:
+  root: /work/project
+  query: when do I file an expense report
+  stats:
+    totalMatches: 1
+    searchDurationMs: 920
+    embedding:
+      model: Xenova/all-MiniLM-L6-v2
+  chunks:
+    - chunkId: knowledge-playbooks-expenses-md-chunk-0
+      resourceId: knowledge-playbooks-expenses-md
+      filePath: knowledge/playbooks/expenses.md
+      headingPath: Expense reports
+      headingLevel: 1
+      startLine: 5
+      endLine: 8
+      type: playbook
+      contentHash: 2d7cb5f57ef71b95a61bb71d5c8a550a1cf1841936205a605c465422663b8d27
+      tokenCount: 10
+      embeddingModel: Xenova/all-MiniLM-L6-v2
+      embeddedAt: 2026-10-04T00:22:49.099Z
+      content: |-
+        # Expense reports
+
+        File within 30 days.
+```
+
+### `rag clear`
+
+The index removed. Produced by `vat rag clear --db .rag-db`.
+
+```yaml vat-report=rag clear
+status: ok
+examined: 1
+findings: []
+summary:
+  errors: 0
+  warnings: 0
+  info: 0
+gate:
+  strict: false
+durationMs: 57
+data:
+  cleared: true
+```