docs(contributing): document running vouch and the webapp in dev mode#462
Open
plind-junior wants to merge 1 commit into
Open
docs(contributing): document running vouch and the webapp in dev mode#462plind-junior wants to merge 1 commit into
plind-junior wants to merge 1 commit into
Conversation
contributing stopped at the editable install and the test gate with nothing on actually running the working tree. add a "running vouch in dev mode" section: scratch kb setup (the repo root's .vouch is real and committed — don't experiment against it), the kb discovery walk and VOUCH_KB_PATH, per-surface recipes (cli, jsonl one-liner, mcp registration against the venv binary, make console for the http backend + vouch-ui dev server pair), and iteration knobs (VOUCH_AGENT, log level, smoke targets). dev setup now covers the webapp npm install alongside the python package, and claude.md's build section points at the new walkthrough.
github-actions
Bot
added
docs
📝 WalkthroughWalkthroughChangesDevelopment workflow documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 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.
Actionable comments posted: 2
🤖 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 `@CLAUDE.md`:
- Around line 88-94: Clarify the development-mode instructions around
VOUCH_KB_PATH: state that it selects an existing initialized .vouch
knowledge-base directory and does not create one. Keep the scratch-KB
initialization guidance separate, while preserving the warning not to use the
repository root’s committed .vouch directory.
In `@CONTRIBUTING.md`:
- Around line 93-96: Update the audit-log statement in the vouch knowledge-base
guidance to say that writes or mutating commands append to the audit log, rather
than claiming every command does. Keep the surrounding `.vouch/` discovery and
scratch-KB warning 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
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: ebc48d73-d4e4-4bd0-a9c5-959685d2bb84
📒 Files selected for processing (2)
CLAUDE.mdCONTRIBUTING.md
Comment on lines
+88
to
+94
| To *run* the thing you're hacking on (dev mode): the editable install's | ||
| `vouch` runs straight from `src/`. Init a scratch KB (`vouch init` in a | ||
| temp dir, or `VOUCH_KB_PATH=/abs/path/.vouch`) — the repo root's own | ||
| `.vouch/` is real and committed, don't experiment against it. `make | ||
| console` runs the HTTP backend + vouch-ui dev server as a pair. Full | ||
| walkthrough: "Running vouch in dev mode" in | ||
| [`CONTRIBUTING.md`](./CONTRIBUTING.md). |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
clarify that VOUCH_KB_PATH selects a kb; it does not create one.
As written, the parenthetical makes VOUCH_KB_PATH sound like an alternative to initializing a scratch KB. Point it at an existing initialized .vouch directory instead.
proposed wording
- Init a scratch KB (`vouch init` in a
- temp dir, or `VOUCH_KB_PATH=/abs/path/.vouch`) — the repo root's own
+ Init a scratch KB with `vouch init` in a
+ temp dir. To use an existing initialized KB elsewhere, set
+ `VOUCH_KB_PATH=/abs/path/.vouch`. The repo root's own📝 Committable suggestion
‼️ 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.
Suggested change
| To *run* the thing you're hacking on (dev mode): the editable install's | |
| `vouch` runs straight from `src/`. Init a scratch KB (`vouch init` in a | |
| temp dir, or `VOUCH_KB_PATH=/abs/path/.vouch`) — the repo root's own | |
| `.vouch/` is real and committed, don't experiment against it. `make | |
| console` runs the HTTP backend + vouch-ui dev server as a pair. Full | |
| walkthrough: "Running vouch in dev mode" in | |
| [`CONTRIBUTING.md`](./CONTRIBUTING.md). | |
| To *run* the thing you're hacking on (dev mode): the editable install's | |
| `vouch` runs straight from `src/`. Init a scratch KB with `vouch init` in a | |
| temp dir. To use an existing initialized KB elsewhere, set | |
| `VOUCH_KB_PATH=/abs/path/.vouch`. The repo root's own | |
| `.vouch/` is real and committed, don't experiment against it. `make | |
| console` runs the HTTP backend + vouch-ui dev server as a pair. Full | |
| walkthrough: "Running vouch in dev mode" in | |
| [`CONTRIBUTING.md`](./CONTRIBUTING.md). |
🤖 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 `@CLAUDE.md` around lines 88 - 94, Clarify the development-mode instructions
around VOUCH_KB_PATH: state that it selects an existing initialized .vouch
knowledge-base directory and does not create one. Keep the scratch-KB
initialization guidance separate, while preserving the warning not to use the
repository root’s committed .vouch directory.
Comment on lines
+93
to
+96
| vouch locates its KB the way git locates a repo: it walks up from the | ||
| current directory looking for `.vouch/`. Mind that this repo's root has a | ||
| **real, committed** `.vouch/` (vouch dogfoods itself) and every command | ||
| appends to its audit log, so point experiments at a scratch KB instead: |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
limit the audit-log warning to writes.
“Every command appends to its audit log” overstates the documented invariant and may incorrectly suggest that read-only commands mutate history. Please describe writes or mutating commands instead.
proposed wording
- and every command appends to its audit log, so point experiments at a scratch KB instead:
+ and writes are recorded in its audit log, so point experiments at a scratch KB instead:📝 Committable suggestion
‼️ 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.
Suggested change
| vouch locates its KB the way git locates a repo: it walks up from the | |
| current directory looking for `.vouch/`. Mind that this repo's root has a | |
| **real, committed** `.vouch/` (vouch dogfoods itself) and every command | |
| appends to its audit log, so point experiments at a scratch KB instead: | |
| vouch locates its kb the way git locates a repo: it walks up from the | |
| current directory looking for `.vouch/`. mind that this repo's root has a | |
| **real, committed** `.vouch/` (vouch dogfoods itself) and writes are recorded | |
| in its audit log, so point experiments at a scratch kb instead: |
🤖 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 `@CONTRIBUTING.md` around lines 93 - 96, Update the audit-log statement in the
vouch knowledge-base guidance to say that writes or mutating commands append to
the audit log, rather than claiming every command does. Keep the surrounding
`.vouch/` discovery and scratch-KB warning unchanged.
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.
contributing covered installing and the test gate but never how to run the working tree. this adds a "running vouch in dev mode" section: the editable install runs straight from src/, kb discovery walks up from the cwd (and the repo root's .vouch is real and committed, so experiments belong in a scratch kb or behind VOUCH_KB_PATH), then one recipe per surface — cli, a jsonl smoke one-liner, registering the venv binary as an mcp server, and make console for the http backend + vouch-ui dev server pair.
dev setup now covers both packages: the python editable install and the webapp's npm install (auto-performed by make console on first run). claude.md's build section points at the new walkthrough.
validated end-to-end against the venv build: vouch init seeds a scratch kb, the jsonl one-liner returns the capabilities envelope, VOUCH_KB_PATH pins the kb from an unrelated cwd, make console brings up both servers (backend /health ok, the console dashboard renders the scratch kb through the vite proxy), and the webapp vitest suite passes (27 files, 148 tests).
docs-only, so targeting main directly per the contributing guidance.
Summary by CodeRabbit