@euraika-labs/pan-ui 0.2.4 → 0.5.0

package/README.md

@@ -1,211 +1,234 @@
-# Pan by Euraika
+<p align="center">
+  <img src="docs/assets/pan-logo.svg" alt="Pan by Euraika" width="120" />
+</p>
 
-[![CI](https://github.com/Euraika-Labs/pan-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/Euraika-Labs/pan-ui/actions/workflows/ci.yml)
-[![CodeQL](https://github.com/Euraika-Labs/pan-ui/actions/workflows/codeql.yml/badge.svg)](https://github.com/Euraika-Labs/pan-ui/actions/workflows/codeql.yml)
-[![npm](https://img.shields.io/npm/v/@euraika-labs/pan-ui)](https://www.npmjs.com/package/@euraika-labs/pan-ui)
-[![Release](https://img.shields.io/github/v/release/Euraika-Labs/pan-ui?display_name=tag)](https://github.com/Euraika-Labs/pan-ui/releases)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+<h1 align="center">Pan by Euraika</h1>
 
-A self-hosted web interface for [Hermes Agent](https://github.com/NousResearch/hermes-agent) — the AI agent by Nous Research. Chat with your agent, manage skills from the skills.sh marketplace, control extensions and MCP integrations, inspect memory, and operate profiles — all from a single dashboard with live runtime awareness.
+<p align="center">
+  <strong>Beautiful WebUI for <a href="https://github.com/NousResearch/hermes-agent">Hermes Agent</a></strong>
+</p>
 
-![Pan chat with runtime tools](docs/assets/screenshots/chat-runtime.png)
+<p align="center">
+  <a href="https://www.npmjs.com/package/@euraika-labs/pan-ui"><img src="https://img.shields.io/npm/v/@euraika-labs/pan-ui" alt="npm" /></a>
+  <a href="https://github.com/Euraika-Labs/pan-ui/actions/workflows/ci.yml"><img src="https://github.com/Euraika-Labs/pan-ui/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/Euraika-Labs/pan-ui/actions/workflows/codeql.yml"><img src="https://github.com/Euraika-Labs/pan-ui/actions/workflows/codeql.yml/badge.svg" alt="CodeQL" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+</p>
 
-## Why Pan
+<p align="center">
+  <a href="#install">Install</a> •
+  <a href="#features">Features</a> •
+  <a href="#screenshots">Screenshots</a> •
+  <a href="#configuration">Configuration</a> •
+  <a href="#development">Development</a> •
+  <a href="CHANGELOG.md">Changelog</a>
+</p>
 
-Pan is not a generic chat wrapper. It exposes the full operational surface of a running Hermes Agent instance:
+---
 
-- **Chat with streaming** — SSE-based streaming connected to a real Hermes runtime, with tool timelines, approval cards, and artifact rendering
-- **Skills marketplace** — Browse 112+ installed skills across 27 categories, discover and install 268+ more from [skills.sh](https://skills.sh) with one click
-- **MCP integrations** — View installed MCP servers, their tools, health status, and diagnostics
-- **Persistent memory** — Inspect and edit both global (shared) and profile-scoped user/agent memory, with proper `§`-separated entry parsing
-- **Profile isolation** — Each profile is a full workspace boundary with its own sessions, skills, memory, API keys, and policy presets
-- **Runtime operations** — Approvals, run history, audit trails, telemetry, runtime health, and JSON/CSV exports
+Pan is a self-hosted web dashboard for [Hermes Agent](https://github.com/NousResearch/hermes-agent). Chat with your agent, manage skills from [skills.sh](https://skills.sh), control MCP integrations, inspect memory, and operate profiles — all from one place.
 
-## Screenshots
+![Pan chat with runtime tools](docs/assets/screenshots/chat-runtime.png)
 
-### Login
+## Install
 
-![Login screen](docs/assets/screenshots/login.png)
+### Prerequisites
 
-### Chat
+- [Node.js](https://nodejs.org/) 18+ installed
+- [Hermes Agent](https://github.com/NousResearch/hermes-agent) installed and configured (`~/.hermes`)
 
-Streaming chat connected to a live Hermes runtime. Session sidebar with search, pinning, and archiving. Tool timelines expand inline. Composer shows active model, mode, tools, and profile.
+### One command
 
-![Empty chat workspace](docs/assets/screenshots/chat-empty.png)
-
-![Active chat with runtime output](docs/assets/screenshots/chat-runtime.png)
+```bash
+npx @euraika-labs/pan-ui
+```
 
-### Skills — Installed
+A setup wizard runs on first launch to connect Pan to your Hermes instance. After setup, open [localhost:3199](http://localhost:3199).
 
-112 installed skills across 27 categories. Search by name, tag, or category. Each card shows source, tags, linked files count, and whether it's loaded in the current session.
+> **First time?** The wizard auto-detects your Hermes home directory, API server, and installed binary. Just press Enter through the defaults to get started.
 
-![Skills installed tab](docs/assets/screenshots/skills-installed.png)
+### Run in the background
 
-### Skills — Discover
+```bash
+npx @euraika-labs/pan-ui start --daemon  # Fork to background
+npx pan-ui status                        # Check if running
+npx pan-ui logs                          # Tail log output
+npx pan-ui stop                          # Stop the daemon
+```
 
-Browse and install skills from the skills.sh hub. Trust badges (Trusted / Official / Community), install counts, security audit results, and direct links to repos.
+### Run as a system service (Linux)
 
-![Skills discover tab](docs/assets/screenshots/skills-discover.png)
+```bash
+npx @euraika-labs/pan-ui service install   # Creates a systemd user service
+npx pan-ui service remove                  # Uninstall it
+```
 
-### Extensions & MCP
+The service starts on login and survives logout. Manage it with standard `systemctl --user` commands.
 
-Installed MCP servers with tool inventories, health badges, and capability toggles. Test connections and view diagnostics.
+### Update
 
-![Extensions page](docs/assets/screenshots/extensions.png)
+```bash
+npx @euraika-labs/pan-ui@latest
+```
 
-### Memory
+Your configuration in `~/.pan-ui/` is preserved across updates.
 
-Global memory (shared across profiles) displayed as read-only cards with a blue "shared" badge. Profile-scoped memory is editable. Entries are separated by `§` and counted correctly.
+## Features
 
-![Memory page](docs/assets/screenshots/memory.png)
+| Feature | Description |
+|---------|-------------|
+| **Chat** | SSE streaming connected to a live Hermes runtime, with tool timelines, approval cards, and artifact rendering |
+| **Sessions** | Unified session sidebar with source badges (CLI, Discord, Telegram, WhatsApp, …), source filtering, and cross-platform session resumption |
+| **Skills** | Browse installed skills, discover and install 268+ more from [skills.sh](https://skills.sh) |
+| **Extensions** | View MCP servers, their tools, health status, and diagnostics |
+| **Memory** | Inspect and edit global and profile-scoped agent memory |
+| **Profiles** | Isolated workspaces — each with its own sessions, skills, memory, and API keys |
+| **Operations** | Approvals, run history, audit trails, telemetry, health monitoring, and exports |
+| **Daemon** | Background process with PID management, log tailing, and systemd integration |
 
-### Profiles
+## Screenshots
 
-Profile-based workspace isolation. Each profile scopes sessions, skills, memory, extensions, and API keys. Policy presets (safe-chat, research, builder, full-power) control tool access and guardrails.
+<details>
+<summary><strong>Login</strong></summary>
 
-![Profiles page](docs/assets/screenshots/profiles.png)
+![Login screen](docs/assets/screenshots/login.png)
+</details>
 
-### Settings
+<details open>
+<summary><strong>Chat</strong></summary>
 
-Runtime status, health monitoring, model selection, run history, audit browser, telemetry, approvals, and MCP diagnostics.
+Streaming chat with session sidebar, tool timelines, and runtime-aware composer.
 
-![Settings page](docs/assets/screenshots/settings.png)
+![Empty chat workspace](docs/assets/screenshots/chat-empty.png)
+![Active chat with runtime output](docs/assets/screenshots/chat-runtime.png)
+</details>
 
-## Tech Stack
+<details>
+<summary><strong>Skills</strong></summary>
 
-| Layer | Technology |
-|-------|-----------| 
-| Framework | Next.js 15 (App Router) |
-| Language | TypeScript |
-| State | TanStack Query v5 |
-| Styling | Tailwind CSS 4 |
-| Testing | Vitest + Playwright |
-| Runtime | Node.js 20+ |
+Installed skills with search and category filters. Discover tab for the skills.sh hub.
 
-## Quick Start
+![Skills installed tab](docs/assets/screenshots/skills-installed.png)
+![Skills discover tab](docs/assets/screenshots/skills-discover.png)
+</details>
 
-### Via npx (recommended)
+<details>
+<summary><strong>Extensions & MCP</strong></summary>
 
-```bash
-npx @euraika-labs/pan-ui
-```
+![Extensions page](docs/assets/screenshots/extensions.png)
+</details>
 
-The setup wizard will guide you through connecting to your Hermes runtime on first launch.
+<details>
+<summary><strong>Memory</strong></summary>
 
-### From source
+![Memory page](docs/assets/screenshots/memory.png)
+</details>
 
-```bash
-# 1. Clone and install
-git clone https://github.com/Euraika-Labs/pan-ui.git
-cd pan-ui
-npm install
+<details>
+<summary><strong>Profiles</strong></summary>
 
-# 2. Start in dev mode (connects to local Hermes instance)
-npm run dev
+![Profiles page](docs/assets/screenshots/profiles.png)
+</details>
 
-# 3. Open in browser
-open http://localhost:3199
-```
+<details>
+<summary><strong>Settings</strong></summary>
 
-Default credentials: `admin` / `changeme`
+![Settings page](docs/assets/screenshots/settings.png)
+</details>
+
+## Configuration
+
+### CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `pan-ui` / `pan-ui start` | Start in foreground |
+| `pan-ui start --daemon` | Start in background |
+| `pan-ui start --port 8080` | Override port |
+| `pan-ui stop` | Stop daemon |
+| `pan-ui status` | Show running state |
+| `pan-ui logs` | Tail daemon logs |
+| `pan-ui setup` | Re-run setup wizard |
+| `pan-ui update` | Check for and install updates |
+| `pan-ui sync-hermes` | Update vendored Hermes to pinned version |
+| `pan-ui version` | Show current version |
+| `pan-ui service install` | Install systemd service |
+| `pan-ui service remove` | Remove systemd service |
+| `pan-ui help` | Show CLI usage |
 
 ### Environment Variables
 
+The setup wizard writes these to `.env.local`. You can also edit them directly or re-run `npx pan-ui setup`.
+
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `HERMES_MOCK_MODE` | `true` | Set `false` to connect to a real Hermes instance |
 | `HERMES_HOME` | `~/.hermes` | Hermes home directory |
 | `HERMES_API_BASE_URL` | `http://127.0.0.1:8642` | Hermes API endpoint |
-| `HERMES_API_KEY` | — | API key for Hermes (if configured) |
+| `HERMES_API_KEY` | — | API key (if Hermes requires one) |
 | `HERMES_WORKSPACE_USERNAME` | `admin` | Login username |
 | `HERMES_WORKSPACE_PASSWORD` | `changeme` | Login password |
-| `HERMES_WORKSPACE_SESSION_SECRET` | — | Cookie signing secret |
-| `PORT` | `3199` | Pan UI port |
+| `HERMES_WORKSPACE_SECRET` | *(auto-generated)* | Cookie signing secret |
+| `HERMES_MOCK_MODE` | `false` | Use mock data when runtime is unavailable |
+| `PORT` | `3199` | Server port |
 
-## Architecture
+### File Locations
 
-```
-┌─────────────────────────────────────────────────┐
-│                   Browser                        │
-│  Next.js App Router + TanStack Query + Tailwind  │
-└───────────────────────┬─────────────────────────┘
-                        │ fetch / SSE
-┌───────────────────────▼─────────────────────────┐
-│              Next.js API Routes                  │
-│  /api/chat/stream    /api/skills    /api/memory  │
-│  /api/profiles       /api/extensions  /api/runtime│
-└──────┬────────────────┬─────────────────────────┘
-       │                │
-       ▼                ▼
-┌──────────────┐  ┌──────────────────────────────┐
-│ Hermes API   │  │ Hermes Filesystem            │
-│ :8642        │  │ ~/.hermes/                   │
-│ OpenAI-compat│  │  ├─ profiles/                │
-│ SSE streaming│  │  ├─ skills/                  │
-└──────────────┘  │  ├─ memories/                │
-                  │  └─ state.db                 │
-                  └──────────────────────────────┘
-```
+| Path | Purpose |
+|------|---------|
+| `~/.pan-ui/pan-ui.pid` | Daemon PID file |
+| `~/.pan-ui/pan-ui.log` | Daemon log output |
+| `~/.config/systemd/user/pan-ui.service` | Systemd service unit (when installed) |
+| `.env.local` (in package dir) | Configuration from setup wizard |
 
-- **Chat streaming** bridges the Hermes OpenAI-compatible `/v1/chat/completions` SSE endpoint to Pan
-- **Skills** are read from `~/.hermes/skills/` with YAML frontmatter parsing; hub skills come from the skills.sh cache
-- **Sessions** are read from `state.db` (SQLite) via the Hermes filesystem
-- **Memory** reads/writes `USER.md` and `MEMORY.md` files at both global and profile scope
-- **Profiles** map to `~/.hermes/profiles/<name>/` directories, each with their own config, memories, sessions, and skills
+## How It Works
 
-## Project Structure
+Pan runs as a standalone Next.js server that bridges your browser to the Hermes runtime. On startup it **automatically launches the Hermes gateway** if it isn't already running — no manual gateway setup required.
 
 ```
-src/
-├── app/                  # Next.js routes and API endpoints
-│   ├── api/              # Server-side API routes
-│   │   ├── chat/         # Chat stream, sessions
-│   │   ├── skills/       # Skills CRUD, hub, categories
-│   │   ├── memory/       # User/agent memory, context inspector
-│   │   ├── profiles/     # Profile CRUD
-│   │   ├── extensions/   # MCP extensions
-│   │   └── runtime/      # Health, approvals, runs, export
-│   └── [page]/           # Client page routes
-├── features/             # UI feature modules
-│   ├── chat/             # Chat screen, composer, transcript, tools
-│   ├── skills/           # Skills browser, detail, hub cards
-│   ├── memory/           # Memory editor, context inspector
-│   ├── extensions/       # Extension cards, tool inventory
-│   ├── profiles/         # Profile management, switcher
-│   ├── sessions/         # Session sidebar, search
-│   └── settings/         # Runtime, health, audit, approvals, runs
-├── server/               # Server-side logic
-│   └── hermes/           # Hermes filesystem bridge
-├── components/           # Shared layout and UI components
-├── lib/                  # Types, schemas, stores, utilities
-└── styles/               # Global CSS and theme variables
-tests/
-├── unit/                 # Vitest unit tests
-└── e2e/                  # Playwright end-to-end tests
-docs/                     # Architecture, specs, and screenshots
+  Browser ──── fetch / SSE ────▶ Pan (Next.js API routes)
+                                    │             │
+                                    ▼             ▼
+                              Hermes Gateway   Hermes Filesystem
+                              :8642            ~/.hermes/
+                              (auto-managed)   (skills, memory, profiles, state.db)
+                                    │
+                                    ▼
+                              Hermes Agent sessions
+                              (tools, streaming, full agent capabilities)
 ```
 
-## Verification
+- **Gateway** — Pan's startup hook detects whether the Hermes gateway is reachable. If not, it spawns `hermes gateway run` as a child process with health monitoring and auto-restart. The gateway uses the active Hermes profile — no hardcoded names or paths.
+- **Vendored Hermes** — Pan pins a specific Hermes Agent version via `hermes.version.json`. On first launch, if no `hermes` binary is found, the setup wizard installs it from the [Euraika-Labs/hermes-agent](https://github.com/Euraika-Labs/hermes-agent) fork. Use `pan-ui sync-hermes` to update.
+- **Chat** streams through Hermes's OpenAI-compatible SSE endpoint
+- **Skills** are read from `~/.hermes/skills/` with YAML frontmatter parsing
+- **Memory** reads/writes `USER.md` and `MEMORY.md` at global and profile scope
+- **Profiles** map to `~/.hermes/profiles/<name>/` directories
+
+> **Already running a gateway?** Pan detects it and skips auto-launch. This works with systemd services, manual `hermes gateway run`, or any external process on the configured port.
+
+## Development
+
+Want to contribute or run from source? See [CONTRIBUTING.md](CONTRIBUTING.md) for full setup instructions.
 
 ```bash
-npm run lint          # ESLint
-npm run test          # Vitest unit tests
-npm run build         # Production build
-npm run test:e2e      # Playwright e2e (requires running dev server)
+git clone https://github.com/Euraika-Labs/pan-ui.git
+cd pan-ui
+npm install
+npm run dev
 ```
 
-## Security
-
-- CLI commands use an allowlist guard (`ALLOWED_COMMANDS`) before `execFileSync` — no arbitrary command injection
-- Profile isolation ensures each workspace boundary has its own sessions, memory, and API keys
-- CodeQL scanning runs on every push and PR
-- File path parameters are sanitized to prevent directory traversal
-- Login is cookie-based with configurable credentials
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Dev server with hot reload |
+| `npm run build` | Production build |
+| `npm run lint` | ESLint |
+| `npm run test` | Vitest unit tests |
+| `npm run test:e2e` | Playwright end-to-end tests |
 
-## Contributing
+## Security
 
-Please read `CONTRIBUTING.md` before opening issues or pull requests.
+See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
 
 ## License
 
-MIT
+[MIT](LICENSE) © [Euraika Labs](https://github.com/Euraika-Labs)