Merge commit 'ada9006b1d2e73bc72267f4a7e6c34d5fb333b12'

docs/DEPLOYMENT.md

@@ -27,3 +27,39 @@ Use the **Deploy All** workflow in the Actions tab (`.github/workflows/deploy-al
 - Trigger manually with **Run workflow** to deploy every service.
 - Provide the optional `serviceId` input to deploy just one service using `deploy:service`.
 - Deployments expect `RAILWAY_TOKEN` to be available as a GitHub Actions secret and run with `NODE_ENV=production`.
+# BlackRoad OS Deployment
+
+This repo is the *orchestrator* for all BlackRoad OS services.
+
+## Commands
+
+- `npm run deploy:all`  
+  Deploys all services (core, api, operator, agents, console, web, docs) via Railway.
+
+- `npm run deploy:service -- core`  
+  Deploy only a single service by `id`.
+
+- `npm run health:all`  
+  Check health endpoints for all services using their public domains.
+
+## Service Registry
+
+All services are defined in `infra/services.json`.
+
+To add or change a service:
+
+1. Edit `infra/services.json` and update:
+   - `id`
+   - `railwayProject`
+   - `railwayService`
+   - `domain`
+   - `healthPath`
+2. Make sure the Railway project/service names match.
+3. Commit and push your changes.
+
+## GitHub Actions
+
+The workflow `.github/workflows/deploy-all.yml` lets you:
+
+- Trigger **Deploy BlackRoad OS** from the Actions tab.
+- Optionally pass `serviceId` to deploy just one service.