Prevent BlackRoad-Operating-System monorepo from being added to Railway services

CRITICAL CHANGES:
- Add comprehensive deployment architecture documentation
- Prevent misconfiguration where monorepo is deployed instead of satellites
- Clarify monorepo-to-satellite sync model across all docs

CHANGES:
1. railway.toml
   - Add critical warning banner at top of file
   - Mark config as local development/testing only
   - Explain correct deployment model (satellites, not monorepo)

2. DEPLOYMENT_ARCHITECTURE.md (NEW)
   - Complete 500+ line deployment guide
   - Monorepo vs satellite model explained in detail
   - Critical rules: NEVER add monorepo to Railway
   - Service-to-repository mapping
   - Environment configuration guide
   - Cloudflare DNS configuration
   - Common mistakes and troubleshooting

3. README.md
   - Add prominent deployment warning box
   - Clarify monorepo is source of truth, not deployable
   - List satellite repos that should be deployed
   - Reference DEPLOYMENT_ARCHITECTURE.md

4. CLAUDE.md
   - Add critical deployment model section
   - Clarify Railway deployment is satellite-only
   - Update deployment workflow explanation
   - Add key rules for deployment

5. backend/.env.example
   - Fix ALLOWED_ORIGINS to reference satellites
   - Remove monorepo Railway URL reference
   - Add correct satellite service URLs

6. ops/domains.yaml
   - Fix os.blackroad.systems DNS target
   - Point to blackroad-os-core-production (satellite)
   - Remove incorrect monorepo Railway URL

7. scripts/validate_deployment_config.py (NEW)
   - Automated validation script
   - Checks for monorepo references in configs
   - Validates railway.toml, env files, DNS configs
   - Ensures DEPLOYMENT_ARCHITECTURE.md exists
   - Exit code 0 = pass, 1 = fail

WHY THIS MATTERS:
- Adding monorepo to Railway creates circular deploy loops
- Environment variables break (wrong service URLs)
- Cloudflare routing fails
- Service dependencies misconfigured
- Prevents production outages from misconfiguration

CORRECT MODEL:
- Monorepo = source of truth (orchestration only)
- Satellites = deployable services (Railway deployment)
- Code flows: monorepo → sync → satellite → Railway

See: DEPLOYMENT_ARCHITECTURE.md for complete details

railway.toml

@@ -1,5 +1,33 @@
+# ==============================================================================
+# ⚠️  CRITICAL WARNING - DO NOT USE THIS CONFIG IN PRODUCTION RAILWAY ⚠️
+# ==============================================================================
+#
+# This railway.toml is for LOCAL DEVELOPMENT AND TESTING ONLY.
+#
+# ❌ DO NOT add "BlackRoad-Operating-System" as a Railway service
+# ❌ DO NOT deploy this monorepo to production Railway environments
+# ❌ DO NOT add this repo to service configurations or env vars
+#
+# ✅ CORRECT DEPLOYMENT MODEL:
+#   - This repo is the SOURCE OF TRUTH (orchestration/sync only)
+#   - Deploy ONLY the satellite repos to Railway:
+#     • blackroad-os-core (from BlackRoad-OS/blackroad-os-core)
+#     • blackroad-os-api (from BlackRoad-OS/blackroad-os-api)
+#     • blackroad-os-operator (from BlackRoad-OS/blackroad-os-operator)
+#     • blackroad-os-prism-console (from BlackRoad-OS/blackroad-os-prism-console)
+#     • blackroad-os-docs (from BlackRoad-OS/blackroad-os-docs)
+#
+# WHY THIS MATTERS:
+#   - Adding the monorepo to Railway will create circular deploy loops
+#   - Environment variables will break (wrong service URLs)
+#   - Cloudflare routing will fail
+#   - Service dependencies will be misconfigured
+#
+# See: docs/os/monorepo-sync.md and DEPLOYMENT_ARCHITECTURE.md
+# ==============================================================================
+
 # BlackRoad OS Monorepo - Railway Configuration
-# This configures multiple services from a single repository
+# This configures multiple services from a single repository FOR LOCAL DEV ONLY
 
 # Backend (Core API)
 [[services]]