Skip to content

Commit 79bcee5

Browse files
wesbillmanPinky
andauthored
docs: finish Buzz rename cleanup (#974)
Signed-off-by: Wes <[email protected]> Co-authored-by: Pinky <44b8e82baa6e0e254e0208d68f335c283c94e7b78dd1fa10d5a49d3f13dd0435@sprout-oss.stage.blox.sqprod.co>
1 parent 6f3733d commit 79bcee5

12 files changed

Lines changed: 303 additions & 303 deletions

File tree

‎.github/workflows/sprig.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
name: Sprig
22

33
# Builds and publishes Sprig — one deploy-anywhere Linux multicall binary for:
4-
# buzz-acp ACP harness that bridges Sprout events to the LLM agent
4+
# buzz-acp ACP harness that bridges Buzz events to the LLM agent
55
# buzz-agent ACP-compliant agent (spawns MCP, calls LLMs)
66
# buzz-dev-mcp Developer MCP server (multicall: rg, tree, buzz,
77
# git-credential-nostr, git-sign-nostr)

‎AGENTS.md‎

Lines changed: 47 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
# AGENTS.md — AI Agent Contributor Guide
22

3-
This guide is for AI agents contributing to the Sprout codebase. It covers
3+
This guide is for AI agents contributing to the Buzz codebase. It covers
44
agent-specific context and conventions. For general contributor info (setup,
55
code style, PR process, architecture), see [CONTRIBUTING.md](CONTRIBUTING.md).
66

77
---
88

99
## Ecosystem
1010

11-
Sprout spans five repos. This one (`block/sprout`) is the OSS source for the relay, desktop, mobile, and CLI. The others handle internal builds and deployment:
11+
Buzz spans five repos. This one (`block/sprout`) is the OSS source for the relay, desktop, mobile, and CLI. The others handle internal builds and deployment:
1212

1313
| Repo | Purpose |
1414
|------|---------|
@@ -37,32 +37,32 @@ access information.
3737
```
3838
crates/
3939
# Relay + core
40-
sprout-relay # WebSocket relay server — main entry point; also hosts git + huddle audio
41-
sprout-core # Core types, event verification, filter matching, kind registry
42-
sprout-db # Postgres event store and data access layer
43-
sprout-auth # Authentication and authorization
44-
sprout-pubsub # Redis pub/sub fan-out, presence, typing indicators
45-
sprout-search # Typesense-backed full-text search
46-
sprout-audit # Hash-chain audit log
47-
sprout-media # Blossom/S3 media storage
40+
buzz-relay # WebSocket relay server — main entry point; also hosts git + huddle audio
41+
buzz-core # Core types, event verification, filter matching, kind registry
42+
buzz-db # Postgres event store and data access layer
43+
buzz-auth # Authentication and authorization
44+
buzz-pubsub # Redis pub/sub fan-out, presence, typing indicators
45+
buzz-search # Typesense-backed full-text search
46+
buzz-audit # Hash-chain audit log
47+
buzz-media # Blossom/S3 media storage
4848
# Agent surface
49-
sprout-acp # ACP harness bridging Sprout events to AI agents
50-
sprout-agent # Minimal ACP-compliant agent (non-streaming, tool-calls-as-output)
51-
sprout-dev-mcp # Developer MCP server — shell + file-edit tools
52-
sprout-persona # Agent persona packs
53-
sprout-workflow # YAML-as-code workflow engine (evalexpr conditions)
49+
buzz-acp # ACP harness bridging Buzz events to AI agents
50+
buzz-agent # Minimal ACP-compliant agent (non-streaming, tool-calls-as-output)
51+
buzz-dev-mcp # Developer MCP server — shell + file-edit tools
52+
buzz-persona # Agent persona packs
53+
buzz-workflow # YAML-as-code workflow engine (evalexpr conditions)
5454
# Clients + interop
55-
sprout-proxy # Nostr client compatibility proxy (NIP-28)
56-
sprout-pair-relay # Ephemeral sidecar relay for NIP-AB device pairing
57-
sprout-pairing-cli # CLI for NIP-AB device pairing interop testing
55+
buzz-proxy # Nostr client compatibility proxy (NIP-28)
56+
buzz-pair-relay # Ephemeral sidecar relay for NIP-AB device pairing
57+
buzz-pairing-cli # CLI for NIP-AB device pairing interop testing
5858
git-sign-nostr # Sign git objects with a Nostr key
5959
git-credential-nostr # Git credential helper for Nostr-authed push/fetch
6060
# Tooling + shared
61-
sprout-cli # Agent-first CLI
62-
sprout-sdk # Typed Nostr event builders
63-
sprout-admin # Operator CLI for relay administration
64-
sprout-ws-client # Shared NIP-42 WebSocket client (connect, auth, publish)
65-
sprout-test-client # Integration test client and E2E test suite
61+
buzz-cli # Agent-first CLI
62+
buzz-sdk # Typed Nostr event builders
63+
buzz-admin # Operator CLI for relay administration
64+
buzz-ws-client # Shared NIP-42 WebSocket client (connect, auth, publish)
65+
buzz-test-client # Integration test client and E2E test suite
6666
sprig # All-in-one harness bundling ACP, agent, and dev MCP
6767
6868
desktop/ # Tauri 2 + React 19 desktop app
@@ -94,8 +94,8 @@ See CONTRIBUTING.md for full setup details and dependency requirements.
9494
Run `just ci` before every PR — it runs `fmt` + `clippy` + desktop lint +
9595
unit tests + builds. Clippy passing does not mean fmt passes; run both.
9696

97-
Run `just test` for integration tests if you touched `sprout-relay`,
98-
`sprout-db`, or `sprout-auth` — these require a running Postgres and Redis.
97+
Run `just test` for integration tests if you touched `buzz-relay`,
98+
`buzz-db`, or `buzz-auth` — these require a running Postgres and Redis.
9999

100100
**Pre-commit hooks** are installed automatically by `just setup` and auto-fix
101101
formatting via `stage_fixed`. Pre-commit runs fix variants in parallel (Rust
@@ -116,21 +116,21 @@ Additional rules:
116116

117117
## Key Patterns
118118

119-
**Dual API surface**: Sprout exposes both a REST API and a NIP-29 WebSocket
120-
relay. Both paths converge on shared DB functions in `sprout-db`. When adding
119+
**Dual API surface**: Buzz exposes both a REST API and a NIP-29 WebSocket
120+
relay. Both paths converge on shared DB functions in `buzz-db`. When adding
121121
a feature, implement the shared DB logic first, then wire up both surfaces.
122122

123123
**Prefer Nostr events over new REST endpoints**: For new feature work, model
124-
the operation as a Nostr event (new kind in `sprout-core/src/kind.rs`, handler
125-
in `sprout-relay`) rather than adding a new REST endpoint. REST is reserved
124+
the operation as a Nostr event (new kind in `buzz-core/src/kind.rs`, handler
125+
in `buzz-relay`) rather than adding a new REST endpoint. REST is reserved
126126
for things that genuinely need an HTTP-only surface: media upload/download
127127
(Blossom), OAuth callbacks, health checks, and the existing read endpoints
128128
that proxy DB queries. Two helpful endpoints already exist and rarely need
129129
to be duplicated:
130130

131131
- `POST /events` — submit any signed event (same path the WebSocket uses).
132132
- `POST /query` — Nostr REQ filters over HTTP. NIP-50 `search` filters
133-
are routed to `sprout-search` (Typesense-backed) automatically.
133+
are routed to `buzz-search` (Typesense-backed) automatically.
134134
- `POST /count` — Nostr COUNT filters over HTTP.
135135

136136
If you find yourself reaching for a new REST endpoint, first check whether
@@ -140,15 +140,15 @@ fan-out, NIP-29 scoping, and the existing auth pipeline for free.
140140
Reference https://github.com/nostr-protocol/nips
141141

142142
**Event kinds**: All event kind integers are defined in
143-
`sprout-core/src/kind.rs`. New features get new kind integers — add them here
143+
`buzz-core/src/kind.rs`. New features get new kind integers — add them here
144144
first, then implement handling in the relay.
145145

146146
**Channel scoping**: Channels use `h` tags (NIP-29 group tag), not `e` tags.
147147
Filters and queries must scope to `h` tags when operating within a channel.
148148

149-
**Agent-facing operations go in `sprout-cli`**: New agent-facing features belong in `sprout-cli` — add a subcommand there first, then wire the REST/WebSocket call in `client.rs`. `sprout-dev-mcp` (shell + file tools for `sprout-agent`) is separate.
149+
**Agent-facing operations go in `buzz-cli`**: New agent-facing features belong in `buzz-cli` — add a subcommand there first, then wire the REST/WebSocket call in `client.rs`. `buzz-dev-mcp` (shell + file tools for `buzz-agent`) is separate.
150150

151-
**Workflow conditions**: `sprout-workflow` uses
151+
**Workflow conditions**: `buzz-workflow` uses
152152
[evalexpr](https://docs.rs/evalexpr) for condition evaluation. Keep expressions
153153
simple and testable.
154154

@@ -158,20 +158,20 @@ check existing reply handlers for the pattern.
158158

159159
---
160160

161-
## Agent CLI (`sprout-cli`)
161+
## Agent CLI (`buzz-cli`)
162162

163-
`sprout` is the agent-first CLI. Auth env vars
164-
(`SPROUT_RELAY_URL`, `SPROUT_PRIVATE_KEY`, `SPROUT_AUTH_TAG`) are auto-injected
163+
`buzz` is the agent-first CLI. Auth env vars
164+
(`BUZZ_RELAY_URL`, `BUZZ_PRIVATE_KEY`, `BUZZ_AUTH_TAG`) are auto-injected
165165
by the ACP harness into managed agent subprocesses. In development, set
166-
`SPROUT_PRIVATE_KEY` and `SPROUT_RELAY_URL` in your environment manually.
166+
`BUZZ_PRIVATE_KEY` and `BUZZ_RELAY_URL` in your environment manually.
167167

168168
### Building the CLI
169169

170170
```bash
171-
cargo build --release -p sprout-cli
171+
cargo build --release -p buzz-cli
172172
```
173173

174-
Binary location: `./target/release/sprout`. Add `./target/release` to `PATH`
174+
Binary location: `./target/release/buzz`. Add `./target/release` to `PATH`
175175
or invoke with the full path.
176176

177177
### Deep Links
@@ -180,7 +180,7 @@ or invoke with the full path.
180180
thread. To read the linked thread:
181181

182182
```bash
183-
sprout messages thread --channel <uuid> --event <hex> --format compact
183+
buzz messages thread --channel <uuid> --event <hex> --format compact
184184
```
185185

186186
Extract `channel` and `id` from the URL query parameters. The optional
@@ -192,9 +192,9 @@ All reads return sig-stripped JSON arrays; all writes return
192192
0=ok, 1=input error, 2=network/relay, 3=auth, 4=other, 5=write conflict (NIP-33 LWW).
193193

194194
`--format compact` is a **global** flag — it goes before the subcommand:
195-
`sprout --format compact channels list`, NOT `sprout channels list --format compact`.
195+
`buzz --format compact channels list`, NOT `buzz channels list --format compact`.
196196

197-
See `crates/sprout-cli/TESTING.md` for the full live-testing runbook.
197+
See `crates/buzz-cli/TESTING.md` for the full live-testing runbook.
198198

199199
---
200200

@@ -205,7 +205,7 @@ just test-unit # unit tests, no infrastructure needed
205205
just test # full integration suite (requires Postgres + Redis)
206206
```
207207

208-
E2E tests live in `crates/sprout-test-client/tests/`:
208+
E2E tests live in `crates/buzz-test-client/tests/`:
209209
- `e2e_relay.rs` — WebSocket relay protocol
210210
- `e2e_rest_api.rs` — REST endpoint coverage
211211
- `e2e_tokens.rs` — auth token flows
@@ -220,7 +220,7 @@ See [TESTING.md](TESTING.md) for the full multi-agent E2E guide.
220220

221221
### Desktop Screenshots (Playwright)
222222

223-
> **Do NOT use `sprout upload`, the relay media endpoint, or any third-party
223+
> **Do NOT use `buzz upload`, the relay media endpoint, or any third-party
224224
> image host for PR screenshots.** Relay media URLs fail through GitHub's camo
225225
> proxy. Always use `scripts/post-screenshots.sh` — see the `desktop-screenshot`
226226
> skill for the full workflow.
@@ -246,7 +246,7 @@ Output is a PNG path on stdout.
246246

247247
Use `--messages` to inject content into a channel before capture. The JSON file
248248
is an array of objects — `channelName` and `content` are required, all other
249-
fields are optional and passed through to `__SPROUT_E2E_EMIT_MOCK_MESSAGE__`:
249+
fields are optional and passed through to `__BUZZ_E2E_EMIT_MOCK_MESSAGE__`:
250250

251251
```json
252252
[
@@ -350,7 +350,7 @@ must run BEFORE `installMockBridge(page)` — React reads state on mount, the
350350
bridge triggers mount.
351351

352352
**Live messages:** Call `waitForMockLiveSubscription(page, channelName)` before
353-
`__SPROUT_E2E_EMIT_MOCK_MESSAGE__` — messages are silently dropped without a
353+
`__BUZZ_E2E_EMIT_MOCK_MESSAGE__` — messages are silently dropped without a
354354
subscription. Navigate to the channel first (triggers subscription), then away
355355
(so unread indicators appear), then inject.
356356

@@ -393,7 +393,7 @@ description. See [PR #803](https://github.com/block/sprout/pull/803).
393393

394394
## Common Gotchas
395395

396-
1. **Kind `39000` for channel metadata, not `41`** — kind 41 is NIP-01 (unused). All kinds defined in `sprout-core/src/kind.rs`.
396+
1. **Kind `39000` for channel metadata, not `41`** — kind 41 is NIP-01 (unused). All kinds defined in `buzz-core/src/kind.rs`.
397397
2. **Relay queries must specify `kinds`** — omitting `kinds` triggers the p-gate (403). Always include explicit kind filters.
398398
3. **`messages search` must include `--kinds`** — an open-ended search (no kinds) hits the relay p-gate and returns 403. Pass at least `--kinds 9,45001,45003` to scope the query.
399399
4. **Worktrees: `cd` in the same command** — shell CWD doesn't persist between tool calls. Use `cd /path && cargo build` as one command.

0 commit comments

Comments
 (0)