docs: promote readme restructure to main - #376
Merged
Merged
Conversation
link karpathy's llm-wiki idea file as the destination vouch is built toward, and state the differentiator in one place: the llm drafts the wiki, but citations are machine-verified and every page passes the review gate. also tighten the demo-video paragraph around the five-step pipeline (capture, summarize, approve, compile, recall) and note the film ends on real recall output.
docs(readme): frame vouch as a review-gated llm-wiki
github-actions
Bot
added
the
docs
📝 WalkthroughWalkthroughREADME.md now adds a living-wiki introduction, expands install and Docker guidance, replaces the quick start with a step-by-step project loop, and shortens the closing rules and links sections. ChangesREADME documentation update
Estimated code review effort: 1 (Trivial) | ~3 minutes Possibly related PRs
🚥 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 |
the readme accumulated sections a new user doesn't need on the way to their first working loop — 30-second tour, object model, file layout, cli surface, mcp method list, jsonl envelope shape, bundles, neighbour comparison, openclaw packaging, a stale pre-1.0 status note. all of that lives in SPEC.md, docs/, or --help output already. what remains maps one-to-one onto docs/vouch-how-it-works.mp4: install, wire claude code (init + install-mcp), set compile.llm_cmd, work a session, approve at the gate (review / review-ui), compile the wiki, recall in the next session, commit .vouch/. plus the three invariants underneath and a going-further link list. every command and claim in the new walkthrough was verified against the released 1.2.1 artifacts earlier today; all relative links checked against the tree.
docs(readme): restructure around reproducing the demo video
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
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 `@README.md`:
- Around line 69-71: The README sample output uses an unlabeled fenced block,
which triggers markdownlint MD040. Update the fenced example in the README to
use a text language label so the sample output stays lint-clean, keeping the
existing message content unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
Comment on lines
69
to
71
| ``` | ||
|
|
||
| The full surface — lifecycle ops, sessions, sources, maintenance, | ||
| migration — is listed by `vouch --help` and machine-readably by | ||
| `vouch capabilities`. | ||
|
|
||
| ## MCP tools / JSONL methods (same surface, two transports) | ||
|
|
||
| Read (unrestricted): `kb.capabilities`, `kb.status`, `kb.search`, `kb.context`, `kb.read_{page,claim,entity,relation}`, `kb.list_{pages,claims,entities,relations,sources,pending}` | ||
|
|
||
| Source intake (not gated — evidence is harmless and de-duplicates): `kb.register_source`, `kb.register_source_from_path`, `kb.source_verify` | ||
|
|
||
| Write (gated → produce proposals): `kb.propose_{claim,page,entity,relation}` (with `dry_run:true` for preview-only) | ||
|
|
||
| Decisions: `kb.approve`, `kb.reject` (host trust required) | ||
|
|
||
| Lifecycle (metadata about reviewed knowledge — direct mutation, audited): `kb.supersede`, `kb.contradict`, `kb.archive`, `kb.confirm`, `kb.cite` | ||
|
|
||
| Sessions: `kb.session_start`, `kb.session_end`, `kb.crystallize` | ||
|
|
||
| Maintenance: `kb.index_rebuild`, `kb.lint`, `kb.doctor`, `kb.audit`, `kb.export`, `kb.export_check`, `kb.import_check`, `kb.import_apply` | ||
|
|
||
| ## Wiring into Claude Code | ||
|
|
||
| In your project's `.mcp.json`: | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "vouch": { | ||
| "command": "vouch", | ||
| "args": ["serve"], | ||
| "env": { "VOUCH_AGENT": "claude-code" } | ||
| } | ||
| } | ||
| } | ||
| 🔔 1 auto-captured session summary(ies) awaiting review — run `vouch review`. | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Label the sample output fence.
The bare fenced block triggers markdownlint (MD040). Use text so the README stays lint-clean.
♻️ Proposed fix
-```
+```text
🔔 1 auto-captured session summary(ies) awaiting review — run `vouch review`.</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 69-69: 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 `@README.md` around lines 69 - 71, The README sample output uses an unlabeled
fenced block, which triggers markdownlint MD040. Update the fenced example in
the README to use a text language label so the sample output stays lint-clean,
keeping the existing message content unchanged.
Source: Linters/SAST tools
This was referenced Jul 6, 2026
jsdevninja
pushed a commit
to jsdevninja/vouch
that referenced
this pull request
Jul 6, 2026
… review) markdownlint md040 wants a language on the fence; matches how the compile flow diagram was labelled after the vouchdev#362 review.
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
1 participant
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.
promotes the readme restructure (#375) to main so the repo front page shows the video-first walkthrough. docs-only — no code between test and main besides #375.
Summary by CodeRabbit