clawport-ui 0.1.0 → 0.2.0

package/BRANDING.md

@@ -42,8 +42,8 @@ TypeScript interfaces, function names, component names, and variable names. Thes
 | `setPortalSubtitle` (setter) | Same as `setPortalName` | |
 | `setPortalEmoji` (setter) | Same as `setPortalName` | |
 | `setPortalIcon` (setter) | Same as `setPortalName` | |
-| `OrgMap` (component) | `components/ManorMap.tsx`, `app/page.tsx`, `docs/COMPONENTS.md` | React Flow org chart component. |
-| `OrgMapProps` (interface) | `components/ManorMap.tsx` | Props type for OrgMap. |
+| `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. |
@@ -77,8 +77,9 @@ Changing these breaks existing users' saved data. Requires a migration function
 
 | Location | Current Value |
 |----------|---------------|
-| `package.json` `name` | `clawport` |
-| `package-lock.json` `name` | `clawport` |
+| `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

package/CLAUDE.md

@@ -10,6 +10,19 @@ 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.
@@ -187,11 +200,12 @@ Used by: `lib/memory.ts`, `lib/cron-runs.ts`, `lib/kanban/chat-store.ts`, `lib/c
 | `AgentAvatar.tsx` | Agent emoji/image avatar with optional background |
 | `DynamicFavicon.tsx` | Updates favicon based on portal emoji/icon settings |
 
-### Scripts
+### Scripts & CLI
 
 | File | Purpose |
 |------|---------|
-| `scripts/setup.mjs` | `npm run setup` -- auto-detects WORKSPACE_PATH, OPENCLAW_BIN, gateway token; writes `.env.local` |
+| `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
 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 John Rice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -14,14 +14,24 @@ ClawPort is an open-source dashboard for managing, monitoring, and talking direc
 - [OpenClaw](https://openclaw.ai) installed and running
 - OpenClaw gateway started (`openclaw gateway run`)
 
-### Quick Start
+### Quick Start (npm)
 
 ```bash
-# Clone the repo
-git clone https://github.com/openclaw/clawport.git
-cd clawport
+# Install globally
+npm install -g clawport-ui
 
-# Install dependencies
+# Auto-detect your OpenClaw config
+clawport setup
+
+# Start the dev server
+clawport dev
+```
+
+### Quick Start (from source)
+
+```bash
+git clone https://github.com/JohnRiceML/clawport-ui.git
+cd clawport-ui
 npm install
 
 # Auto-detect your OpenClaw config and write .env.local
@@ -257,6 +267,27 @@ npx next build       # Production build
 
 ---
 
+## npm
+
+```bash
+npm install -g clawport-ui
+clawport help
+```
+
+Published as [`clawport-ui`](https://www.npmjs.com/package/clawport-ui) on npm.
+
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `clawport dev` | Start the development server |
+| `clawport start` | Build and start the production server |
+| `clawport setup` | Auto-detect OpenClaw config and write `.env.local` |
+| `clawport status` | Check gateway reachability and current config |
+| `clawport help` | Show usage |
+
+---
+
 ## License
 
 MIT

package/SETUP.md

@@ -15,8 +15,12 @@ This guide walks you through getting ClawPort running against your own OpenClaw
 ## 1. Install ClawPort
 
 ```bash
-git clone https://github.com/openclaw/clawport.git
-cd clawport
+# 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
 ```
 
@@ -27,6 +31,10 @@ npm install
 The fastest way is the auto-setup script:
 
 ```bash
+# If installed globally via npm
+clawport setup
+
+# Or if running from source
 npm run setup
 ```
 
@@ -119,6 +127,10 @@ Leave this running while you use ClawPort. If the gateway isn't running, chat an
 ## 4. Run ClawPort
 
 ```bash
+# If installed globally via npm
+clawport dev
+
+# Or if running from source
 npm run dev
 ```
 
@@ -246,6 +258,10 @@ Your `agents.json` should be an array of agent objects. Here's the minimal requi
 ## 6. Production Build
 
 ```bash
+# If installed globally via npm
+clawport start
+
+# Or if running from source
 npx next build
 npm start
 ```

package/app/docs/page.tsx

@@ -9,6 +9,7 @@ import { CronSystemSection } from "@/components/docs/CronSystemSection";
 import { ThemingSection } from "@/components/docs/ThemingSection";
 import { ComponentsSection } from "@/components/docs/ComponentsSection";
 import { TroubleshootingSection } from "@/components/docs/TroubleshootingSection";
+import { BestPracticesSection } from "@/components/docs/BestPracticesSection";
 
 /* ─── Section Definitions ──────────────────────────────────────── */
 
@@ -42,6 +43,13 @@ const SECTIONS: DocSectionDef[] = [
     description: "Registry, hierarchy, customization",
     component: AgentsSection,
   },
+  {
+    id: "best-practices",
+    label: "Best Practices",
+    emoji: "\u{1F3AF}",
+    description: "Hierarchy, memory, tools, naming",
+    component: BestPracticesSection,
+  },
   {
     id: "api-reference",
     label: "API Reference",

package/app/page.tsx

@@ -12,7 +12,7 @@ import { GridView } from "@/components/GridView"
 import { FeedView } from "@/components/FeedView"
 
 const OrgMap = dynamic(
-  () => import("@/components/ManorMap").then((m) => ({ default: m.OrgMap })),
+  () => import("@/components/OrgMap").then((m) => ({ default: m.OrgMap })),
   {
     ssr: false,
     loading: () => (

package/bin/clawport.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+
+// ---------------------------------------------------------------------------
+// Resolve package root (where app/, lib/, etc. live)
+// ---------------------------------------------------------------------------
+
+const __filename = fileURLToPath(import.meta.url)
+const PKG_ROOT = resolve(dirname(__filename), '..')
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const green = (s) => `\x1b[32m${s}\x1b[0m`
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`
+const red = (s) => `\x1b[31m${s}\x1b[0m`
+const dim = (s) => `\x1b[2m${s}\x1b[0m`
+const bold = (s) => `\x1b[1m${s}\x1b[0m`
+
+function run(cmd, args = []) {
+  const child = spawn(cmd, args, {
+    cwd: PKG_ROOT,
+    stdio: 'inherit',
+    shell: true,
+  })
+  child.on('close', (code) => process.exit(code ?? 0))
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+function showHelp() {
+  console.log(`
+${bold('ClawPort')} -- AI Agent Dashboard
+
+${bold('Usage:')} clawport <command>
+
+${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('help')}     Show this help message
+
+${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(`Package root: ${PKG_ROOT}`)}
+`)
+}
+
+function cmdDev() {
+  console.log(`\n  ${bold('Starting ClawPort dev server...')}\n`)
+  run('npx', ['next', 'dev'])
+}
+
+function cmdStart() {
+  console.log(`\n  ${bold('Building and starting ClawPort...')}\n`)
+  run('npx', ['next', 'build', '&&', 'npx', 'next', 'start'])
+}
+
+function cmdSetup() {
+  console.log()
+  run('node', [resolve(PKG_ROOT, 'scripts/setup.mjs'), `--cwd=${PKG_ROOT}`])
+}
+
+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
+  }
+
+  if (gatewayUp) {
+    console.log(`  ${green('+')} Gateway reachable at ${dim('localhost:18789')}`)
+  } else {
+    console.log(`  ${red('x')} Gateway not responding at ${dim('localhost:18789')}`)
+    console.log(`    ${dim('Start it with: openclaw gateway run')}`)
+  }
+
+  // Check .env.local
+  const envPath = resolve(PKG_ROOT, '.env.local')
+  console.log()
+  if (existsSync(envPath)) {
+    console.log(`  ${green('+')} .env.local found`)
+    const content = readFileSync(envPath, 'utf-8')
+    const lines = content.split('\n').filter((l) => l && !l.startsWith('#'))
+    for (const line of lines) {
+      const [key, ...rest] = line.split('=')
+      const value = rest.join('=')
+      if (key === 'OPENCLAW_GATEWAY_TOKEN' && value) {
+        console.log(`    ${dim(key)}=${dim(value.slice(0, 8) + '...' + value.slice(-4))}`)
+      } else if (key && value) {
+        console.log(`    ${dim(key)}=${dim(value)}`)
+      }
+    }
+  } else {
+    console.log(`  ${yellow('!')} No .env.local found`)
+    console.log(`    ${dim('Run: clawport setup')}`)
+  }
+
+  console.log()
+  console.log(`  ${dim(`Package root: ${PKG_ROOT}`)}`)
+  console.log()
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const command = process.argv[2]
+
+switch (command) {
+  case 'dev':
+    cmdDev()
+    break
+  case 'start':
+    cmdStart()
+    break
+  case 'setup':
+    cmdSetup()
+    break
+  case 'status':
+    cmdStatus()
+    break
+  case 'help':
+  default:
+    showHelp()
+    break
+}

package/components/docs/BestPracticesSection.tsx

@@ -0,0 +1,612 @@
+import {
+  Heading,
+  SubHeading,
+  Paragraph,
+  CodeBlock,
+  InlineCode,
+  Table,
+  BulletList,
+  NumberedList,
+  Callout,
+  InfoCard,
+} from "./DocSection";
+
+export function BestPracticesSection() {
+  return (
+    <>
+      <Heading>Best Practices</Heading>
+      <Paragraph>
+        This guide covers the patterns and conventions behind a production agent
+        team. Every example uses real agents from the bundled registry so you can
+        see exactly how hierarchy, memory, tools, and crons come together.
+      </Paragraph>
+
+      {/* ─── Hierarchy ──────────────────────────────────────── */}
+
+      <SubHeading>Hierarchy Design</SubHeading>
+      <Paragraph>
+        A well-structured agent team follows a clear chain of command. The
+        pattern is: one orchestrator at the top, team leads in the middle, and
+        specialist leaf agents at the bottom. Each level has a distinct
+        responsibility.
+      </Paragraph>
+
+      <InfoCard title="The Three Tiers">
+        <Table
+          headers={["Tier", "Role", "Example"]}
+          rows={[
+            [
+              "Orchestrator",
+              "Top-level coordinator. Holds team memory, routes work, delivers briefings.",
+              <><strong key="j">Jarvis</strong> -- the root node. reportsTo: null.</>,
+            ],
+            [
+              "Team Lead",
+              "Owns a domain. Manages a sub-team and runs pipelines end-to-end.",
+              <>
+                <strong key="v">VERA</strong> (Strategy),{" "}
+                <strong key="l">LUMEN</strong> (SEO),{" "}
+                <strong key="h">HERALD</strong> (LinkedIn)
+              </>,
+            ],
+            [
+              "Specialist",
+              "Does one thing well. Reports up, never manages others.",
+              <>
+                <strong key="t">TRACE</strong> (Market Research),{" "}
+                <strong key="q">QUILL</strong> (LinkedIn Writer),{" "}
+                <strong key="s">SCOUT</strong> (Content Scout)
+              </>,
+            ],
+          ]}
+        />
+      </InfoCard>
+
+      <Paragraph>
+        The bundled registry ships 22 agents organized into five teams:
+      </Paragraph>
+
+      <CodeBlock title="Team Structure">
+        {`Jarvis (Orchestrator)
+  |
+  +-- VERA (Strategy)
+  |     +-- Robin (Field Intel)
+  |           +-- TRACE (Market Research)
+  |           +-- PROOF (Validation Design)
+  |
+  +-- LUMEN (SEO)
+  |     +-- SCOUT (Content Scout)
+  |     +-- ANALYST (SEO Analyst)
+  |     +-- STRATEGIST (Content Strategy)
+  |     +-- WRITER (Content Writer)
+  |     +-- AUDITOR (Quality Gate)
+  |
+  +-- HERALD (LinkedIn)
+  |     +-- QUILL (LinkedIn Writer)
+  |     +-- MAVEN (LinkedIn Strategist)
+  |
+  +-- Pulse (Trend Radar)      -- standalone
+  +-- ECHO (Community Voice)   -- standalone
+  +-- SAGE (ICP Expert)        -- standalone
+  +-- KAZE (Flight Monitor)    -- standalone
+  +-- SPARK (Tech Discovery)   -- standalone
+  +-- SCRIBE (Memory Architect)-- standalone`}
+      </CodeBlock>
+
+      <Callout type="tip">
+        Standalone agents (no direct reports) report directly to the
+        orchestrator. Keep this list short -- if you have more than 8-10 direct
+        reports on the root node, it's time to group them under a team lead.
+      </Callout>
+
+      <SubHeading>Hierarchy Rules</SubHeading>
+      <NumberedList
+        items={[
+          <>
+            <strong>One root.</strong> Exactly one agent has{" "}
+            <InlineCode>{"\"reportsTo\": null"}</InlineCode>. This is your
+            orchestrator (Jarvis).
+          </>,
+          <>
+            <strong>Team leads own pipelines.</strong> LUMEN owns the full SEO
+            pipeline (SCOUT to AUDITOR). HERALD owns the LinkedIn pipeline
+            (QUILL + MAVEN). Each lead is responsible for end-to-end delivery.
+          </>,
+          <>
+            <strong>Leaf agents are specialists.</strong> They do one thing and
+            report up. TRACE does market research. QUILL writes posts. AUDITOR
+            runs the quality gate. No scope creep.
+          </>,
+          <>
+            <strong>Max depth of 3.</strong> Jarvis to Robin to TRACE is
+            three levels. Going deeper adds latency and coordination overhead
+            with little benefit.
+          </>,
+          <>
+            <strong>Keep directReports consistent.</strong> If agent B has{" "}
+            <InlineCode>{"\"reportsTo\": \"A\""}</InlineCode>, then agent A's
+            directReports array must include B's id. The Org Map renders from
+            these relationships.
+          </>,
+        ]}
+      />
+
+      {/* ─── SOUL.md ────────────────────────────────────────── */}
+
+      <SubHeading>SOUL.md -- Agent Character Documents</SubHeading>
+      <Paragraph>
+        Every agent has a SOUL.md file that defines its personality, expertise,
+        and operating constraints. This is not a system prompt -- it's a
+        character document. The agent reads it to understand who it is.
+      </Paragraph>
+
+      <CodeBlock title="Recommended SOUL.md Structure">
+        {`# AGENT_NAME -- Role Title
+
+## Identity
+Who the agent is. Personality traits. Communication style.
+First-person voice: "I am VERA, the Chief Strategy Officer."
+
+## Expertise
+What domains this agent knows deeply.
+What it should be consulted on vs. what it defers.
+
+## Operating Rules
+Hard constraints. What it must always/never do.
+Output format requirements.
+
+## Relationships
+Who it reports to. Who reports to it.
+How it collaborates with peer agents.
+
+## Memory
+What it remembers between sessions.
+Where its persistent knowledge lives.`}
+      </CodeBlock>
+
+      <BulletList
+        items={[
+          <>
+            <strong>Be specific about personality.</strong> HERALD is described
+            as brash and direct. SAGE is contemplative and precise. Distinct
+            voices prevent all agents from sounding the same.
+          </>,
+          <>
+            <strong>Define what the agent does NOT do.</strong> SCRIBE (Memory
+            Architect) is a "silent worker" -- it never initiates conversation.
+            SAGE (ICP Expert) is read-only -- it never writes to external
+            systems.
+          </>,
+          <>
+            <strong>Include output format examples.</strong> If the agent
+            produces Market Briefs, show the exact format. TRACE returns
+            structured TAM/competitor/pricing data, not prose.
+          </>,
+          <>
+            <strong>Keep it under 500 lines.</strong> Long SOUL files dilute
+            the agent's focus. If you need more detail, link to reference docs.
+          </>,
+        ]}
+      />
+
+      <Callout type="note">
+        SOUL.md files live in your OpenClaw workspace at the path defined by
+        each agent's <InlineCode>soulPath</InlineCode> field. ClawPort reads
+        and displays them on the agent detail page.
+      </Callout>
+
+      {/* ─── Naming ─────────────────────────────────────────── */}
+
+      <SubHeading>Naming Conventions</SubHeading>
+      <Paragraph>
+        Agent naming follows a simple pattern that signals the agent's scope
+        at a glance:
+      </Paragraph>
+
+      <Table
+        headers={["Pattern", "When to Use", "Examples"]}
+        rows={[
+          [
+            "UPPERCASE",
+            "Agents that are part of a pipeline or team. Feels like a callsign.",
+            "VERA, LUMEN, HERALD, SCOUT, QUILL, ECHO, SAGE",
+          ],
+          [
+            "Title Case",
+            "Standalone agents with more personality. The orchestrator or personal-feeling agents.",
+            "Jarvis, Robin, Pulse",
+          ],
+        ]}
+      />
+
+      <Paragraph>
+        Ids are always lowercase slugs:{" "}
+        <InlineCode>vera</InlineCode>,{" "}
+        <InlineCode>lumen</InlineCode>,{" "}
+        <InlineCode>herald</InlineCode>. The display name in the{" "}
+        <InlineCode>name</InlineCode> field is what users see in the UI.
+      </Paragraph>
+
+      {/* ─── Tools ──────────────────────────────────────────── */}
+
+      <SubHeading>Tool Assignment</SubHeading>
+      <Paragraph>
+        Follow the principle of least privilege. Each agent gets only the tools
+        it needs for its job -- nothing more.
+      </Paragraph>
+
+      <Table
+        headers={["Tool", "Purpose", "Who Gets It"]}
+        rows={[
+          [
+            <InlineCode key="r">read</InlineCode>,
+            "Read files from workspace",
+            "Almost everyone. The base capability.",
+          ],
+          [
+            <InlineCode key="w">write</InlineCode>,
+            "Write/create files",
+            "Agents that produce artifacts (WRITER, ANALYST, STRATEGIST)",
+          ],
+          [
+            <InlineCode key="e">exec</InlineCode>,
+            "Run shell commands",
+            "Orchestrator + leads who run pipelines (Jarvis, LUMEN, HERALD)",
+          ],
+          [
+            <InlineCode key="ws">web_search</InlineCode>,
+            "Search the web",
+            "Research agents (TRACE, Robin, SCOUT, Pulse, SPARK)",
+          ],
+          [
+            <InlineCode key="wf">web_fetch</InlineCode>,
+            "Fetch a specific URL",
+            "Agents that scrape or monitor (ECHO, KAZE, Robin)",
+          ],
+          [
+            <InlineCode key="m">message</InlineCode>,
+            "Send messages to other agents",
+            "Agents that coordinate (Jarvis, Robin, Pulse, HERALD)",
+          ],
+          [
+            <InlineCode key="ss">sessions_spawn</InlineCode>,
+            "Spawn sub-agent sessions",
+            "Only orchestrator + team leads (Jarvis, VERA)",
+          ],
+          [
+            <InlineCode key="ms">memory_search</InlineCode>,
+            "Search across team memory",
+            "Orchestrator only (Jarvis)",
+          ],
+          [
+            <InlineCode key="tt">tts</InlineCode>,
+            "Text-to-speech",
+            "Orchestrator only (Jarvis)",
+          ],
+        ]}
+      />
+
+      <Callout type="warning">
+        Giving <InlineCode>exec</InlineCode> to a leaf agent is almost always
+        a mistake. If a specialist needs to run a command, it should ask its
+        team lead to do it. This keeps the blast radius small.
+      </Callout>
+
+      <InfoCard title="Tool Assignment Examples">
+        <CodeBlock>
+          {`// SAGE -- read-only knowledge agent
+"tools": ["read"]
+
+// SCOUT -- web researcher
+"tools": ["web_search", "web_fetch", "read"]
+
+// WRITER -- content producer
+"tools": ["read", "write"]
+
+// HERALD -- team lead running a pipeline
+"tools": ["web_search", "web_fetch", "read", "write", "message", "exec"]
+
+// Jarvis -- orchestrator with full access
+"tools": ["exec", "read", "write", "edit", "web_search", "tts", "message", "sessions_spawn", "memory_search"]`}
+        </CodeBlock>
+      </InfoCard>
+
+      {/* ─── Memory ─────────────────────────────────────────── */}
+
+      <SubHeading>Memory Architecture</SubHeading>
+      <Paragraph>
+        Agent memory uses a three-tier system. Each tier serves a different
+        purpose, and together they give agents both short-term recall and
+        long-term knowledge.
+      </Paragraph>
+
+      <InfoCard title="The Three Memory Tiers">
+        <Table
+          headers={["Tier", "What", "Lifespan", "Who Manages"]}
+          rows={[
+            [
+              "1. Daily Logs",
+              "Raw output from each agent session. Unedited, timestamped.",
+              "7-14 days (then compressed or archived)",
+              "Each agent writes its own",
+            ],
+            [
+              "2. MEMORY.md",
+              "Curated, compressed knowledge. The agent's persistent brain.",
+              "Indefinite (updated weekly)",
+              <>
+                <strong>SCRIBE</strong> runs weekly compression
+              </>,
+            ],
+            [
+              "3. Team Memory",
+              "Shared knowledge across agents. Market data, ICP profiles, strategy docs.",
+              "Indefinite",
+              "Team leads + orchestrator",
+            ],
+          ]}
+        />
+      </InfoCard>
+
+      <SubHeading>Tier 1: Daily Logs</SubHeading>
+      <Paragraph>
+        Every time an agent runs, it writes a log file. These are the raw
+        session transcripts -- what the agent did, what it found, what it
+        produced. Daily logs are high-volume and low-curation.
+      </Paragraph>
+      <CodeBlock title="Daily log path pattern">
+        {`$WORKSPACE_PATH/agents/<agent-id>/logs/YYYY-MM-DD.md`}
+      </CodeBlock>
+
+      <SubHeading>Tier 2: MEMORY.md</SubHeading>
+      <Paragraph>
+        Each agent has a MEMORY.md file that persists its key knowledge between
+        sessions. Unlike daily logs (which are raw), MEMORY.md is curated --
+        only the important patterns, decisions, and facts survive.
+      </Paragraph>
+      <CodeBlock title="MEMORY.md structure">
+        {`# Agent Name -- Memory
+
+## Key Patterns
+- Pattern 1 confirmed across 3+ sessions
+- Pattern 2 from last week's research
+
+## Active Context
+- Current project status
+- Open questions / blockers
+
+## Learned Preferences
+- User prefers X over Y
+- Always include Z in output`}
+      </CodeBlock>
+      <Paragraph>
+        <strong>SCRIBE</strong> (Memory Architect) runs weekly to compress daily
+        logs into each agent's MEMORY.md. SCRIBE reads the raw logs, extracts
+        durable insights, and updates the memory file -- discarding
+        session-specific noise. This keeps MEMORY.md concise and high-signal.
+      </Paragraph>
+
+      <SubHeading>Tier 3: Team Memory (Shared)</SubHeading>
+      <Paragraph>
+        Some knowledge needs to be shared across agents. Market intelligence,
+        ICP profiles, competitive analysis, and brand voice docs all live in a
+        shared team-memory directory. Any agent with{" "}
+        <InlineCode>read</InlineCode> access to the workspace can reference
+        these files.
+      </Paragraph>
+      <CodeBlock title="Team memory path">
+        {`$WORKSPACE_PATH/team-memory/
+  market-brief.md       -- TRACE's latest research
+  icp-profile.md        -- SAGE's ICP knowledge
+  competitor-map.md     -- Robin's competitive intel
+  brand-voice.md        -- Voice profile for content agents
+  content-calendar.md   -- MAVEN's editorial calendar`}
+      </CodeBlock>
+
+      <Callout type="tip">
+        Team memory files are the glue between agents. When STRATEGIST needs
+        market context, it reads TRACE's market brief. When WRITER needs brand
+        voice, it reads the voice profile. No agent-to-agent API calls needed
+        -- just shared files.
+      </Callout>
+
+      {/* ─── Communication ──────────────────────────────────── */}
+
+      <SubHeading>Agent Communication</SubHeading>
+      <Paragraph>
+        Agents communicate through files, not direct API calls. This is
+        intentional -- file-based communication is debuggable, auditable, and
+        doesn't create tight coupling.
+      </Paragraph>
+
+      <NumberedList
+        items={[
+          <>
+            <strong>Upstream (reporting up):</strong> An agent writes its output
+            to a file. The team lead or orchestrator reads it on the next run.
+            Example: SCOUT writes topic suggestions, LUMEN reads them to
+            brief STRATEGIST.
+          </>,
+          <>
+            <strong>Downstream (delegating):</strong> A team lead writes a
+            brief file that the specialist reads. Example: HERALD writes an
+            angle brief, QUILL reads it and drafts the post.
+          </>,
+          <>
+            <strong>Cross-team (shared context):</strong> Agents read from
+            team-memory. Example: STRATEGIST reads SAGE's ICP profile and
+            ECHO's community voice data to pick the right content angle.
+          </>,
+        ]}
+      />
+
+      <Callout type="note">
+        The <InlineCode>message</InlineCode> tool exists for real-time
+        coordination (e.g., Pulse alerting LUMEN about a trending topic), but
+        the default communication channel is always files. Messages are for
+        urgency; files are for substance.
+      </Callout>
+
+      {/* ─── Crons ──────────────────────────────────────────── */}
+
+      <SubHeading>Cron Patterns</SubHeading>
+      <Paragraph>
+        Cron jobs are the heartbeat of an autonomous agent team. Each cron
+        follows the same philosophy: one fetch, one decision, one output.
+      </Paragraph>
+
+      <BulletList
+        items={[
+          <>
+            <strong>Assign crons to the right tier.</strong> Research crons go
+            on leaf agents (SCOUT, TRACE, ECHO). Pipeline crons go on team
+            leads (LUMEN, HERALD). Briefing crons go on the orchestrator
+            (Jarvis).
+          </>,
+          <>
+            <strong>Stagger schedules.</strong> Don't run all crons at the same
+            time. Space them out so upstream agents finish before downstream
+            agents read their output.
+          </>,
+          <>
+            <strong>Keep crons focused.</strong> Each cron does one thing.
+            "Scan subreddits" is a good cron. "Scan subreddits, analyze
+            sentiment, write a blog post, and publish" is four crons pretending
+            to be one.
+          </>,
+          <>
+            <strong>Error isolation.</strong> If a cron fails, it should only
+            affect its own output. Other agents reading stale data is better
+            than a cascade failure.
+          </>,
+        ]}
+      />
+
+      <Table
+        headers={["Cron", "Agent", "Schedule", "Pattern"]}
+        rows={[
+          [
+            "Community scan",
+            <strong key="e">ECHO</strong>,
+            "Weekly",
+            "Fetch subreddit posts, extract customer language, write to team-memory",
+          ],
+          [
+            "Trend radar",
+            <strong key="p">Pulse</strong>,
+            "Every other day",
+            "Scan trending signals, write hot topics file, message LUMEN if urgent",
+          ],
+          [
+            "Flight monitor",
+            <strong key="k">KAZE</strong>,
+            "Daily",
+            "Check flight prices, message Jarvis if deal found under threshold",
+          ],
+          [
+            "Memory compression",
+            <strong key="s">SCRIBE</strong>,
+            "Weekly",
+            "Read daily logs, compress into MEMORY.md, archive old logs",
+          ],
+          [
+            "Content pipeline",
+            <strong key="l">LUMEN</strong>,
+            "Weekly",
+            "Orchestrate SCOUT -> ANALYST -> STRATEGIST -> WRITER -> AUDITOR",
+          ],
+        ]}
+      />
+
+      {/* ─── Voice ──────────────────────────────────────────── */}
+
+      <SubHeading>Voice System</SubHeading>
+      <Paragraph>
+        Agents that interact directly with the operator can have an ElevenLabs
+        voice ID assigned. This enables text-to-speech on their responses in
+        the chat interface. Not every agent needs a voice -- only those the
+        operator talks to regularly.
+      </Paragraph>
+
+      <BulletList
+        items={[
+          <>
+            <strong>Give voices to conversational agents.</strong> Jarvis
+            (orchestrator), VERA (strategy advisor), Pulse (trend alerts) --
+            agents you chat with benefit from voice.
+          </>,
+          <>
+            <strong>Skip voices for pipeline workers.</strong> SCOUT, ANALYST,
+            WRITER, AUDITOR run in pipelines and rarely need to speak. Don't
+            waste voice slots on them.
+          </>,
+          <>
+            Set <InlineCode>voiceId</InlineCode> to{" "}
+            <InlineCode>null</InlineCode> for agents without voice. The UI
+            hides the TTS button when voiceId is null.
+          </>,
+        ]}
+      />
+
+      {/* ─── Design Principles ──────────────────────────────── */}
+
+      <SubHeading>Design Principles</SubHeading>
+
+      <InfoCard title="1. Agents are characters, not functions">
+        <Paragraph>
+          Each agent has a name, a personality, and a role title. They're not
+          interchangeable worker threads -- they're team members with distinct
+          expertise. VERA thinks strategically. ECHO listens to communities.
+          KAZE watches flights. This makes the team legible and memorable.
+        </Paragraph>
+      </InfoCard>
+
+      <InfoCard title="2. Least privilege, always">
+        <Paragraph>
+          An agent should have exactly the tools it needs and nothing more. SAGE
+          is read-only because it's a knowledge base, not an actor. SCRIBE has{" "}
+          <InlineCode>exec</InlineCode> because it needs to run file operations
+          during memory compression. If you're unsure whether an agent needs a
+          tool, start without it. You can always add it later.
+        </Paragraph>
+      </InfoCard>
+
+      <InfoCard title="3. Files over messages">
+        <Paragraph>
+          Prefer file-based communication over real-time messages. Files are
+          inspectable, diffable, and persist across sessions. Messages are for
+          urgent signals only (e.g., Pulse alerting about a breaking trend).
+          Everything else goes through shared files in team-memory.
+        </Paragraph>
+      </InfoCard>
+
+      <InfoCard title="4. One agent, one job">
+        <Paragraph>
+          Resist the urge to make Swiss Army knife agents. TRACE does market
+          research -- it doesn't also write blog posts. QUILL writes LinkedIn
+          posts -- it doesn't also analyze metrics. When an agent's description
+          needs the word "and" more than once, split it into two agents.
+        </Paragraph>
+      </InfoCard>
+
+      <InfoCard title="5. Depth of 3, max">
+        <Paragraph>
+          Jarvis to Robin to TRACE is three levels. Going deeper adds latency
+          and makes the chain of command confusing. If you need more
+          specialization, add lateral agents (more direct reports) instead of
+          deeper nesting.
+        </Paragraph>
+      </InfoCard>
+
+      <InfoCard title="6. Let SCRIBE handle memory">
+        <Paragraph>
+          Don't make every agent manage its own memory compression. SCRIBE
+          exists specifically to read daily logs, extract patterns, and update
+          MEMORY.md files. This single responsibility keeps memory consistent
+          and prevents agents from spending cycles on housekeeping instead of
+          their actual job.
+        </Paragraph>
+      </InfoCard>
+    </>
+  );
+}

package/components/docs/GettingStartedSection.tsx

@@ -41,7 +41,27 @@ export function GettingStartedSection() {
         ]}
       />
 
-      <SubHeading>Quick Start</SubHeading>
+      <SubHeading>Quick Start (npm)</SubHeading>
+      <CodeBlock title="terminal">
+        {`# Install globally
+npm install -g clawport-ui
+
+# Run the setup wizard (auto-detects your OpenClaw config)
+clawport setup
+
+# Start the dev server
+clawport dev`}
+      </CodeBlock>
+      <Callout type="warning">
+        If you get <InlineCode>EACCES: permission denied</InlineCode> or{" "}
+        <InlineCode>EEXIST</InlineCode> errors during install, your npm cache
+        has broken permissions (usually from a previous{" "}
+        <InlineCode>sudo npm install</InlineCode>). Fix it with:{" "}
+        <InlineCode>sudo chown -R $(whoami) ~/.npm</InlineCode> then retry.
+        See the Troubleshooting section for full details.
+      </Callout>
+
+      <SubHeading>Quick Start (from source)</SubHeading>
       <CodeBlock title="terminal">
         {`# Clone the repo
 git clone https://github.com/openclaw/clawport.git

package/components/docs/TroubleshootingSection.tsx

@@ -17,6 +17,71 @@ export function TroubleshootingSection() {
         Common issues and their solutions when running ClawPort.
       </Paragraph>
 
+      {/* ── npm install permission errors ──────────────────────── */}
+      <SubHeading>
+        EACCES / permission denied during npm install -g
+      </SubHeading>
+      <Paragraph>
+        If you see errors like <InlineCode>EACCES: permission denied</InlineCode>,{" "}
+        <InlineCode>EEXIST</InlineCode>, or{" "}
+        <InlineCode>Invalid response body while trying to fetch</InlineCode> when
+        running <InlineCode>npm install -g clawport-ui</InlineCode>, your npm
+        cache directory has broken permissions. This usually happens if{" "}
+        <InlineCode>npm install -g</InlineCode> was previously run with{" "}
+        <InlineCode>sudo</InlineCode>.
+      </Paragraph>
+      <Paragraph>
+        Fix it in three steps:
+      </Paragraph>
+      <NumberedList
+        items={[
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>
+              Fix cache permissions
+            </strong>
+          </>,
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>
+              Fix global node_modules permissions
+            </strong>
+          </>,
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>
+              Retry the install
+            </strong>
+          </>,
+        ]}
+      />
+      <CodeBlock title="terminal">
+        {`# 1. Fix npm cache ownership
+sudo chown -R $(whoami) ~/.npm
+
+# 2. Fix global node_modules ownership (find your prefix first)
+npm prefix -g
+# Then fix permissions on that path, e.g.:
+sudo chown -R $(whoami) /usr/local/lib/node_modules
+sudo chown -R $(whoami) /usr/local/bin
+
+# 3. Retry without sudo
+npm install -g clawport-ui`}
+      </CodeBlock>
+      <Paragraph>
+        If that still fails, clear the cache entirely and retry:
+      </Paragraph>
+      <CodeBlock title="terminal">
+        {`npm cache clean --force
+npm install -g clawport-ui`}
+      </CodeBlock>
+      <Callout type="warning">
+        Never use <InlineCode>sudo npm install -g</InlineCode> -- it creates
+        root-owned files in your user's npm cache and global directories, which
+        causes permission errors on every future install. If your setup requires
+        sudo for global installs, consider using{" "}
+        <InlineCode>nvm</InlineCode> (Node Version Manager) instead, which
+        installs Node and global packages in your home directory with no
+        permission issues.
+      </Callout>
+
       {/* ── Issue 1 ────────────────────────────────────────────── */}
       <SubHeading>
         "Missing required environment variable: WORKSPACE_PATH"

package/lib/agents.json

@@ -6,7 +6,7 @@
     "reportsTo": null,
     "directReports": ["vera", "lumen", "herald", "pulse", "echo", "sage", "kaze", "spark", "scribe"],
     "soulPath": "SOUL.md",
-    "voiceId": "agL69Vji082CshT65Tcy",
+    "voiceId": null,
     "color": "#f5c518",
     "emoji": "\ud83e\udd16",
     "tools": ["exec", "read", "write", "edit", "web_search", "tts", "message", "sessions_spawn", "memory_search"],
@@ -20,7 +20,7 @@
     "reportsTo": "jarvis",
     "directReports": ["robin"],
     "soulPath": "agents/vera/SOUL.md",
-    "voiceId": "EAHourGM2PqzHHl0Ywjp",
+    "voiceId": null,
     "color": "#a855f7",
     "emoji": "\u265f\ufe0f",
     "tools": ["web_search", "web_fetch", "read", "write", "sessions_spawn"],
@@ -34,7 +34,7 @@
     "reportsTo": "vera",
     "directReports": ["trace", "proof"],
     "soulPath": "agents/robin/SOUL.md",
-    "voiceId": "IRHApOXLvnW57QJPQH2P",
+    "voiceId": null,
     "color": "#3b82f6",
     "emoji": "\ud83e\udd85",
     "tools": ["web_search", "web_fetch", "read", "write", "message"],
@@ -76,7 +76,7 @@
     "reportsTo": "jarvis",
     "directReports": ["scout", "analyst", "strategist", "writer", "auditor"],
     "soulPath": "agents/seo-team/SOUL.md",
-    "voiceId": "EVy5l1wEi54nXdQwAJJf",
+    "voiceId": null,
     "color": "#22c55e",
     "emoji": "\ud83d\udd26",
     "tools": ["web_search", "web_fetch", "read", "write", "exec"],
@@ -202,7 +202,7 @@
     "reportsTo": "jarvis",
     "directReports": [],
     "soulPath": "agents/pulse/SOUL.md",
-    "voiceId": "eadgjmk4R4uojdsheG9t",
+    "voiceId": null,
     "color": "#eab308",
     "emoji": "\ud83c\udf0a",
     "tools": ["web_search", "web_fetch", "read", "write", "message"],
@@ -258,7 +258,7 @@
     "reportsTo": "jarvis",
     "directReports": [],
     "soulPath": "agents/spark/SOUL.md",
-    "voiceId": "xNtG3W2oqJs0cJZuTyBc",
+    "voiceId": null,
     "color": "#f59e0b",
     "emoji": "\u26a1",
     "tools": ["web_fetch", "web_search", "message"],

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "clawport-ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Open-source dashboard for managing, monitoring, and chatting with your OpenClaw AI agents.",
   "homepage": "https://clawport.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/openclaw/clawport.git"
+    "url": "https://github.com/JohnRiceML/clawport-ui.git"
   },
   "bugs": {
-    "url": "https://github.com/openclaw/clawport/issues"
+    "url": "https://github.com/JohnRiceML/clawport-ui/issues"
   },
   "keywords": [
     "openclaw",
@@ -19,12 +19,16 @@
     "next.js"
   ],
   "license": "MIT",
+  "bin": {
+    "clawport": "./bin/clawport.mjs"
+  },
   "scripts": {
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
     "test": "vitest run",
-    "setup": "node scripts/setup.mjs"
+    "setup": "node scripts/setup.mjs",
+    "prepublishOnly": "npx tsc --noEmit && vitest run"
   },
   "dependencies": {
     "@xyflow/react": "^12.10.1",

package/scripts/setup.mjs

@@ -155,8 +155,12 @@ async function main() {
     }
   }
 
+  // Support --cwd flag for CLI usage (clawport setup writes .env.local into the package dir)
+  const cwdFlag = process.argv.find((a) => a.startsWith('--cwd='))
+  const targetDir = cwdFlag ? cwdFlag.split('=')[1] : process.cwd()
+
   // Check if .env.local already exists
-  const envPath = resolve(process.cwd(), '.env.local')
+  const envPath = resolve(targetDir, '.env.local')
   if (existsSync(envPath)) {
     const overwrite = await ask(`  ${yellow('?')} .env.local already exists. Overwrite? (y/N) `)
     if (overwrite.toLowerCase() !== 'y') {