From b4f47af5569079b9425645d0cd22c1690bc12952 Mon Sep 17 00:00:00 2001 From: luciferlive112116 Date: Tue, 7 Jul 2026 17:36:08 +0800 Subject: [PATCH] docs: add INSTALL_FOR_AGENTS.md agent install checklist Add a numbered, imperative install guide for agents (closes #329): detect host via install-mcp --list, wire MCP, verify capabilities, init KB, and run a propose-to-human-approve smoke test. Link from llms.txt and distinguish from getting-started.md. Co-authored-by: Cursor --- docs/INSTALL_FOR_AGENTS.md | 151 +++++++++++++++++++++++++++++++++++++ llms.txt | 3 +- 2 files changed, 153 insertions(+), 1 deletion(-) create mode 100644 docs/INSTALL_FOR_AGENTS.md diff --git a/docs/INSTALL_FOR_AGENTS.md b/docs/INSTALL_FOR_AGENTS.md new file mode 100644 index 00000000..3ccb2ff9 --- /dev/null +++ b/docs/INSTALL_FOR_AGENTS.md @@ -0,0 +1,151 @@ +# install for agents + +machine-readable, top-to-bottom checklist for an assistant dropped into a +fresh project. every step is a concrete `vouch` command plus an assertion on +its output. if a step fails, stop and fix it before continuing. + +this doc is for agents. humans should start with +[getting-started.md](getting-started.md). + +## prerequisites + +1. confirm `vouch` is on `PATH`: + + ```bash + vouch --version + ``` + + **assert:** prints a version string and exits 0. + +2. `cd` to the project root you are wiring (the tree that will hold `.vouch/`). + +## 1. detect the host + +```bash +vouch install-mcp --list +``` + +**assert:** + +- exits 0. +- prints a bullet list of adapter names (for example `claude-code`, `cursor`, + `codex`, `windsurf`, `zed`). +- your host name appears in that list. if it does not, stop — pick the closest + supported adapter or wire `vouch serve` manually per + [transports.md](transports.md). + +## 2. wire the server + +replace `` with the name from step 1. + +```bash +vouch install-mcp +``` + +optional flags (all real — verified against `cli.py`): + +- `--tier T1|T2|T3|T4` — how much to install; tiers stack (default `T4`). +- `--path ` or `--target ` — project root to write into (default `.`). + +re-runs are flat-noop: expect lines containing `written`, `appended`, `merged`, +or `skipped`. you may run this command unconditionally on every session start. + +**assert:** exits 0; no `error:` lines. + +## 3. verify the kb.* surface + +```bash +vouch capabilities +``` + +**assert** on the JSON object: + +- `.name` is `"vouch"`. +- `.review_gated` is `true`. +- `.methods` includes at least: + - `kb.propose_claim` + - `kb.list_pending` + - `kb.approve` + +(`kb.approve` is exposed for trusted hosts; agents must still not call it — +see step 6.) + +## 4. create or locate a kb + +if `.vouch/` is missing: + +```bash +vouch init +``` + +**assert:** prints a path under the project and creates `.vouch/config.yaml`. + +if `.vouch/` already exists: + +```bash +vouch status +``` + +**assert:** prints `KB at …` with artifact counts and a `pending:` line. + +## 5. smoke test — propose (agent) + +create a throwaway citation file and register it: + +```bash +printf 'vouch agent install smoke test\n' > /tmp/vouch-agent-smoke.txt +vouch source add /tmp/vouch-agent-smoke.txt --title "agent smoke test" +``` + +**assert:** prints a 64-character hex source id (sha256 content address). + +propose a claim citing that source (replace ``): + +```bash +vouch propose-claim \ + --text "vouch agent install smoke test passed." \ + --source \ + --type observation \ + --confidence 0.9 +``` + +**assert:** prints a proposal id (for example `20260707-…`). + +confirm it is pending: + +```bash +vouch pending +``` + +**assert:** lists the proposal id from the previous step with `[claim]`. + +## 6. smoke test — approve (human only) + +**stop — this step is for the human reviewer, not the agent.** + +the agent must not run `vouch approve`, must not self-approve, and must not +hand-write files under `.vouch/claims/`, `.vouch/pages/`, or other `decided/` +paths. proposals live in `.vouch/proposed/` (gitignored) until a human decides. + +the human runs: + +```bash +vouch approve --reason "agent install smoke test" +vouch status +``` + +**assert:** `vouch status` shows the durable claim count incremented by one +compared to the count before step 5. + +## 7. what agents must never do + +- call `vouch approve` or `kb.approve` — the review gate is human-held. +- write yaml or markdown directly into `.vouch/claims/`, `.vouch/pages/`, or + other approved artifact directories. +- skip citation: every `propose-claim` needs at least one `--source` id. + +## where next + +- human-oriented walkthrough: [getting-started.md](getting-started.md) +- protocol and method shapes: [../SPEC.md](../SPEC.md) +- host-specific manifests: [../adapters/](../adapters/) diff --git a/llms.txt b/llms.txt index 3d3e9c3e..66482ee0 100644 --- a/llms.txt +++ b/llms.txt @@ -21,7 +21,8 @@ Repo: https://github.com/vouchdev/vouch · PyPI: `vouch-kb` · CLI: `vouch` ## Quick start and onboarding -- [docs/getting-started.md](https://raw.githubusercontent.com/vouchdev/vouch/main/docs/getting-started.md): Agent-side loop — register a source, propose a claim, get it approved. +- [docs/INSTALL_FOR_AGENTS.md](https://raw.githubusercontent.com/vouchdev/vouch/main/docs/INSTALL_FOR_AGENTS.md): Imperative, agent-followable install checklist — detect host, `install-mcp`, verify `capabilities`, init KB, propose → (human) approve smoke test. Distinct from the human-facing getting-started walkthrough below. +- [docs/getting-started.md](https://raw.githubusercontent.com/vouchdev/vouch/main/docs/getting-started.md): Human-oriented quickstart — register a source, propose a claim, get it approved. - [docs/example-session.md](https://raw.githubusercontent.com/vouchdev/vouch/main/docs/example-session.md): End-to-end captured walkthrough that the demo gif is recorded from. - [docs/faq.md](https://raw.githubusercontent.com/vouchdev/vouch/main/docs/faq.md): "Why not Notion / Obsidian / a vector DB" and other recurring asks.