clawport-ui 0.1.0

package/.env.example

@@ -0,0 +1,35 @@
+# =============================================================================
+# ClawPort — Environment Configuration
+# =============================================================================
+# Copy this file to .env.local and fill in your values:
+#   cp .env.example .env.local
+#
+# See SETUP.md for detailed instructions on finding each value.
+# =============================================================================
+
+# ---------------------------------------------------------------------------
+# Required
+# ---------------------------------------------------------------------------
+
+# Path to your OpenClaw workspace directory.
+# Default location: ~/.openclaw/workspace
+# Find yours: ls ~/.openclaw/workspace
+WORKSPACE_PATH=/Users/yourname/.openclaw/workspace
+
+# Path to the openclaw CLI binary.
+# Find yours: which openclaw
+OPENCLAW_BIN=/usr/local/bin/openclaw
+
+# OpenClaw gateway authentication token.
+# All API calls (chat, vision, TTS, transcription) use this token.
+# Find yours: openclaw gateway status
+OPENCLAW_GATEWAY_TOKEN=your-gateway-token-here
+
+# ---------------------------------------------------------------------------
+# Optional
+# ---------------------------------------------------------------------------
+
+# ElevenLabs API key — enables voice indicators on agent profiles.
+# Get one at: https://elevenlabs.io
+# Leave blank or remove this line if you don't need voice features.
+# ELEVENLABS_API_KEY=sk_your-elevenlabs-key-here

package/BRANDING.md

@@ -0,0 +1,131 @@
+# 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/ManorMap.tsx`, `app/page.tsx`, `docs/COMPONENTS.md` | React Flow org chart component. |
+| `OrgMapProps` (interface) | `components/ManorMap.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` |
+| `package-lock.json` `name` | `clawport` |
+| 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

@@ -0,0 +1,252 @@
+# 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
+```
+
+## 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
+
+| File | Purpose |
+|------|---------|
+| `scripts/setup.mjs` | `npm run setup` -- auto-detects WORKSPACE_PATH, OPENCLAW_BIN, gateway token; writes `.env.local` |
+
+## 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/README.md

@@ -0,0 +1,262 @@
+# ClawPort
+
+A visual command centre for your AI agent team.
+
+ClawPort is an open-source dashboard for managing, monitoring, and talking directly to your [OpenClaw](https://openclaw.ai) AI agents. Built with Next.js 16, React 19, and a dark command-centre aesthetic with five themes.
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- [Node.js 22+](https://nodejs.org) (LTS recommended)
+- [OpenClaw](https://openclaw.ai) installed and running
+- OpenClaw gateway started (`openclaw gateway run`)
+
+### Quick Start
+
+```bash
+# Clone the repo
+git clone https://github.com/openclaw/clawport.git
+cd clawport
+
+# Install dependencies
+npm install
+
+# Auto-detect your OpenClaw config and write .env.local
+npm run setup
+
+# Start the dev server
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000). On first launch you'll see the **onboarding wizard**, which walks you through naming your portal, choosing a theme, and personalizing agent avatars.
+
+See [SETUP.md](SETUP.md) for detailed environment configuration and troubleshooting.
+
+---
+
+## Features
+
+### Org Map
+Interactive org chart of your entire agent team. Nodes show hierarchy, cron status, voice capabilities, and relationships at a glance. Powered by React Flow with BFS-based auto-layout.
+
+### Chat (Call Box)
+Full-featured messenger for direct agent conversations:
+- **Streaming text chat** via Claude (through the OpenClaw gateway)
+- **Image attachments** with vision -- agents can see and describe images
+- **Voice messages** -- hold-to-record with waveform playback
+- **File attachments** -- PDFs, docs, text files with type-aware rendering
+- **Clipboard paste and drag-and-drop** for images
+- **Clear chat** per agent
+- Conversations persist to localStorage
+
+### Agent Detail
+Full profile: SOUL.md viewer, tool list, hierarchy, associated crons, voice ID, and direct chat link.
+
+### Kanban
+Task board for managing work across your agent team. Drag-and-drop cards with agent assignment and chat context.
+
+### Cron Monitor
+Live status of all scheduled jobs. Filter by status (all/ok/error/idle), sort errors to top, expand for error details. Auto-refreshes every 60 seconds.
+
+### Memory Browser
+Read team memory, long-term memory, and daily logs. Markdown rendering and JSON syntax highlighting built-in. Search, copy, and download support.
+
+### Settings
+Personalize your portal: custom name, subtitle, logo/emoji, accent color, agent avatar overrides, and theme selection. All settings persist in your browser.
+
+---
+
+## Configuration
+
+### Required Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `WORKSPACE_PATH` | Path to your OpenClaw workspace directory (default: `~/.openclaw/workspace`) |
+| `OPENCLAW_BIN` | Path to the `openclaw` CLI binary |
+| `OPENCLAW_GATEWAY_TOKEN` | Token that authenticates all API calls to the gateway |
+
+### Optional Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ELEVENLABS_API_KEY` | ElevenLabs API key for voice/TTS indicators on agent profiles |
+
+No separate AI API keys are needed. All AI calls (chat, vision, TTS, transcription) route through the OpenClaw gateway.
+
+See [SETUP.md](SETUP.md) for how to find each value.
+
+---
+
+## Agent Customization
+
+ClawPort ships with a bundled agent registry (`lib/agents.json`) as a working example. To use your own agents, create a file at:
+
+```
+$WORKSPACE_PATH/clawport/agents.json
+```
+
+ClawPort checks for this file on every request. If it exists, it takes priority over the bundled registry. If it's missing or malformed, the bundled default is used as a fallback.
+
+Each agent entry looks like this:
+
+```json
+{
+  "id": "my-agent",
+  "name": "My Agent",
+  "title": "What they do",
+  "reportsTo": "parent-agent-id",
+  "directReports": [],
+  "soulPath": "agents/my-agent/SOUL.md",
+  "voiceId": null,
+  "color": "#06b6d4",
+  "emoji": "🤖",
+  "tools": ["read", "write"],
+  "memoryPath": null,
+  "description": "One-liner description of this agent."
+}
+```
+
+See [SETUP.md](SETUP.md) for the full field reference and examples.
+
+---
+
+## Architecture
+
+### How Chat Works
+
+Text messages go through the OpenClaw gateway's OpenAI-compatible endpoint (`/v1/chat/completions`) for streaming responses.
+
+Image messages use a different pipeline because the gateway's HTTP endpoint strips image data. Instead, ClawPort uses the same path as Discord/Telegram channels:
+
+```
+User attaches image
+  → Client resizes to 1200px max (fits within OS arg limits)
+  → Client converts to base64 data URL
+  → POST /api/chat/[id] detects image in latest message
+  → Server calls `openclaw gateway call chat.send` via CLI
+  → Server polls `openclaw gateway call chat.history` every 2s
+  → Agent processes image + text through Anthropic vision API
+  → Response returned to client as SSE
+```
+
+Voice messages are recorded in-browser using the MediaRecorder API, transcribed server-side via Whisper (through the gateway's `/v1/audio/transcriptions` endpoint), and sent as text with the audio waveform preserved for playback.
+
+### Directory Structure
+
+```
+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
+  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
+  ThemeToggle.tsx       — Theme switcher (5 themes)
+  GlobalSearch.tsx      — Cmd+K agent search
+  chat/
+    ConversationView.tsx — Message history + input with media
+    AgentList.tsx        — Agent sidebar for chat
+    VoiceMessage.tsx     — Waveform playback component
+    FileAttachment.tsx   — File bubble with icon + download
+    MediaPreview.tsx     — Pre-send attachment strip
+
+lib/
+  agents.ts             — Agent registry + SOUL.md reader
+  agents-registry.ts    — Registry loader (workspace override or bundled)
+  agents.json           — Bundled default agent registry
+  anthropic.ts          — OpenClaw vision pipeline (chat.send + poll)
+  audio-recorder.ts     — MediaRecorder + waveform extraction
+  conversations.ts      — Client-side conversation store (localStorage)
+  crons.ts              — Cron data via openclaw CLI
+  env.ts                — Environment variable helper
+  memory.ts             — Memory file reader
+  multimodal.ts         — Message → API content format converter
+  sanitize.ts           — HTML/markdown sanitization
+  settings.ts           — ClawPort settings (localStorage)
+  transcribe.ts         — Whisper transcription with fallback
+  validation.ts         — Chat message validation
+  types.ts              — Shared TypeScript types
+  themes.ts             — Theme definitions
+  styles.ts             — Semantic style constants
+  utils.ts              — Tailwind merge utility
+```
+
+### Key Design Decisions
+
+- **No separate API keys** -- All AI calls (chat, vision, TTS, transcription) route through the OpenClaw gateway. One subscription, one token.
+- **No external charting/media libraries** -- Voice waveforms use plain div bars (not canvas), images resize via native Canvas API, all CSS uses Tailwind custom properties.
+- **Client-side persistence** -- Conversations stored in localStorage with base64 data URLs. Blob URLs don't survive page reload; data URLs do.
+- **Image resize before send** -- Images are resized client-side to max 1200px longest side before base64 encoding. This keeps the CLI argument payload under macOS's 1MB `ARG_MAX` limit.
+- **Send-then-poll for vision** -- The gateway's `chat.send` is async (returns immediately). We poll `chat.history` every 2 seconds until the assistant response appears, matched by timestamp.
+
+---
+
+## Themes
+
+Five built-in themes, toggled via the sidebar button:
+
+| Theme | Description |
+|-------|-------------|
+| **Dark** | Apple Dark Mode with warm blacks, gold accent |
+| **Glass** | Frosted translucent panels on deep blue-black |
+| **Color** | Vibrant purple-indigo gradients |
+| **Light** | Apple Light Mode, clean whites |
+| **System** | Follows OS preference |
+
+All themes use CSS custom properties. Components reference semantic tokens (`--bg`, `--text-primary`, `--accent`, etc.) so every theme is automatic.
+
+---
+
+## Stack
+
+- [Next.js 16](https://nextjs.org) (App Router, Turbopack)
+- [React 19](https://react.dev)
+- [TypeScript 5](https://typescriptlang.org)
+- [Tailwind CSS 4](https://tailwindcss.com)
+- [React Flow (@xyflow/react)](https://reactflow.dev) -- Org chart
+- [OpenAI SDK](https://github.com/openai/openai-node) -- Gateway client (routed to Claude via OpenClaw)
+- [Vitest 4](https://vitest.dev) -- Test runner
+- [OpenClaw](https://openclaw.ai) -- AI gateway, agent runtime, vision pipeline
+
+---
+
+## Development
+
+See [CLAUDE.md](CLAUDE.md) for the full developer guide: architecture deep-dives, test patterns, common tasks, and contribution conventions.
+
+```bash
+npm run dev          # Start dev server (Turbopack, port 3000)
+npm test             # Run all tests via Vitest
+npx tsc --noEmit     # Type-check (expect 0 errors)
+npx next build       # Production build
+```
+
+---
+
+## Built by
+
+[John Rice](https://github.com/johnrice) with [Jarvis](https://openclaw.ai) (OpenClaw AI)
+
+---
+
+## License
+
+MIT