# 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.