From 0fc6fe0c8ef8920475874febe0e27c350615a26c Mon Sep 17 00:00:00 2001
From: zyl <zyl@local>
Date: Sun, 29 Mar 2026 23:46:45 +0800
Subject: [PATCH] frontend: document runtime host bundle

---
 frontend/runtime-host/README.md             | 43 +++++++++++++++++++++
 frontend/runtime-host/manifest.example.json | 17 ++++++++
 2 files changed, 60 insertions(+)
 create mode 100644 frontend/runtime-host/README.md
 create mode 100644 frontend/runtime-host/manifest.example.json

diff --git a/frontend/runtime-host/README.md b/frontend/runtime-host/README.md
new file mode 100644
index 0000000..21888fb
--- /dev/null
+++ b/frontend/runtime-host/README.md
@@ -0,0 +1,43 @@
+# sgClaw Runtime Host Bundle
+
+`frontendBundleDir` lets SuperRPA prefer an external `sgclaw-chat` bundle at
+runtime while keeping the browser host, security boundary, and `chrome.send`
+bridge inside Chromium.
+
+## Contract
+
+- SuperRPA remains the host and security boundary.
+- sgClaw remains the runtime and planner/execution owner.
+- The frontend bundle only renders state that comes from the existing host
+  bridge.
+- Missing external files fall back to Chromium-bundled resources.
+
+## Directory Layout
+
+The external bundle root must mirror the Chromium resource paths under
+`functions/sgclaw-chat/`.
+
+Example:
+
+```text
+frontend-bundle/
+  sgclaw-chat/
+    sgclaw-chat.js
+    sgclaw-chat.css.js
+    sgclaw-chat.html.js
+    components/
+      sgclaw-chat-shell.js
+      sgclaw-message-list.js
+```
+
+When `frontendBundleDir` points at `frontend-bundle/`, the browser will try to
+serve `sgclaw-chat/*` from that directory first. Any file that is absent will
+continue loading from the built-in Chromium resource pack.
+
+## Packaging Notes
+
+- Keep relative import paths inside the bundle identical to the bundled
+  `sgclaw-chat` tree.
+- Do not move planner or execution logic into the bundle.
+- Treat [manifest.example.json](/home/zyl/projects/sgClaw/claw/frontend/runtime-host/manifest.example.json)
+  as a packaging reference for humans and tooling.
diff --git a/frontend/runtime-host/manifest.example.json b/frontend/runtime-host/manifest.example.json
new file mode 100644
index 0000000..9ed7d81
--- /dev/null
+++ b/frontend/runtime-host/manifest.example.json
@@ -0,0 +1,17 @@
+{
+  "bundleId": "sgclaw-chat",
+  "version": "0.1.0",
+  "description": "External sgclaw chat presentation bundle for SuperRPA runtime hosting.",
+  "resourceRoot": ".",
+  "resourcePrefix": "sgclaw-chat/",
+  "entries": [
+    "sgclaw-chat/sgclaw-chat.js",
+    "sgclaw-chat/sgclaw-chat.css.js",
+    "sgclaw-chat/sgclaw-chat.html.js"
+  ],
+  "notes": [
+    "Paths should mirror Chromium bundled sgclaw-chat resources.",
+    "Missing files fall back to bundled Chromium resources.",
+    "The bundle must stay presentation-only and use the existing host bridge."
+  ]
+}