docs: add strategy-platform configuration specification and sync tool

- STRATEGY_PLATFORM_SPEC.md: complete spec for adding strategies, platforms, plugins
- sync_strategy_config.py: auto-generate RUNTIME_TARGET_JSON + Scheduler jobs
- strategy_platform_config.example.json: centralized config template

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Pigbibi

docs/STRATEGY_PLATFORM_SPEC.md

@@ -0,0 +1,142 @@
+# Strategy-Platform Configuration Specification
+
+## Single Source of Truth
+
+Every platform service has **one** canonical config entry-point:
+
+```
+RUNTIME_TARGET_JSON = {"platform_id": "...", "strategy_profile": "...", ...}
+```
+
+All other config values that reference the strategy name MUST derive from
+`RUNTIME_TARGET_JSON.strategy_profile` — either at code level or through the
+auto-sync layer described below.
+
+### Derived values (auto-synced on startup)
+
+| Config location | Field | Auto-sync |
+|---|---|---|
+| `SCHWAB_STRATEGY_PLUGIN_MOUNTS_JSON` | `.strategy_plugins[].strategy` | ✅ corrected on startup |
+| `STRATEGY_PLUGIN_MOUNTS_JSON` (IBKR, LB) | `.strategy_plugins[].strategy` | ✅ corrected on startup |
+| `MONITOR_DISPATCH_TARGETS_JSON` | `.targets[].strategy_profile` | ✅ corrected on startup (Schwab) |
+| `SCHWAB_MONITOR_DISPATCH_TARGETS_JSON` | `.targets[].strategy_profile` | ✅ corrected on startup (Schwab) |
+
+### Deprecated (do NOT set)
+
+- `STRATEGY_PROFILE` — was a standalone env var that duplicated `RUNTIME_TARGET_JSON.strategy_profile`. Removed in Schwab `runtime_config_support.py`. IBKR and LongBridge never had this fallback.
+
+---
+
+## Adding a New Strategy
+
+1. Add strategy definition to the shared catalog (`us_equity_strategies` or `hk_equity_strategies`)
+2. Set `compatible_platforms` to list which platforms support it
+3. Add to `runtime_enabled_profiles` for the rollout
+4. Each platform repo picks it up via `derive_enabled_profiles_for_platform()` — no per-platform code change needed unless the strategy requires special exclusions
+5. To deploy: update `RUNTIME_TARGET_JSON.strategy_profile` on the target service, and optionally add plugin mounts
+
+**Checklist:**
+```
+[ ] strategy definition in shared catalog
+[ ] compatible_platforms includes target platform(s)
+[ ] runtime_enabled_profiles includes profile name
+[ ] platform's capability matrix supports required inputs/domain
+[ ] RUNTIME_TARGET_JSON.strategy_profile updated on target service
+[ ] plugin mounts JSON (if any) updated — or rely on auto-sync
+[ ] Scheduler jobs exist for the service (already there if service exists)
+```
+
+---
+
+## Adding a New Platform
+
+1. Create platform repo from template (copy an existing one)
+2. Implement `strategy_registry.py`:
+   - Define `PLATFORM_CAPABILITY_MATRIX` (domains, inputs, capabilities)
+   - Define `*_EXCLUDED_LIVE_PROFILES` (strategies not yet ready)
+   - Derive `ELIGIBLE_STRATEGY_PROFILES` and `*_ENABLED_PROFILES`
+3. Implement `runtime_config_support.py`:
+   - Define `PlatformRuntimeSettings` dataclass with all platform-specific fields
+   - All non-default fields MUST appear BEFORE any field with a default value
+   - Implement `load_platform_runtime_settings()` reading from env vars
+4. Implement broker adapters, market data ports, execution ports
+5. Add Cloud Scheduler jobs:
+   - `{platform}-{strategy}-main`: `45 15 * * *` → `/run`
+   - `{platform}-{strategy}-precheck`: `45 9 * * *` → `/dry-run`
+   - `{platform}-{strategy}-backup`: `52 15 * * 1-5` → `/run`
+6. Set `RUNTIME_TARGET_JSON` on the Cloud Run service
+7. Wire into `MONITOR_DISPATCH_TARGETS_JSON` for cross-platform health checks
+
+**Platform dataclass rule:**
+```python
+@dataclass(frozen=True)
+class PlatformRuntimeSettings:
+    # Required fields FIRST (no defaults)
+    project_id: str | None
+    secret_name: str
+    strategy_profile: str
+    # ... more required fields ...
+
+    # Fields with defaults AFTER all required fields
+    notification_channel: str = "telegram"
+    dry_run_only: bool = False  # ← note: False IS a valid default here
+    # ...
+```
+
+---
+
+## Adding a New Plugin
+
+1. Add plugin definition with `signal_path`, `enabled`, `expected_mode`
+2. Add to `{PLATFORM}_STRATEGY_PLUGIN_MOUNTS_JSON` env var:
+   ```json
+   {
+     "strategy_plugins": [{
+       "strategy": "<strategy_profile>",
+       "plugin": "<plugin_name>",
+       "signal_path": "gs://...",
+       "enabled": true,
+       "expected_mode": "shadow"
+     }]
+   }
+   ```
+3. The `strategy` field is auto-synced to match `RUNTIME_TARGET_JSON.strategy_profile` — you can set it to anything and it will be corrected on startup. Setting it correctly is still recommended for documentation.
+
+---
+
+## Configuration Validation
+
+Before deploying, run:
+```bash
+# Check required env vars
+python scripts/check_required_env.py --platform=schwab --json
+
+# Check strategy-platform consistency
+python scripts/validate_platform_consistency.py
+```
+
+These should be integrated into CI pipelines for all platform repos.
+
+---
+
+## Deployment Checklist
+
+When changing a strategy's configuration:
+
+```
+[ ] RUNTIME_TARGET_JSON updated (ONLY this is required)
+[ ] Deploy the service (Cloud Run picks up new env var)
+[ ] Verify: check Cloud Logging for "[config-sync]" messages
+[ ] Verify: trigger /dry-run via Scheduler or manual POST
+[ ] Verify: check execution report in GCS for expected strategy name
+```
+
+The auto-sync layer handles everything else (plugin mounts, monitor targets).
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---|---|---|
+| 1.0 | 2026-06-30 | Initial spec: single source of truth, auto-sync, validation scripts |