From b38fa73ee37ebbce036ff72cd9104d521945c9e7 Mon Sep 17 00:00:00 2001
From: Will Pfleger <wpfleger@block.xyz>
Date: Fri, 5 Jun 2026 12:02:37 -0400
Subject: [PATCH] docs: add ecosystem section, fix stale release info

Add an Ecosystem section to CONTRIBUTING.md covering the multi-repo
structure and contributor access paths. Replace the incomplete inline
crate list in Architecture Overview with cross-references to
AGENTS.md and ARCHITECTURE.md.

Fix RELEASING.md: remove duplicated internal release instructions
(canonical home is sprout-releases/README.md) and remove references
to Linux desktop artifacts that the pipeline does not produce.
---
 AGENTS.md       |  4 +++-
 CONTRIBUTING.md | 63 ++++++++++++++++++++++++++-----------------------
 RELEASING.md    | 24 +++++++------------
 3 files changed, 45 insertions(+), 46 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 893d08a192..698d8e6893 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -26,7 +26,9 @@ block/sprout (source)
   └─── sprout-backend-blox         (Blox compute provider for Desktop agent launch)
 ```
 
-See [RELEASING.md](RELEASING.md) for the desktop release flow across `block/sprout` and `sprout-releases`.
+See [RELEASING.md](RELEASING.md) for the desktop release flow and
+[CONTRIBUTING.md § Ecosystem](CONTRIBUTING.md#ecosystem) for contributor
+access information.
 
 ---
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c337683449..73d2481200 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,10 +17,11 @@ reach out in the community channels.
 4. [Code Style](#code-style)
 5. [Making a Pull Request](#making-a-pull-request)
 6. [Architecture Overview](#architecture-overview)
-7. [How to Add a New Event Kind](#how-to-add-a-new-event-kind)
-8. [How to Add a New MCP Tool](#how-to-add-a-new-mcp-tool)
-9. [How to Add a New API Endpoint](#how-to-add-a-new-api-endpoint)
-10. [License and CLA](#license-and-cla)
+7. [Ecosystem](#ecosystem)
+8. [How to Add a New Event Kind](#how-to-add-a-new-event-kind)
+9. [How to Add a New MCP Tool](#how-to-add-a-new-mcp-tool)
+10. [How to Add a New API Endpoint](#how-to-add-a-new-api-endpoint)
+11. [License and CLA](#license-and-cla)
 
 ---
 
@@ -279,40 +280,42 @@ required. The scope (in parentheses) is optional but encouraged.
 
 ## Architecture Overview
 
-See [README.md](README.md) for the full crate map and architecture diagram.
-The short version:
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full system design and
+[AGENTS.md](AGENTS.md#repo-structure) for the complete crate map. The key
+design principles:
 
-```
-sprout-relay      ← WebSocket server, REST API, event ingestion
-sprout-core       ← Shared types, event verification, filter matching
-sprout-db         ← Postgres access layer (sqlx)
-sprout-auth       ← NIP-42 + NIP-98 + API token scopes
-sprout-pubsub     ← Redis fan-out
-sprout-search     ← Typesense full-text search
-sprout-audit      ← Tamper-evident hash-chain audit log
-sprout-workflow   ← YAML-as-code workflow engine
-sprout-acp        ← ACP harness (bridges Sprout relay events to AI agents via stdio)
-sprout-proxy      ← Nostr client compatibility layer
-sprout-sdk        ← Typed Nostr event builders (used by sprout-cli)
-sprout-media      ← Blossom/S3 media storage
-sprout-cli        ← Agent-first CLI for interacting with the relay
-sprout-admin      ← Operator CLI
-sprout-test-client← Integration test harness
-desktop/          ← Desktop app (Tauri 2 + React 19 + Vite + Tailwind)
-```
-
-**Key design principle:** The relay is the single source of truth. All state
-flows through the event store. Crates communicate through the database and
-Redis pub/sub — not through direct function calls across crate boundaries
-(with the exception of `sprout-core` types, which are shared everywhere).
+**The relay is the single source of truth.** All state flows through the
+event store. Crates communicate through the database and Redis pub/sub — not
+through direct function calls across crate boundaries (with the exception
+of `sprout-core` types, which are shared everywhere).
 
-**Event kinds** are the only switch. Every action in the system — a message,
+**Event kinds are the only switch.** Every action in the system — a message,
 a reaction, a workflow step, a canvas update — is a Nostr event with a kind
 integer. Adding a new feature means defining a new kind. No breaking changes
 to existing clients.
 
 ---
 
+## Ecosystem
+
+Sprout is developed across multiple repositories. This repo (`block/sprout`)
+is the open-source home for all application code — the relay, desktop app,
+mobile app, CLI, and agent harness. Internal repositories handle
+enterprise-signed builds and infrastructure deployment.
+
+See [AGENTS.md § Ecosystem](AGENTS.md#ecosystem) for the full repo table and
+dependency diagram.
+
+**External contributors:** Fork `block/sprout`, open a PR, and CI runs
+automatically. No special access is required.
+
+**Block team members:** See the internal
+[sprout-releases CONTRIBUTING.md](https://github.com/squareup/sprout-releases/blob/main/CONTRIBUTING.md)
+for team access setup, onboarding, and the full repo inventory. See
+[RELEASING.md](RELEASING.md) for the release process.
+
+---
+
 ## How to Add a New Event Kind
 
 1. **Define the kind constant** in `sprout-core/src/kind.rs`:
diff --git a/RELEASING.md b/RELEASING.md
index 52322fa5f7..28c56296c4 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -68,19 +68,10 @@ If the automated flow isn't suitable (e.g., building from a non-main ref):
 
 ## Internal Releases
 
-After the OSS release ships, trigger an internal build via the **sprout-releases** Buildkite pipeline:
-
-1. Go to the [sprout-releases pipeline](https://buildkite.com/runway/sprout-releases) and click **New Build**
-2. Fill in the input fields:
-
-   | Field | Value | Notes |
-   |-------|-------|-------|
-   | `version` | `0.3.0` | Semver, no `v` prefix |
-   | `sprout_ref` | `v0.3.0` | The OSS git tag — use the tag, not a branch name |
-   | `relay_url` | *(default)* | Pre-filled with the production relay; usually leave as-is |
-   | `publish_latest` | `true` | Updates `latest.json` on Artifactory so installed apps auto-update. Set to `false` for test builds. |
-
-Internal desktop builds display a `-block` suffix in the version (e.g., `v0.3.0-block` in the Settings panel). This distinguishes them from OSS builds at a glance. iOS builds and GitHub release tags use the clean version (`0.3.0`) since Apple's `CFBundleShortVersionString` rejects pre-release suffixes.
+After the OSS release ships, trigger an internal build via the
+[sprout-releases Buildkite pipeline](https://buildkite.com/runway/sprout-releases).
+See the [sprout-releases README](https://github.com/squareup/sprout-releases#cutting-a-release)
+for the full step-by-step instructions and input field reference.
 
 ---
 
@@ -88,9 +79,12 @@ Internal desktop builds display a `-block` suffix in the version (e.g., `v0.3.0-
 
 Each release produces two GitHub releases:
 
-1. **`v<version>`** — the user-facing release with the `.dmg` installer (macOS) and `.deb`/`.AppImage` (Linux).
+1. **`v<version>`** — the user-facing release with the `.dmg` installer
+   (macOS).
 
-2. **`sprout-desktop-latest`** — a rolling pre-release for the Tauri auto-updater containing `latest.json`, the signed `.tar.gz` archive, and its `.sig` signature.
+2. **`sprout-desktop-latest`** — a rolling pre-release for the Tauri
+   auto-updater containing `latest.json`, the signed `.tar.gz` archive,
+   and its `.sig` signature.
 
 ---
 
