From c0bb34c514ba6024bb6eb0e33693976aa4807676 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Sat, 18 Apr 2026 16:03:27 +0700
Subject: [PATCH] docs: document service-script env vars and split dev into
 daemon+app

Document the PASEO_SERVICE_<NAME>_URL/PORT and PASEO_URL/PORT contract exposed
by the service-script runtime. Split paseo.json's monolithic "server" script
into "daemon" and "app" services so peer discovery exercises the new env.
---
 docs/DEVELOPMENT.md | 27 +++++++++++++++++++++++++++
 paseo.json          |  8 ++++++--
 2 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 9fa18db0d..0c9fb09d3 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -54,6 +54,33 @@ npm run db:query -- --db /path/to/db "SELECT ..."
 Auto-detects the running dev daemon's database from `/tmp/paseo-dev.*`, `PASEO_HOME`, or `~/.paseo/db`.
 Pass either a DB directory or a `paseo.sqlite` file to `--db`. The script opens the database directly in read-only mode.
 
+## paseo.json service scripts
+
+Every `scripts` entry with `"type": "service"` receives these environment variables:
+
+| Variable | Value |
+|---|---|
+| `PASEO_SERVICE_<NAME>_URL` | Proxied daemon URL for a declared peer service. Prefer this for peer discovery; it survives peer restarts. |
+| `PASEO_SERVICE_<NAME>_PORT` | Raw ephemeral port for a declared peer service. Use only as a bypass escape hatch; it can go stale if that peer restarts. |
+| `PASEO_URL` | Self alias for `PASEO_SERVICE_<SELF>_URL`. |
+| `PASEO_PORT` | Self alias for `PASEO_SERVICE_<SELF>_PORT`. |
+| `HOST` | Bind host for the service process. |
+
+`<NAME>` is normalized from the script name by uppercasing it, replacing each run of non-`A-Z0-9` characters with `_`, and trimming leading or trailing `_`. For example, `app-server` and `app.server` both normalize to `APP_SERVER`; that collision fails at spawn time with an actionable error.
+
+`PORT` is not injected by default. If a framework requires `PORT`, set it in the command:
+
+```json
+{
+  "scripts": {
+    "web": {
+      "type": "service",
+      "command": "PORT=$PASEO_PORT npm run dev:web"
+    }
+  }
+}
+```
+
 ## Build sync gotchas
 
 ### Relay → Daemon
diff --git a/paseo.json b/paseo.json
index a1d21b31f..a86c6ad28 100644
--- a/paseo.json
+++ b/paseo.json
@@ -7,9 +7,13 @@
     ]
   },
   "scripts": {
-    "server": {
+    "daemon": {
       "type": "service",
-      "command": "npm run dev"
+      "command": "PASEO_LISTEN=0.0.0.0:$PASEO_PORT npm run dev:server"
+    },
+    "app": {
+      "type": "service",
+      "command": "cd packages/app && BROWSER=none EXPO_PUBLIC_LOCAL_DAEMON=\"${PASEO_SERVICE_DAEMON_URL#http://}\" npx expo start"
     },
     "typecheck": {
       "command": "npm run typecheck"