docs: define superrpa sgclaw runtime boundary

docs/plans/2026-03-29-sgclaw-superrpa-runtime-config-design.md

@@ -0,0 +1,137 @@
+# sgClaw SuperRPA Runtime Config Design
+
+**Status**: Draft frozen before implementation  
+**Date**: 2026-03-29
+
+## 1. Goal
+
+Freeze the runtime-boundary design before further implementation so Task 2+ do not drift back into browser-compiled behavior.
+
+The design line is fixed:
+
+- `host` keeps the security boundary.
+- sgClaw keeps runtime behavior.
+- `frontend bundle` keeps display rights only.
+- High-frequency changes move to runtime-managed files whenever possible.
+
+## 2. Ownership Split
+
+### 2.1 host
+
+SuperRPA as `host` owns only the trusted boundary:
+
+- process spawning
+- pipe lifecycle and session security
+- browser / office capability exposure
+- path validation for runtime-managed files
+- fallback to bundled defaults when external files are missing or unsafe
+
+`host` does not own planner policy, model routing, provider selection, skill orchestration, or business behavior.
+
+### 2.2 sgClaw runtime
+
+sgClaw owns runtime behavior:
+
+- planner / executor orchestration
+- provider list and active provider selection
+- skill loading and prompt mode
+- browser / office backend selection
+- runtime profile behavior
+- planner-first execution sequencing
+
+### 2.3 frontend bundle
+
+`frontend bundle` owns presentation only:
+
+- render runtime state, logs, and conversation
+- render planner output before execution
+- collect user input and forward it through host events
+
+`frontend bundle` must not:
+
+- decide whether planner runs
+- directly select provider/backend outside runtime contract
+- bypass sgClaw / zeroclaw execution
+
+## 3. Runtime-Managed Files
+
+### 3.1 launch config
+
+Owned by `host`, preferred path:
+
+```text
+<profile>/superrpa/sgclaw_launch_config.json
+```
+
+Fields:
+
+- `binary`
+- `args`
+- `env`
+- `working_dir`
+- `runtime_config_path`
+- `frontend_bundle_dir`
+
+Fallback rules:
+
+1. Prefer external `launch config`
+2. Fall back to bundled browser defaults when file is missing or invalid
+3. Fall back to profile-local `runtime config` if `runtime_config_path` is absent
+4. Fall back to bundled frontend resources if `frontend_bundle_dir` is absent or invalid
+
+### 3.2 runtime config
+
+Owned by sgClaw, current default path:
+
+```text
+<profile>/superrpa/sgclaw_config.json
+```
+
+This file should carry runtime behavior instead of browser compile-time constants, including:
+
+- planner mode
+- providers and active provider
+- browser backend
+- office backend
+- skills prompt mode
+- runtime profile
+
+### 3.3 frontend bundle
+
+Owned by `host` for loading, but externally replaceable at runtime:
+
+- prefer `frontend_bundle_dir`
+- validate path and allowed loading rules
+- fall back to bundled resources if invalid
+
+## 4. Planner-First Rule
+
+`planner-first` is a runtime contract, not a frontend trick.
+
+The sequence must be:
+
+1. sgClaw / zeroclaw produces a plan
+2. `frontend bundle` displays the plan
+3. runtime continues into execution
+4. acceptance verifies both visible plan rendering and actual execution ordering
+
+## 5. Failing Checklist
+
+The following questions remain intentionally unresolved at design-freeze time and must be closed by implementation plus verification:
+
+- [ ] Can browser startup switch sgClaw binary without rebuilding Chromium?
+- [ ] Can model/provider selection change without rebuilding Chromium?
+- [ ] Can floating UI be replaced without rebuilding Chromium?
+- [ ] Can acceptance flows prove planner-first behavior visually and functionally?
+
+## 6. Terminology Guardrail
+
+All related docs and code reviews must use the same terms:
+
+- `host`
+- `launch config`
+- `runtime config`
+- `frontend bundle`
+- `planner-first`
+
+Any proposal that moves planner or executor logic back into browser-side presentation code is out of bounds for this design.