docs: add tutorials, host-comms walkthrough, one-line mcp install#295
Merged
plind-junior merged 1 commit intoJun 30, 2026
Merged
Conversation
github-actions
Bot
added
docs
📝 WalkthroughWalkthroughAdds documentation for MCP transport and agent wiring, plus a tutorials landing page and four tutorial guides covering KB setup, agent integration, sharing, and Obsidian-based editing. ChangesDocumentation expansion
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (3)
docs/transports.md (1)
56-70: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd a language specifier to the diagram code block.
The ASCII diagram block triggers a markdownlint warning (MD040) because it lacks a language tag. Add
textto the fence:- ``` + ```text host (e.g. Claude Code) vouch serve (child process)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/transports.md` around lines 56 - 70, The diagram fence in the transport documentation is missing a language tag, which triggers the markdownlint MD040 warning. Update the code block around the ASCII transport diagram to use the same fence with a text specifier so the block is explicitly marked as plain text. Keep the diagram content unchanged and ensure the fix is applied in the documentation section containing the host/vouch serve flow.Source: Linters/SAST tools
docs/getting-started.md (1)
104-113: 📐 Maintainability & Code Quality | 🔵 TrivialClarify where the
-e VOUCH_AGENTflag belongs.The instruction says to "Add
-e VOUCH_AGENT=claude-code" but doesn't show the complete command. Readers may be unsure whether the flag goes onclaude mcp addor onvouch serveitself.Show the full command, e.g.:
claude mcp add vouch --env VOUCH_AGENT=claude-code -- vouch serveOr, if
-eis indeed the correct short flag for Claude's CLI:claude mcp add -e VOUCH_AGENT=claude-code vouch -- vouch serve🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/getting-started.md` around lines 104 - 113, The `vouch serve` setup instructions are ambiguous about where the `VOUCH_AGENT` environment flag belongs; update the getting-started command in the registration example so the full `claude mcp add` invocation clearly shows the flag in the correct place alongside `vouch serve`, and keep the surrounding explanation aligned with that exact command.docs/tutorials/edit-in-obsidian.md (1)
87-89: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueClarify why the proposer is
vault-sync.The tutorial states the proposal is "by vault-sync" without explaining where that actor name comes from. Consider adding a brief note that
vouch syncsetsVOUCH_AGENT=vault-sync(or however the actor is determined) so readers understand why the gate is satisfied by their approval.• 20260630-074121-a44eb574 [page] by vault-sync Edit in Obsidian
+>
vault-syncis the default actor for forward-sync proposals, so your human
+> approval satisfies the self-approval gate.<details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/tutorials/edit-in-obsidian.mdaround lines 87 - 89, Clarify the “by
vault-sync” proposer label in the Edit in Obsidian tutorial by explaining where
that actor name comes from and how the approval gate is satisfied. Update the
surrounding prose in the tutorial section that mentions the forward-sync
proposal so it references the actor selection used by vouch sync (for example,
that it sets VOUCH_AGENT to vault-sync or otherwise uses vault-sync as the
default actor), and keep the note near the proposal example so readers can
connect the label to their own approval.</details> <!-- cr-comment:v1:e9698ca3fc0175d72cfc346b --> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.Nitpick comments:
In@docs/getting-started.md:
- Around line 104-113: The
vouch servesetup instructions are ambiguous about
where theVOUCH_AGENTenvironment flag belongs; update the getting-started
command in the registration example so the fullclaude mcp addinvocation
clearly shows the flag in the correct place alongsidevouch serve, and keep
the surrounding explanation aligned with that exact command.In
@docs/transports.md:
- Around line 56-70: The diagram fence in the transport documentation is missing
a language tag, which triggers the markdownlint MD040 warning. Update the code
block around the ASCII transport diagram to use the same fence with a text
specifier so the block is explicitly marked as plain text. Keep the diagram
content unchanged and ensure the fix is applied in the documentation section
containing the host/vouch serve flow.In
@docs/tutorials/edit-in-obsidian.md:
- Around line 87-89: Clarify the “by vault-sync” proposer label in the Edit in
Obsidian tutorial by explaining where that actor name comes from and how the
approval gate is satisfied. Update the surrounding prose in the tutorial section
that mentions the forward-sync proposal so it references the actor selection
used by vouch sync (for example, that it sets VOUCH_AGENT to vault-sync or
otherwise uses vault-sync as the default actor), and keep the note near the
proposal example so readers can connect the label to their own approval.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro Plus **Run ID**: `d9d74cc7-11fd-44a0-91f2-af53f0d2c6f8` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 94e84b145aa4b1764b720fe1583cd2804a3ddd3a and 0dca8bb2778a992d66ffaf942bba0b3b922c6645. </details> <details> <summary>📒 Files selected for processing (8)</summary> * `CLAUDE.md` * `docs/getting-started.md` * `docs/transports.md` * `docs/tutorials/README.md` * `docs/tutorials/connect-coding-agent.md` * `docs/tutorials/edit-in-obsidian.md` * `docs/tutorials/first-knowledge-base.md` * `docs/tutorials/share-a-knowledge-base.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
add docs/tutorials/ — an index plus four diátaxis walkthroughs (build your first knowledge base, give a coding agent a reviewed memory, share a kb via bundles, edit a kb in obsidian). every command was run end-to-end against the cli before it went in, so the walkthroughs only cover verified behaviour (including the real forbidden_self_approval review gate). feature the native one-line wire-up `claude mcp add vouch -- vouch serve` in getting-started step 6, and add a "how a host talks to vouch" section to docs/transports.md describing the stdio mcp path end to end — spawn, handshake, tool call, review gate, _meta sidebars, server-to-client push. fix the read-sidebar guidance in claude.md: the per-tool read sidebar is _meta.vouch_salience (salience.py, attached by kb_context), not vouch_hot_memory — that key is written only by the openclaw context engine's assemble().
dripsmvcp
force-pushed
the
docs/tutorials-and-host-comms
branch
from
0dca8bb to
8ac0775
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/tutorials/first-knowledge-base.md`:
- Around line 186-245: The `vouch context` and `vouch synthesize` examples in
`first-knowledge-base` are out of date, so update the tutorial to match the
current CLI schema. In the `context` walkthrough, adjust the example output to
include the current `query` and `quality` fields and add each item’s `type`,
`score`, and `freshness`; in the `synthesize` section, either show the current
full answer structure or clearly label the snippet as intentionally abbreviated.
Use the existing `vouch context` and `vouch synthesize` headings to locate the
affected examples and keep the surrounding narrative consistent with the updated
response shapes.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 6af1b40c-61d5-4a3c-940c-356d51f1de99
📒 Files selected for processing (8)
CLAUDE.mddocs/getting-started.mddocs/transports.mddocs/tutorials/README.mddocs/tutorials/connect-coding-agent.mddocs/tutorials/edit-in-obsidian.mddocs/tutorials/first-knowledge-base.mddocs/tutorials/share-a-knowledge-base.md
✅ Files skipped from review due to trivial changes (2)
- docs/getting-started.md
- CLAUDE.md
Comment on lines
+186
to
+245
| ```bash | ||
| vouch context "how does auth work" | ||
| ``` | ||
|
|
||
| ```json | ||
| { | ||
| "backend": "fts5", | ||
| "items": [ | ||
| { | ||
| "id": "auth-uses-jwts-in-the-authorization-header", | ||
| "summary": "Auth uses JWTs in the Authorization header.", | ||
| "citations": ["532e2b4d95c9dd17aa1c0feed366746ca47e40e4cb8e8582f3677b0931b55d70"] | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| **A cited synthesis** — a direct answer built only from approved claims, with | ||
| inline citation markers: | ||
|
|
||
| ```bash | ||
| vouch synthesize "how does auth work" | ||
| ``` | ||
|
|
||
| ```json | ||
| { | ||
| "answer": "Auth uses JWTs in the Authorization header [auth-uses-jwts-in-the-authorization-header].", | ||
| "claims": ["auth-uses-jwts-in-the-authorization-header"] | ||
| } | ||
| ``` | ||
|
|
||
| `synthesize` never invents — if the KB doesn't have it, the answer says so. | ||
| Every sentence traces back to a claim that went through the gate. | ||
|
|
||
| ## 7. Trace the provenance | ||
|
|
||
| Because every write is an event, you can always answer "why does this claim | ||
| exist, and who put it there?" | ||
|
|
||
| ```bash | ||
| vouch why auth-uses-jwts-in-the-authorization-header | ||
| ``` | ||
|
|
||
| ``` | ||
| why auth-uses-jwts-in-the-authorization-header (claim) | ||
| approvedBy -> … (event) [2026-06-30T07:39:17Z] | ||
| cites -> 532e2b4d… (source) [2026-06-30T07:39:17Z] | ||
| ``` | ||
|
|
||
| ```bash | ||
| vouch audit | ||
| ``` | ||
|
|
||
| ``` | ||
| … proposal.claim.create by a objects=['20260630-073841-d722ac24'] | ||
| … proposal.claim.approve by alice-reviewer objects=['20260630-073841-d722ac24', 'auth-uses-jwts-…'] | ||
| ``` | ||
|
|
||
| The audit log is the authoritative history: who proposed, who approved, when, | ||
| and citing what. It's append-only and committed alongside the claims. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# This requires a vouch KB with approved claims; run in a test environment with KB
vouch context --help 2>/dev/null | head -5
vouch synthesize --help 2>/dev/null | head -5
vouch why --help 2>/dev/null | head -5
vouch audit --help 2>/dev/null | head -5Repository: vouchdev/vouch
Length of output: 152
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== shell log =="
sed -n '1,200p' /tmp/coderabbit-shell-logs/shell-output-odKE9Z
echo
echo "== docs/tutorials/first-knowledge-base.md around cited lines =="
nl -ba docs/tutorials/first-knowledge-base.md | sed -n '170,260p'
echo
echo "== search for command names and output format docs =="
rg -n --hidden --glob '!**/node_modules/**' --glob '!**/.git/**' \
'vouch (context|synthesize|why|audit)|approvedBy ->|proposal\.claim\.approve|backend": "fts5"|claims": \[' \
.Repository: vouchdev/vouch
Length of output: 273
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== log file =="
sed -n '1,200p' /tmp/coderabbit-shell-logs/shell-output-SwOLzK
echo
echo "== docs slice =="
awk 'NR>=170 && NR<=260 {printf "%5d %s\n", NR, $0}' docs/tutorials/first-knowledge-base.md
echo
echo "== command/search hits =="
rg -n --hidden --glob '!**/node_modules/**' --glob '!**/.git/**' \
'vouch (context|synthesize|why|audit)|approvedBy ->|proposal\.claim\.approve|backend": "fts5"|claims": \[' \
.Repository: vouchdev/vouch
Length of output: 13993
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== log file =="
sed -n '1,200p' /tmp/coderabbit-shell-logs/shell-output-SwOLzK || true
echo
echo "== docs slice =="
python3 - <<'PY'
from pathlib import Path
p = Path("docs/tutorials/first-knowledge-base.md")
for i, line in enumerate(p.read_text().splitlines(), 1):
if 170 <= i <= 260:
print(f"{i:5d} {line}")
PY
echo
echo "== command/search hits =="
rg -n --hidden --glob '!**/node_modules/**' --glob '!**/.git/**' \
'vouch (context|synthesize|why|audit)|approvedBy ->|proposal\.claim\.approve|backend": "fts5"|claims": \[' \
.Repository: vouchdev/vouch
Length of output: 13993
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n --hidden --glob '!**/node_modules/**' --glob '!**/.git/**' \
'context|synthesize|why|audit|approvedBy|proposal\.claim\.approve|proposal\.claim\.create|backend' \
cmd internal pkg docs .Repository: vouchdev/vouch
Length of output: 50371
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== docs/example-session.md relevant slice =="
python3 - <<'PY'
from pathlib import Path
p = Path("docs/example-session.md")
for i, line in enumerate(p.read_text().splitlines(), 1):
if 120 <= i <= 170:
print(f"{i:5d} {line}")
PY
echo
echo "== docs/retrieval.md relevant slice =="
python3 - <<'PY'
from pathlib import Path
p = Path("docs/retrieval.md")
for i, line in enumerate(p.read_text().splitlines(), 1):
if 35 <= i <= 110:
print(f"{i:5d} {line}")
PY
echo
echo "== docs/provenance.md relevant slice =="
python3 - <<'PY'
from pathlib import Path
p = Path("docs/provenance.md")
for i, line in enumerate(p.read_text().splitlines(), 1):
if 35 <= i <= 60:
print(f"{i:5d} {line}")
PY
echo
echo "== CLI/doc references for why/audit/context formatting =="
rg -n --hidden --glob '!**/node_modules/**' --glob '!**/.git/**' \
'ContextPack dict|always emit JSON|vouch context|vouch synthesize|vouch why|vouch audit|returns: "Dict \{backend|print.*audit|tree grouped by edge' \
src docs examples desktop/src/shared/methods.gen.tsRepository: vouchdev/vouch
Length of output: 11366
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== docs/example-session.md relevant slice =="
python3 - <<'PY'
from pathlib import Path
p = Path("docs/example-session.md")
for i, line in enumerate(p.read_text().splitlines(), 1):
if 120 <= i <= 170:
print(f"{i:5d} {line}")
PY
echo
echo "== docs/retrieval.md relevant slice =="
python3 - <<'PY'
from pathlib import Path
p = Path("docs/retrieval.md")
for i, line in enumerate(p.read_text().splitlines(), 1):
if 35 <= i <= 110:
print(f"{i:5d} {line}")
PY
echo
echo "== docs/provenance.md relevant slice =="
python3 - <<'PY'
from pathlib import Path
p = Path("docs/provenance.md")
for i, line in enumerate(p.read_text().splitlines(), 1):
if 35 <= i <= 60:
print(f"{i:5d} {line}")
PY
echo
echo "== CLI/doc references for why/audit/context formatting =="
rg -n --hidden --glob '!**/node_modules/**' --glob '!**/.git/**' \
'ContextPack dict|always emit JSON|vouch context|vouch synthesize|vouch why|vouch audit|returns: "Dict \{backend|tree grouped by edge' \
src docs examples desktop/src/shared/methods.gen.tsRepository: vouchdev/vouch
Length of output: 11225
Align the vouch context and vouch synthesize examples with the current CLI schema
The tutorial’s context output is stale: current results include query and quality, and each item carries type, score, and freshness. The synthesize example should also match the current answer format, or be labeled as intentionally abbreviated.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 229-229: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 239-239: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/tutorials/first-knowledge-base.md` around lines 186 - 245, The `vouch
context` and `vouch synthesize` examples in `first-knowledge-base` are out of
date, so update the tutorial to match the current CLI schema. In the `context`
walkthrough, adjust the example output to include the current `query` and
`quality` fields and add each item’s `type`, `score`, and `freshness`; in the
`synthesize` section, either show the current full answer structure or clearly
label the snippet as intentionally abbreviated. Use the existing `vouch context`
and `vouch synthesize` headings to locate the affected examples and keep the
surrounding narrative consistent with the updated response shapes.
Contributor
Author
|
@plind-junior Would you review this PR? I confirmed all the features working |
Collaborator
|
Love it! Did you also check if desktop version is fully compatible with vouch? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
adds a
docs/tutorials/set — an index plus four diátaxis walkthroughs(build your first knowledge base, give a coding agent a reviewed memory,
share a kb via bundles, edit a kb in obsidian) — and features the native
one-line wire-up
claude mcp add vouch -- vouch servein getting-startedstep 6. also adds a "how a host talks to vouch" section to
docs/transports.mddescribing the stdio mcp path end to end (spawn →handshake → tool call → review gate →
_metasidebars → server-to-clientpush), and corrects the read-sidebar note in
CLAUDE.md.Why
there was no learning-oriented on-ramp: getting-started is a reference
quickstart, not a walkthrough. the tutorials take a reader from zero to a
working outcome, and every command in them was run end-to-end against the
cli first, so they only document verified behaviour — including the real
forbidden_self_approvalreview gate and the actual proposal id shape.the install docs led with
vouch install-mcp claude-code(writes configfiles) and never mentioned that
vouch serveis already a stdio mcpserver, so
claude mcp add vouch -- vouch serveworks directly. thatone-liner is now the headline path, with
install-mcpkept as the richeroption.
the
CLAUDE.mdfix is a correctness one: it told contributors that readmethods attach
_meta.vouch_hot_memoryfromhot_memory.py. grep-verifiedagainst the tree, the per-tool read sidebar is actually
_meta.vouch_salience(salience.py, attached bykb_context);vouch_hot_memoryis written only by the openclaw context engine'sassemble().What might break
nothing. docs-only plus one comment-style correction in
CLAUDE.md. nofile moves, no on-disk field changes, no
kb.*behaviour changes. userswith an existing
.vouch/are unaffected.VEP
not a surface change — no VEP needed.
Tests
src/changed, so the mypy/pytest gate isunaffected; every documented command was verified end-to-end against
the live cli before it went in
CHANGELOG.mdupdated — skipped; docs-only, no user-facing surfacechange
Summary by CodeRabbit
vouch serveas a stdio MCP server, including native registration viaclaude mcp add vouch -- vouch serveand agent attribution viaVOUCH_AGENT.