refactor(makefile): rename start → backend, add restart logic for api and dashboard

- `make backend` replaces `make start`; polls postgres with nc (up to 10s)
  instead of fixed sleep, kills any running uvicorn before starting fresh
- `make dashboard` kills any running observable preview before restarting
- Update all references in CLAUDE.md, README.md, SCOPE.md, state-hub/README.md,
  and dashboard/src/docs/live-data.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Makefile

@@ -1,4 +1,4 @@
-.PHONY: install install-cli db db-tools migrate seed api dashboard check test start clean register-project validate-adr add-domain rename-domain add-repo list-repos register-path cleanup-stale tunnel tunnel-daemon tunnel-loop tunnel-status tunnel-stop install-hooks install-hooks-all gitea-inventory
+.PHONY: install install-cli db db-tools migrate seed api dashboard check test backend clean register-project validate-adr add-domain rename-domain add-repo list-repos register-path cleanup-stale tunnel tunnel-daemon tunnel-loop tunnel-status tunnel-stop install-hooks install-hooks-all gitea-inventory
 
 COMPOSE = docker compose -f infra/docker-compose.yml --env-file .env
 
@@ -36,6 +36,7 @@ mcp-http:
 	MCP_TRANSPORT=sse MCP_PORT=8001 uv run python mcp_server/server.py
 
 dashboard:
+	@pkill -f "observable preview" 2>/dev/null && echo "Stopped running dashboard" || true
 	cd dashboard && npm run dev
 
 check:
@@ -105,9 +106,16 @@ tunnel-stop:
 	@pkill -f "autossh.*$(TUNNEL_PORT)" 2>/dev/null && echo "autossh stopped" || true
 	@pkill -f "ssh.*-R $(TUNNEL_PORT)" 2>/dev/null && echo "ssh loop stopped" || true
 
-start: db
-	sleep 3
+## Shortcut: start (or restart) the full backend — db + migrate + api.
+## If the API is already running it is stopped first; postgres wait is skipped if already up.
+backend: db
+	@echo "Waiting for postgres..."; \
+	for i in 1 2 3 4 5 6 7 8 9 10; do \
+	  nc -z 127.0.0.1 5432 2>/dev/null && break; \
+	  sleep 1; \
+	done
 	$(MAKE) migrate
+	@pkill -f "uvicorn api.main:app" 2>/dev/null && echo "Stopped running API" || true
 	$(MAKE) api
 
 ## Register a project: make register-project DOMAIN=railiance PROJECT_PATH=/home/worsch/railiance

README.md

@@ -42,7 +42,7 @@ make api                      # uvicorn :8000 --reload
 ### Shortcut
 
 ```bash
-make start    # db + sleep + migrate + api
+make backend  # db + migrate + api (restarts if already running)
 ```
 
 ### Dashboard
@@ -74,7 +74,7 @@ custodian register-project    # register cwd as a Custodian project
 | `make api` | `uvicorn api.main:app --reload` |
 | `make dashboard` | Observable dev server |
 | `make check` | `curl /state/health` |
-| `make start` | `db` + wait + `migrate` + `api` |
+| `make backend` | `db` + wait + `migrate` + `api` (restarts if running) |
 | `make register-project DOMAIN=x PROJECT_PATH=y` | Register a project |
 | `make clean` | `docker compose down -v` (destroys DB volume) |
 

dashboard/src/docs/live-data.md

@@ -41,7 +41,7 @@ To restart the API:
 cd ~/the-custodian/state-hub
 make api          # starts uvicorn on 127.0.0.1:8000
 # or, if postgres is not running:
-make start        # db + migrate + api
+make backend      # db + migrate + api (restarts if already running)
 ```
 
 ---