From ae96eaf0cd5747333ed11fd220b602c249b5be5b Mon Sep 17 00:00:00 2001
From: Tristan Escalada <355457+tescalada@users.noreply.github.com>
Date: Wed, 26 Aug 2026 11:48:41 -0400
Subject: [PATCH] docs: point development setup at the groundbolt-dev workspace

Readers of the Development section were following the Local steps as if
they were the standard setup, since Docker and Local were presented as
two equal options. Lead the section with a callout directing developers
to the groundbolt-dev workspace, explain that the webapp alone has no
database, metering provider, or sync, and mark the Local steps as a
webapp-only, non-Docker alternative.
---
 README.md | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 368d134..c80fd9e 100644
--- a/README.md
+++ b/README.md
@@ -103,15 +103,20 @@ docker compose exec ground uv run flask user create
 
 ## Development
 
-This document is to help you get the development environment up and running. You can choose between two options, hit either of the links below for more details:
+> [!IMPORTANT]
+> **The development environment lives in the [groundbolt-dev workspace](https://github.com/EarthSpark/groundbolt-dev), not in this repo.** Start there: its README walks you through cloning this repo alongside its sibling components and bringing up the whole system with Docker Compose.
 
-1. [Docker](#docker)
-2. [Local](#local)
+This webapp is one component of a larger system. On its own it has no database, no metering provider to talk to, and no ground↔cloud sync. The [groundbolt-dev workspace](https://github.com/EarthSpark/groundbolt-dev) runs all of those — the ground and cloud webapps, their Postgres databases, the SymmetricDS sync pair, and the `sparknet-http` metering provider — from a single compose file, which is why development setup happens there rather than here.
+
+What stays in this repo:
+
+1. [Docker](#docker) — the self-contained unit-test harness (`docker-compose.test.yml`) and webapp-specific commands.
+2. [Local](#local) — running just the webapp process directly on your machine, without Docker. Only useful for narrow webapp-only iteration; most people don't need this.
 
 
 ### Docker
 
-Dockerized development happens in the **groundbolt-dev workspace metarepo**, which clones this repo and its sibling component repos side by side and runs the whole system — the ground and cloud webapps, their databases, the SymmetricDS sync pair, and the `sparknet-http` metering provider — from a single compose file. See that repo's README for setup.
+Dockerized development happens in the **[groundbolt-dev workspace](https://github.com/EarthSpark/groundbolt-dev)**, which clones this repo and its sibling component repos side by side and runs the whole system — the ground and cloud webapps, their databases, the SymmetricDS sync pair, and the `sparknet-http` metering provider — from a single compose file. See that repo's README for setup.
 
 This repo's `docker-compose.test.yml` is the self-contained test harness: a throwaway Postgres plus the test-image runner, needing nothing outside this repo. It's what CI runs.
 
@@ -171,8 +176,10 @@ $ docker compose logs -f
 
 ### Local
 
+> [!NOTE]
+> This is **not** the standard development setup — that's the [groundbolt-dev workspace](https://github.com/EarthSpark/groundbolt-dev). The steps below run only the webapp process, directly on your machine: no metering provider, no cloud side, no sync. Use this only if you specifically want to iterate on webapp code without Docker (you'll need a local PostgreSQL — see [OS Requirements](#os-requirements)).
 
-To setup a development environment locally, you need to follow the steps below:
+To set up the webapp by itself locally, follow the steps below:
 
 #### 1. Setup the project and install the dependencies