clawport-ui 0.1.0

package/components/docs/AgentsSection.tsx

@@ -0,0 +1,209 @@
+import {
+  Heading,
+  SubHeading,
+  Paragraph,
+  CodeBlock,
+  InlineCode,
+  Table,
+  BulletList,
+  NumberedList,
+  Callout,
+} from "./DocSection";
+
+export function AgentsSection() {
+  return (
+    <>
+      <Heading>Agents</Heading>
+      <Paragraph>
+        ClawPort ships with a default agent registry at{" "}
+        <InlineCode>lib/agents.json</InlineCode>. 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.
+      </Paragraph>
+
+      <SubHeading>Using Your Own Agents</SubHeading>
+      <Paragraph>
+        To define your own agent team, create a file at:
+      </Paragraph>
+      <CodeBlock>{`$WORKSPACE_PATH/clawport/agents.json`}</CodeBlock>
+      <Paragraph>
+        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.
+      </Paragraph>
+
+      <SubHeading>Agent Entry Format</SubHeading>
+      <CodeBlock title="agents.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": "\u{1F916}",
+    "tools": ["read", "write"],
+    "memoryPath": null,
+    "description": "One-liner about this agent."
+  }
+]`}
+      </CodeBlock>
+
+      <SubHeading>Field Reference</SubHeading>
+      <Table
+        headers={["Field", "Type", "Description"]}
+        rows={[
+          [
+            <InlineCode key="id">id</InlineCode>,
+            "string",
+            'Unique slug for the agent (e.g., "vera")',
+          ],
+          [
+            <InlineCode key="name">name</InlineCode>,
+            "string",
+            'Display name (e.g., "VERA")',
+          ],
+          [
+            <InlineCode key="title">title</InlineCode>,
+            "string",
+            'Role title (e.g., "Chief Strategy Officer")',
+          ],
+          [
+            <InlineCode key="rt">reportsTo</InlineCode>,
+            "string | null",
+            "Parent agent id for the org chart. null for the root.",
+          ],
+          [
+            <InlineCode key="dr">directReports</InlineCode>,
+            "string[]",
+            "Array of child agent ids",
+          ],
+          [
+            <InlineCode key="sp">soulPath</InlineCode>,
+            "string | null",
+            "Path to the agent's SOUL.md, relative to WORKSPACE_PATH",
+          ],
+          [
+            <InlineCode key="vi">voiceId</InlineCode>,
+            "string | null",
+            "ElevenLabs voice ID (requires ELEVENLABS_API_KEY)",
+          ],
+          [
+            <InlineCode key="co">color</InlineCode>,
+            "string",
+            "Hex color for the agent's node in the Org Map",
+          ],
+          [
+            <InlineCode key="em">emoji</InlineCode>,
+            "string",
+            "Emoji shown as the agent's avatar",
+          ],
+          [
+            <InlineCode key="to">tools</InlineCode>,
+            "string[]",
+            "List of tools this agent has access to",
+          ],
+          [
+            <InlineCode key="mp">memoryPath</InlineCode>,
+            "string | null",
+            "Path to agent-specific memory (relative to WORKSPACE_PATH)",
+          ],
+          [
+            <InlineCode key="de">description</InlineCode>,
+            "string",
+            "One-line description shown in the UI",
+          ],
+        ]}
+      />
+
+      <SubHeading>Hierarchy Rules</SubHeading>
+      <BulletList
+        items={[
+          <>
+            Exactly one agent should have{" "}
+            <InlineCode>{"\"reportsTo\": null"}</InlineCode> -- this is your
+            root/orchestrator node.
+          </>,
+          <>
+            <InlineCode>directReports</InlineCode> should be consistent with{" "}
+            <InlineCode>reportsTo</InlineCode>. 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.",
+        ]}
+      />
+
+      <SubHeading>Example: Minimal Two-Agent Setup</SubHeading>
+      <CodeBlock title="agents.json">
+        {`[
+  {
+    "id": "boss",
+    "name": "Boss",
+    "title": "Orchestrator",
+    "reportsTo": null,
+    "directReports": ["worker"],
+    "soulPath": "SOUL.md",
+    "voiceId": null,
+    "color": "#f5c518",
+    "emoji": "\u{1F451}",
+    "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": "\u{2699}\u{FE0F}",
+    "tools": ["read", "write"],
+    "memoryPath": null,
+    "description": "Handles assigned tasks."
+  }
+]`}
+      </CodeBlock>
+
+      <SubHeading>Registry Resolution</SubHeading>
+      <NumberedList
+        items={[
+          <>
+            <InlineCode>loadRegistry()</InlineCode> checks{" "}
+            <InlineCode>$WORKSPACE_PATH/clawport/agents.json</InlineCode> first
+            (user override).
+          </>,
+          <>
+            Falls back to bundled <InlineCode>lib/agents.json</InlineCode> if
+            the workspace file is missing or has invalid JSON.
+          </>,
+          <>
+            <InlineCode>lib/agents.ts</InlineCode> merges in SOUL.md content
+            from each agent's <InlineCode>soulPath</InlineCode>.
+          </>,
+          "The result is the full agent list used by all pages.",
+        ]}
+      />
+
+      <Callout type="tip">
+        You can add a new agent without editing any source code -- just update
+        your workspace <InlineCode>agents.json</InlineCode>. The agent will
+        automatically appear in the Org Map, Chat, and Detail pages.
+      </Callout>
+
+      <SubHeading>Agent Display Overrides</SubHeading>
+      <Paragraph>
+        Each agent can have per-agent emoji and/or profile image overrides via
+        the Settings page. These are stored in{" "}
+        <InlineCode>ClawPortSettings.agentOverrides</InlineCode> keyed by agent ID.
+        The <InlineCode>getAgentDisplay()</InlineCode> function resolves the
+        effective visual for each agent, considering overrides.
+      </Paragraph>
+    </>
+  );
+}

package/components/docs/ApiReferenceSection.tsx

@@ -0,0 +1,256 @@
+import {
+  Heading,
+  SubHeading,
+  Paragraph,
+  CodeBlock,
+  InlineCode,
+  Table,
+  Callout,
+  InfoCard,
+} from "./DocSection";
+
+export function ApiReferenceSection() {
+  return (
+    <>
+      <Heading>API Reference</Heading>
+      <Paragraph>
+        All API routes are Next.js App Router route handlers under{" "}
+        <InlineCode>app/api/</InlineCode>. The base URL during development is{" "}
+        <InlineCode>http://localhost:3000</InlineCode>.
+      </Paragraph>
+
+      <InfoCard title="Error Format">
+        <Paragraph>
+          All error responses share a consistent JSON shape:
+        </Paragraph>
+        <CodeBlock>{`{ "error": "Human-readable error message" }`}</CodeBlock>
+      </InfoCard>
+
+      <SubHeading>Route Summary</SubHeading>
+      <Table
+        headers={["Method", "Endpoint", "Gateway", "Content-Type"]}
+        rows={[
+          [
+            "GET",
+            <InlineCode key="1">/api/agents</InlineCode>,
+            "No",
+            "application/json",
+          ],
+          [
+            "POST",
+            <InlineCode key="2">/api/chat/[id]</InlineCode>,
+            "Yes",
+            "text/event-stream",
+          ],
+          [
+            "GET",
+            <InlineCode key="3">/api/crons</InlineCode>,
+            "No",
+            "application/json",
+          ],
+          [
+            "GET",
+            <InlineCode key="4">/api/cron-runs</InlineCode>,
+            "No",
+            "application/json",
+          ],
+          [
+            "GET",
+            <InlineCode key="5">/api/memory</InlineCode>,
+            "No",
+            "application/json",
+          ],
+          [
+            "POST",
+            <InlineCode key="6">/api/tts</InlineCode>,
+            "Yes",
+            "audio/mpeg",
+          ],
+          [
+            "POST",
+            <InlineCode key="7">/api/transcribe</InlineCode>,
+            "Yes",
+            "application/json",
+          ],
+          [
+            "POST",
+            <InlineCode key="8">/api/kanban/chat/[id]</InlineCode>,
+            "Yes",
+            "text/event-stream",
+          ],
+          [
+            "GET",
+            <InlineCode key="9">/api/kanban/chat-history/[ticketId]</InlineCode>,
+            "No",
+            "application/json",
+          ],
+          [
+            "POST",
+            <InlineCode key="10">/api/kanban/chat-history/[ticketId]</InlineCode>,
+            "No",
+            "application/json",
+          ],
+        ]}
+      />
+
+      {/* ── GET /api/agents ────────────────────────────────────── */}
+      <SubHeading>GET /api/agents</SubHeading>
+      <Paragraph>
+        Returns the full list of registered agents, each with their SOUL.md
+        content loaded from the filesystem. No parameters required.
+      </Paragraph>
+      <Table
+        headers={["Field", "Type", "Description"]}
+        rows={[
+          [<InlineCode key="id">id</InlineCode>, "string", "Slug identifier"],
+          [<InlineCode key="n">name</InlineCode>, "string", "Display name"],
+          [<InlineCode key="t">title</InlineCode>, "string", "Role title"],
+          [
+            <InlineCode key="s">soul</InlineCode>,
+            "string | null",
+            "Full SOUL.md content, or null if file not found",
+          ],
+          [
+            <InlineCode key="c">crons</InlineCode>,
+            "CronJob[]",
+            "Always [] from this endpoint (populated client-side)",
+          ],
+        ]}
+      />
+
+      {/* ── POST /api/chat/[id] ────────────────────────────────── */}
+      <SubHeading>POST /api/chat/[id]</SubHeading>
+      <Paragraph>
+        Send a chat message to an agent and receive a streaming response. Has
+        two pipelines depending on whether the latest user message contains
+        images.
+      </Paragraph>
+      <Table
+        headers={["Field", "Type", "Required", "Description"]}
+        rows={[
+          [
+            <InlineCode key="m">messages</InlineCode>,
+            "ApiMessage[]",
+            "Yes",
+            "Conversation history",
+          ],
+          [
+            <InlineCode key="o">operatorName</InlineCode>,
+            "string",
+            "No",
+            'Name shown to the agent. Defaults to "Operator"',
+          ],
+        ]}
+      />
+      <Paragraph>
+        <strong style={{ color: "var(--text-primary)" }}>Pipeline 1 (Text):</strong>{" "}
+        Streaming chat completion via the gateway. Response is SSE with{" "}
+        <InlineCode>{"data: {\"content\":\"token\"}"}</InlineCode> frames.
+      </Paragraph>
+      <Paragraph>
+        <strong style={{ color: "var(--text-primary)" }}>Pipeline 2 (Vision):</strong>{" "}
+        When the latest message contains image_url content. Uses CLI chat.send +
+        chat.history polling. Complete response arrives in a single SSE frame.
+      </Paragraph>
+
+      {/* ── GET /api/crons ─────────────────────────────────────── */}
+      <SubHeading>GET /api/crons</SubHeading>
+      <Paragraph>
+        Returns all cron jobs registered with OpenClaw, enriched with schedule
+        descriptions, agent ownership, and delivery config. Runs{" "}
+        <InlineCode>openclaw cron list --json</InlineCode> via the CLI.
+      </Paragraph>
+
+      {/* ── GET /api/cron-runs ─────────────────────────────────── */}
+      <SubHeading>GET /api/cron-runs</SubHeading>
+      <Paragraph>
+        Returns cron run history parsed from JSONL log files on the filesystem.
+        Results sorted newest-first. Optional{" "}
+        <InlineCode>jobId</InlineCode> query parameter filters to a specific
+        job.
+      </Paragraph>
+
+      {/* ── GET /api/memory ────────────────────────────────────── */}
+      <SubHeading>GET /api/memory</SubHeading>
+      <Paragraph>
+        Returns the contents of key memory files from the workspace: long-term
+        memory, team memory, team intel, and the daily logs for today and
+        yesterday. Only files that exist are included in the response.
+      </Paragraph>
+
+      {/* ── POST /api/tts ──────────────────────────────────────── */}
+      <SubHeading>POST /api/tts</SubHeading>
+      <Paragraph>
+        Converts text to speech audio using the OpenClaw gateway's TTS endpoint.
+      </Paragraph>
+      <Table
+        headers={["Field", "Type", "Required", "Description"]}
+        rows={[
+          [
+            <InlineCode key="t">text</InlineCode>,
+            "string",
+            "Yes",
+            "The text to synthesize",
+          ],
+          [
+            <InlineCode key="v">voice</InlineCode>,
+            "string",
+            "No",
+            'Voice identifier. Defaults to "alloy"',
+          ],
+        ]}
+      />
+
+      {/* ── POST /api/transcribe ───────────────────────────────── */}
+      <SubHeading>POST /api/transcribe</SubHeading>
+      <Paragraph>
+        Transcribes audio to text using the Whisper endpoint. Request body is
+        multipart form data with an <InlineCode>audio</InlineCode> file field.
+      </Paragraph>
+
+      {/* ── SSE Protocol ───────────────────────────────────────── */}
+      <SubHeading>SSE Stream Protocol</SubHeading>
+      <Paragraph>
+        All streaming chat endpoints use the same Server-Sent Events protocol:
+      </Paragraph>
+      <CodeBlock>
+        {`data: {"content":"Hello"}
+
+data: {"content":" there"}
+
+data: [DONE]`}
+      </CodeBlock>
+      <Callout type="note">
+        Content-Type is <InlineCode>text/event-stream</InlineCode> with{" "}
+        <InlineCode>Cache-Control: no-cache</InlineCode>. If a stream error
+        occurs mid-response, the server sends [DONE] and closes the connection.
+      </Callout>
+
+      <SubHeading>Client-Side Consumption</SubHeading>
+      <CodeBlock title="example">
+        {`const reader = response.body.getReader()
+const decoder = new TextDecoder()
+let fullText = ''
+
+while (true) {
+  const { done, value } = await reader.read()
+  if (done) break
+
+  const chunk = decoder.decode(value, { stream: true })
+  const lines = chunk.split('\\n')
+
+  for (const line of lines) {
+    if (line.startsWith('data: ')) {
+      const payload = line.slice(6)
+      if (payload === '[DONE]') return fullText
+      try {
+        const { content } = JSON.parse(payload)
+        fullText += content
+      } catch { /* skip malformed frames */ }
+    }
+  }
+}`}
+      </CodeBlock>
+    </>
+  );
+}

package/components/docs/ArchitectureSection.tsx

@@ -0,0 +1,221 @@
+import {
+  Heading,
+  SubHeading,
+  Paragraph,
+  CodeBlock,
+  InlineCode,
+  Table,
+  BulletList,
+  Callout,
+  InfoCard,
+} from "./DocSection";
+
+export function ArchitectureSection() {
+  return (
+    <>
+      <Heading>Architecture</Heading>
+      <Paragraph>
+        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, kanban task board, and memory browsing. All AI
+        calls route through the OpenClaw gateway -- no separate API keys needed.
+      </Paragraph>
+
+      <SubHeading>Tech Stack</SubHeading>
+      <BulletList
+        items={[
+          "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 (17 suites, 288 tests)",
+          "OpenAI SDK (routed to Claude via OpenClaw gateway at localhost:18789)",
+          "React Flow (@xyflow/react) for org chart",
+        ]}
+      />
+
+      <SubHeading>Agent Registry Resolution</SubHeading>
+      <CodeBlock>
+        {`loadRegistry() checks:
+  1. $WORKSPACE_PATH/clawport/agents.json  (user override)
+  2. Bundled lib/agents.json            (default)`}
+      </CodeBlock>
+      <Paragraph>
+        <InlineCode>lib/agents-registry.ts</InlineCode> exports{" "}
+        <InlineCode>loadRegistry()</InlineCode>.{" "}
+        <InlineCode>lib/agents.ts</InlineCode> calls it to build the full agent
+        list (merging in SOUL.md content from the workspace). Users customize
+        their agent team by dropping an{" "}
+        <InlineCode>agents.json</InlineCode> into their workspace -- no source
+        edits needed.
+      </Paragraph>
+
+      <SubHeading>Chat Pipeline (Text)</SubHeading>
+      <CodeBlock>
+        {`Client -> POST /api/chat/[id] -> OpenAI SDK -> localhost:18789/v1/chat/completions -> Claude
+                                         (streaming SSE response)`}
+      </CodeBlock>
+
+      <SubHeading>Chat Pipeline (Images/Vision)</SubHeading>
+      <Paragraph>
+        The gateway's HTTP endpoint strips image_url content. Vision uses the
+        CLI agent pipeline:
+      </Paragraph>
+      <CodeBlock>
+        {`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`}
+      </CodeBlock>
+
+      <InfoCard title="Design Decisions">
+        <BulletList
+          items={[
+            <>
+              <strong style={{ color: "var(--text-primary)" }}>
+                Why send-then-poll?
+              </strong>{" "}
+              chat.send is async -- it returns immediately. We poll chat.history
+              until the assistant's response appears.
+            </>,
+            <>
+              <strong style={{ color: "var(--text-primary)" }}>
+                Why CLI and not WebSocket?
+              </strong>{" "}
+              The gateway WebSocket requires device keypair signing for
+              operator.write scope. The CLI has the device keys; custom clients
+              don't.
+            </>,
+            <>
+              <strong style={{ color: "var(--text-primary)" }}>
+                Why resize to 1200px?
+              </strong>{" "}
+              macOS ARG_MAX is 1MB. Unresized photos can produce multi-MB base64
+              that exceeds CLI argument limits (E2BIG error).
+            </>,
+          ]}
+        />
+      </InfoCard>
+
+      <SubHeading>Voice Message Pipeline</SubHeading>
+      <CodeBlock>
+        {`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`}
+      </CodeBlock>
+
+      <SubHeading>operatorName Flow</SubHeading>
+      <CodeBlock>
+        {`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)`}
+      </CodeBlock>
+      <Callout type="note">
+        No hardcoded operator names anywhere. Falls back to "Operator" / "??"
+        when unset.
+      </Callout>
+
+      <SubHeading>Directory Structure</SubHeading>
+      <CodeBlock>
+        {`app/
+  page.tsx              -- Org Map (React Flow org chart)
+  chat/page.tsx         -- Multi-agent messenger
+  agents/[id]/page.tsx  -- Agent detail profile
+  kanban/page.tsx       -- Task board
+  crons/page.tsx        -- Cron job monitor
+  memory/page.tsx       -- Memory file browser
+  settings/page.tsx     -- ClawPort personalization
+  docs/page.tsx         -- Documentation browser
+  api/
+    agents/route.ts     -- GET agents from registry
+    chat/[id]/route.ts  -- POST chat (text + vision)
+    crons/route.ts      -- GET crons via CLI
+    memory/route.ts     -- GET memory files
+    tts/route.ts        -- POST text-to-speech
+    transcribe/route.ts -- POST audio transcription
+
+components/
+  OrgMap.tsx          -- React Flow graph with auto-layout
+  AgentNode.tsx         -- Custom node for the org chart
+  Sidebar.tsx           -- Desktop navigation sidebar
+  MobileSidebar.tsx     -- Mobile hamburger menu
+  NavLinks.tsx          -- Sidebar nav links
+  ThemeToggle.tsx       -- Theme switcher (5 themes)
+  GlobalSearch.tsx      -- Cmd+K agent search
+  chat/                 -- Chat components
+  kanban/               -- Kanban components
+  crons/                -- Cron components
+  docs/                 -- Documentation components
+
+lib/
+  agents.ts             -- Agent registry + SOUL.md reader
+  agents-registry.ts    -- Registry loader
+  anthropic.ts          -- Vision pipeline (send + poll)
+  conversations.ts      -- Conversation store (localStorage)
+  settings.ts           -- ClawPortSettings type + persistence
+  themes.ts             -- Theme definitions
+  types.ts              -- Shared TypeScript types`}
+      </CodeBlock>
+
+      <SubHeading>Key Libraries</SubHeading>
+      <Table
+        headers={["File", "Purpose"]}
+        rows={[
+          [
+            <InlineCode key="a">lib/agents.ts</InlineCode>,
+            "Agent list builder -- calls loadRegistry(), merges SOUL.md",
+          ],
+          [
+            <InlineCode key="ar">lib/agents-registry.ts</InlineCode>,
+            "loadRegistry() -- workspace override -> bundled fallback",
+          ],
+          [
+            <InlineCode key="an">lib/anthropic.ts</InlineCode>,
+            "Vision pipeline: hasImageContent, sendViaOpenClaw (send + poll), execCli",
+          ],
+          [
+            <InlineCode key="c">lib/conversations.ts</InlineCode>,
+            "Conversation store with localStorage persistence",
+          ],
+          [
+            <InlineCode key="e">lib/env.ts</InlineCode>,
+            "requireEnv(name) -- safe env var access with clear errors",
+          ],
+          [
+            <InlineCode key="m">lib/multimodal.ts</InlineCode>,
+            "buildApiContent() -- converts Message+Media to OpenAI API format",
+          ],
+          [
+            <InlineCode key="s">lib/settings.ts</InlineCode>,
+            "ClawPortSettings type, loadSettings(), saveSettings() (localStorage)",
+          ],
+          [
+            <InlineCode key="v">lib/validation.ts</InlineCode>,
+            "validateChatMessages() -- validates text + multimodal content arrays",
+          ],
+        ]}
+      />
+
+      <SubHeading>Conventions</SubHeading>
+      <BulletList
+        items={[
+          "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",
+          "Call requireEnv() inside functions, not at module top level",
+        ]}
+      />
+    </>
+  );
+}