From 4779df01c4fa6d9fefe2230cdf83d78a653c7e0d Mon Sep 17 00:00:00 2001
From: plind-junior <59729252+plind-junior@users.noreply.github.com>
Date: Mon, 13 Jul 2026 14:36:54 +0900
Subject: [PATCH] docs(contributing): document running vouch and the webapp in
 dev mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 CLAUDE.md       |  8 ++++++
 CONTRIBUTING.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 636b8deb..e09b5aa5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -85,6 +85,14 @@ make check
 For the embedding-heavy tests (separate job in CI): `pip install
 -e '.[embeddings]'` then drop the `--ignore=tests/embeddings` flag.
 
+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).
+
 ## Ship a feature branch
 
 ```bash
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7b06f924..d534721f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -65,6 +65,8 @@ touch behavior.
 
 ## Dev setup
 
+The Python package:
+
 ```bash
 git clone https://github.com/vouchdev/vouch
 cd vouch
@@ -72,6 +74,76 @@ python -m venv .venv && source .venv/bin/activate
 pip install -e '.[dev]'
 ```
 
+The web console under `webapp/` is a separate npm package (React +
+Vite) and needs Node.js + npm:
+
+```bash
+cd webapp && npm install
+```
+
+You only need the npm step if you work on (or run) the console —
+`make console` performs it automatically on first run.
+
+## Running vouch in dev mode
+
+The editable install puts a `vouch` entry point in `.venv/bin/` that runs
+straight from `src/` — edit, re-run, no reinstall (`python -m vouch` is
+equivalent).
+
+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:
+
+```bash
+mkdir /tmp/vouch-scratch && cd /tmp/vouch-scratch
+vouch init          # creates ./.vouch/ with a seeded starter KB
+vouch status
+```
+
+`VOUCH_KB_PATH=/abs/path/.vouch` skips the walk and pins the KB
+explicitly, wherever you run from.
+
+Then pick the surface you're working on:
+
+- **CLI** — run commands from the scratch dir; `vouch --help` lists them.
+- **JSONL server** — the quickest way to hit the `kb.*` surface without
+  an agent host (see [docs/transports.md](docs/transports.md)):
+
+  ```bash
+  echo '{"id":"r1","method":"kb.capabilities"}' \
+    | vouch serve --transport jsonl | jq '.result.methods | length'
+  ```
+
+- **MCP against a real agent** — register the venv binary so the agent
+  exercises your working tree:
+
+  ```bash
+  claude mcp add vouch-dev -- /path/to/vouch/.venv/bin/vouch serve
+  ```
+
+- **HTTP + web console** — `make console` starts `vouch serve
+  --transport http` (127.0.0.1:8731) and the vouch-ui Vite dev server
+  (http://localhost:5173) as a pair; Ctrl-C stops both. Edits under
+  `webapp/src/` hot-reload. The backend serves the `.vouch/` discovered
+  from the cwd — set `VOUCH_KB_PATH` to serve a scratch KB instead of
+  the repo's own. To run the console alone against a backend you
+  started yourself: `cd webapp && npm run dev`, then enter the endpoint
+  in the connect dialog. `npm test` runs the vitest suite; `npm run
+  e2e` runs the playwright smoke test (needs `vouch` on PATH). See
+  [webapp/README.md](webapp/README.md) for the full script list.
+
+Useful knobs while iterating:
+
+- `VOUCH_AGENT=alice-example` — set the actor identity, e.g. two shells
+  with different values to exercise the proposer ≠ approver rule.
+- `VOUCH_LOG_LEVEL=DEBUG` — verbose logs; see the environment-variable
+  table below for the other logging knobs.
+- `make smoke-capture` / `make smoke-recall` — end-to-end checks of the
+  session capture and recall flows.
+
+The dockerized end-to-end demo lives in [demo/](demo/README.md).
+
 ## The gate
 
 `make check` is the same gate CI runs. The individual pieces: