docs: deployment guides, CHANGELOG, and env-var alignment

- Traditional / docker deployment guides with systemd + launchd notes
- logrotate copytruncate sample for orb-server.log
- ORB_ env-var prefix throughout (replacing legacy HF_ references)
- CHANGELOG entries for orb-server.token, allow_destructive_admin, alembic migrations
- API reference + user guide updates for new routers

Author: fgogolli

CHANGELOG.md

@@ -8,6 +8,28 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 <!-- insertion marker -->
 ## Unreleased
 
+### BREAKING CHANGES
+
+- **Daemon token file at `<work_dir>/server/orb-server.token`.**
+  When `orb server start` is invoked (daemon or `--foreground` mode), a
+  random bearer token is written to `<work_dir>/server/orb-server.token`
+  with mode `0600`.  The CLI reads this file to authenticate loopback admin
+  requests such as `orb server reload`.  The file is removed when the daemon
+  exits.  Operators who snapshot the work directory should exclude
+  `*.token` from backups.
+
+- **`allow_destructive_admin` config field (default `false`).**
+  Administrative endpoints that can wipe state (purge, bulk-delete, etc.)
+  now require `allow_destructive_admin: true` in the server config.  The
+  field defaults to `false` and must be opted in explicitly.
+
+- **SQL storage strategy applies Alembic migrations on startup.**
+  When `storage.strategy` is `sql`, the server now runs `alembic upgrade
+  head` automatically on startup.  Operators using a managed database
+  (RDS, Aurora) should ensure the database user has DDL privileges, or run
+  migrations out-of-band with `orb db upgrade` before starting the server
+  with `allow_auto_migrate: false`.
+
 ### Added
 
 - New `[aws]` extra (alias for AWS deps currently in core). The canonical install

CONTRIBUTING.md

@@ -330,7 +330,7 @@ The container supports multiple entry points:
 docker run --rm image --version
 
 # API server
-docker run -p 8000:8000 image system serve
+docker run -p 8000:8000 image server start --foreground
 
 # Health check
 docker run --rm image --health

README.md

@@ -229,7 +229,7 @@ See the [CLI Reference](docs/root/cli/cli-reference.md) for the full flag refere
 <details>
 <summary>REST API</summary>
 
-Example API calls. Requires `pip install "orb-py[api]"` and `orb system serve`.
+Example API calls. Requires `pip install "orb-py[api]"` and `orb server start` (add `--foreground` for an in-shell variant).
 
 ```bash
 # Get available templates

docs/root/cli/cli-reference.md

@@ -612,23 +612,68 @@ orb system metrics [OPTIONS]
 |------|-------------|---------|
 | `--format` | Output format | `--format table` |
 
-#### `system serve`
+### Server
 
-Start REST API server.
+Process lifecycle for the local ORB daemon (REST API + optional embedded UI).
+`orb system *` is for **remote API observability** (status/health/metrics/reload of a
+running ORB). `orb server *` manages **the local process** itself.
+
+#### `server start`
+
+Start the ORB server. Daemonised by default; pass `--foreground` to keep it in
+the current shell (useful for containers, systemd `Type=simple`, and dev).
 
 **Usage:**
 ```bash
-orb system serve [OPTIONS]
+orb server start [OPTIONS]
 ```
 
 **Options:**
 | Flag | Description | Default | Example |
 |------|-------------|---------|---------|
-| `--host` | Server host | `0.0.0.0` | `--host localhost` |
-| `--port` | Server port | `8000` | `--port 9000` |
-| `--workers` | Number of workers | `1` | `--workers 4` |
-| `--reload` | Enable auto-reload | `false` | `--reload` |
-| `--server-log-level` | Server log level | `info` | `--server-log-level debug` |
+| `--foreground`, `-F` | Run in the foreground instead of daemonising | `false` | `--foreground` |
+| `--api-only` | Skip the embedded UI even if `ui.enabled=true` | `false` | `--api-only` |
+| `--host` | Server host (overrides config) | from config | `--host localhost` |
+| `--port` | Server port (overrides config) | from config | `--port 9000` |
+| `--workers` | Number of workers | from config | `--workers 4` |
+| `--reload` | Enable uvicorn auto-reload (dev only) | `false` | `--reload` |
+| `--server-log-level` | Server log level | from config | `--server-log-level debug` |
+| `--socket-path` | Unix domain socket path (alternative to host/port) | none | `--socket-path /tmp/orb.sock` |
+
+#### `server stop`
+
+Stop the running ORB server. Sends `SIGTERM`, waits up to the configured
+`stop_timeout_seconds`, then escalates to `SIGKILL`. The whole process group
+is signalled so the embedded Reflex tree (Node/Next included) terminates with
+the parent.
+
+```bash
+orb server stop [--timeout N]
+```
+
+#### `server status`
+
+Report PID, liveness, and a best-effort `/health` probe.
+
+```bash
+orb server status
+```
+
+#### `server restart`
+
+`stop` followed by `start`. Accepts the same flags as `start`.
+
+#### `server reload`
+
+Send `SIGHUP` to the running daemon.
+
+#### `server logs`
+
+Tail the daemon log file (`<log_dir>/orb-server.log` by default).
+
+```bash
+orb server logs [-n LINES]
+```
 
 ### Config
 
@@ -1447,5 +1492,5 @@ orb config validate
 orb storage test --timeout 60
 
 # Start API server for development
-orb system serve --reload --port 9000
+orb server start --foreground --reload --port 9000
 ```

docs/root/cli/provider-override.md

@@ -315,7 +315,7 @@ orb --provider aws-prod mcp serve --stdio
 
 ```bash
 # Start API server with provider override
-orb --provider aws-dev system serve --port 8000
+orb --provider aws-dev server start --foreground --port 8000
 ```
 
 ### Batch Operations

docs/root/configuration-guide.md

@@ -125,7 +125,7 @@ The consolidated configuration format provides comprehensive provider management
   },
   "logging": {
     "level": "INFO",
-    "file_path": "logs/app.log",
+    "file_path": "logs/orb.log",
     "console_enabled": true
   },
   "storage": {
@@ -424,7 +424,7 @@ export ORB_CIRCUIT_BREAKER__ENABLED=true
 export ORB_CIRCUIT_BREAKER__FAILURE_THRESHOLD=5
 
 # Start the application
-orb system serve --port 8000
+orb server start --foreground --port 8000
 ```
 
 ### Configuration Validation

docs/root/configuration/examples.md

@@ -611,7 +611,7 @@ The scheduler configuration determines how the system interfaces with job schedu
   },
   "logging": {
     "level": "INFO",
-    "file_path": "logs/app.log",
+    "file_path": "logs/orb.log",
     "console_enabled": true
   }
 }

docs/root/deployment/monitoring.md

@@ -73,7 +73,7 @@ The application exposes metrics for:
     "level": "INFO",
     "format": "json",
     "file_enabled": true,
-    "file_path": "/app/logs/app.log",
+    "file_path": "/app/logs/orb.log",
     "console_enabled": true
   }
 }
@@ -102,7 +102,7 @@ output.elasticsearch:
 ```conf
 <source>
   @type tail
-  path /app/logs/app.log
+  path /app/logs/orb.log
   pos_file /var/log/fluentd/orb.log.pos
   tag orb.api
   format json

docs/root/deployment/readme.md

@@ -65,13 +65,13 @@ spec:
         ports:
         - containerPort: 8000
         env:
-        - name: HF_SERVER_ENABLED
+        - name: ORB_SERVER_ENABLED
           value: "true"
-        - name: HF_AUTH_ENABLED
+        - name: ORB_AUTH_ENABLED
           value: "true"
-        - name: HF_AUTH_STRATEGY
+        - name: ORB_AUTH_STRATEGY
           value: "bearer_token"
-        - name: HF_AUTH_BEARER_SECRET_KEY
+        - name: ORB_AUTH_BEARER_SECRET_KEY
           valueFrom:
             secretKeyRef:
               name: orb-secrets
@@ -108,7 +108,7 @@ gcloud run deploy orb-api \
   --image gcr.io/your-project/orb-api:latest \
   --platform managed \
   --region us-central1 \
-  --set-env-vars HF_SERVER_ENABLED=true,HF_AUTH_ENABLED=true
+  --set-env-vars ORB_SERVER_ENABLED=true,ORB_AUTH_ENABLED=true
 ```
 
 ### [Server] Traditional Server Deployment
@@ -127,8 +127,11 @@ pip install -e .
 cp config/default_config.json config/production.json
 # Edit config/production.json
 
-# Start server
-orb system serve --host 0.0.0.0 --port 8000 --config config/production.json
+# Start server (foreground)
+orb --config config/production.json server start --foreground --host 0.0.0.0 --port 8000
+
+# Or daemonise (writes a PID file under <work_dir>/server/orb-server.pid)
+orb --config config/production.json server start --host 0.0.0.0 --port 8000
 ```
 
 #### Systemd Service
@@ -143,9 +146,9 @@ Type=simple
 User=orb
 Group=orb
 WorkingDirectory=/opt/orb
-Environment=HF_SERVER_ENABLED=true
-Environment=HF_AUTH_ENABLED=true
-ExecStart=/opt/orb/.venv/bin/python src/run.py system serve --config config/production.json
+Environment=ORB_SERVER_ENABLED=true
+Environment=ORB_AUTH_ENABLED=true
+ExecStart=/opt/orb/.venv/bin/orb --config config/production.json server start --foreground
 Restart=always
 RestartSec=10
 
@@ -161,38 +164,38 @@ WantedBy=multi-user.target
 
 ```bash
 # Server Configuration
-HF_SERVER_ENABLED=true
-HF_SERVER_HOST=0.0.0.0
-HF_SERVER_PORT=8000
-HF_SERVER_WORKERS=4
-HF_SERVER_LOG_LEVEL=info
-HF_SERVER_DOCS_ENABLED=false  # Disable in production
+ORB_SERVER_ENABLED=true
+ORB_SERVER_HOST=0.0.0.0
+ORB_SERVER_PORT=8000
+ORB_SERVER_WORKERS=4
+ORB_SERVER_LOG_LEVEL=info
+ORB_SERVER_DOCS_ENABLED=false  # Disable in production
 
 # Authentication Configuration
-HF_AUTH_ENABLED=true
-HF_AUTH_STRATEGY=bearer_token
-HF_AUTH_BEARER_SECRET_KEY=your-very-secure-secret-key
-HF_AUTH_BEARER_TOKEN_EXPIRY=3600
+ORB_AUTH_ENABLED=true
+ORB_AUTH_STRATEGY=bearer_token
+ORB_AUTH_BEARER_SECRET_KEY=your-very-secure-secret-key
+ORB_AUTH_BEARER_TOKEN_EXPIRY=3600
 
 # AWS Provider Configuration
-HF_PROVIDER_TYPE=aws
-HF_PROVIDER_AWS_REGION=us-east-1
+ORB_PROVIDER_TYPE=aws
+ORB_PROVIDER_AWS_REGION=us-east-1
 AWS_ACCESS_KEY_ID=your-access-key
 AWS_SECRET_ACCESS_KEY=your-secret-key
 
 # Storage Configuration
-HF_STORAGE_STRATEGY=json
-HF_STORAGE_BASE_PATH=/app/data
+ORB_STORAGE_STRATEGY=json
+ORB_STORAGE_BASE_PATH=/app/data
 
 # Logging Configuration
-HF_LOGGING_LEVEL=INFO
-HF_LOGGING_CONSOLE_ENABLED=true
-HF_LOGGING_FILE_ENABLED=true
-HF_LOGGING_FILE_PATH=/app/logs/app.log
+ORB_LOGGING_LEVEL=INFO
+ORB_LOGGING_CONSOLE_ENABLED=true
+ORB_LOGGING_FILE_ENABLED=true
+ORB_LOGGING_FILE_PATH=/app/logs/orb.log
 
 # Security Configuration
-HF_SERVER_REQUIRE_HTTPS=true
-HF_SERVER_TRUSTED_HOSTS=your-domain.com,api.your-domain.com
+ORB_SERVER_REQUIRE_HTTPS=true
+ORB_SERVER_TRUSTED_HOSTS=your-domain.com,api.your-domain.com
 ```
 
 ### Configuration Files
@@ -217,7 +220,7 @@ services:
     secrets:
       - orb-jwt-secret
     environment:
-      HF_AUTH_BEARER_SECRET_KEY_FILE: /run/secrets/orb-jwt-secret
+      ORB_AUTH_BEARER_SECRET_KEY_FILE: /run/secrets/orb-jwt-secret
 ```
 
 #### Kubernetes Secrets
@@ -244,7 +247,7 @@ aws secretsmanager create-secret \
 {
   "secrets": [
     {
-      "name": "HF_AUTH_BEARER_SECRET_KEY",
+      "name": "ORB_AUTH_BEARER_SECRET_KEY",
       "valueFrom": "arn:aws:secretsmanager:region:account:secret:orb/jwt-secret"
     }
   ]
@@ -255,11 +258,11 @@ aws secretsmanager create-secret \
 
 ### Production Security Checklist
 
-- [ ] **Authentication enabled**: `HF_AUTH_ENABLED=true`
+- [ ] **Authentication enabled**: `ORB_AUTH_ENABLED=true`
 - [ ] **Strong JWT secret**: Use cryptographically secure random key
-- [ ] **HTTPS required**: `HF_SERVER_REQUIRE_HTTPS=true`
+- [ ] **HTTPS required**: `ORB_SERVER_REQUIRE_HTTPS=true`
 - [ ] **Trusted hosts configured**: Limit to your domains
-- [ ] **API docs disabled**: `HF_SERVER_DOCS_ENABLED=false`
+- [ ] **API docs disabled**: `ORB_SERVER_DOCS_ENABLED=false`
 - [ ] **Non-root execution**: Container runs as `orb` user
 - [ ] **Resource limits**: Set CPU and memory limits
 - [ ] **Network isolation**: Use private networks where possible
@@ -323,7 +326,7 @@ livenessProbe:
 {
   "logging": {
     "level": "INFO",
-    "file_path": "/app/logs/app.log",
+    "file_path": "/app/logs/orb.log",
     "console_enabled": true,
     "file_enabled": true,
     "max_file_size": "50MB",
@@ -441,7 +444,7 @@ docker exec -i orb-postgres psql -U orb orb < backup-20250107.sql
 docker logs container-name
 
 # Check configuration
-docker exec container-name env | grep HF_
+docker exec container-name env | grep ORB_
 
 # Test configuration
 docker run --rm -it orb-api:latest bash
@@ -456,7 +459,7 @@ docker stats
 curl http://localhost:8000/metrics
 
 # Increase workers
-docker run -e HF_SERVER_WORKERS=4 orb-api:latest
+docker run -e ORB_SERVER_WORKERS=4 orb-api:latest
 ```
 
 **Authentication problems:**
@@ -476,7 +479,7 @@ print(config.get_typed(ServerConfig).auth.enabled)
 
 ```bash
 # Enable debug mode
-docker run -e HF_DEBUG=true -e HF_LOGGING_LEVEL=DEBUG orb-api:latest
+docker run -e ORB_DEBUG=true -e ORB_LOGGING_LEVEL=DEBUG orb-api:latest
 
 # Interactive debugging
 docker run -it --rm orb-api:latest bash
@@ -501,11 +504,11 @@ resources:
 
 ```bash
 # Increase worker processes
-HF_SERVER_WORKERS=4
+ORB_SERVER_WORKERS=4
 
 # Optimize for high concurrency
-HF_SERVER_WORKER_CLASS=uvicorn.workers.UvicornWorker
-HF_SERVER_WORKER_CONNECTIONS=1000
+ORB_SERVER_WORKER_CLASS=uvicorn.workers.UvicornWorker
+ORB_SERVER_WORKER_CONNECTIONS=1000
 ```
 
 ## Migration Guide