From 0ea95470127068e671da33081088ce9f2ca6ed84 Mon Sep 17 00:00:00 2001
From: Miles Smith <msmith@vps>
Date: Mon, 26 Jan 2026 09:02:37 -0700
Subject: [PATCH] docs: document IDENTITY.md PWA customization feature
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add documentation for the undocumented IDENTITY.md → PWA manifest
customization feature:

- Updated agent-workspace.md to explain that the Name field in IDENTITY.md
  automatically customizes the Control UI PWA manifest
- Added dedicated PWA customization section to control-ui.md with examples
- Documented the current limitation: name changes after initial setup
  require manual manifest editing
- Included workaround steps for runtime name changes

This feature allows users to personalize their Clawdbot PWA appearance
(e.g., 'Nova - Clawdbot Control' instead of generic 'Clawdbot Control').
---
 docs/concepts/agent-workspace.md | 10 +++++++
 docs/web/control-ui.md           | 46 ++++++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+)

diff --git a/docs/concepts/agent-workspace.md b/docs/concepts/agent-workspace.md
index 4033fd267..f912767b4 100644
--- a/docs/concepts/agent-workspace.md
+++ b/docs/concepts/agent-workspace.md
@@ -77,6 +77,16 @@ These are the standard files Clawdbot expects inside the workspace:
 - `IDENTITY.md`
   - The agent's name, vibe, and emoji.
   - Created/updated during the bootstrap ritual.
+  - **PWA customization:** The agent's `Name` field automatically customizes the
+    Control UI PWA manifest at build/install time. For example, if your
+    IDENTITY.md contains `- **Name:** Nova`, the PWA will appear as
+    "Nova - Clawdbot Control" in app launchers and browsers.
+  - **Runtime limitation:** Changes to the name after initial setup are not
+    automatically applied to the manifest. To update the PWA name after changing
+    IDENTITY.md, manually edit
+    `<install-path>/dist/control-ui/manifest.json` and restart the gateway. A
+    hard browser refresh (Ctrl+Shift+R) is required due to aggressive PWA
+    caching.
 
 - `TOOLS.md`
   - Notes about your local tools and conventions.
diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md
index 996ed0fe4..4b3d51ac4 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -161,3 +161,49 @@ Notes:
 - Use `wss://` when the Gateway is behind TLS (Tailscale Serve, HTTPS proxy, etc.).
 
 Remote access setup details: [Remote access](/gateway/remote).
+
+## PWA customization
+
+The Control UI supports installation as a Progressive Web App (PWA) for a
+native-like experience. The PWA name and display settings are defined in
+`dist/control-ui/manifest.json`.
+
+### Automatic name customization
+
+If your workspace contains an `IDENTITY.md` file with a `Name` field, Clawdbot
+automatically customizes the PWA manifest at build/install time:
+
+```markdown
+# IDENTITY.md
+- **Name:** Nova
+```
+
+This updates the manifest to:
+
+```json
+{
+  "name": "Nova - Clawdbot Control",
+  "short_name": "Nova",
+  ...
+}
+```
+
+The customized PWA name appears in app launchers, browser tabs, and the OS app
+switcher.
+
+### Updating the name after initial setup
+
+**Important:** Name changes after initial setup are not automatically applied to
+the manifest. This is a known limitation.
+
+**Manual workaround:**
+1. Edit `IDENTITY.md` with the new name
+2. Manually edit `<install-path>/dist/control-ui/manifest.json`:
+   - Update `"name"` to `"YourNewName - Clawdbot Control"`
+   - Update `"short_name"` to `"YourNewName"`
+3. Restart the gateway: `clawdbot gateway restart`
+4. Force a hard browser refresh (Ctrl+Shift+R or Cmd+Shift+R)
+5. Reinstall the PWA if the name doesn't update
+
+See [Agent workspace](/concepts/agent-workspace#workspace-file-map-what-each-file-means)
+for the full IDENTITY.md structure and usage.