From b47491bf555d865c8fd5d69b35461cca5eee87ff Mon Sep 17 00:00:00 2001 From: Will Pfleger Date: Thu, 21 May 2026 11:54:09 -0400 Subject: [PATCH] docs: add sprout-cli section and common gotchas to AGENTS.md --- AGENTS.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 51596e34b0..d9ac2514c2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,8 +52,8 @@ See CONTRIBUTING.md for full setup details and dependency requirements. ## Quality Gates -Run `just ci` before every PR. It runs: Rust `fmt` + `clippy`, desktop lint -(Biome), unit tests, desktop build, and Tauri check. All must pass. +Run `just ci` before every PR — it runs `fmt` + `clippy` + desktop lint + +unit tests + builds. Clippy passing does not mean fmt passes; run both. Run `just test` for integration tests if you touched `sprout-relay`, `sprout-db`, or `sprout-auth` — these require a running Postgres and Redis. @@ -113,6 +113,19 @@ check existing reply handlers for the pattern. --- +## Agent CLI (`sprout-cli`) + +`sprout` is the agent-first CLI replacing `sprout-mcp`. Auth env vars +(`SPROUT_RELAY_URL`, `SPROUT_PRIVATE_KEY`) are auto-injected by the ACP +harness into managed agent subprocesses. + +All reads return sig-stripped JSON arrays; all writes return +`{event_id, accepted, message}`; creates add the entity ID. Exit codes: +0=ok, 1=input error, 3=auth missing. See `crates/sprout-cli/TESTING.md` +for the full live-testing runbook. + +--- + ## Testing ```bash @@ -136,6 +149,15 @@ See [TESTING.md](TESTING.md) for the full multi-agent E2E guide. --- +## Common Gotchas + +1. **Kind `39000` for channel metadata, not `41`** — kind 41 is NIP-01 (unused). All kinds defined in `sprout-core/src/kind.rs`. +2. **Relay queries must specify `kinds`** — omitting `kinds` triggers the p-gate (403). Always include explicit kind filters. +3. **Worktrees: `cd` in the same command** — shell CWD doesn't persist between tool calls. Use `cd /path && cargo build` as one command. +4. **Desktop fmt check fails in worktrees** — run `just desktop-tauri-fmt-check` from the main checkout. CI is unaffected. + +--- + ## Desktop App The desktop app is Tauri 2 + React 19 + Vite + Tailwind CSS. Features are