docs: INSTALL_FOR_AGENTS.md — machine-readable agent-driven install protocol

[plind-junior]

docs/getting-started.md is written for a human operator: it interleaves prose, "in ten minutes you'll have…", and steps that assume a person is reading, deciding, and typing. an assistant dropped into a fresh repo has no equivalent — it has to reverse-engineer the flow from the readme and llms.txt, guess at verb names, and risk trying to write approved artifacts directly. a short, deterministic, agent-followable doc — docs/INSTALL_FOR_AGENTS.md — that an assistant reads top-to-bottom and executes end to end closes that gap: detect the host, wire the mcp server, verify the kb.* surface, point at (or create) a .vouch/, and smoke-test one propose → approve round trip. docs only; no new method, no code path.

proposed surface

a single new file, docs/INSTALL_FOR_AGENTS.md, plus one line in llms.txt under "quick start and onboarding" pointing at it (distinct from the existing human-facing docs/getting-started.md link). the doc is a numbered, imperative checklist; each step is a concrete command with a concrete assertion on the output, so an agent can branch on success/failure instead of pattern-matching prose:

• detect + list hosts — vouch install-mcp --list enumerates the available adapters (resolved from adapters/*/install.yaml via install_adapter.available_adapters()); the agent matches its own host name against the printed set.
• wire the server — vouch install-mcp <host> (--tier T1|T2|T3|T4 selects how much to install; tiers stack. --path/--target for a non-cwd tree). reruns are flat-noop, reported as written/appended/merged/skipped, so an agent may run it unconditionally.
• verify the surface — vouch capabilities and assert .name == "vouch", .review_gated == true, and that expected methods (kb.propose_claim, kb.approve, kb.list_pending, …) appear in .methods.
• create or point at a kb — vouch init if no .vouch/ exists, else vouch status to confirm the existing one (counts + pending).
• smoke-test the round trip — vouch source add <file>, vouch propose-claim --text … --source <id>, vouch pending, then (human) vouch approve <prop-id> --reason …, ending with vouch status showing the count incremented.

review gate & scope

the doc must model the gate, not route around it. the smoke test separates the two actors explicitly: the agent runs vouch propose-claim, which lands a pending proposal under .vouch/proposed/ (gitignored, local-only) through proposals.propose_claim; a human runs vouch approve. the doc names approval as a required human step and never tells an agent to approve, to self-approve, or to hand-write a durable .vouch/claims/*.yaml. everything stays local-first: only the cwd .vouch/ and the host's own config tree are touched — no network, no shared service.

adjacent issues: #191 (vouch install-mcp adapter writer) is the tooling this doc drives — this issue documents how an agent sequences that tooling, it does not change it. #231 (drop vouch into an openclaw deployment in 5 minutes) is a host-specific walkthrough for one target; this doc is host-agnostic and agent-executable. it complements llms.txt, the readme, and the human-facing docs/getting-started.md rather than replacing any of them.

acceptance criteria

• docs/INSTALL_FOR_AGENTS.md exists as a numbered, imperative, agent-followable checklist
• every command shown is a real vouch verb verified against cli.py (install-mcp --list, install-mcp <host> [--tier T1|T2|T3|T4] [--path|--target], capabilities, init, status, source add, propose-claim, pending, approve) — no invented flags or methods
• the surface check asserts on real vouch capabilities fields (name, review_gated, methods)
• the smoke test walks a full propose → approve round trip and asserts on vouch status output
• the doc names vouch approve as a human step and never instructs an agent to approve or to write approved artifacts directly
• the doc is host-agnostic (drives install-mcp --list to detect the host rather than hardcoding one)
• llms.txt links the new doc under onboarding, with a one-line note distinguishing it from docs/getting-started.md
• prose and headers are lowercase; no comparison to any other product, tool, or framework