From 69cc92a52ed8ed571b70ad0e39236c2a1b0296e5 Mon Sep 17 00:00:00 2001
From: Sprite <noreply@sprite.dev>
Date: Sat, 7 Feb 2026 21:43:31 +0000
Subject: [PATCH] refactor: Update README.md to document shared/common.sh
 architecture

Added "Architecture" section explaining:
- Library structure (shared/common.sh + cloud-specific extensions)
- How shared utilities reduce duplication across providers
- Benefits: DRY, consistency, maintainability, extensibility

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/README.md b/README.md
index ad47b5e7..e28f46d8 100644
--- a/README.md
+++ b/README.md
@@ -351,6 +351,51 @@ OPENROUTER_API_KEY=sk-or-v1-xxxxx \
 
 ---
 
+## Architecture
+
+Spawn uses a **shared library pattern** to reduce code duplication across cloud providers:
+
+### Library Structure
+
+```
+spawn/
+  shared/
+    common.sh         # Provider-agnostic utilities (logging, OAuth, SSH helpers)
+  {cloud}/
+    lib/common.sh     # Cloud-specific functions (sources shared/common.sh)
+    {agent}.sh        # Agent deployment scripts
+```
+
+### How It Works
+
+1. **`shared/common.sh`** - Core utilities used by all clouds:
+   - Color logging (`log_info`, `log_warn`, `log_error`)
+   - Safe input handling (`safe_read`)
+   - OAuth flow for OpenRouter authentication
+   - Network utilities (`nc_listen`, `open_browser`)
+   - SSH key management and connectivity helpers
+   - Security validation (`validate_model_id`, `json_escape`)
+
+2. **`{cloud}/lib/common.sh`** - Cloud-specific extensions:
+   - Sources `shared/common.sh` first
+   - Adds provider-specific functions (API wrappers, provisioning logic)
+   - Examples: `sprite/lib/common.sh` adds Sprite CLI functions, `hetzner/lib/common.sh` adds Hetzner API functions
+
+3. **Agent scripts** - Combine shared utilities with cloud-specific provisioning:
+   - Source their cloud's `lib/common.sh`
+   - Use shared functions for authentication and setup
+   - Use cloud functions for server provisioning
+   - Deploy and configure the specific agent
+
+### Benefits
+
+- **DRY (Don't Repeat Yourself)** - OAuth, logging, and SSH logic are written once
+- **Consistency** - All scripts use the same patterns for authentication and error handling
+- **Maintainability** - Bug fixes in `shared/common.sh` benefit all cloud providers
+- **Extensibility** - Adding a new cloud only requires writing provider-specific logic
+
+---
+
 ## Security
 
 ### API Token Storage