@jmoak/vibrissa 0.1.0 → 2.0.0-alpha.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Jordan Moak
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Jordan Moak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,315 +1,329 @@
-## vibrissa (whisker) — JSON‑Driven MCP Integration Test Runner
+# vibrissa
 
-End‑to‑end test your MCP server over stdio using declarative JSON cases. Ship stable, contract‑focused integration suites that humans can review and LLMs can author.
+> *vibrissa* (n.): a whisker; a sensory organ for probing the world.
 
-### Why Vibrissa?
-- Integration‑first: validates real I/O over MCP stdio
-- JSON cases: simple, diff‑friendly, easy to generate
-- Powerful matching: exact, partial, regex, wildcard, unordered arrays
-- Flexible: CLI (`vib-test`) or library API
+**Contract testing for MCP servers.** Record real responses as JSON, replay them in CI,
+lock your tool manifest, fuzz your schemas. No test code: the whole suite is data.
 
-### Requirements
-- Node.js >= 20
-- ESM-only package (use `import`, not `require`)
+[![npm](https://img.shields.io/npm/v/%40jmoak%2Fvibrissa?color=cb3837&label=npm)](https://www.npmjs.com/package/@jmoak/vibrissa)
+[![CI](https://github.com/JMoak/vibrissa/actions/workflows/ci.yml/badge.svg)](https://github.com/JMoak/vibrissa/actions/workflows/ci.yml)
+[![node >= 20](https://img.shields.io/badge/node-%E2%89%A5%2020-3c873a)](https://nodejs.org)
+[![MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
-### Install
-```bash
-npm i -D @jmoak/vibrissa
-```
+Vibrissa drives your server over stdio or Streamable HTTP, speaks both MCP 2026-07-28
+and the 2025 revisions, and diffs every tool, resource, and prompt result against
+committed JSON. It also snapshots the server's whole surface into a lock file, so a
+changed schema or a quietly rewritten tool description fails the PR instead of reaching
+a client.
 
-### Quickstart
 ```bash
 npm i -D @jmoak/vibrissa
-vib init
-# edit vibrissa.json server block if needed
-vib tools
-vib call echo --arg text=hello --arg uppercase=true
-vib record echo --arg text=hello --arg uppercase=true --name "echo uppercase"
-vib run
+npx vib init                      # vibrissa.json + a real sample case from your server
+npx vib discover                  # protocol era, capabilities, identity
+npx vib tools                     # what the server exposes
+npx vib call echo --arg text=hello
+npx vib record echo --arg text=hello --name "echo hello"
+npx vib manifest record           # lock the surface
+npx vib run                       # replay every case: the CI gate
+npx vib check                     # spec sanity + description lint
+npx vib fuzz echo --runs 200      # schema-driven fuzzing
 ```
 
-Or scaffold by hand:
+Releases ship through npm [trusted publishing](https://docs.npmjs.com/trusted-publishers/)
+with provenance: each version links to the commit and workflow that built it.
 
-1) Create `vibrissa.json` in your MCP server repo (root):
-```json
-{
-  "$schema": "./node_modules/@jmoak/vibrissa/schema/vibrissa.schema.json",
-  "server": { "cmd": "node", "args": ["dist/index.js"] },
-  "globs": ["tests/integration/**/*.json"]
-}
-```
+---
+
+## Why
+
+MCP testing has sorted itself into layers:
+
+| Layer | Question | Tools |
+|---|---|---|
+| 0: Conformance | Does the server speak the spec? | official conformance suite; `vib check` covers the deterministic subset |
+| **1: Contract** | **Given these args, does this server return this?** | **Vibrissa** |
+| 2: Robustness | Fuzzing, poisoning, rug pulls | `vib fuzz`, `vib check`, manifest lock (deterministic subset) |
+| 3: Model evals | Does an LLM pick the right tool? | eval platforms; out of core by design |
+
+Vibrissa owns Layer 1 and absorbs the deterministic halves of 0 and 2. No LLM in the
+critical path, no accounts, no hosted anything: CI gates are reproducible and the loop is
+sub-second.
+
+The 2026-07-28 revision rewrote the core. Each change lands on what a contract tester
+must do:
+
+| 2026-07-28 change | Vibrissa |
+|---|---|
+| `initialize` replaced by `server/discover` | `protocol: auto` negotiates either era |
+| `resultType` + `_meta` serverInfo on every result | normalized away; old goldens stay green |
+| Multi Round-Trip Requests (`input_required`) | `respond` scripts the answers |
+| No protocol sessions; state in server-minted handles | flows with `capture` and `{{name}}` |
+| Deterministic `tools/list` with cache hints | manifest lock; `vib check` |
+| JSON Schema 2020-12 `outputSchema` | enforced on every call |
+| Tasks extension with `tasks/get` polling | `await`, `expectTask` |
+| Renumbered error codes | stable code names on both eras |
+
+## The loop
+
+| Step | Command | What it does |
+|---|---|---|
+| explore | `vib discover`, `vib tools`, `vib resources`, `vib prompts` | see the surface |
+| probe | `vib call <tool>`, `vib read <uri>`, `vib get-prompt <name>` | one live request, printed |
+| capture | `vib record ...`, `vib tap -- <server>` | real responses become golden cases |
+| gate | `vib run` | replay everything, diff the manifest; non-zero on any mismatch |
+| harden | `vib check`, `vib fuzz <tool>` | spec sanity, poisoning lint, generated edge cases |
+
+Every command except `tap` takes `--json`. [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector)
+is still the place to click around: `vib inspect` opens it with your config.
+
+## Anatomy of a case
+
+The v1 shape is still the core shape. `tests/integration/echo.basic.json`:
 
-2) Create a case: `tests/integration/echo.basic.json`
 ```json
 {
   "name": "echo basic",
   "tool": "echo",
-  "args": {
-    "text": "hello",
-    "uppercase": true
-  },
-  "expect": {
-    "content": [
-      {
-        "type": "text",
-        "text": "HELLO"
-      }
-    ]
-  }
+  "args": { "text": "hello" },
+  "expect": { "content": [{ "type": "text", "text": "hello" }] }
 }
 ```
 
-3) Run
-```bash
-vib-test run
-```
+`expect` is exact deep equality over the normalized result unless a matcher says
+otherwise. `resource`, `resourceTemplate`, and `prompt` work the same way as `tool`.
 
-Optional: add an NPM script
-```json
-{
-  "scripts": {
-    "test:integration": "vib-test run"
-  }
-}
-```
+**A flow** chains steps on one session and passes values forward:
 
-### Test Case Semantics
-- Default is exact deep equality.
-- Partial
-```json
-{
-  "expect": {
-    "$partial": true,
-    "content": [
-      {
-        "type": "text"
-      }
-    ]
-  }
-}
-```
-- Regex
-```json
-{
-  "expect": {
-    "content": [
-      {
-        "type": "text",
-        "text": {
-          "$regex": "^hel+o$",
-          "flags": "i"
-        }
-      }
-    ]
-  }
-}
-```
-- Wildcard (glob‑like)
-```json
-{
-  "expect": {
-    "content": [
-      {
-        "type": "text",
-        "text": {
-          "$wildcard": "hel*o"
-        }
-      }
-    ]
-  }
-}
-```
-- Unordered arrays
 ```json
 {
-  "expect": {
-    "content": {
-      "$unordered": true,
-      "value": [
-        {
-          "type": "text"
-        }
-      ]
+  "name": "sum flows into echo",
+  "steps": [
+    { "tool": "typed", "args": { "a": 2, "b": 3 }, "capture": { "sum": "structuredContent.sum" } },
+    {
+      "tool": "echo",
+      "args": { "text": "sum is {{sum}}" },
+      "expect": { "content": [{ "type": "text", "text": "sum is 5" }] }
     }
-  }
+  ]
 }
 ```
-- Error expectations
+
+**An MRTR case** answers the server's question and asserts it was asked:
+
 ```json
 {
-  "expectError": {
-    "code": "InvalidParams",
-    "message": {
-      "$regex": "Invalid.*echo"
-    }
-  }
+  "name": "confirm deploy",
+  "tool": "confirm",
+  "args": { "action": "deploy" },
+  "respond": { "elicitation/create": { "action": "accept", "content": { "confirm": true } } },
+  "expectInputRequired": { "$partial": true, "elicitation/create": { "message": "Proceed with deploy?" } },
+  "expect": { "content": [{ "type": "text", "text": "confirmed: deploy" }] }
 }
 ```
 
-Note: `expect` is matched against the **entire** `tools/call` result object. If your server
-returns fields beyond `content` (e.g. `structuredContent`, `_meta`), an exact match will fail
-with an "unexpected key" mismatch — either include those fields in `expect` or set
-`"$partial": true` to assert only the fields you care about. `vib record` captures the full
-result, so recorded cases are always exact-match ready.
+Also: `setup` / `teardown`, `await` for long-running tasks, `budgetMs`, `tags`, `skip`,
+`flaky`, per-case `server`, `$ref` fragments. Every key: [docs/CASES.md](./docs/CASES.md).
+
+## Matchers
+
+Matchers nest anywhere in an expectation. Several in one object must all pass.
+
+| Matcher | Example | Asserts |
+|---|---|---|
+| `$partial` | `{"$partial": true, "isError": false}` | only the fields you name |
+| `$regex` | `{"$regex": "^hel+o$", "flags": "i"}` | pattern match |
+| `$wildcard` | `{"$wildcard": "req_*"}` | glob match |
+| `$unordered` | `{"$unordered": true, "value": [1, 2]}` | array in any order |
+| `$any` / `$ignore` | `{"$any": true}` | present / don't care |
+| `$type` | `{"$type": ["string", "null"]}` | JSON type |
+| `$schema` | `{"$schema": {"type": "string", "format": "date-time"}}` | inline JSON Schema |
+| `$oneOf` | `{"$oneOf": ["queued", "running"]}` | any alternative |
+| `$contains` | `{"$contains": {"type": "image"}, "count": 1}` | some element matches |
+| `$length` / `$number` | `{"$length": {"min": 1}}` | sizes and ranges |
+| `$ref` | `{"$ref": "./shared/user.json"}` | reuse a fragment |
+| `$literal` | `{"$literal": {"$ref": "#/a"}}` | data that looks like a matcher |
+
+`expectError` asserts that a call fails correctly:
+`{"code": "InvalidParams", "message": {"$regex": "text"}}`. Full reference:
+[docs/MATCHERS.md](./docs/MATCHERS.md).
+
+## Manifest lock
+
+`vib manifest record` snapshots `server/discover`, `tools/list`, `resources/list`,
+`resources/templates/list`, and `prompts/list` into
+`tests/integration/__manifest__.json`. From then on `vib run` diffs the live surface
+against it and fails on added or removed tools, changed input or output schemas, changed
+annotations, changed capabilities, and **changed descriptions**.
+
+It is `package-lock.json` for your MCP surface. It also catches rug pulls: a tool
+description that changes after review, the move behind tool-poisoning attacks, shows up
+as a reviewed diff in git instead of a silent change. Each change is marked breaking or
+not (a removed property or a newly required one is; a reworded description is drift, but
+not breaking), with a word diff for prose. Accept intended changes with
+`vib run --update-manifest` and commit the lock with the PR that caused them. One lock
+serves both protocol eras; `requireManifest: true` makes a missing lock fail CI.
+
+## Checks and fuzz
+
+**`vib check`** runs offline checks over the manifest: `spec/*` sanity (known protocol
+version, deterministic `tools/list`, cache hints, valid 2020-12 schemas, resolvable
+`$ref`s) and `desc/*` lint for hidden instructions, invisible Unicode, tool shadowing,
+credential paths, and exfiltration URLs in model-visible text. It is a smoke detector,
+not a scanner. `vib run --check` folds it into CI. Ids and allow-listing:
+[docs/CHECKS.md](./docs/CHECKS.md).
+
+**`vib fuzz <tool>`** generates arguments from the tool's `inputSchema`: valid,
+boundary, invalid, and (with `--inject`) prompt-injection payloads. It checks invariants
+that need no golden: valid args never cause a protocol error, invalid args get
+`InvalidParams`, the server never crashes. Seeded and reproducible;
+`--record-failures` writes each counterexample as a case. See [docs/FUZZ.md](./docs/FUZZ.md).
+
+## Reporters and CI
+
+Reporters: `console` (default), `json` (`reports/results.json`), `junit`
+(`reports/junit.xml`), `github` (annotations + job summary), `tap`. Use several at once.
+
+```yaml
+# .github/workflows/vibrissa.yml (vib init --ci writes this)
+name: vibrissa
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: npm }
+      - run: npm ci
+      - run: npm run build --if-present
+      - run: npx vib run --profile ci
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with: { name: vibrissa-reports, path: reports/ }
+```
+
+**Delta gating:** `vib run --baseline reports/last-green.json` fails only on regressions
+against a previous green run, so a known-broken case does not block unrelated PRs.
+`--repeat 5` measures flake rates, `--shard 2/4` splits the suite across jobs, and every
+failing case gets a JSON-RPC transcript under `reports/traces/`. Details:
+[docs/CI.md](./docs/CI.md).
 
-### CLI — vib / vib-test
+## Agents write great cases
 
-Subcommands (default is `run` when omitted):
+JSON cases are the most generatable test format there is, and `record` keeps agents
+honest. Start the agent with **`vib help cases`**: the whole case format, every matcher,
+flows, MRTR, and tasks on one screen. Then the same loop you use:
 
-```bash
-vib init
-vib tools
-vib call echo --arg text=hello --arg uppercase=true
-vib record echo --arg text=hello --arg uppercase=true --name "echo uppercase"
-vib run
-vib inspect          # opens MCP Inspector with the same server config
-```
+1. `vib tools --json`: the agent reads the contract, schemas included.
+2. `vib call <tool> --args '{...}' --json`: it probes behavior and edge cases.
+3. `vib record ...`: real responses become goldens. No hallucinated envelopes, and
+   timestamps, UUIDs, and values that change between calls are loosened to matchers
+   automatically. (The stable check calls the tool twice; pass `--no-stable-check` for
+   tools with side effects. Tools annotated destructive are called once.)
+4. `vib tap -- node dist/index.js`: or record real client sessions and pick calls with
+   `vib record --from-tap`.
+5. `vib run --json --brief`: the agent verifies its own suite from one JSON report on
+   stdout, listing only what failed.
 
-| Command | Purpose |
-|--------|---------|
-| `run` | Execute JSON cases (CI gate) |
-| `tools` | List tools + argument shapes |
-| `call` | One-shot `tools/call`, print result |
-| `record` | One-shot call → write a golden case file |
-| `init` | Scaffold `vibrissa.json` + sample case + npm script |
-| `inspect` | Launch [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) against this server |
-
-**Division of labor:** use Inspector for visual exploration and debugging; use Vibrissa `tools` → `call` → `record` → `run` for the authoring/regression loop. `inspect` reuses your `vibrissa.json` server block so you do not re-type command/args/env.
-
-Shared options:
-- **--config**: path to your config file (otherwise auto-discovered from the current directory)
-- **--server**: override server command (quoted argv ok), e.g. `--server "node dist/index.js"`
-- **--server-cwd**: working directory for starting the server (overrides `server.cwd`; relative paths resolve from the shell cwd)
-- **--env KEY=VALUE**: extra environment (repeatable)
-- **--timeout**: per-call / spawn timeout in ms
-- **--json**: machine-readable output for `tools` / `call` / `record`
-
-`run` options:
-- **--cases**: glob of JSON cases (relative to the shell cwd when passed on the CLI)
-- **--allow-empty**: exit 0 when no cases match (by default, zero matches is a failure)
-- **--fail-fast**, **--pretty** / **--no-pretty**
-
-`record` options: `--out`, `--name`, `--partial`, `--force`
-
-Notes:
-- Globs in `vibrissa.json` resolve relative to the config file's directory.
-- Relative `server.cwd` values in config also resolve from that directory.
-- Matching zero case files exits `1` unless `--allow-empty` / `allowEmpty: true` is set.
-- Recorded cases include `$schema` pointing at `schema/case.schema.json` for editor validation.
-
-### Case Layout (recommended)
-```
-tests/
-  integration/
-    echo.basic.json
-    tools/
-      invalid-args.json
-      flow.multistep.json
-```
+Everything is built for that loop: `--json` always prints one object with `ok` (errors
+too, as `{ "ok": false, "error": { "type", "code", "message", "hint" }, "next" }`), unknown
+flags, tools, keys, matchers, and error codes all fail with a did-you-mean, and every
+error message says what to do next.
+
+The worst an agent can do is record a case you don't want, and that is a one-file JSON
+review. `vib explain` paraphrases what each case asserts and flags weak assertions (a
+bare `$partial`, `expectError: {}`, no expectation), for faster PR review.
+
+Cases can also be emitted from a [`tdd-dsl`](https://github.com/Rosavera-I/tdd-dsl)
+contract: `tdd-dsl emit --target vibrissa --out-dir tests/integration contract.tdd`.
 
-### Configuration (vibrissa.json)
-Create a `vibrissa.json` in your project root to avoid repeating flags and enable IDE IntelliSense via `$schema`.
+## Configuration
+
+`vibrissa.json` at the repo root (`vib init` creates it):
 
 ```json
 {
   "$schema": "./node_modules/@jmoak/vibrissa/schema/vibrissa.schema.json",
-  "server": {
-    "cmd": "node",
-    "args": ["dist/index.js"],
-    "cwd": ".",
-    "env": {
-      "LOG_LEVEL": "info"
+  "servers": {
+    "default": { "cmd": "node", "args": ["dist/index.js"] },
+    "staging": {
+      "url": "https://mcp.example.com/mcp",
+      "headers": { "Authorization": "Bearer ${MCP_TOKEN}" }
     }
   },
-  "globs": [
-    "tests/integration/**/*.json"
-  ],
+  "defaultServer": "default",
+  "globs": ["tests/integration/**/*.json"],
   "timeoutMs": 15000,
-  "failFast": false
+  "profiles": {
+    "ci": { "reporters": ["console", "github", "junit", "json"], "check": true, "requireManifest": true },
+    "legacy": { "servers": { "default": { "protocol": "legacy" } } }
+  }
 }
 ```
 
-Then run:
-```bash
-vib-test
-```
+Precedence is defaults, then the file, then `--profile`, then CLI flags. Paths resolve
+from the config file's directory. Zero matching cases fails the run unless `allowEmpty`.
+Every key: [docs/CONFIG.md](./docs/CONFIG.md).
+
+## Compatibility
+
+v1 case files and v1 `vibrissa.json` (with `server`) load unchanged, and goldens
+recorded against 2025 servers keep passing against 2026 servers because normalization
+strips the new envelope fields. `vib migrate` rewrites old error-code names and the v1
+`$schema` paths. See [docs/MIGRATION.md](./docs/MIGRATION.md).
 
-Notes:
-- `$schema` gives editor validation/autocomplete. Using the local path works immediately after install and offline.
-- CLI flags always override config values.
+## Library API
 
-### Library API
 ```ts
-import { runCases } from "vibrissa";
-
-await runCases({
-  server: { cmd: process.execPath, args: ["dist/index.js"], env: {} },
-  globs: ["tests/integration/**/*.json"],
-  failFast: true,
-  timeoutMs: 15000
-});
-```
+import { loadConfig, runCases } from '@jmoak/vibrissa'
 
-### CI (GitHub Actions)
-```yaml
-name: integration
-on: [push, pull_request]
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: npm
-      - run: npm ci
-      - run: npm run build
-      - run: npx vib-test --config vibrissa.json
-      - uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: junit
-          path: reports/junit/junit.xml
+const { options } = loadConfig(process.cwd(), { profile: 'ci' })
+process.exitCode = await runCases(options) // 0 ok, 1 failures, 2 config error
 ```
 
-### What to Test
-- Tools contract: `listTools`, `tools/call`
-- Arg validation: codes/messages for bad inputs
-- Multi‑step flows: sequences across tools
-- Streaming/long ops: use partial/regex for stability
-- Optional performance thresholds per case
+The v1 call shape (`runCases({ server: { cmd, args }, globs })`) still works.
+`new Runner(options).execute()` returns the full result instead of an exit code.
+
+### Vitest bridge
 
-### Troubleshooting
-- Hanging cases: increase `--timeout` and inspect server logs
-- Flaky text: prefer `$partial` or `$regex`
-- Globs not matching: run with quotes and verify working directory
+Teams with an existing Vitest suite can run the contract suite inside it, gated on the same
+things as `vib run`:
 
-### License
-MIT
+```ts
+// tests/mcp.contract.test.ts
+import { describeCases } from '@jmoak/vibrissa/vitest'
 
-### Authoring from tdd-dsl
+await describeCases({ profile: 'ci', checks: true })
+```
 
-You can author Vibrissa cases from a shared `.tdd` contract and emit JSON with [tdd-dsl](https://github.com/JMoak/tdd-dsl):
+It registers a manifest-lock test per server, a checks test (with `checks`), and one `it`
+per case. A string argument is a case glob. Options (`config`, `profile`, `globs`,
+`checks`, `lockManifest`, `title`, `api`, runner options): [docs/CI.md](./docs/CI.md#inside-a-vitest-suite).
 
-```text
-suite "Echo MCP contract"
-target vibrissa "echo-server"
+Also exported: `McpSession`, `loadCases`, `executeCase`, `matchValue`,
+`normalizeResult`, `diffManifest`, `createReporters`, `registerReporter`, `runChecks`,
+`generateArgs`.
 
-case "echo basic":
-  given input:
-    {"text": "hello"}
-  when call "echo"
-  then equals:
-    {"content": [{"type": "text", "text": "hello"}]}
-```
+## Docs
 
-```bash
-tdd-dsl emit --target vibrissa --out-dir tests/integration contract.tdd
-vib run
-```
+| Doc | Covers |
+|---|---|
+| [CASES.md](./docs/CASES.md) | every case-file key, flows, MRTR, tasks, recipes |
+| [MATCHERS.md](./docs/MATCHERS.md) | the assertion language |
+| [CONFIG.md](./docs/CONFIG.md) | `vibrissa.json`, servers, profiles |
+| [CLI.md](./docs/CLI.md) | every command and flag |
+| [CI.md](./docs/CI.md) | GitHub Actions, JUnit, shards, baselines |
+| [CHECKS.md](./docs/CHECKS.md) | `vib check` ids |
+| [FUZZ.md](./docs/FUZZ.md) | `vib fuzz` generation and invariants |
+| [MIGRATION.md](./docs/MIGRATION.md) | v1 to v2 |
+| [FUTURE.md](./docs/FUTURE.md) | after 2.0 |
 
-Mapping: `when call` → `tool`, `given input` → `args`, `then equals` → `expect`. Prefer recording once with `vib record` so `expect` matches the real MCP `tools/call` envelope.
+Contributing (humans and agents): [AGENTS.md](./AGENTS.md). Releasing:
+[RELEASING.md](./RELEASING.md).
 
-**Layering:** keep Vitest/Jest for unit tests of Vibrissa itself and of MCP handler logic. Use Vibrissa JSON for protocol e2e. Do **not** pull Python / tdd-dsl into Vibrissa CI — emit cases in the contract repo (or regenerate locally) and commit the JSON that `vib run` executes.
+## License
 
+[MIT](./LICENSE) © Jordan Moak

package/bin/vib-test.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import('../dist/cli.js')
+import('../dist/cli.js').then((cli) => cli.runCli(process.argv.slice(2)))