clawport-ui 0.2.4 → 0.3.1

package/README.md

@@ -16,8 +16,11 @@ ClawPort is an open-source dashboard for managing, monitoring, and talking direc
 
 ### Quick Start (npm)
 
+> **Note:** The npm package is `clawport-ui`. The CLI command is `clawport`.
+> Do not install the unrelated `clawport` package.
+
 ```bash
-# Install globally
+# Install globally (package: clawport-ui, command: clawport)
 npm install -g clawport-ui
 
 # Auto-detect your OpenClaw config
@@ -225,7 +228,7 @@ Five built-in themes, toggled via the sidebar button:
 
 | Theme | Description |
 |-------|-------------|
-| **Dark** | Apple Dark Mode with warm blacks, gold accent |
+| **Dark** | Apple Dark Mode with warm blacks, red accent |
 | **Glass** | Frosted translucent panels on deep blue-black |
 | **Color** | Vibrant purple-indigo gradients |
 | **Light** | Apple Light Mode, clean whites |
@@ -274,7 +277,7 @@ npm install -g clawport-ui
 clawport help
 ```
 
-Published as [`clawport-ui`](https://www.npmjs.com/package/clawport-ui) on npm.
+Published as [`clawport-ui`](https://www.npmjs.com/package/clawport-ui) on npm. The CLI command is `clawport` (not `clawport-ui`). The separate `clawport` npm package is unrelated and not affiliated with this project.
 
 ### CLI Commands
 

package/app/globals.css

@@ -80,9 +80,9 @@
   --text-secondary: rgba(235,235,245,0.60);
   --text-tertiary: rgba(235,235,245,0.30);
   --text-quaternary: rgba(235,235,245,0.18);
-  --accent: #F5C518;
-  --accent-fill: rgba(245,197,24,0.15);
-  --accent-contrast: #000;
+  --accent: #EF4444;
+  --accent-fill: rgba(239,68,68,0.15);
+  --accent-contrast: #fff;
   --system-blue: #0A84FF;
   --system-green: #30D158;
   --system-red: #FF453A;
@@ -128,9 +128,9 @@
   --text-secondary: rgba(255,255,255,0.60);
   --text-tertiary: rgba(255,255,255,0.30);
   --text-quaternary: rgba(255,255,255,0.18);
-  --accent: #F5C518;
-  --accent-fill: rgba(245,197,24,0.18);
-  --accent-contrast: #000;
+  --accent: #EF4444;
+  --accent-fill: rgba(239,68,68,0.18);
+  --accent-contrast: #fff;
   --system-blue: #3B9EFF;
   --system-green: #34D058;
   --system-red: #FF5C57;
@@ -176,9 +176,9 @@
   --text-secondary: rgba(220,210,255,0.70);
   --text-tertiary: rgba(220,210,255,0.35);
   --text-quaternary: rgba(220,210,255,0.20);
-  --accent: #F5C518;
-  --accent-fill: rgba(245,197,24,0.20);
-  --accent-contrast: #000;
+  --accent: #EF4444;
+  --accent-fill: rgba(239,68,68,0.20);
+  --accent-contrast: #fff;
   --system-blue: #60A5FA;
   --system-green: #34D399;
   --system-red: #F87171;
@@ -224,8 +224,8 @@
   --text-secondary: rgba(60,60,67,0.60);
   --text-tertiary: rgba(60,60,67,0.44);
   --text-quaternary: rgba(60,60,67,0.30);
-  --accent: #B8860B;
-  --accent-fill: rgba(184,134,11,0.12);
+  --accent: #DC2626;
+  --accent-fill: rgba(220,38,38,0.12);
   --accent-contrast: #fff;
   --system-blue: #007AFF;
   --system-green: #28CD41;

package/app/settings/page.tsx

@@ -12,10 +12,10 @@ import { OnboardingWizard } from '@/components/OnboardingWizard'
 // ---------------------------------------------------------------------------
 
 const ACCENT_PRESETS = [
+  { label: 'Red', value: '#EF4444' },
   { label: 'Gold', value: '#F5C518' },
   { label: 'Blue', value: '#3B82F6' },
   { label: 'Green', value: '#22C55E' },
-  { label: 'Red', value: '#EF4444' },
   { label: 'Orange', value: '#F97316' },
   { label: 'Purple', value: '#A855F7' },
   { label: 'Pink', value: '#EC4899' },
@@ -368,7 +368,7 @@ export default function SettingsPage() {
                         ? 'transparent'
                         : settings.accentColor
                           ? `linear-gradient(135deg, ${settings.accentColor}, ${settings.accentColor}dd)`
-                          : 'linear-gradient(135deg, #f5c518, #e8b800)',
+                          : 'transparent',
                       boxShadow: settings.iconBgHidden ? 'none' : 'var(--shadow-card)',
                       display: 'flex',
                       alignItems: 'center',

package/bin/clawport.mjs

@@ -3,8 +3,21 @@
 import { fileURLToPath } from 'node:url'
 import { dirname, resolve } from 'node:path'
 import { spawn } from 'node:child_process'
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, accessSync, constants } from 'node:fs'
 import { execSync } from 'node:child_process'
+import { createServer } from 'node:net'
+
+// ---------------------------------------------------------------------------
+// Node version gate (must be 22+ for native fetch / AbortSignal.timeout)
+// ---------------------------------------------------------------------------
+
+const [major] = process.versions.node.split('.').map(Number)
+if (major < 22) {
+  console.error(
+    `\x1b[31mError:\x1b[0m Node.js 22+ required (found ${process.versions.node})`
+  )
+  process.exit(1)
+}
 
 // ---------------------------------------------------------------------------
 // Resolve package root (where app/, lib/, etc. live)
@@ -25,6 +38,8 @@ const red = (s) => `\x1b[31m${s}\x1b[0m`
 const dim = (s) => `\x1b[2m${s}\x1b[0m`
 const bold = (s) => `\x1b[1m${s}\x1b[0m`
 
+const extraArgs = process.argv.slice(3)
+
 function run(cmd, args = []) {
   const child = spawn(cmd, args, {
     cwd: PKG_ROOT,
@@ -34,6 +49,40 @@ function run(cmd, args = []) {
   child.on('close', (code) => process.exit(code ?? 0))
 }
 
+async function checkGateway() {
+  try {
+    const res = await fetch('http://127.0.0.1:18789/', {
+      signal: AbortSignal.timeout(3000),
+    })
+    return res.ok || res.status > 0
+  } catch {
+    return false
+  }
+}
+
+function findBinary(name) {
+  const cmd = process.platform === 'win32' ? 'where' : 'which'
+  try {
+    return execSync(`${cmd} ${name}`, {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim()
+  } catch {
+    return null
+  }
+}
+
+function checkPort(port) {
+  return new Promise((resolve) => {
+    const server = createServer()
+    server.once('error', () => resolve(false))
+    server.once('listening', () => {
+      server.close(() => resolve(true))
+    })
+    server.listen(port, '127.0.0.1')
+  })
+}
+
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
@@ -42,19 +91,25 @@ function showHelp() {
   console.log(`
 ${bold('ClawPort')} -- AI Agent Dashboard
 
-${bold('Usage:')} clawport <command>
+${bold('Usage:')} clawport <command> [options]
 
 ${bold('Commands:')}
   ${green('dev')}      Start the development server (next dev)
   ${green('start')}    Build and start the production server
   ${green('setup')}    Run the setup wizard (auto-detect OpenClaw config)
   ${green('status')}   Check gateway reachability and current config
+  ${green('doctor')}   Run full environment health check
   ${green('help')}     Show this help message
 
+${bold('Options:')}
+  ${dim('--port <n>')}  Port for dev/start (passed through to Next.js)
+
 ${bold('Examples:')}
-  ${dim('$ clawport setup     # Configure your OpenClaw connection')}
-  ${dim('$ clawport dev       # Start dev server on localhost:3000')}
-  ${dim('$ clawport status    # Check if gateway is reachable')}
+  ${dim('$ clawport setup          # Configure your OpenClaw connection')}
+  ${dim('$ clawport dev            # Start dev server on localhost:3000')}
+  ${dim('$ clawport dev --port 3005  # Start dev server on port 3005')}
+  ${dim('$ clawport status         # Check if gateway is reachable')}
+  ${dim('$ clawport doctor         # Diagnose environment issues')}
 
 ${dim(`Package root: ${PKG_ROOT}`)}
 `)
@@ -62,12 +117,20 @@ ${dim(`Package root: ${PKG_ROOT}`)}
 
 function cmdDev() {
   console.log(`\n  ${bold('Starting ClawPort dev server...')}\n`)
-  run(NEXT_BIN, ['dev'])
+  run(NEXT_BIN, ['dev', ...extraArgs])
 }
 
 function cmdStart() {
   console.log(`\n  ${bold('Building and starting ClawPort...')}\n`)
-  run(NEXT_BIN, ['build', '&&', NEXT_BIN, 'start'])
+  const build = spawn(NEXT_BIN, ['build'], {
+    cwd: PKG_ROOT,
+    stdio: 'inherit',
+    shell: true,
+  })
+  build.on('close', (code) => {
+    if (code !== 0) process.exit(code)
+    run(NEXT_BIN, ['start', ...extraArgs])
+  })
 }
 
 function cmdSetup() {
@@ -75,22 +138,13 @@ function cmdSetup() {
   run('node', [resolve(PKG_ROOT, 'scripts/setup.mjs'), `--cwd=${PKG_ROOT}`])
 }
 
-function cmdStatus() {
+async function cmdStatus() {
   console.log()
   console.log(bold('  ClawPort Status'))
   console.log()
 
   // Check gateway
-  let gatewayUp = false
-  try {
-    const result = execSync(
-      'curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/ 2>/dev/null',
-      { encoding: 'utf-8', timeout: 5000 }
-    ).trim()
-    gatewayUp = result && result !== '000'
-  } catch {
-    // gateway not reachable
-  }
+  const gatewayUp = await checkGateway()
 
   if (gatewayUp) {
     console.log(`  ${green('+')} Gateway reachable at ${dim('localhost:18789')}`)
@@ -125,6 +179,89 @@ function cmdStatus() {
   console.log()
 }
 
+async function cmdDoctor() {
+  console.log()
+  console.log(bold('  ClawPort Doctor'))
+  console.log()
+
+  let passed = 0
+  let total = 0
+
+  function check(ok, label, fix) {
+    total++
+    if (ok) {
+      passed++
+      console.log(`  ${green('+')} ${label}`)
+    } else {
+      console.log(`  ${red('x')} ${label}`)
+      if (fix) console.log(`    ${dim(fix)}`)
+    }
+  }
+
+  // 1. Node.js version
+  check(major >= 22, `Node.js ${process.versions.node}`, 'Upgrade to Node.js 22 or later')
+
+  // 2. Package integrity -- next binary exists
+  check(existsSync(NEXT_BIN), 'Package integrity (node_modules/.bin/next)', 'Run: npm install')
+
+  // 3. OpenClaw binary
+  const openclawPath = findBinary('openclaw')
+  check(!!openclawPath, openclawPath ? `OpenClaw binary (${openclawPath})` : 'OpenClaw binary', 'Install OpenClaw: https://docs.openclaw.dev/install')
+
+  // 4. Gateway reachable
+  const gatewayUp = await checkGateway()
+  check(gatewayUp, 'Gateway reachable at localhost:18789', 'Start it with: openclaw gateway run')
+
+  // 5. Configuration -- .env.local with required vars
+  const envPath = resolve(PKG_ROOT, '.env.local')
+  const requiredVars = ['WORKSPACE_PATH', 'OPENCLAW_BIN', 'OPENCLAW_GATEWAY_TOKEN']
+  let envOk = false
+  let envFix = 'Run: clawport setup'
+  if (existsSync(envPath)) {
+    const content = readFileSync(envPath, 'utf-8')
+    const missing = requiredVars.filter((v) => !content.includes(`${v}=`))
+    if (missing.length === 0) {
+      envOk = true
+    } else {
+      envFix = `Missing in .env.local: ${missing.join(', ')}`
+    }
+  }
+  check(envOk, '.env.local with required variables', envFix)
+
+  // 6. Workspace structure
+  let workspaceOk = false
+  let workspaceFix = 'Set WORKSPACE_PATH in .env.local via: clawport setup'
+  if (envOk) {
+    const content = readFileSync(envPath, 'utf-8')
+    const match = content.match(/^WORKSPACE_PATH=(.+)$/m)
+    if (match) {
+      const wsPath = match[1].trim()
+      const hasSoul = existsSync(resolve(wsPath, 'SOUL.md'))
+      const hasAgents = existsSync(resolve(wsPath, 'agents'))
+      const hasMemory = existsSync(resolve(wsPath, 'memory'))
+      if (hasSoul || hasAgents || hasMemory) {
+        workspaceOk = true
+      } else {
+        workspaceFix = `Workspace at ${wsPath} missing expected files (SOUL.md, agents/, memory/)`
+      }
+    }
+  }
+  check(workspaceOk, 'Workspace structure', workspaceFix)
+
+  // 7. Port 3000 available
+  const portFree = await checkPort(3000)
+  check(portFree, 'Port 3000 available', 'Port 3000 is in use. Use: clawport dev --port 3001')
+
+  // Summary
+  console.log()
+  if (passed === total) {
+    console.log(`  ${green(`${passed}/${total} checks passed`)}`)
+  } else {
+    console.log(`  ${yellow(`${passed}/${total} checks passed`)} -- ${total - passed} issue${total - passed === 1 ? '' : 's'} found`)
+  }
+  console.log()
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -144,6 +281,9 @@ switch (command) {
   case 'status':
     cmdStatus()
     break
+  case 'doctor':
+    cmdDoctor()
+    break
   case 'help':
   default:
     showHelp()

package/components/MobileSidebar.tsx

@@ -116,7 +116,7 @@ export function MobileSidebar({
                 borderRadius: '6px',
                 background: settings.accentColor
                   ? `linear-gradient(135deg, ${settings.accentColor}, ${settings.accentColor}dd)`
-                  : 'linear-gradient(135deg, #f5c518, #e8b800)',
+                  : 'transparent',
                 display: 'flex',
                 alignItems: 'center',
                 justifyContent: 'center',
@@ -202,7 +202,7 @@ export function MobileSidebar({
                   borderRadius: '10px',
                   background: settings.accentColor
                     ? `linear-gradient(135deg, ${settings.accentColor}, ${settings.accentColor}dd)`
-                    : 'linear-gradient(135deg, #f5c518, #e8b800)',
+                    : 'transparent',
                   boxShadow: 'var(--shadow-card)',
                   display: 'flex',
                   alignItems: 'center',

package/components/OnboardingWizard.tsx

@@ -12,10 +12,10 @@ import type { ThemeId } from '@/lib/themes'
 // ---------------------------------------------------------------------------
 
 const ACCENT_PRESETS = [
+  { label: 'Red', value: '#EF4444' },
   { label: 'Gold', value: '#F5C518' },
   { label: 'Blue', value: '#3B82F6' },
   { label: 'Green', value: '#22C55E' },
-  { label: 'Red', value: '#EF4444' },
   { label: 'Orange', value: '#F97316' },
   { label: 'Purple', value: '#A855F7' },
   { label: 'Pink', value: '#EC4899' },
@@ -508,7 +508,7 @@ export function OnboardingWizard({ forceOpen, onClose }: OnboardingWizardProps)
                       padding: '1px 4px',
                       borderRadius: 3,
                       color: 'var(--code-text)',
-                    }}>npm run setup</code> in your terminal to auto-detect and configure your environment.
+                    }}>clawport setup</code> in your terminal to auto-detect and configure your environment.
                     You can continue setup and fix this later.
                   </div>
                 </div>
@@ -657,7 +657,7 @@ export function OnboardingWizard({ forceOpen, onClose }: OnboardingWizardProps)
                     borderRadius: 8,
                     background: settings.accentColor
                       ? `linear-gradient(135deg, ${settings.accentColor}, ${settings.accentColor}dd)`
-                      : 'linear-gradient(135deg, #f5c518, #e8b800)',
+                      : 'transparent',
                     display: 'flex',
                     alignItems: 'center',
                     justifyContent: 'center',

package/components/Sidebar.tsx

@@ -60,7 +60,7 @@ export function Sidebar() {
                     ? 'transparent'
                     : settings.accentColor
                       ? `linear-gradient(135deg, ${settings.accentColor}, ${settings.accentColor}dd)`
-                      : 'linear-gradient(135deg, #f5c518, #e8b800)',
+                      : 'transparent',
                   boxShadow: settings.iconBgHidden ? 'none' : 'var(--shadow-card)',
                   display: 'flex',
                   alignItems: 'center',

package/components/docs/GettingStartedSection.tsx

@@ -42,8 +42,13 @@ export function GettingStartedSection() {
       />
 
       <SubHeading>Quick Start (npm)</SubHeading>
+      <Callout type="note">
+        The npm package is <InlineCode>clawport-ui</InlineCode>. The CLI command
+        is <InlineCode>clawport</InlineCode>. Do not install the unrelated{" "}
+        <InlineCode>clawport</InlineCode> package.
+      </Callout>
       <CodeBlock title="terminal">
-        {`# Install globally
+        {`# Install globally (package: clawport-ui, command: clawport)
 npm install -g clawport-ui
 
 # Run the setup wizard (auto-detects your OpenClaw config)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawport-ui",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "description": "Open-source dashboard for managing, monitoring, and chatting with your OpenClaw AI agents.",
   "homepage": "https://clawport.dev",
   "repository": {
@@ -19,6 +19,22 @@
     "next.js"
   ],
   "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "app/",
+    "bin/",
+    "components/",
+    "docs/",
+    "lib/",
+    "public/",
+    "scripts/",
+    "next.config.mjs",
+    "postcss.config.mjs",
+    "tsconfig.json",
+    ".env.example"
+  ],
   "bin": {
     "clawport": "./bin/clawport.mjs"
   },

package/scripts/setup.mjs

@@ -48,7 +48,8 @@ function detectWorkspacePath() {
 }
 
 function detectOpenClawBin() {
-  return exec('which openclaw')
+  const cmd = process.platform === 'win32' ? 'where' : 'which'
+  return exec(`${cmd} openclaw`)
 }
 
 function detectGatewayToken() {
@@ -63,9 +64,15 @@ function detectGatewayToken() {
   }
 }
 
-function checkGatewayRunning() {
-  const result = exec('curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/ 2>/dev/null')
-  return result && result !== '000'
+async function checkGatewayRunning() {
+  try {
+    const res = await fetch('http://127.0.0.1:18789/', {
+      signal: AbortSignal.timeout(3000),
+    })
+    return res.ok || res.status > 0
+  } catch {
+    return false
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -84,7 +91,7 @@ async function main() {
     OPENCLAW_GATEWAY_TOKEN: detectGatewayToken(),
   }
 
-  const gatewayUp = checkGatewayRunning()
+  const gatewayUp = await checkGatewayRunning()
 
   // Report findings
   const entries = [
@@ -203,12 +210,13 @@ async function main() {
   console.log()
   console.log(`  ${green('Done!')} .env.local written.`)
   console.log()
+  const startCmd = cwdFlag ? 'clawport dev' : 'npm run dev'
   console.log(`  Next steps:`)
   if (!gatewayUp) {
     console.log(`    1. Start the gateway:  ${dim('openclaw gateway run')}`)
-    console.log(`    2. Start ClawPort:   ${dim('npm run dev')}`)
+    console.log(`    2. Start ClawPort:     ${dim(startCmd)}`)
   } else {
-    console.log(`    ${dim('npm run dev')}`)
+    console.log(`    ${dim(startCmd)}`)
   }
   console.log()
 }

package/BRANDING.md

@@ -1,132 +0,0 @@
-# Branding Reference
-
-Current brand name: **ClawPort**
-
-This document maps every location in the codebase where the brand name appears. Use it as a checklist when rebranding.
-
----
-
-## 1. User-Facing Text (UI strings, page titles)
-
-These are what end users see. Change these first during a rebrand.
-
-| File | Line(s) | What | Current Value |
-|------|---------|------|---------------|
-| `app/layout.tsx` | ~10 | `<title>` metadata | `"ClawPort -- Command Centre"` |
-| `components/Sidebar.tsx` | ~84 | Sidebar header fallback name | `'ClawPort'` |
-| `components/MobileSidebar.tsx` | ~138, ~226 | Mobile sidebar fallback name | `'ClawPort'` |
-| `components/OnboardingWizard.tsx` | ~271 | Welcome screen heading | `"Welcome to ClawPort"` |
-| `components/OnboardingWizard.tsx` | ~282 | Welcome screen description | `"A visual command centre for your AI agent team..."` |
-| `components/OnboardingWizard.tsx` | ~572 | Name input placeholder | `"ClawPort"` |
-| `components/OnboardingWizard.tsx` | ~675 | Sidebar preview fallback | `'ClawPort'` |
-| `components/GlobalSearch.tsx` | ~349, ~389-390 | Search modal aria-label + placeholder | `"Search ClawPort"` / `"Search ClawPort..."` |
-| `app/chat/page.tsx` | ~173 | Chat page header | `"ClawPort Messages"` |
-| `lib/agents.json` | ~5, ~14 | Default root agent title + description | `"ClawPort Orchestrator"` |
-| `scripts/setup.mjs` | ~77 | Setup script banner | `"ClawPort Setup"` |
-| `scripts/setup.mjs` | ~184 | Generated .env.local comment | `"# ClawPort -- generated by npm run setup"` |
-| `scripts/setup.mjs` | ~205 | Post-setup instructions | `"Start ClawPort"` |
-| `.env.example` | ~2 | File header comment | `"# ClawPort -- Environment Configuration"` |
-
-## 2. Internal Code Identifiers
-
-TypeScript interfaces, function names, component names, and variable names. These are developer-facing only. Renaming requires updating all imports and references.
-
-| Identifier | Files | Notes |
-|------------|-------|-------|
-| `ClawPortSettings` (interface) | `lib/settings.ts`, `app/settings-provider.tsx`, `docs/THEMING.md`, `docs/COMPONENTS.md` | Core settings type. 20+ references. |
-| `portalName` (field) | `lib/settings.ts`, `app/settings-provider.tsx`, `components/Sidebar.tsx`, `MobileSidebar.tsx`, `OnboardingWizard.tsx`, `app/settings/page.tsx`, `DynamicFavicon.tsx` | Settings field for custom name. |
-| `portalSubtitle` (field) | Same as `portalName` | Settings field for subtitle. |
-| `portalEmoji` (field) | Same as `portalName` | Settings field for emoji. |
-| `portalIcon` (field) | Same as `portalName` | Settings field for uploaded icon image. |
-| `setPortalName` (setter) | `app/settings-provider.tsx`, `OnboardingWizard.tsx`, `app/settings/page.tsx` | Context setter callback. |
-| `setPortalSubtitle` (setter) | Same as `setPortalName` | |
-| `setPortalEmoji` (setter) | Same as `setPortalName` | |
-| `setPortalIcon` (setter) | Same as `setPortalName` | |
-| `OrgMap` (component) | `components/OrgMap.tsx`, `app/page.tsx`, `docs/COMPONENTS.md` | React Flow org chart component. |
-| `OrgMapProps` (interface) | `components/OrgMap.tsx` | Props type for OrgMap. |
-| `HomePage` (component) | `app/page.tsx` | Home page component. |
-| `handleIconUpload` (function) | `app/settings/page.tsx` | Icon upload handler. |
-| `iconInputRef` (ref) | `app/settings/page.tsx` | File input ref. |
-
-## 3. localStorage Keys
-
-Changing these breaks existing users' saved data. Requires a migration function or accept data loss.
-
-| Key | File(s) | Purpose |
-|-----|---------|---------|
-| `clawport-settings` | `lib/settings.ts` | All user settings (name, subtitle, emoji, icon, accent, etc.) |
-| `clawport-theme` | `app/providers.tsx` | Selected theme ID |
-| `clawport-onboarded` | `components/OnboardingWizard.tsx` | First-run completion flag |
-| `clawport-conversations` | `lib/conversations.ts` | Chat message history per agent |
-| `clawport-kanban` | `lib/kanban/store.ts` | Kanban board state |
-
-## 4. Custom Events
-
-| Event Name | File(s) | Purpose |
-|------------|---------|---------|
-| `clawport:open-search` | `components/Sidebar.tsx`, `components/GlobalSearch.tsx` | Triggers Cmd+K search modal |
-
-## 5. API / Session Keys
-
-| Key | File | Purpose |
-|-----|------|---------|
-| `agent:main:clawport` | `lib/anthropic.ts` | Default session key for OpenClaw gateway calls |
-| `clawport-${Date.now()}-...` | `lib/anthropic.ts` | Idempotency key prefix for chat.send |
-
-## 6. Package / Repository
-
-| Location | Current Value |
-|----------|---------------|
-| `package.json` `name` | `clawport-ui` |
-| `package-lock.json` `name` | `clawport-ui` |
-| npm package | [`clawport-ui`](https://www.npmjs.com/package/clawport-ui) |
-| Git clone URLs in docs | `https://github.com/openclaw/clawport.git` |
-
-## 7. Workspace Paths
-
-The user's agent registry override lives at `$WORKSPACE_PATH/clawport/agents.json`. This path is referenced in:
-
-| File | What |
-|------|------|
-| `lib/agents-registry.ts` | `join(workspacePath, 'clawport', 'agents.json')` |
-| Multiple test files | Mock paths like `/tmp/test-workspace/clawport/agents.json` |
-| Documentation | Setup instructions referencing `$WORKSPACE_PATH/clawport/` |
-
-## 8. Documentation Files
-
-Every `.md` file contains brand references. Full list:
-
-| File | Approximate Occurrences |
-|------|------------------------|
-| `README.md` | ~20 |
-| `SETUP.md` | ~25 |
-| `CLAUDE.md` | ~20 |
-| `docs/API.md` | ~5 |
-| `docs/THEMING.md` | ~30 |
-| `docs/COMPONENTS.md` | ~35 |
-| `.env.example` | 1 |
-
-## 9. Test Files
-
-Tests reference brand strings in mock data and localStorage keys:
-
-| File | What |
-|------|------|
-| `lib/settings.test.ts` | `clawport-settings` key, `portalName`/`portalSubtitle`/`portalEmoji`/`portalIcon` fields |
-| `lib/agents.test.ts` | `clawport/agents.json` paths, "ClawPort Orchestrator" in mock data |
-| `lib/conversations.test.ts` | `clawport-conversations` key |
-| `lib/kanban/store.test.ts` | `clawport-kanban` key |
-
----
-
-## Rebrand Checklist
-
-1. **User-facing text** (Section 1) -- find-and-replace the display name
-2. **Documentation** (Section 8) -- update all .md files
-3. **Package name** (Section 6) -- update package.json, re-run npm install
-4. **Internal identifiers** (Section 2) -- rename interfaces, components, functions, fields
-5. **localStorage keys** (Section 3) -- add migration in `loadSettings()` to read old keys
-6. **Custom events** (Section 4) -- rename event strings
-7. **API keys** (Section 5) -- update session key and idempotency prefix
-8. **Workspace paths** (Section 7) -- update `agents-registry.ts` path, support both old/new
-9. **Test files** (Section 9) -- update all mock data and key references

package/CLAUDE.md

@@ -1,266 +0,0 @@
-# ClawPort -- Developer Guide
-
-## Quick Reference
-
-```bash
-npm run setup        # Auto-detect OpenClaw config, write .env.local
-npm run dev          # Start dev server (Turbopack, port 3000)
-npm test             # Run all 288 tests via Vitest (17 suites)
-npx tsc --noEmit     # Type-check (expect 0 errors)
-npx next build       # Production build
-```
-
-### CLI (global install)
-
-```bash
-npm install -g clawport-ui
-clawport setup       # Auto-detect config, write .env.local into package dir
-clawport dev         # Start dev server
-clawport start       # Build + start production server
-clawport status      # Check gateway reachability + env config
-clawport help        # Show usage
-```
-
-The CLI resolves its own package root via `import.meta.url`, so all commands work regardless of the user's current working directory. Entry point: `bin/clawport.mjs`.
-
-## Project Overview
-
-ClawPort is a Next.js 16 dashboard for managing OpenClaw AI agents. It provides an org chart (Org Map), direct agent chat with multimodal support, cron monitoring, and memory browsing. All AI calls route through the OpenClaw gateway -- no separate API keys needed.
-
-## Tech Stack
-
-- Next.js 16.1.6 (App Router, Turbopack)
-- React 19.2.3, TypeScript 5
-- Tailwind CSS 4 with CSS custom properties for theming
-- Vitest 4 with jsdom environment
-- OpenAI SDK (routed to Claude via OpenClaw gateway at localhost:18789)
-- React Flow (@xyflow/react) for org chart
-
-## Environment Variables
-
-```env
-WORKSPACE_PATH       # Required -- path to .openclaw/workspace
-OPENCLAW_BIN         # Required -- path to openclaw binary
-OPENCLAW_GATEWAY_TOKEN  # Required -- gateway auth token
-ELEVENLABS_API_KEY   # Optional -- voice indicators
-```
-
-Run `npm run setup` to auto-detect all required values from your local OpenClaw installation.
-
-## Architecture
-
-### Agent Registry Resolution
-
-```
-loadRegistry() checks:
-  1. $WORKSPACE_PATH/clawport/agents.json  (user override)
-  2. Bundled lib/agents.json            (default)
-```
-
-`lib/agents-registry.ts` exports `loadRegistry()`. `lib/agents.ts` calls it to build the full agent list (merging in SOUL.md content from the workspace). Users customize their agent team by dropping an `agents.json` into their workspace -- no source edits needed.
-
-### operatorName Flow
-
-```
-OnboardingWizard / Settings page
-  -> ClawPortSettings.operatorName (localStorage)
-  -> settings-provider.tsx (React context)
-  -> NavLinks.tsx (dynamic initials + display name)
-  -> ConversationView.tsx (sends operatorName in POST body)
-  -> /api/chat/[id] route (injects into system prompt: "You are speaking with {operatorName}")
-```
-
-No hardcoded operator names anywhere. Falls back to "Operator" / "??" when unset.
-
-### Chat Pipeline (Text)
-
-```
-Client -> POST /api/chat/[id] -> OpenAI SDK -> localhost:18789/v1/chat/completions -> Claude
-                                             (streaming SSE response)
-```
-
-### Chat Pipeline (Images/Vision)
-
-The gateway's HTTP endpoint strips image_url content. Vision uses the CLI agent pipeline:
-
-```
-Client resizes image to 1200px max (Canvas API)
-  -> base64 data URL in message
-  -> POST /api/chat/[id]
-  -> Detects image in LATEST user message only (not history)
-  -> execFile: openclaw gateway call chat.send --params <json> --token <token>
-  -> Polls: openclaw gateway call chat.history every 2s
-  -> Matches response by timestamp >= sendTs
-  -> Returns assistant text via SSE
-```
-
-Key files: `lib/anthropic.ts` (send + poll logic), `app/api/chat/[id]/route.ts` (routing)
-
-**Why send-then-poll?** `chat.send` is async -- it returns `{runId, status: "started"}` immediately. The `--expect-final` flag doesn't block for this method. We poll `chat.history` until the assistant's response appears.
-
-**Why CLI and not WebSocket?** The gateway WebSocket requires device keypair signing for `operator.write` scope (needed by `chat.send`). The CLI has the device keys; custom clients don't.
-
-**Why resize to 1200px?** macOS ARG_MAX is 1MB. Unresized photos can produce multi-MB base64 that exceeds CLI argument limits (E2BIG error). 1200px JPEG at 0.85 quality keeps base64 well under 1MB.
-
-### Voice Message Pipeline
-
-```
-Browser MediaRecorder (webm/opus or mp4)
-  -> AudioContext AnalyserNode captures waveform (40-60 samples)
-  -> Stop -> audioBlob + waveform data
-  -> POST /api/transcribe (Whisper via gateway)
-  -> Transcription text sent as message content
-  -> Audio data URL + waveform stored in message for playback
-```
-
-Key files: `lib/audio-recorder.ts`, `lib/transcribe.ts`, `components/chat/VoiceMessage.tsx`
-
-### Conversation Persistence
-
-Messages stored in localStorage as JSON. Media attachments are base64 data URLs (not blob URLs -- those don't survive reload). The `conversations.ts` module provides `addMessage()`, `updateLastMessage()`, and `parseMedia()`.
-
-### Theming
-
-Five themes defined via CSS custom properties in `app/globals.css`:
-- Dark (default), Glass, Color, Light, System
-- Components use semantic tokens: `--bg`, `--text-primary`, `--accent`, `--separator`, etc.
-- Theme state managed by `app/providers.tsx` ThemeProvider (localStorage)
-
-## Onboarding
-
-`components/OnboardingWizard.tsx` -- 5-step first-run setup wizard:
-
-1. **Welcome** -- portal name, subtitle, operator name (with live sidebar preview)
-2. **Theme** -- pick from available themes (applies live)
-3. **Accent Color** -- color preset grid
-4. **Voice Chat** -- microphone permission test (optional)
-5. **Overview** -- feature summary (Agent Map, Chat, Kanban, Crons, Memory)
-
-**First-run detection:** checks `localStorage('clawport-onboarded')`. If absent, wizard shows automatically.
-
-**Mounting:** `OnboardingWizard` is rendered in `app/layout.tsx` (always present, self-hides when not needed).
-
-**Re-run:** settings page has a button that renders `<OnboardingWizard forceOpen onClose={...} />`. When `forceOpen` is true, the wizard pre-populates from current settings and does not set `clawport-onboarded` on completion.
-
-## Environment Safety
-
-`lib/env.ts` exports `requireEnv(name)` -- throws a clear error with the missing variable name and a pointer to `.env.example`.
-
-**Critical pattern:** call `requireEnv()` inside functions, never at module top level. This prevents imports from crashing during `next build` or test runs when env vars are not set.
-
-Used by: `lib/memory.ts`, `lib/cron-runs.ts`, `lib/kanban/chat-store.ts`, `lib/crons.ts`
-
-## File Map
-
-### API Routes
-
-| Route | Method | Purpose |
-|-------|--------|---------|
-| `/api/agents` | GET | All agents from registry + SOUL.md |
-| `/api/chat/[id]` | POST | Agent chat -- text (streaming) or vision (send+poll) |
-| `/api/crons` | GET | Cron jobs via `openclaw cron list --json` |
-| `/api/memory` | GET | Memory files from workspace |
-| `/api/tts` | POST | Text-to-speech via OpenClaw |
-| `/api/transcribe` | POST | Audio transcription via Whisper |
-
-### Core Libraries
-
-| File | Purpose |
-|------|---------|
-| `lib/agents.ts` | Agent list builder -- calls `loadRegistry()`, merges SOUL.md |
-| `lib/agents-registry.ts` | `loadRegistry()` -- workspace override -> bundled fallback |
-| `lib/agents.json` | Bundled default agent registry |
-| `lib/anthropic.ts` | Vision pipeline: `hasImageContent`, `extractImageAttachments`, `buildTextPrompt`, `sendViaOpenClaw` (send + poll), `execCli` |
-| `lib/audio-recorder.ts` | `createAudioRecorder()` -- MediaRecorder + waveform via AnalyserNode |
-| `lib/conversations.ts` | Conversation store with localStorage persistence |
-| `lib/crons.ts` | Cron data fetching via CLI |
-| `lib/env.ts` | `requireEnv(name)` -- safe env var access with clear errors |
-| `lib/multimodal.ts` | `buildApiContent()` -- converts Message+Media to OpenAI API format |
-| `lib/settings.ts` | `ClawPortSettings` type, `loadSettings()`, `saveSettings()` (localStorage) |
-| `lib/transcribe.ts` | `transcribe(audioBlob)` -- Whisper API with graceful fallback |
-| `lib/validation.ts` | `validateChatMessages()` -- validates text + multimodal content arrays |
-
-### Chat Components
-
-| Component | Purpose |
-|-----------|---------|
-| `ConversationView.tsx` | Main chat: messages, input, recording, paste/drop, file staging. Sends `operatorName` in POST body. |
-| `VoiceMessage.tsx` | Waveform playback: play/pause + animated bar visualization |
-| `FileAttachment.tsx` | File bubble: icon by type + name + size + download |
-| `MediaPreview.tsx` | Pre-send strip of staged attachments with remove buttons |
-| `AgentList.tsx` | Desktop agent sidebar with unread badges |
-
-### Other Components
-
-| Component | Purpose |
-|-----------|---------|
-| `OnboardingWizard.tsx` | 5-step first-run setup wizard (name, theme, accent, mic, overview) |
-| `NavLinks.tsx` | Sidebar nav with dynamic operator initials + name from settings |
-| `Sidebar.tsx` | Sidebar layout shell |
-| `AgentAvatar.tsx` | Agent emoji/image avatar with optional background |
-| `DynamicFavicon.tsx` | Updates favicon based on portal emoji/icon settings |
-
-### Scripts & CLI
-
-| File | Purpose |
-|------|---------|
-| `bin/clawport.mjs` | CLI entry point -- `clawport dev`, `clawport setup`, `clawport status`, etc. Resolves package root via `import.meta.url` |
-| `scripts/setup.mjs` | `npm run setup` / `clawport setup` -- auto-detects WORKSPACE_PATH, OPENCLAW_BIN, gateway token; writes `.env.local`. Accepts `--cwd=<path>` flag for CLI usage |
-
-## Testing
-
-17 test suites, 288 tests total. All in `lib/` directory.
-
-```bash
-npx vitest run                     # All tests
-npx vitest run lib/anthropic.test.ts  # Single suite
-npx vitest --watch                  # Watch mode
-```
-
-Key test patterns:
-- `vi.mock('child_process')` for CLI tests (anthropic.ts)
-- `vi.useFakeTimers({ shouldAdvanceTime: true })` for polling tests
-- `vi.stubEnv()` for environment variable tests
-- jsdom environment for DOM-dependent tests
-
-## Conventions
-
-- No external charting/media libraries -- native Web APIs (Canvas, MediaRecorder, AudioContext)
-- Base64 data URLs for all persisted media (not blob URLs)
-- CSS custom properties for theming -- no Tailwind color classes directly
-- Inline styles referencing CSS vars (e.g., `style={{ color: 'var(--text-primary)' }}`)
-- Tests colocated with source: `lib/foo.ts` + `lib/foo.test.ts`
-- Agent chat uses `claude-sonnet-4-6` model via OpenClaw gateway
-- No em dashes in agent responses (enforced via system prompt)
-- Call `requireEnv()` inside functions, not at module top level
-- No hardcoded operator names -- use `operatorName` from settings context
-
-## Common Tasks
-
-### Add a new agent
-Edit `lib/agents.json` (or drop a custom `agents.json` into `$WORKSPACE_PATH/clawport/`). Auto-appears in map, chat, and detail pages.
-
-### Customize agents for your workspace
-Create `$WORKSPACE_PATH/clawport/agents.json` with your own agent entries. ClawPort loads this instead of the bundled default. Format matches `lib/agents.json`.
-
-### Re-run onboarding wizard
-Go to Settings page and click "Re-run Setup Wizard". This opens the wizard with `forceOpen` so it pre-populates current values and does not reset the `clawport-onboarded` flag.
-
-### Add a new setting field
-1. Add the field to `ClawPortSettings` interface in `lib/settings.ts`
-2. Add a default value in `DEFAULTS`
-3. Add parsing logic in `loadSettings()`
-4. Add a setter method in `app/settings-provider.tsx`
-5. Consume via `useSettings()` hook in components
-
-### Change the chat model
-Edit `app/api/chat/[id]/route.ts` -- change the `model` field in `openai.chat.completions.create()`.
-
-### Add a new theme
-Add a `[data-theme="name"]` block in `app/globals.css` with all CSS custom properties. Add the theme ID to `lib/themes.ts`.
-
-### Debug image pipeline
-1. Check server console for `sendViaOpenClaw execFile error:` or `sendViaOpenClaw: timed out`
-2. Test CLI directly: `openclaw gateway call chat.send --params '{"sessionKey":"agent:main:clawport","idempotencyKey":"test","message":"describe","attachments":[]}' --token <token> --json`
-3. Check history: `openclaw gateway call chat.history --params '{"sessionKey":"agent:main:clawport"}' --token <token> --json`
-4. Verify gateway is running: `openclaw gateway call health --token <token>`

package/SETUP.md

@@ -1,353 +0,0 @@
-# ClawPort -- Setup Guide
-
-This guide walks you through getting ClawPort running against your own OpenClaw instance. If you just want the quick version, see the [README](README.md).
-
----
-
-## Prerequisites
-
-1. **Node.js 22+** -- [Download](https://nodejs.org). Verify with `node -v`.
-2. **OpenClaw** -- [Install OpenClaw](https://openclaw.ai) and make sure the CLI works: `openclaw --version`.
-3. **OpenClaw gateway running** -- ClawPort talks to the gateway at `localhost:18789`. Start it before launching the UI.
-
----
-
-## 1. Install ClawPort
-
-```bash
-# Install globally from npm
-npm install -g clawport-ui
-
-# Or clone the repo
-git clone https://github.com/JohnRiceML/clawport-ui.git
-cd clawport-ui
-npm install
-```
-
----
-
-## 2. Configure Environment
-
-The fastest way is the auto-setup script:
-
-```bash
-# If installed globally via npm
-clawport setup
-
-# Or if running from source
-npm run setup
-```
-
-This auto-detects your `WORKSPACE_PATH`, `OPENCLAW_BIN`, and gateway token from your local OpenClaw installation, shows you what it found, and writes `.env.local` after you confirm.
-
-If you prefer to configure manually, copy the template and edit:
-
-```bash
-cp .env.example .env.local
-```
-
-Open `.env.local` in your editor and set the three required variables.
-
-### WORKSPACE_PATH
-
-The path to your OpenClaw workspace directory. This is where OpenClaw stores agent SOUL files, memory, and other data.
-
-**Default location:** `~/.openclaw/workspace`
-
-To verify:
-
-```bash
-ls ~/.openclaw/workspace
-```
-
-You should see files like `SOUL.md`, an `agents/` directory, and a `memory/` directory. Use the full absolute path in your `.env.local`:
-
-```env
-WORKSPACE_PATH=/Users/yourname/.openclaw/workspace
-```
-
-### OPENCLAW_BIN
-
-The absolute path to the `openclaw` CLI binary. ClawPort calls this binary for vision messages, cron listing, and other CLI operations.
-
-To find it:
-
-```bash
-which openclaw
-```
-
-Use whatever that returns:
-
-```env
-OPENCLAW_BIN=/usr/local/bin/openclaw
-```
-
-If you installed via nvm or a version manager, the path might be something like `/Users/yourname/.nvm/versions/node/v22.14.0/bin/openclaw`. That's fine -- just use the full path.
-
-### OPENCLAW_GATEWAY_TOKEN
-
-The token that authenticates all API calls to the OpenClaw gateway. Every request ClawPort makes (chat, vision, TTS, transcription) includes this token.
-
-To find it:
-
-```bash
-openclaw gateway status
-```
-
-This should display your gateway configuration including the token. Copy it into your `.env.local`:
-
-```env
-OPENCLAW_GATEWAY_TOKEN=your-token-here
-```
-
-### ELEVENLABS_API_KEY (optional)
-
-If you want voice indicators on agent profiles, add your ElevenLabs API key. Get one at [elevenlabs.io](https://elevenlabs.io).
-
-```env
-ELEVENLABS_API_KEY=sk_your-key-here
-```
-
-If you skip this, everything works normally. Voice indicators just won't appear.
-
----
-
-## 3. Start the Gateway
-
-ClawPort expects the OpenClaw gateway to be running at `localhost:18789`. Start it in a separate terminal:
-
-```bash
-openclaw gateway run
-```
-
-Leave this running while you use ClawPort. If the gateway isn't running, chat and all AI features will fail with connection errors.
-
----
-
-## 4. Run ClawPort
-
-```bash
-# If installed globally via npm
-clawport dev
-
-# Or if running from source
-npm run dev
-```
-
-Open [http://localhost:3000](http://localhost:3000).
-
-### First-Run Onboarding
-
-On your first visit, ClawPort launches the **onboarding wizard**. This walks you through:
-
-- **Naming your portal** -- give your command centre a custom name and subtitle
-- **Choosing a theme** -- pick from Dark, Glass, Color, Light, or System
-- **Setting an accent color** -- personalize the UI highlight color
-- **Customizing your logo** -- upload an icon or choose an emoji
-- **Entering your name** -- so the UI knows who the operator is
-
-All of these can be changed later in the Settings page. The wizard just gets you started quickly.
-
----
-
-## 5. Agent Customization
-
-### Using the Bundled Registry
-
-ClawPort ships with a default agent registry at `lib/agents.json`. This is a working example showing a full team hierarchy. It works out of the box if your OpenClaw workspace has matching agent SOUL files.
-
-### Using Your Own Agents
-
-To define your own agent team, create a file at:
-
-```
-$WORKSPACE_PATH/clawport/agents.json
-```
-
-For example, if your `WORKSPACE_PATH` is `/Users/yourname/.openclaw/workspace`:
-
-```bash
-mkdir -p /Users/yourname/.openclaw/workspace/clawport
-```
-
-Then create `agents.json` in that directory. ClawPort checks for this file on every request. If it exists, it replaces the bundled registry entirely. If it's missing or contains invalid JSON, the bundled default is used as a fallback.
-
-### Agent Entry Format
-
-Your `agents.json` should be an array of agent objects. Here's the minimal required shape:
-
-```json
-[
-  {
-    "id": "my-agent",
-    "name": "My Agent",
-    "title": "What this agent does",
-    "reportsTo": null,
-    "directReports": [],
-    "soulPath": "agents/my-agent/SOUL.md",
-    "voiceId": null,
-    "color": "#06b6d4",
-    "emoji": "🤖",
-    "tools": ["read", "write"],
-    "memoryPath": null,
-    "description": "One-liner about this agent."
-  }
-]
-```
-
-### Field Reference
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | string | Unique slug for the agent (e.g., `"vera"`) |
-| `name` | string | Display name (e.g., `"VERA"`) |
-| `title` | string | Role title (e.g., `"Chief Strategy Officer"`) |
-| `reportsTo` | string or null | Parent agent `id` for the org chart. `null` for the root. |
-| `directReports` | string[] | Array of child agent `id`s |
-| `soulPath` | string or null | Path to the agent's SOUL.md, relative to `WORKSPACE_PATH` |
-| `voiceId` | string or null | ElevenLabs voice ID (requires `ELEVENLABS_API_KEY`) |
-| `color` | string | Hex color for the agent's node in the Org Map |
-| `emoji` | string | Emoji shown as the agent's avatar |
-| `tools` | string[] | List of tools this agent has access to |
-| `memoryPath` | string or null | Path to agent-specific memory (relative to `WORKSPACE_PATH`) |
-| `description` | string | One-line description shown in the UI |
-
-### Hierarchy Rules
-
-- Exactly one agent should have `"reportsTo": null` -- this is your root/orchestrator node.
-- `directReports` should be consistent with `reportsTo`. If agent B reports to agent A, then A's `directReports` should include B's `id`.
-- The Org Map uses these relationships to build the org chart automatically.
-
-### Example: Minimal Two-Agent Setup
-
-```json
-[
-  {
-    "id": "boss",
-    "name": "Boss",
-    "title": "Orchestrator",
-    "reportsTo": null,
-    "directReports": ["worker"],
-    "soulPath": "SOUL.md",
-    "voiceId": null,
-    "color": "#f5c518",
-    "emoji": "👑",
-    "tools": ["read", "write", "exec", "message"],
-    "memoryPath": null,
-    "description": "Top-level orchestrator."
-  },
-  {
-    "id": "worker",
-    "name": "Worker",
-    "title": "Task Runner",
-    "reportsTo": "boss",
-    "directReports": [],
-    "soulPath": "agents/worker/SOUL.md",
-    "voiceId": null,
-    "color": "#22c55e",
-    "emoji": "⚙️",
-    "tools": ["read", "write"],
-    "memoryPath": null,
-    "description": "Handles assigned tasks."
-  }
-]
-```
-
----
-
-## 6. Production Build
-
-```bash
-# If installed globally via npm
-clawport start
-
-# Or if running from source
-npx next build
-npm start
-```
-
-The production server runs on port 3000 by default. The gateway still needs to be running at `localhost:18789`.
-
----
-
-## Troubleshooting
-
-### "Missing required environment variable: WORKSPACE_PATH"
-
-Your `.env.local` is missing or the variable isn't set. Make sure you copied `.env.example`:
-
-```bash
-cp .env.example .env.local
-```
-
-Then fill in the values. Restart the dev server after changing `.env.local`.
-
-### Gateway connection refused / chat not working
-
-The OpenClaw gateway isn't running. Start it:
-
-```bash
-openclaw gateway run
-```
-
-Verify it's reachable:
-
-```bash
-curl http://localhost:18789/v1/models
-```
-
-You should get a JSON response. If not, check that nothing else is using port 18789.
-
-### No agents showing up
-
-1. **Check `WORKSPACE_PATH`** -- make sure it points to a valid OpenClaw workspace directory.
-2. **Check your agents.json** -- if you placed a custom `agents.json` at `$WORKSPACE_PATH/clawport/agents.json`, make sure it's valid JSON. A syntax error will cause a silent fallback to the bundled registry. Test with:
-   ```bash
-   cat $WORKSPACE_PATH/clawport/agents.json | python3 -m json.tool
-   ```
-3. **Check the server console** -- ClawPort logs errors to the terminal where `npm run dev` is running.
-
-### Agent SOUL.md not loading
-
-The `soulPath` in your agents.json is relative to `WORKSPACE_PATH`. If your workspace is at `/Users/you/.openclaw/workspace` and `soulPath` is `"agents/vera/SOUL.md"`, ClawPort will look for `/Users/you/.openclaw/workspace/agents/vera/SOUL.md`.
-
-Make sure the file exists at that path.
-
-### Images not working in chat
-
-Image messages use the CLI pipeline (`openclaw gateway call chat.send`). Common issues:
-
-1. **`OPENCLAW_BIN` path is wrong** -- run `which openclaw` and update `.env.local`.
-2. **Gateway token is wrong** -- verify with `openclaw gateway status`.
-3. **Image too large** -- ClawPort resizes to 1200px max, but extremely large images may still hit limits. Try a smaller image.
-
-Check the server console for errors like `sendViaOpenClaw execFile error:` or `E2BIG`.
-
-### Voice/TTS features not working
-
-Voice features require `ELEVENLABS_API_KEY` in your `.env.local`. Without it, voice indicators won't appear on agent profiles.
-
-Audio transcription (speech-to-text) uses Whisper through the OpenClaw gateway and does not require a separate key.
-
-### Port 3000 already in use
-
-Another process is using port 3000. Either stop it or run ClawPort on a different port:
-
-```bash
-npm run dev -- -p 3001
-```
-
----
-
-## Running Tests
-
-```bash
-npm test             # Run all tests via Vitest
-npx tsc --noEmit     # Type-check (expect 0 errors)
-```
-
----
-
-## Developer Guide
-
-For architecture deep-dives, test patterns, and contribution conventions, see [CLAUDE.md](CLAUDE.md).

package/components.json

@@ -1,23 +0,0 @@
-{
-  "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "new-york",
-  "rsc": true,
-  "tsx": true,
-  "tailwind": {
-    "config": "",
-    "css": "app/globals.css",
-    "baseColor": "neutral",
-    "cssVariables": true,
-    "prefix": ""
-  },
-  "iconLibrary": "lucide",
-  "rtl": false,
-  "aliases": {
-    "components": "@/components",
-    "utils": "@/lib/utils",
-    "ui": "@/components/ui",
-    "lib": "@/lib",
-    "hooks": "@/hooks"
-  },
-  "registries": {}
-}

package/vitest.config.ts

@@ -1,17 +0,0 @@
-import { defineConfig } from 'vitest/config'
-import react from '@vitejs/plugin-react'
-import path from 'path'
-
-export default defineConfig({
-  plugins: [react()],
-  resolve: {
-    alias: {
-      '@': path.resolve(__dirname, './'),
-    },
-  },
-  test: {
-    environment: 'jsdom',
-    include: ['**/*.test.ts', '**/*.test.tsx'],
-    exclude: ['node_modules', '.next'],
-  },
-})