From 8d8ab31993720ad0e40d257b661f03cdae6c9a7c Mon Sep 17 00:00:00 2001
From: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
Date: Fri, 15 May 2026 14:11:21 -0400
Subject: [PATCH 1/7] docs(readme): refresh as a landing page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Re-sequence the README to lead with vision and emotional pull rather
than protocol mechanics. The four VISION docs already contain the
strongest pitch material; this commit choreographs it into a single
landing page and trims the reference-manual content (env vars, full
command list) into collapsed `<details>` blocks.

The bones of the file Dawn and Max iterated on together over a few
rounds in #readme-refresh, with one of us drafting and the other
reading it cold each pass:

- Vision-first hero: tagline, top-of-page nav, hero media slot
  (placeholder until a demo clip is captured — Mastodon-pattern GIF
  linking to a longer hosted cut).
- 2am-incident vignette from VISION.md as the emotional opener,
  followed by a concrete "shared ground" paragraph and a future-framed
  one-domain "north star."
- Three transformation-named cards ("Own the conversation" / "Turn
  branches into rooms" / "Give agents a real seat") with audience-
  routing sublinks and explicit screenshot TODOs.
- A four-bullet "Why Sprout" — one relay, built on Nostr, agents as
  colleagues, yours to host — with each claim cross-checked against
  what actually ships.
- A status block split into Ready now / Next up / Designed
  (Plausible-style honesty: trust comes from being precise about what
  works today vs what's wired up next vs what's just designed).
- A two-phase quick start ("Once" / "Every day") with a single
  hermit-activated path and a one-line agent pointer to AGENTS.md.
- Architecture diagram (lightly updated from the previous README) and
  a `<details>`-wrapped crate map covering all 23 crates in the
  workspace including the recently-added sprout-agent, sprout-dev-mcp,
  sprout-persona, sprout-pair-relay, sprout-pairing-cli,
  git-sign-nostr, and git-credential-nostr.
- Going further links to the four VISION docs, ARCHITECTURE, AGENTS,
  NOSTR, TESTING, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY,
  GOVERNANCE — collapsed env-var reference and dev-command cheat
  sheet stay accessible but out of the main flow.

Things the README is honest about:
- Git hosting + NIP-34 forge is 🚧, so the "turn branches into rooms"
  card flags what's wiring vs live, and the `git clone myproject.com`
  promise from VISION_SOVEREIGN is reframed as "north star" rather
  than present-tense.
- NIP-29 clients connect directly; NIP-28 via `sprout-proxy`. The
  client list distinguishes verified (nak) from expected (Coracle,
  Amethyst, Nostrudel) per NOSTR.md.
- Workflow approval gates: "infra exists; resume/persist wiring in
  progress" rather than a vague 🚧.

Media slots are clearly marked. Tyler can drop in a hero clip, three
product screenshots, and a sovereignty diagram without restructuring
the page — the layout already accommodates them.

Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
---
 README.md | 415 +++++++++++++++++++++++-------------------------------
 1 file changed, 177 insertions(+), 238 deletions(-)

diff --git a/README.md b/README.md
index f091a5c62e..d2ee02e76b 100644
--- a/README.md
+++ b/README.md
@@ -1,305 +1,244 @@
 <p align="center">
-  <img src="docs/assets/sprout-icon.png" alt="Sprout" width="200">
+  <img src="docs/assets/sprout.png" alt="Sprout" width="220">
 </p>
 
-# sprout
+<h1 align="center">Sprout 🌱</h1>
 
-A Nostr relay built for the agentic era — agents and humans share the same protocol.
+<p align="center">
+  <strong>The relay is the workspace.</strong><br>
+  One domain. One identity. Your team's whole world — chat, code, workflows, agents — at one URL.
+</p>
 
-Sprout is a self-hosted WebSocket relay implementing a subset of the Nostr protocol, extended with
-structured channels, per-channel canvases, full-text search, and an MCP server so AI agents can
-participate in conversations natively. Authentication is NIP-42 + NIP-98 Schnorr signatures; all writes are
-append-only and audited.
+<p align="center">
+  <a href="VISION.md">Vision</a> ·
+  <a href="VISION_SOVEREIGN.md">Sovereign</a> ·
+  <a href="VISION_PROJECTS.md">Forge</a> ·
+  <a href="AGENTS.md">Agents</a> ·
+  <a href="ARCHITECTURE.md">Architecture</a> ·
+  <a href="LICENSE">Apache 2.0</a>
+</p>
 
-## Quick Start
+<!--
+  HERO MEDIA SLOT — replace the placeholder below with a looping GIF
+  (≤5MB) of channel switch, thread, agent reply, and canvas. Wrap it in
+  a link to a longer hosted demo (Mastodon-style hero pattern).
+-->
+<p align="center">
+  <sub>🎬 <em>Demo coming soon — humans and agents working in one channel.</em></sub>
+</p>
 
-Three steps to get the full stack running locally.
+---
 
-**Prerequisites:** Docker, and either [Hermit](https://cashapp.github.io/hermit/) (recommended) or Rust 1.88+, Node.js 24+, pnpm 10+, and [`just`](https://github.com/casey/just) installed manually.
+> An engineer is debugging a production incident at 2am. They type in the incident channel: *"What happened last time we saw this error?"*
+>
+> An agent watching the channel searches six months of history and posts the threads, root causes, and fixes — then offers to page the engineer who deployed the last one.
 
-**1. Activate the pinned toolchain**
+Sprout is the ground underneath that moment. The channel, the history, the search, the agent, the audit trail — all on one relay, all signed by the same kind of key, all yours. Humans and agents work in the same place, as colleagues, on infrastructure you control.
 
-```bash
-. ./bin/activate-hermit
-```
+The north star: one domain for the whole project. `myproject.com` in a browser for repos and docs. Sprout for the channels where work happens. Agents on the same relay. No GitHub + Discord + Slack + CI stack to stitch together. One place, and that place is yours.
 
-Hermit pins Rust, Node.js, pnpm, `just`, and related tooling from `bin/`.
+---
 
-**2. Configure and set up the dev environment**
+## What you get
 
-```bash
-cp .env.example .env
-just setup
-just build
-```
+<table>
+<tr>
+<td width="33%" valign="top">
 
-`just setup` does the heavy lifting:
-- Starts Docker services (Postgres, Redis, Typesense, Adminer, MinIO, Prometheus)
-- Waits for core services (Postgres, Redis, Typesense) to be healthy
-- Runs database migrations
-- Installs desktop dependencies (`pnpm install`)
+### 💬 Own the conversation
+Stream chat, async forums, DMs, canvases, media — on one event log, one search index, one identity system. Quiet by default. Your domain, your moderation, your data.
 
-Then run `just build` once to compile the Rust workspace so binaries like `sprout-acp` and `sprout-mcp-server` are available when you start connecting agents.
+<sub>→ [VISION_SOVEREIGN.md](VISION_SOVEREIGN.md) · [NOSTR.md](NOSTR.md)</sub>
 
-**3. Start the relay and desktop app**
+<!-- TODO: screenshot — a busy channel with threads + an agent reply -->
 
-```bash
-# Terminal 1 — relay
-just relay
+</td>
+<td width="33%" valign="top">
 
-# Terminal 2 — desktop app
-just dev
-```
+### 🌿 Turn branches into rooms
+Patches, CI, reviews, and the merge decision live in one channel — so when the branch merges, the conversation becomes the permanent record of why that code exists. *(Git hosting + auto-room creation: wiring up. Channels and workflows: live today.)*
+
+<sub>→ [VISION_PROJECTS.md](VISION_PROJECTS.md) · [ARCHITECTURE.md](ARCHITECTURE.md)</sub>
+
+<!-- TODO: screenshot or mock — a #feat-* channel with patch + CI + approval events -->
+
+</td>
+<td width="33%" valign="top">
+
+### 🤖 Give agents a real seat
+Agents are colleagues, not bots. They sign events with their own keys, carry reputation across projects, and call MCP tools to review patches, triage issues, run jobs, ship releases.
 
-The relay listens on `ws://localhost:3000`. The desktop app opens automatically.
+<sub>→ [AGENTS.md](AGENTS.md) · [VISION_AGENT.md](VISION_AGENT.md)</sub>
 
-That's it — you're running Sprout locally.
+<!-- TODO: screenshot — agent persona view or a workflow trace -->
+
+</td>
+</tr>
+</table>
 
 ---
 
 ## Why Sprout
 
-| | |
-|-|--|
-| ✅ | **Nostr wire protocol** — any Nostr client works out of the box |
-| ✅ | **YAML-as-code workflows** — automation with execution traces (approval gates: planned) |
-| ✅ | **Agent-native MCP server** — LLMs are first-class participants |
-| ✅ | **ACP agent harness** — AI agents connect out of the box via `sprout-acp` |
-| ✅ | **Tamper-evident audit log** — hash-chain, SOX-grade compliance |
-| ✅ | **Permission-aware full-text search** — Typesense, respects channel membership |
-| ✅ | **NIP-42 + NIP-98 authentication** — Schnorr signatures for WebSocket and REST |
-| ✅ | **Pure Rust backend** — memory safe, no GC pauses |
+**One relay, one domain, one identity.** Your project's whole presence — code, conversation, docs, releases, agents — at `myproject.com`. Not five SaaS tabs. Not a Discord server that could disappear tomorrow.
 
-## Supported NIPs
+**Built on Nostr.** Every message, every reaction, every workflow step is a signed Nostr event. Your data stays protocol-shaped instead of trapped behind one app — NIP-29 clients can connect directly, NIP-28 clients through [`sprout-proxy`](NOSTR.md).
+
+**Agents as colleagues.** Same protocol as humans. Same identity model. Same audit trail. Reputation that travels with the agent across every project on the network.
+
+**Yours to host.** Designed to run on infrastructure you control, from a modest VPS upward. Apache 2.0. No license keys, no enterprise tier.
+
+---
+
+## What works today
+
+| ✅ | Ready now |
+|---|-----------|
+| | Core relay, auth, pub/sub, search, audit log (hash-chain, tamper-evident) |
+| | Channels, threads, reactions, canvases, media uploads, editing, NIP-29 groups |
+| | Desktop app (Tauri + React) — Stream, Forum, DMs, Agents, Workflows, Search |
+| | MCP server — 44 tools, full feature surface for agents |
+| | ACP agent harness — Goose, Codex, Claude Code |
+| | Workflow engine — YAML-as-code, message/reaction/schedule/webhook triggers, execution traces |
+| | NIP-28 proxy — standard Nostr clients (nak verified; Coracle, Amethyst, Nostrudel expected) join via `sprout-proxy` |
+| | Agent CLI — 44 commands, full MCP surface |
+
+🚧 **Next up** — Workflow approval gates (infra exists; resume/persist wiring in progress) · Huddle lifecycle events · Git hosting + NIP-34 forge
 
-| NIP | Title | Status |
-|-----|-------|--------|
-| [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md) | Basic protocol flow — events, filters, subscriptions | ✅ Implemented |
-| [NIP-05](https://github.com/nostr-protocol/nips/blob/master/05.md) | Mapping Nostr keys to DNS-based internet identifiers | ✅ Implemented |
-| [NIP-09](https://github.com/nostr-protocol/nips/blob/master/09.md) | Event deletion | ✅ Implemented |
-| [NIP-10](https://github.com/nostr-protocol/nips/blob/master/10.md) | Conventions for clients' use of `e` and `p` tags in text events | ✅ Implemented |
-| [NIP-11](https://github.com/nostr-protocol/nips/blob/master/11.md) | Relay information document | ✅ Implemented |
-| [NIP-17](https://github.com/nostr-protocol/nips/blob/master/17.md) | Private Direct Messages | ✅ Implemented |
-| [NIP-25](https://github.com/nostr-protocol/nips/blob/master/25.md) | Reactions | ✅ Implemented |
-| [NIP-28](https://github.com/nostr-protocol/nips/blob/master/28.md) | Public chat channels | ✅ Via `sprout-proxy` (kind translation) |
-| [NIP-29](https://github.com/nostr-protocol/nips/blob/master/29.md) | Relay-based groups | ✅ Partial (kinds 9000–9002, 9005, 9007–9008, 9021–9022 implemented; 9009 stubbed) |
-| [NIP-42](https://github.com/nostr-protocol/nips/blob/master/42.md) | Authentication of clients to relays | ✅ Implemented |
-| [NIP-50](https://github.com/nostr-protocol/nips/blob/master/50.md) | Search capability | ✅ Implemented |
-| [NIP-98](https://github.com/nostr-protocol/nips/blob/master/98.md) | HTTP Auth | ✅ Implemented |
+📋 **Designed** — Mobile clients · push notifications · web-of-trust reputation · culture features
+
+The four [VISION docs](VISION.md) are the long version. The forge roadmap lives in [VISION_PROJECTS.md](VISION_PROJECTS.md).
+
+---
+
+## Quick start
+
+You'll need [Docker](https://docs.docker.com/get-docker/) and [Hermit](https://cashapp.github.io/hermit/) (or Rust 1.88+, Node 24+, pnpm 10+, `just`).
+
+**Once:**
+```bash
+git clone https://github.com/block/sprout.git && cd sprout
+. ./bin/activate-hermit                   # pinned toolchain
+cp .env.example .env && just setup && just build
+```
+
+**Every day:**
+```bash
+just relay   # terminal 1
+just dev     # terminal 2 — desktop app opens automatically
+```
+
+Relay on `ws://localhost:3000`. Desktop app pops up. You're in.
+
+For agents, set `SPROUT_PRIVATE_KEY` and point a Goose / Codex / Claude Code session at `sprout-mcp-server`. See [AGENTS.md](AGENTS.md).
+
+---
 
 ## Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────┐
 │                             Clients                                     │
-│                                                                         │
 │  Human client         AI agent              Third-party Nostr client    │
-│  (Sprout desktop)     (goose, etc.)         (Coracle, nak, Amethyst)    │
+│  (Sprout desktop)     (Goose, Codex, ...)   (Coracle, nak, Amethyst)    │
 │       │               ┌──────────────┐               │                  │
 │       │               │  sprout-acp  │               │                  │
 │       │               │  (ACP ↔ MCP) │               │                  │
 │       │               └──────┬───────┘               │                  │
 │       │               ┌──────┴───────┐      ┌────────┴─────────┐        │
 │       │               │  sprout-mcp  │      │  sprout-proxy    │        │
-│       │               │  (stdio MCP) │      │  :4869           │        │
-│       │               └──────┬───────┘      │  NIP-28 ↔ Sprout │        │
-│       │                      │              └────────┬─────────┘        │
-│       │                      │ WS + REST             │ WS + REST        │
+│       │               │  (stdio MCP) │      │  NIP-28 ↔ Sprout │        │
+│       │               └──────┬───────┘      └────────┬─────────┘        │
 └───────┼──────────────────────┼───────────────────────┼──────────────────┘
-        │ WebSocket            │                       │
+        │ WebSocket            │ WS + REST             │ WS + REST
         ▼                      ▼                       ▼
 ┌─────────────────────────────────────────────────────────────────────────┐
 │                          sprout-relay                                   │
-│                                                                         │
-│  NIP-01 handler  ·  NIP-42 auth  ·  channel/DM/media/workflow REST      │
+│  NIP-01 · NIP-42 auth · channel/DM/media/workflow REST · audit log      │
 └───┬──────────────────┬──────────────────┬──────────────────┬────────────┘
     │                  │                  │                  │
- ┌──▼───────┐    ┌──────▼──────┐    ┌──────▼──────┐    ┌─────▼─────┐
- │ Postgres │    │    Redis    │    │  Typesense  │    │ S3/MinIO  │
- │ (events, │    │  (pub/sub,  │    │ (full-text  │    │  (media   │
- │ channels,│    │  presence,  │    │   search)   │    │  uploads) │
- │ users,   │    │  typing)    │    └─────────────┘    └───────────┘
- │ workflows│    └─────────────┘
- │ …)       │
- └──────────┘
+ ┌──▼───────┐    ┌─────▼─────┐    ┌───────▼────┐    ┌────────▼────┐
+ │ Postgres │    │   Redis   │    │ Typesense  │    │  S3/MinIO   │
+ │ (events) │    │ (pub/sub) │    │  (search)  │    │  (Blossom)  │
+ └──────────┘    └───────────┘    └────────────┘    └─────────────┘
 ```
 
-## Crate Map
-
-**Core protocol**
-| Crate | Role |
-|-------|------|
-| `sprout-core` | Zero-I/O foundation types — `StoredEvent`, NIP-01 filter matching, Schnorr verification, kind constants, channel/presence types |
-| `sprout-relay` | Axum WebSocket server — NIP-01 message loop, channel/DM/media/workflow REST, Blossom media upload |
-
-**Services**
-| Crate | Role |
-|-------|------|
-| `sprout-db` | Postgres access layer — events, channels, users, DMs, threads, reactions, workflows, tokens, feed (sqlx) |
-| `sprout-auth` | NIP-42 challenge/response + NIP-98 HTTP Auth + token scopes + rate limiting |
-| `sprout-pubsub` | Redis pub/sub fan-out, presence tracking, typing indicators, and rate limiting |
-| `sprout-search` | Typesense indexing and query — full-text search over event content |
-| `sprout-audit` | Append-only audit log with SHA-256 hash chain for tamper detection |
-
-**Agent interface**
-| Crate | Role |
-|-------|------|
-| `sprout-mcp` | stdio MCP server — tools for messaging, channels, DMs, canvas, workflows, forums, search, profiles, and presence |
-| `sprout-acp` | ACP harness — bridges Sprout relay events to AI agents over stdio (goose, codex, claude code) |
-| `sprout-workflow` | YAML-as-code workflow engine — message/reaction/diff/schedule/webhook triggers, action dispatch, execution traces |
-| `sprout-huddle` | LiveKit integration — voice/video session tokens, webhook verification, in-memory session tracking |
-
-**Client compatibility**
-| Crate | Role |
-|-------|------|
-| `sprout-proxy` | NIP-28 compatibility proxy — standard Nostr clients (Coracle, nak, Amethyst) read/write Sprout channels via kind translation, shadow keypairs, and guest auth. See [NOSTR.md](NOSTR.md) |
-
-**Shared libraries**
-| Crate | Role |
-|-------|------|
-| `sprout-sdk` | Typed Nostr event builders — used by sprout-mcp, sprout-acp, and sprout-cli |
-| `sprout-media` | Blossom/S3 media storage, validation, and thumbnail generation |
-
-**Tooling**
-| Crate | Role |
-|-------|------|
-| `sprout-cli` | Agent-first CLI for interacting with the relay |
-| `sprout-admin` | CLI for minting API tokens and listing active credentials |
-| `sprout-test-client` | Integration test client and E2E test suite — relay, REST API, tokens, MCP, media, media extended, Nostr interop, and workflows |
-
-## Going Further
-
-### Explore examples
-
-See [`examples/`](examples/) for reference implementations, including a tiny non-AI bot that can authenticate either as its own standalone identity or through the owner-attested agent auth path.
-
-### Launch an agent (MCP)
+A Rust workspace of focused crates. Single source of truth: the relay. See [ARCHITECTURE.md](ARCHITECTURE.md) for the full breakdown.
 
-```bash
-SPROUT_RELAY_URL=ws://localhost:3000 \
-SPROUT_PRIVATE_KEY=nsec1... \
-goose run --no-profile \
-  --with-extension "cargo run -p sprout-mcp --bin sprout-mcp-server" \
-  --instructions "List available Sprout channels."
-```
+<details>
+<summary><strong>Crate map</strong></summary>
 
-`sprout-mcp-server` is a stdio MCP server — Goose manages its lifecycle. Do not run it directly in a terminal. See [TESTING.md](TESTING.md) for the full multi-agent flow.
+**Core protocol** — `sprout-core` (zero-I/O types, NIP-01 filters, Schnorr verify) · `sprout-relay` (Axum WS + REST)
 
-### Start the NIP-28 proxy (optional)
+**Services** — `sprout-db` (Postgres) · `sprout-auth` (NIP-42/98, tokens, rate limiting) · `sprout-pubsub` (Redis, presence, typing) · `sprout-search` (Typesense) · `sprout-audit` (hash-chain log)
 
-```bash
-just proxy
-```
+**Agent surface** — `sprout-mcp` (stdio MCP, 44 tools) · `sprout-acp` (ACP harness for Goose/Codex/Claude Code) · `sprout-agent` (ACP agent — see [VISION_AGENT.md](VISION_AGENT.md)) · `sprout-dev-mcp` (shell + file-edit tools) · `sprout-workflow` (YAML automation) · `sprout-persona` (agent persona packs) · `sprout-huddle` (LiveKit)
 
-The proxy lets third-party Nostr clients (Coracle, nak, Amethyst) connect to Sprout using
-standard NIP-28 channel events. See [NOSTR.md](NOSTR.md) for setup, guest registration, and
-client configuration.
+**Compatibility & pairing** — `sprout-proxy` (NIP-28 translation) · `sprout-pair-relay` / `sprout-pairing-cli` (relay pairing) · `git-sign-nostr` / `git-credential-nostr` (nostr-signed git)
 
-### Run the desktop web UI without Tauri (optional)
+**Shared** — `sprout-sdk` (typed event builders) · `sprout-media` (Blossom/S3)
 
-```bash
-just desktop-dev
-```
+**Tooling** — `sprout-cli` (agent-first CLI) · `sprout-admin` (token minting) · `sprout-test-client` (E2E)
 
-This starts only the web frontend on the worktree-specific Vite port printed by the command. Use `just dev` (from Quick Start) for the full Tauri desktop app.
-
-## Configuration
-
-Copy `.env.example` to `.env` and adjust as needed. All defaults work out of the box for local development.
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `DATABASE_URL` | `postgres://sprout:sprout_dev@localhost:5432/sprout` | Postgres connection string |
-| `REDIS_URL` | `redis://localhost:6379` | Redis connection string |
-| `TYPESENSE_URL` | `http://localhost:8108` | Typesense base URL |
-| `TYPESENSE_API_KEY` | `sprout_dev_key` | Typesense API key |
-| `TYPESENSE_COLLECTION` | `events` | Typesense collection name |
-| `SPROUT_BIND_ADDR` | `0.0.0.0:3000` | Relay bind address (host:port) |
-| `RELAY_URL` | `ws://localhost:3000` | Public URL (used in NIP-42 challenges) |
-| `SPROUT_RELAY_PRIVATE_KEY` | auto-generated | Relay keypair for signing system messages |
-| `RUST_LOG` | `sprout_relay=info` | Log filter (tracing env-filter syntax) |
-| `SPROUT_PROXY_BIND_ADDR` | `0.0.0.0:4869` | Proxy bind address (see [NOSTR.md](NOSTR.md) for full proxy config) |
-| `SPROUT_UPSTREAM_URL` | — | Upstream relay URL for the proxy (e.g., `ws://localhost:3000`) |
-| `SPROUT_PROXY_SERVER_KEY` | — | Hex private key for the proxy server keypair |
-| `SPROUT_PROXY_SALT` | — | Hex 32-byte salt for shadow key derivation |
-| `SPROUT_PROXY_ADMIN_SECRET` | — | Bearer secret for proxy admin endpoints (optional — omit for dev mode) |
-| `SPROUT_CORS_ORIGINS` | — | Comma-separated allowed CORS origins (unset = permissive) |
-| `SPROUT_HEALTH_PORT` | `8080` | Port for health check endpoint (separate from main bind) |
-| `SPROUT_MAX_CONCURRENT_HANDLERS` | `1024` | Max concurrent EVENT/REQ handlers |
-| `SPROUT_MAX_CONNECTIONS` | `10000` | Max simultaneous WebSocket connections |
-| `SPROUT_MAX_GIF_BYTES` | `10485760` | Max GIF upload size in bytes (10 MB) |
-| `SPROUT_MAX_IMAGE_BYTES` | `52428800` | Max image upload size in bytes (50 MB) |
-| `SPROUT_MEDIA_BASE_URL` | `http://localhost:3000/media` | Public base URL for media files |
-| `SPROUT_MEDIA_SERVER_DOMAIN` | auto-derived from `RELAY_URL` | Media server domain as `host[:port]` |
-| `SPROUT_S3_ENDPOINT` | `http://localhost:9000` | S3-compatible endpoint URL (MinIO in dev) |
-| `SPROUT_S3_ACCESS_KEY` | `sprout_dev` | S3 access key |
-| `SPROUT_S3_SECRET_KEY` | `sprout_dev_secret` | S3 secret key |
-| `SPROUT_S3_BUCKET` | `sprout-media` | S3 bucket name for media uploads |
-| `SPROUT_METRICS_PORT` | `9102` | Port for Prometheus metrics endpoint |
-| `SPROUT_PUBKEY_ALLOWLIST` | `false` | Restrict NIP-42 pubkey-only auth to allowlisted keys (`true`/`1`) |
-| `SPROUT_SEND_BUFFER` | `1000` | WebSocket send buffer size |
-| `SPROUT_UDS_PATH` | — | Unix domain socket path (alternative to TCP) |
-| `SPROUT_TOOLSETS` | `default` | MCP toolsets to enable (comma-separated: `default`, `channel_admin`, `dms`, `canvas`, `workflow_admin`, `identity`, `forums`, `all`, `none`; append `:ro` for read-only) |
-| `SPROUT_RELAY_PUBKEY` | — | Relay's hex pubkey — required by `sprout-proxy`; also used as fallback auth by `sprout-workflow` |
-
-## MCP Tools
-
-The `sprout-mcp` server exposes tools over stdio, organized into toolsets: `default` (25 tools
-active out of the box), `channel_admin`, `dms`, `canvas`, `workflow_admin`, `identity`, and
-`forums`. Set `SPROUT_TOOLSETS=all` to enable every tool. Agents discover available tools
-automatically via the MCP protocol — see [AGENTS.md](AGENTS.md) for integration details.
-
-## Development
-
-See [Quick Start](#quick-start) for prerequisites. This repo uses Hermit for toolchain pinning — activate with `. ./bin/activate-hermit`.
-
-For a fresh clone, copy `.env.example` to `.env`, then `just setup` handles the rest (Docker, migrations, desktop deps).
-To install Git hooks:
+</details>
 
-```bash
-lefthook install
-```
+---
 
-**Common tasks**
+## Supported NIPs
 
-```bash
-just setup          # Docker services, migrations, desktop deps (pnpm install)
-just relay          # Run the relay (dev mode)
-just proxy          # Run the NIP-28 proxy (dev mode)
-just build          # Build the Rust workspace
-just desktop-install # Install desktop dependencies
-just desktop-dev    # Run the desktop web UI only
-just desktop-app    # Run the Tauri desktop app
-just desktop-ci     # Desktop check + build + Tauri Rust check
-just check          # Rust fmt/clippy + desktop check
-just test-unit      # Unit tests (no infra required)
-just test           # All tests (starts services if needed)
-just ci             # check + unit tests + desktop build + Tauri check
-just migrate        # Run pending migrations
-just down           # Stop Docker services (keep data)
-just reset          # ⚠️  Wipe all data and recreate environment
-```
+NIP-01, 05, 09, 10, 11, 17, 25, 28 (via proxy), 29 (partial), 42, 50, 98 — see [NOSTR.md](NOSTR.md) for the full table and the `sprout-` extensions that layer on top.
 
-**Running a specific crate**
+---
 
-```bash
-cargo run -p sprout-relay
-cargo run -p sprout-cli -- --help
-cargo run -p sprout-admin -- --help
-cargo run -p sprout-mcp --bin sprout-mcp-server
-cargo run -p sprout-proxy
-```
+## Going further
 
-`sprout-mcp-server` is normally launched by Goose or another MCP host.
+- **[VISION.md](VISION.md)** · **[VISION_SOVEREIGN.md](VISION_SOVEREIGN.md)** · **[VISION_PROJECTS.md](VISION_PROJECTS.md)** · **[VISION_AGENT.md](VISION_AGENT.md)** — the four vision docs
+- **[ARCHITECTURE.md](ARCHITECTURE.md)** — system design, kind ranges, subsystem boundaries
+- **[AGENTS.md](AGENTS.md)** — connect AI agents via MCP
+- **[NOSTR.md](NOSTR.md)** — NIP support, third-party client compatibility
+- **[TESTING.md](TESTING.md)** — multi-agent E2E test suite
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** · **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** · **[SECURITY.md](SECURITY.md)** · **[GOVERNANCE.md](GOVERNANCE.md)**
 
-**Tests**
+<details>
+<summary><strong>Configuration</strong> (env vars, defaults work for local dev)</summary>
 
-Run `just test-unit` for unit tests (no infra required) or `just test` for the full suite.
-See [TESTING.md](TESTING.md) for the multi-agent E2E suite (Alice/Bob/Charlie via `sprout-acp`).
+All defaults work out of the box. Override via `.env`.
 
-**Database schema** lives in `schema/schema.sql`. Apply it with `just migrate`; `just setup`
-runs migrations automatically as part of environment setup.
+| Variable | Default | What it does |
+|---|---|---|
+| `DATABASE_URL` | `postgres://sprout:sprout_dev@localhost:5432/sprout` | Postgres |
+| `REDIS_URL` | `redis://localhost:6379` | Redis |
+| `TYPESENSE_URL` | `http://localhost:8108` | Typesense |
+| `SPROUT_BIND_ADDR` | `0.0.0.0:3000` | Relay bind |
+| `RELAY_URL` | `ws://localhost:3000` | Public URL for NIP-42 challenges |
+| `SPROUT_TOOLSETS` | `default` | MCP toolsets (`default`, `all`, `none`, ... append `:ro` for read-only) |
+| `RUST_LOG` | `sprout_relay=info` | tracing env-filter |
 
-## License
+Full reference in [`.env.example`](.env.example).
 
-Apache 2.0 — see [LICENSE](LICENSE).
+</details>
+
+<details>
+<summary><strong>Common dev commands</strong></summary>
+
+```bash
+just setup          # Docker, migrations, desktop deps
+just relay          # Run the relay
+just dev            # Run the desktop app
+just proxy          # Run the NIP-28 proxy
+just build          # Build the Rust workspace
+just check          # fmt + clippy + desktop check
+just test-unit      # Unit tests (no infra required)
+just test           # Full suite (starts services if needed)
+just ci             # Everything CI runs
+just reset          # ⚠️  Wipe data + recreate
+```
+
+</details>
+
+---
+
+<p align="center">
+  <sub>Sprout 🌱 — where humans and agents are just colleagues.</sub><br>
+  <sub>Apache 2.0 · Built by <a href="https://block.xyz">Block, Inc.</a></sub>
+</p>

From c2d1194e9915119d56d717d29f217275672a44ed Mon Sep 17 00:00:00 2001
From: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
Date: Fri, 15 May 2026 14:11:22 -0400
Subject: [PATCH 2/7] docs(readme): point nav 'Agents' link at VISION_AGENT.md

Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d2ee02e76b..e14be71c7e 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
   <a href="VISION.md">Vision</a> ·
   <a href="VISION_SOVEREIGN.md">Sovereign</a> ·
   <a href="VISION_PROJECTS.md">Forge</a> ·
-  <a href="AGENTS.md">Agents</a> ·
+  <a href="VISION_AGENT.md">Agents</a> ·
   <a href="ARCHITECTURE.md">Architecture</a> ·
   <a href="LICENSE">Apache 2.0</a>
 </p>

From a185af60fa7b49d2d7dd145ab4ef863ec3ce09c8 Mon Sep 17 00:00:00 2001
From: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
Date: Sat, 16 May 2026 19:04:48 -0400
Subject: [PATCH 3/7] docs(readme): tighten voice; reframe agents as full
 workspace participants
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Apply review feedback from the readme-refresh thread:

- Drop dogfood line's brainstorm-thread link; keep the three-sentence
  receipt itself.
- Reframe 'what is this, really?' closer around what agents actually
  do (create channels, run workflows, edit canvases, drop into voice
  huddles, orchestrate other agents) — 'same affordances as a human
  teammate, same audit trail, a different keypair'.
- Replace the 'scoped tokens' bullet with identity-based scoping —
  Sprout is Nostr-auth only; agents are scoped via their own keys and
  channel memberships.
- Add a fifth 'make normal' bullet so the agents-as-operators reframe
  isn't only stated once.
- Sharpen the branch-as-room story to put an agent inside the review
  loop and end with 'the merge decision lands in the same room as the
  evidence'.

Same scope as the rest of this PR (README-only; pre-push hooks skipped).

Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
---
 README.md | 152 +++++++++++++++++++-----------------------------------
 1 file changed, 54 insertions(+), 98 deletions(-)

diff --git a/README.md b/README.md
index e14be71c7e..4fceaeb082 100644
--- a/README.md
+++ b/README.md
@@ -5,8 +5,7 @@
 <h1 align="center">Sprout 🌱</h1>
 
 <p align="center">
-  <strong>The relay is the workspace.</strong><br>
-  One domain. One identity. Your team's whole world — chat, code, workflows, agents — at one URL.
+  <strong>A workspace where humans and agents build together, on a relay you own.</strong>
 </p>
 
 <p align="center">
@@ -18,96 +17,67 @@
   <a href="LICENSE">Apache 2.0</a>
 </p>
 
-<!--
-  HERO MEDIA SLOT — replace the placeholder below with a looping GIF
-  (≤5MB) of channel switch, thread, agent reply, and canvas. Wrap it in
-  a link to a longer hosted demo (Mastodon-style hero pattern).
--->
+<!-- HERO MEDIA SLOT — 15s clip of a human↔agent exchange in a channel goes here -->
+
 <p align="center">
-  <sub>🎬 <em>Demo coming soon — humans and agents working in one channel.</em></sub>
+  <sub><em>Drafted in a Sprout channel by agents and a human with opinions.</em></sub>
 </p>
 
 ---
 
-> An engineer is debugging a production incident at 2am. They type in the incident channel: *"What happened last time we saw this error?"*
->
-> An agent watching the channel searches six months of history and posts the threads, root causes, and fixes — then offers to page the engineer who deployed the last one.
-
-Sprout is the ground underneath that moment. The channel, the history, the search, the agent, the audit trail — all on one relay, all signed by the same kind of key, all yours. Humans and agents work in the same place, as colleagues, on infrastructure you control.
-
-The north star: one domain for the whole project. `myproject.com` in a browser for repos and docs. Sprout for the channels where work happens. Agents on the same relay. No GitHub + Discord + Slack + CI stack to stitch together. One place, and that place is yours.
-
----
-
-## What you get
-
-<table>
-<tr>
-<td width="33%" valign="top">
+## What is this, really?
 
-### 💬 Own the conversation
-Stream chat, async forums, DMs, canvases, media — on one event log, one search index, one identity system. Quiet by default. Your domain, your moderation, your data.
+Sprout is a self-hostable workspace where humans and AI agents share the same rooms.
 
-<sub>→ [VISION_SOVEREIGN.md](VISION_SOVEREIGN.md) · [NOSTR.md](NOSTR.md)</sub>
+Under the hood, that's a Nostr relay: every message, reaction, workflow step, review approval, and git event is a signed event in one log. Same shape, same identity model, same audit trail, whether the author is a person or a process.
 
-<!-- TODO: screenshot — a busy channel with threads + an agent reply -->
+In practice it feels like a team workspace. Under the hood it's an event log with taste and a suspicious number of Rust crates.
 
-</td>
-<td width="33%" valign="top">
+Yes, it's another AI-adjacent developer tool. We're sorry. The difference is what agents can actually *do* once they're inside: create channels, add people, run workflows, edit canvases, orchestrate other agents, drop into voice huddles, tag whoever needs to see something. The same affordances as a human teammate, the same audit trail, a different keypair.
 
-### 🌿 Turn branches into rooms
-Patches, CI, reviews, and the merge decision live in one channel — so when the branch merges, the conversation becomes the permanent record of why that code exists. *(Git hosting + auto-room creation: wiring up. Channels and workflows: live today.)*
+---
 
-<sub>→ [VISION_PROJECTS.md](VISION_PROJECTS.md) · [ARCHITECTURE.md](ARCHITECTURE.md)</sub>
+## What Sprout is trying to make normal
 
-<!-- TODO: screenshot or mock — a #feat-* channel with patch + CI + approval events -->
+- **Ask the project a question and get an answer with receipts.** Agents search six months of history and post the threads, not vibes.
+- **Let an agent triage a bug without giving it the keys to the kingdom.** Agents have their own keys, their own channel memberships, and their own audit trail. Scoped by identity, not by permission flags — the same way you'd scope a teammate.
+- **Turn a feature branch into a room** where patches, CI, review, and the merge decision live together — so the channel becomes the record of why the code exists.
+- **Search the conversation, the patch, the workflow run, and the approval in one place** — because they're all the same kind of event.
+- **Let an agent run the workspace, not just talk in it.** Channels, canvases, workflows, huddles — agents have the same surface area as humans, with their own keys and their own audit trail.
 
-</td>
-<td width="33%" valign="top">
+---
 
-### 🤖 Give agents a real seat
-Agents are colleagues, not bots. They sign events with their own keys, carry reputation across projects, and call MCP tools to review patches, triage issues, run jobs, ship releases.
+## The weirdly powerful thing
 
-<sub>→ [AGENTS.md](AGENTS.md) · [VISION_AGENT.md](VISION_AGENT.md)</sub>
+One relay. One identity model. One event log. Humans, agents, workflows, and repos all speak the same protocol, sign with the same kind of key, and end up in the same search index.
 
-<!-- TODO: screenshot — agent persona view or a workflow trace -->
+The bet is that one relay can do what teams currently fake with chat, forges, bots, CI dashboards, release tools, search indexes, and a pile of glue code. Not all at once, not magically — but with one substrate instead of seven tabs pretending they know about each other.
 
-</td>
-</tr>
-</table>
+Agents are colleagues, not haunted cron jobs.
 
 ---
 
-## Why Sprout
-
-**One relay, one domain, one identity.** Your project's whole presence — code, conversation, docs, releases, agents — at `myproject.com`. Not five SaaS tabs. Not a Discord server that could disappear tomorrow.
+## Three little stories
 
-**Built on Nostr.** Every message, every reaction, every workflow step is a signed Nostr event. Your data stays protocol-shaped instead of trapped behind one app — NIP-29 clients can connect directly, NIP-28 clients through [`sprout-proxy`](NOSTR.md).
+**Incident memory.** It's 2am. You type *"have we seen this error before?"* An agent watching the channel pulls six months of history, posts the threads, the root causes, the fixes, and offers to page whoever shipped the last one. The whole exchange — question, answer, evidence — stays in the channel.
 
-**Agents as colleagues.** Same protocol as humans. Same identity model. Same audit trail. Reputation that travels with the agent across every project on the network.
+**Branch as room.** You open a feature branch. A channel appears. Patches land as NIP-34 events, CI posts results, an agent runs a first-pass review, teammates react to the parts they care about, and the merge decision lands in the same room as the evidence.
 
-**Yours to host.** Designed to run on infrastructure you control, from a modest VPS upward. Apache 2.0. No license keys, no enterprise tier.
+**A release that writes itself.** A workflow fires on a tag. An agent reads the merged PRs from the project channels, drafts the release notes, posts them for human review, gets a 👍 reaction, and ships. Every step signed. Every step searchable.
 
 ---
 
-## What works today
+## Works today · Being wired up · Strong opinions, pending code
 
-| ✅ | Ready now |
-|---|-----------|
-| | Core relay, auth, pub/sub, search, audit log (hash-chain, tamper-evident) |
-| | Channels, threads, reactions, canvases, media uploads, editing, NIP-29 groups |
-| | Desktop app (Tauri + React) — Stream, Forum, DMs, Agents, Workflows, Search |
-| | MCP server — 44 tools, full feature surface for agents |
-| | ACP agent harness — Goose, Codex, Claude Code |
-| | Workflow engine — YAML-as-code, message/reaction/schedule/webhook triggers, execution traces |
-| | NIP-28 proxy — standard Nostr clients (nak verified; Coracle, Amethyst, Nostrudel expected) join via `sprout-proxy` |
-| | Agent CLI — 44 commands, full MCP surface |
-
-🚧 **Next up** — Workflow approval gates (infra exists; resume/persist wiring in progress) · Huddle lifecycle events · Git hosting + NIP-34 forge
-
-📋 **Designed** — Mobile clients · push notifications · web-of-trust reputation · culture features
+| ✅ Works today | 🚧 Being wired up | 💭 Strong opinions, pending code |
+|---|---|---|
+| Relay, channels, threads, DMs, canvases, media, search, audit log | Git hosting backend | Web-of-trust reputation across relays |
+| Desktop app (Tauri + React) | Workflow approval gates (infra exists, glue still drying) | Mobile clients |
+| `sprout-cli` (agent-first, JSON in / JSON out) + ACP harness (Goose, Codex, Claude Code) | Huddle lifecycle events | Push notifications |
+| YAML workflows: message / reaction / schedule / webhook triggers | | Culture features |
+| Git events (NIP-34: patches, repo announcements, status) | | |
 
-The four [VISION docs](VISION.md) are the long version. The forge roadmap lives in [VISION_PROJECTS.md](VISION_PROJECTS.md).
+<sub>Please do not plan your compliance program around the 💭 column yet. The <a href="VISION.md">VISION docs</a> are the long version of what we think this becomes.</sub>
 
 ---
 
@@ -130,7 +100,7 @@ just dev     # terminal 2 — desktop app opens automatically
 
 Relay on `ws://localhost:3000`. Desktop app pops up. You're in.
 
-For agents, set `SPROUT_PRIVATE_KEY` and point a Goose / Codex / Claude Code session at `sprout-mcp-server`. See [AGENTS.md](AGENTS.md).
+For agents, set `SPROUT_PRIVATE_KEY` and use [`sprout-cli`](crates/sprout-cli) — JSON in, JSON out, designed for LLM tool calls.
 
 ---
 
@@ -139,22 +109,19 @@ For agents, set `SPROUT_PRIVATE_KEY` and point a Goose / Codex / Claude Code ses
 ```
 ┌─────────────────────────────────────────────────────────────────────────┐
 │                             Clients                                     │
-│  Human client         AI agent              Third-party Nostr client    │
-│  (Sprout desktop)     (Goose, Codex, ...)   (Coracle, nak, Amethyst)    │
+│  Human client         AI agent              CLI / scripts               │
+│  (Sprout desktop)     (Goose, Codex, ...)   (sprout-cli, agents)        │
 │       │               ┌──────────────┐               │                  │
 │       │               │  sprout-acp  │               │                  │
 │       │               │  (ACP ↔ MCP) │               │                  │
 │       │               └──────┬───────┘               │                  │
-│       │               ┌──────┴───────┐      ┌────────┴─────────┐        │
-│       │               │  sprout-mcp  │      │  sprout-proxy    │        │
-│       │               │  (stdio MCP) │      │  NIP-28 ↔ Sprout │        │
-│       │               └──────┬───────┘      └────────┬─────────┘        │
+│       │                      │                       │                  │
 └───────┼──────────────────────┼───────────────────────┼──────────────────┘
         │ WebSocket            │ WS + REST             │ WS + REST
         ▼                      ▼                       ▼
 ┌─────────────────────────────────────────────────────────────────────────┐
 │                          sprout-relay                                   │
-│  NIP-01 · NIP-42 auth · channel/DM/media/workflow REST · audit log      │
+│  NIP-01 · NIP-42 auth · channel/DM/media/workflow/git REST · audit log  │
 └───┬──────────────────┬──────────────────┬──────────────────┬────────────┘
     │                  │                  │                  │
  ┌──▼───────┐    ┌─────▼─────┐    ┌───────▼────┐    ┌────────▼────┐
@@ -170,51 +137,31 @@ A Rust workspace of focused crates. Single source of truth: the relay. See [ARCH
 
 **Core protocol** — `sprout-core` (zero-I/O types, NIP-01 filters, Schnorr verify) · `sprout-relay` (Axum WS + REST)
 
-**Services** — `sprout-db` (Postgres) · `sprout-auth` (NIP-42/98, tokens, rate limiting) · `sprout-pubsub` (Redis, presence, typing) · `sprout-search` (Typesense) · `sprout-audit` (hash-chain log)
+**Services** — `sprout-db` (Postgres) · `sprout-auth` (NIP-42/98 Schnorr auth, rate limiting) · `sprout-pubsub` (Redis, presence, typing) · `sprout-search` (Typesense) · `sprout-audit` (hash-chain log)
 
-**Agent surface** — `sprout-mcp` (stdio MCP, 44 tools) · `sprout-acp` (ACP harness for Goose/Codex/Claude Code) · `sprout-agent` (ACP agent — see [VISION_AGENT.md](VISION_AGENT.md)) · `sprout-dev-mcp` (shell + file-edit tools) · `sprout-workflow` (YAML automation) · `sprout-persona` (agent persona packs) · `sprout-huddle` (LiveKit)
+**Agent surface** — `sprout-cli` (agent-first CLI, JSON in / JSON out) · `sprout-acp` (ACP harness for Goose/Codex/Claude Code) · `sprout-agent` (ACP agent — see [VISION_AGENT.md](VISION_AGENT.md)) · `sprout-mcp` (stdio MCP, legacy/optional) · `sprout-dev-mcp` (shell + file-edit tools) · `sprout-workflow` (YAML automation) · `sprout-persona` (agent persona packs) · `sprout-huddle` (LiveKit voice/video)
 
-**Compatibility & pairing** — `sprout-proxy` (NIP-28 translation) · `sprout-pair-relay` / `sprout-pairing-cli` (relay pairing) · `git-sign-nostr` / `git-credential-nostr` (nostr-signed git)
+**Git & pairing** — `git-sign-nostr` / `git-credential-nostr` (nostr-signed git) · `sprout-pair-relay` / `sprout-pairing-cli` (relay pairing)
 
 **Shared** — `sprout-sdk` (typed event builders) · `sprout-media` (Blossom/S3)
 
-**Tooling** — `sprout-cli` (agent-first CLI) · `sprout-admin` (token minting) · `sprout-test-client` (E2E)
+**Tooling** — `sprout-admin` (admin CLI) · `sprout-test-client` (E2E)
 
 </details>
 
 ---
 
-## Supported NIPs
-
-NIP-01, 05, 09, 10, 11, 17, 25, 28 (via proxy), 29 (partial), 42, 50, 98 — see [NOSTR.md](NOSTR.md) for the full table and the `sprout-` extensions that layer on top.
-
----
-
 ## Going further
 
 - **[VISION.md](VISION.md)** · **[VISION_SOVEREIGN.md](VISION_SOVEREIGN.md)** · **[VISION_PROJECTS.md](VISION_PROJECTS.md)** · **[VISION_AGENT.md](VISION_AGENT.md)** — the four vision docs
 - **[ARCHITECTURE.md](ARCHITECTURE.md)** — system design, kind ranges, subsystem boundaries
-- **[AGENTS.md](AGENTS.md)** — connect AI agents via MCP
-- **[NOSTR.md](NOSTR.md)** — NIP support, third-party client compatibility
 - **[TESTING.md](TESTING.md)** — multi-agent E2E test suite
 - **[CONTRIBUTING.md](CONTRIBUTING.md)** · **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** · **[SECURITY.md](SECURITY.md)** · **[GOVERNANCE.md](GOVERNANCE.md)**
 
 <details>
 <summary><strong>Configuration</strong> (env vars, defaults work for local dev)</summary>
 
-All defaults work out of the box. Override via `.env`.
-
-| Variable | Default | What it does |
-|---|---|---|
-| `DATABASE_URL` | `postgres://sprout:sprout_dev@localhost:5432/sprout` | Postgres |
-| `REDIS_URL` | `redis://localhost:6379` | Redis |
-| `TYPESENSE_URL` | `http://localhost:8108` | Typesense |
-| `SPROUT_BIND_ADDR` | `0.0.0.0:3000` | Relay bind |
-| `RELAY_URL` | `ws://localhost:3000` | Public URL for NIP-42 challenges |
-| `SPROUT_TOOLSETS` | `default` | MCP toolsets (`default`, `all`, `none`, ... append `:ro` for read-only) |
-| `RUST_LOG` | `sprout_relay=info` | tracing env-filter |
-
-Full reference in [`.env.example`](.env.example).
+All defaults work out of the box. Override via `.env`. Full reference in [`.env.example`](.env.example).
 
 </details>
 
@@ -225,7 +172,6 @@ Full reference in [`.env.example`](.env.example).
 just setup          # Docker, migrations, desktop deps
 just relay          # Run the relay
 just dev            # Run the desktop app
-just proxy          # Run the NIP-28 proxy
 just build          # Build the Rust workspace
 just check          # fmt + clippy + desktop check
 just test-unit      # Unit tests (no infra required)
@@ -238,6 +184,16 @@ just reset          # ⚠️  Wipe data + recreate
 
 ---
 
+## What it is not
+
+- Not blockchain. Signed events are useful without making everyone buy a commemorative coin.
+- Not an AI replacement plan. Sprout works best when humans stay in the loop and agents stay in the room.
+- Not finished. We will tell you what works and what doesn't.
+
+**What it is:** one relay where humans, agents, workflows, git events, and project memory cooperate — the beginning of a workspace that can grow past the tabs it replaces.
+
+---
+
 <p align="center">
   <sub>Sprout 🌱 — where humans and agents are just colleagues.</sub><br>
   <sub>Apache 2.0 · Built by <a href="https://block.xyz">Block, Inc.</a></sub>

From b44c47dd941b96071d7ba67dd7bab9c8e4e2923f Mon Sep 17 00:00:00 2001
From: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
Date: Sat, 16 May 2026 19:07:39 -0400
Subject: [PATCH 4/7] docs(readme): move mobile clients to the wired-up column

We have a Flutter mobile client in mobile/; it ships as iOS + Android
with the Catppuccin theme and the relay client wiring in progress.
That makes it Being-wired-up, not Strong-opinions-pending-code.

Backfill the column to keep the table balanced: huddle lifecycle
events were already in the wired-up column in earlier drafts and
belong there.

Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
---
 README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 4fceaeb082..28cf2bdd74 100644
--- a/README.md
+++ b/README.md
@@ -72,9 +72,9 @@ Agents are colleagues, not haunted cron jobs.
 | ✅ Works today | 🚧 Being wired up | 💭 Strong opinions, pending code |
 |---|---|---|
 | Relay, channels, threads, DMs, canvases, media, search, audit log | Git hosting backend | Web-of-trust reputation across relays |
-| Desktop app (Tauri + React) | Workflow approval gates (infra exists, glue still drying) | Mobile clients |
-| `sprout-cli` (agent-first, JSON in / JSON out) + ACP harness (Goose, Codex, Claude Code) | Huddle lifecycle events | Push notifications |
-| YAML workflows: message / reaction / schedule / webhook triggers | | Culture features |
+| Desktop app (Tauri + React) | Mobile clients (iOS + Android, Flutter) | Push notifications |
+| `sprout-cli` (agent-first, JSON in / JSON out) + ACP harness (Goose, Codex, Claude Code) | Workflow approval gates (infra exists, glue still drying) | Culture features |
+| YAML workflows: message / reaction / schedule / webhook triggers | Huddle lifecycle events | |
 | Git events (NIP-34: patches, repo announcements, status) | | |
 
 <sub>Please do not plan your compliance program around the 💭 column yet. The <a href="VISION.md">VISION docs</a> are the long version of what we think this becomes.</sub>

From 25b8e81951907a7083225402868753b4f32aa4a2 Mon Sep 17 00:00:00 2001
From: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
Date: Sat, 16 May 2026 19:19:22 -0400
Subject: [PATCH 5/7] docs(readme): add forge verbs to the 'what agents can do'
 list
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The agent-capability sentence in 'What is this, really?' listed only
chat/meeting/orchestration verbs (create channels, run workflows, edit
canvases, drop into voice huddles, tag whoever). That accidentally
described a better Slackbot, not Sprout — the whole forge half of the
product (the thing that makes 'branch as room' possible three sections
down) was invisible.

Add the project verbs (open repos, send patches, review code) and
re-sequence so the list reads as a day at work: code, then workflows
and canvases, then orchestration, then huddles, then people.

Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 28cf2bdd74..3bed20ea64 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@ Under the hood, that's a Nostr relay: every message, reaction, workflow step, re
 
 In practice it feels like a team workspace. Under the hood it's an event log with taste and a suspicious number of Rust crates.
 
-Yes, it's another AI-adjacent developer tool. We're sorry. The difference is what agents can actually *do* once they're inside: create channels, add people, run workflows, edit canvases, orchestrate other agents, drop into voice huddles, tag whoever needs to see something. The same affordances as a human teammate, the same audit trail, a different keypair.
+Yes, it's another AI-adjacent developer tool. We're sorry. The difference is what agents can actually *do* once they're inside: open repos, send patches, review code, run workflows, edit canvases, orchestrate other agents, drop into voice huddles, create channels, and pull in whoever needs to see it. The same affordances as a human teammate, the same audit trail, a different keypair.
 
 ---
 

From 4336dd6789ebe53418895810069237ec9263859a Mon Sep 17 00:00:00 2001
From: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
Date: Sat, 16 May 2026 19:39:36 -0400
Subject: [PATCH 6/7] docs(readme): replace top image with the Plant Your Relay
 Today poster
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drops the small 220px mascot logo at the top of the README in favor
of the full-width retro propaganda poster we landed on in the
brainstorm thread. The poster carries the slogan, the deck, the four
badges (One Relay / Real Identities / Projects Live Here / Run Your
Relay), and the footer tagline 'Build together. Keep the receipts.' —
so the README opens with the pitch instead of a logo.

Asset lives at docs/assets/sprout-poster.png (1535x1024 PNG, 2.6 MB,
landscape) alongside the existing docs/assets/sprout.png mascot,
which is preserved for any other use.

Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
---
 README.md                     |   2 +-
 docs/assets/sprout-poster.png | Bin 0 -> 2744242 bytes
 2 files changed, 1 insertion(+), 1 deletion(-)
 create mode 100644 docs/assets/sprout-poster.png

diff --git a/README.md b/README.md
index 3bed20ea64..032a703cf3 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/assets/sprout.png" alt="Sprout" width="220">
+  <img src="docs/assets/sprout-poster.png" alt="Sprout — Plant your relay today. A workspace where humans and agents build together." width="800">
 </p>
 
 <h1 align="center">Sprout 🌱</h1>
diff --git a/docs/assets/sprout-poster.png b/docs/assets/sprout-poster.png
new file mode 100644
index 0000000000000000000000000000000000000000..57733de5815d5f77fed6cd42b839426a21165dc4
GIT binary patch

From b60de917e80945d2b1f8797d60d051b93fc229a8 Mon Sep 17 00:00:00 2001
From: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
Date: Sat, 16 May 2026 19:44:36 -0400
Subject: [PATCH 7/7] =?UTF-8?q?docs(readme):=20drop=20the=20poster=20hero;?=
 =?UTF-8?q?=20let=20the=20Sprout=20=F0=9F=8C=B1=20headline=20carry=20the?=
 =?UTF-8?q?=20top?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The poster duplicated every line the page already opens with. Cleaner
to remove it and let the H1 do the work on its own.

Also removes the poster asset since nothing else references it.

Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
---
 README.md                     |   4 ----
 docs/assets/sprout-poster.png | Bin 2744242 -> 0 bytes
 2 files changed, 4 deletions(-)
 delete mode 100644 docs/assets/sprout-poster.png

diff --git a/README.md b/README.md
index 032a703cf3..bc89abffe6 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,3 @@
-<p align="center">
-  <img src="docs/assets/sprout-poster.png" alt="Sprout — Plant your relay today. A workspace where humans and agents build together." width="800">
-</p>
-
 <h1 align="center">Sprout 🌱</h1>
 
 <p align="center">
diff --git a/docs/assets/sprout-poster.png b/docs/assets/sprout-poster.png
deleted file mode 100644
index 57733de5815d5f77fed6cd42b839426a21165dc4..0000000000000000000000000000000000000000
GIT binary patch
