From b130b881a0a26cedfb6e4207a3c882cbcd844d6b Mon Sep 17 00:00:00 2001
From: Bhavik Patel <bhavikpatel13792@gmail.com>
Date: Thu, 5 Mar 2026 07:58:45 +0400
Subject: [PATCH] docs: improve workspace and memory UX guidance
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Issue #146 — How to add workspace:
- Add Workspace Management section to README with Super Admin panel docs
- Add Super Admin API endpoints to API overview table
- Add info banner in Settings panel (admin only) linking to Super Admin

Issue #143 — Memory tab in agent view:
- Add info banner in agent Memory tab clearly distinguishing agent
  working memory (DB scratchpad) from workspace memory files
- Add clickable link to Memory Browser page from agent Memory tab
- Improve subtitle text with WORKING.md storage detail

Fixes #146
Fixes #143
---
 README.md                                   | 22 +++++++++++++++++++++
 src/components/panels/agent-detail-tabs.tsx | 10 +++++++++-
 src/components/panels/settings-panel.tsx    | 17 ++++++++++++++++
 3 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index dc4ab10..8edfc04 100644
--- a/README.md
+++ b/README.md
@@ -113,6 +113,14 @@ Inter-agent communication via the comms API. Agents can send messages to each ot
 ### Integrations
 Outbound webhooks with delivery history, configurable alert rules with cooldowns, and multi-gateway connection management. Optional 1Password CLI integration for secret management.
 
+### Workspace Management
+Workspaces (tenant instances) are created and managed through the **Super Admin** panel, accessible from the sidebar under **Admin > Super Admin**. From there, admins can:
+- **Create** new client instances (slug, display name, Linux user, gateway port, plan tier)
+- **Monitor** provisioning jobs and their step-by-step progress
+- **Decommission** tenants with optional cleanup of state directories and Linux users
+
+Each workspace gets its own isolated environment with a dedicated OpenClaw gateway, state directory, and workspace root. See the [Super Admin API](#api-overview) endpoints under `/api/super/*` for programmatic access.
+
 ### Update Checker
 Automatic GitHub release check notifies you when a new version is available, displayed as a banner in the dashboard.
 
@@ -277,6 +285,20 @@ All endpoints require authentication unless noted. Full reference below.
 
 </details>
 
+<details>
+<summary><strong>Super Admin (Workspace/Tenant Management)</strong></summary>
+
+| Method | Path | Role | Description |
+|--------|------|------|-------------|
+| `GET` | `/api/super/tenants` | admin | List all tenants with latest provisioning status |
+| `POST` | `/api/super/tenants` | admin | Create tenant and queue bootstrap job |
+| `POST` | `/api/super/tenants/[id]/decommission` | admin | Queue tenant decommission job |
+| `GET` | `/api/super/provision-jobs` | admin | List provisioning jobs (filter: `?tenant_id=`, `?status=`) |
+| `POST` | `/api/super/provision-jobs` | admin | Queue additional job for existing tenant |
+| `POST` | `/api/super/provision-jobs/[id]/action` | admin | Approve, reject, or cancel a provisioning job |
+
+</details>
+
 <details>
 <summary><strong>Direct CLI</strong></summary>
 
diff --git a/src/components/panels/agent-detail-tabs.tsx b/src/components/panels/agent-detail-tabs.tsx
index 1e6bee1..4f5ffd0 100644
--- a/src/components/panels/agent-detail-tabs.tsx
+++ b/src/components/panels/agent-detail-tabs.tsx
@@ -517,7 +517,7 @@ export function MemoryTab({
         <div>
           <h4 className="text-lg font-medium text-foreground">Working Memory</h4>
           <p className="text-xs text-muted-foreground mt-1">
-            Agent-level scratchpad only. Use the global Memory page to browse all workspace memory files.
+            This is <strong className="text-foreground">agent-level</strong> scratchpad memory (stored as WORKING.md in the database), not the workspace memory folder.
           </p>
         </div>
         <div className="flex gap-2">
@@ -543,6 +543,14 @@ export function MemoryTab({
         </div>
       </div>
 
+      {/* Info Banner */}
+      <div className="bg-blue-500/10 border border-blue-500/20 rounded-lg p-3 text-xs text-blue-300">
+        <strong className="text-blue-200">Agent Memory vs Workspace Memory:</strong>{' '}
+        This tab edits only this agent&apos;s private working memory (a scratchpad stored in the database).
+        To browse or edit all workspace memory files (daily logs, knowledge base, MEMORY.md, etc.), visit the{' '}
+        <Link href="/memory" className="text-blue-400 underline hover:text-blue-300">Memory Browser</Link> page.
+      </div>
+
       {/* Memory Content */}
       <div>
         <label className="block text-sm font-medium text-muted-foreground mb-1">
diff --git a/src/components/panels/settings-panel.tsx b/src/components/panels/settings-panel.tsx
index 08912c8..3573d35 100644
--- a/src/components/panels/settings-panel.tsx
+++ b/src/components/panels/settings-panel.tsx
@@ -2,6 +2,7 @@
 
 import { useState, useEffect, useCallback } from 'react'
 import { useMissionControl } from '@/store'
+import { useNavigateToPanel } from '@/lib/navigation'
 
 interface Setting {
   key: string
@@ -24,6 +25,7 @@ const categoryOrder = ['general', 'retention', 'gateway', 'custom']
 
 export function SettingsPanel() {
   const { currentUser } = useMissionControl()
+  const navigateToPanel = useNavigateToPanel()
   const [settings, setSettings] = useState<Setting[]>([])
   const [grouped, setGrouped] = useState<Record<string, Setting[]>>({})
   const [loading, setLoading] = useState(true)
@@ -180,6 +182,21 @@ export function SettingsPanel() {
         </div>
       </div>
 
+      {/* Workspace Info */}
+      {currentUser?.role === 'admin' && (
+        <div className="bg-blue-500/10 border border-blue-500/20 rounded-lg p-3 text-xs text-blue-300">
+          <strong className="text-blue-200">Workspace Management:</strong>{' '}
+          To create or manage workspaces (tenant instances), go to the{' '}
+          <button
+            onClick={() => navigateToPanel('super-admin')}
+            className="text-blue-400 underline hover:text-blue-300 cursor-pointer"
+          >
+            Super Admin
+          </button>{' '}
+          panel under Admin &gt; Super Admin in the sidebar. From there you can create new client instances, manage tenants, and monitor provisioning jobs.
+        </div>
+      )}
+
       {/* Feedback */}
       {feedback && (
         <div className={`rounded-lg p-3 text-xs font-medium ${