docs: rewrite README with badges, features, download table, and quick-start

2026-04-27 12:09:15 -05:00
parent 7379c35a6b
commit fba5f3e2b3
1 changed files with 83 additions and 36 deletions
--- a/README.md
+++ b/README.md
@@ -1,31 +1,64 @@
-# Honcho UI
+<div align="center">
+  <img src="packages/web/public/favicon.svg" width="96" height="96" alt="OpenConcho" />
+  <h1>OpenConcho</h1>
+  <p>A fast, privacy-first desktop &amp; web UI for self-hosted <a href="https://github.com/plastic-labs/honcho">Honcho</a> instances.</p>

-A clean, fast frontend for browsing and chatting with a self-hosted [Honcho](https://github.com/plastic-labs/honcho) instance.
-
-> **Privacy-first**: all connection details (base URL, optional token) are stored locally in your browser — never sent anywhere except directly to your Honcho instance.
+  <p>
+    <a href="https://github.com/offendingcommit/openconcho/actions/workflows/ci.yml">
+      <img src="https://github.com/offendingcommit/openconcho/actions/workflows/ci.yml/badge.svg" alt="CI" />
+    </a>
+    <a href="https://github.com/offendingcommit/openconcho/releases/latest">
+      <img src="https://img.shields.io/github/v/release/offendingcommit/openconcho" alt="Latest release" />
+    </a>
+    <a href="https://github.com/offendingcommit/openconcho/releases/latest">
+      <img src="https://img.shields.io/github/downloads/offendingcommit/openconcho/total" alt="Downloads" />
+    </a>
+    <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue" alt="Platforms" />
+    <a href="LICENSE">
+      <img src="https://img.shields.io/github/license/offendingcommit/openconcho" alt="License" />
+    </a>
+  </p>
+</div>

 ---

+Browse memories, peers, sessions, and conclusions — or chat with full memory context — directly against your own Honcho instance. All connection details stay in your browser; nothing leaves except requests to the URL you configure.
+
 ## Features

- **Dashboard** — workspace count and queue status at a glance, auto-refreshes every 10 s
- **Workspaces** — paginated list with per-workspace navigation
- **Peers** — browse peers, view representations, context, and peer cards
- **Sessions** — paginated message history with summaries and context
- **Conclusions** — semantic search across conclusions with observer/subject display
- **Chat** — conversational interface that sends messages through Honcho's chat endpoint with memory context
- **Dark / light mode** — persisted per browser, instant toggle
- **Optional auth** — token field is optional; a connection health check auto-detects whether auth is required
+| | |
+|---|---|
+| **Dashboard** | Workspace count and queue status, auto-refreshes every 10 s |
+| **Workspaces** | Paginated list with per-workspace navigation |
+| **Peers** | Browse peers, view representations, context, and peer cards |
+| **Sessions** | Paginated message history with summaries and context |
+| **Conclusions** | Semantic search across conclusions with observer/subject display |
+| **Webhooks** | Manage and trigger webhooks per workspace |
+| **Chat** | Conversational interface through Honcho's chat endpoint with memory context |
+| **Schedule Dream** | Trigger Honcho's dream/consolidation pass on demand |
+| **Dark / light mode** | Persisted per device, instant toggle |
+| **Optional auth** | Token field is optional; connection health check auto-detects auth requirement |
+
+## Download
+
+Pre-built binaries are attached to every [GitHub Release](https://github.com/offendingcommit/openconcho/releases/latest):
+
+| Platform | File |
+|---|---|
+| macOS (Apple Silicon) | `OpenConcho_*_aarch64.dmg` |
+| macOS (Intel) | `OpenConcho_*_x64.dmg` |
+| Linux | `openconcho_*_amd64.deb` / `openconcho_*_amd64.AppImage` |
+| Windows | `OpenConcho_*_x64-setup.exe` / `OpenConcho_*_x64_en-US.msi` |

 ## Quick Start

 ### Prerequisites

- Node.js ≥ 20
- pnpm ≥ 9
- A running Honcho instance (local or remote)
+- [Node.js](https://nodejs.org/) ≥ 20
+- [pnpm](https://pnpm.io/) ≥ 9
+- A running [Honcho](https://github.com/plastic-labs/honcho) instance (local or remote)

-### Install & run
+### Web app

 ```bash
 git clone https://github.com/offendingcommit/openconcho.git
@@ -34,26 +67,38 @@ pnpm install
 pnpm dev
 ```

-Open http://localhost:5173 — you'll be prompted to enter your Honcho URL.
+Open http://localhost:5173 and enter your Honcho URL when prompted.

-### Connect to your instance
+### Desktop app (Tauri)
+
+Additional prerequisites: [Rust](https://rustup.rs/) stable + [Tauri system dependencies](https://v2.tauri.app/start/prerequisites/) for your OS.
+
+```bash
+git clone https://github.com/offendingcommit/openconcho.git
+cd openconcho
+pnpm install
+pnpm --filter @openconcho/desktop dev
+```
+
+### Connecting to your instance

 1. Enter the base URL of your Honcho instance (e.g. `http://localhost:8000`)
 2. Optionally enter an API token if your instance requires auth
-3. Click **Test connection** — the UI will tell you if auth is needed
+3. Click **Test connection** — the UI reports whether auth is needed
 4. Click **Save** — you're in

-### Build for production
+### Production build

 ```bash
-pnpm build
-# Output in dist/ — serve with any static host
+pnpm build                                    # web only → packages/web/dist/
+pnpm --filter @openconcho/desktop build       # desktop → packages/desktop/src-tauri/target/release/bundle/
 ```

 ## Stack

 | Layer | Library |
-|-------|---------|
+|---|---|
+| Desktop shell | [Tauri v2](https://v2.tauri.app/) |
 | Framework | React 19 + Vite 8 |
 | Routing | TanStack Router v1 (file-based) |
 | Data fetching | TanStack Query v5 |
@@ -61,36 +106,38 @@ pnpm build
 | Styling | Tailwind CSS v4 + CSS custom properties |
 | Animation | framer-motion |
 | Icons | lucide-react |
-| Lint / format | Biome |
-| Tests | Vitest + Testing Library |
+| Lint / format | Biome 2 |
+| Tests | Vitest 4 + Testing Library |
+| Releases | semantic-release (conventional commits) |

 ## Development

 ```bash
-pnpm dev          # dev server with HMR
+pnpm dev              # Vite dev server (web, http://localhost:5173)
+pnpm test             # Vitest test suite
 pnpm lint:fix         # Biome lint + format
-pnpm test         # run tests
-pnpm generate:api # regenerate src/api/schema.d.ts from openapi.json
+pnpm typecheck        # TypeScript strict check
+pnpm generate:api     # Regenerate src/api/schema.d.ts from openapi.json
 ```

-## Regenerating API types
+### Regenerating API types

-If your Honcho instance is updated, grab a fresh `openapi.json` and run:
+When your Honcho instance is updated, pull a fresh schema and regenerate:

 ```bash
-curl http://your-honcho-url/openapi.json -o openapi.json
-pnpm generate:api
+curl http://your-honcho-url/openapi.json -o packages/web/openapi.json
+pnpm --filter @openconcho/web generate:api
 ```

 ## Privacy

- Base URL and token are stored in `localStorage` under `openconcho:config`
- Theme preference is stored in `localStorage` under `openconcho:theme`
+- Base URL and token stored in `localStorage` under `openconcho:config`
+- Theme preference stored in `localStorage` under `openconcho:theme`
 - No telemetry, no analytics, no external requests beyond your configured Honcho instance

 ## Contributing

-Issues and PRs welcome. Open an issue first for significant changes.
+Open an issue first for significant changes. PRs welcome.

 ## License