From c8828f98537e3d242c7cc1e08f0dd982c82db1b5 Mon Sep 17 00:00:00 2001 From: cozy Date: Sat, 11 Apr 2026 01:24:22 -0400 Subject: [PATCH] docs: sync to v0.5.0 reality The docs were lagging the code. Most issues fall into three groups: 1. The new ch4p gui desktop app (apps/gui, shipped in v0.5.0) was undocumented. Added a row to the README "Three modes" table (now four), a Where-to-Start blurb in docs/index.md, and a new "GUI app" paragraph in docs/explanation/architecture.md so the six-layer stack reflects all three surfaces. 2. Stale version strings from when the project was on 0.1.x: - docs/reference/cli.md had "Version 0.1.0" in the status output example. - docs/tutorials/getting-started.md had "ch4p v0.1.3" in two example outputs. 3. Stale channel counts from when there were 14 channels: - docs/reference/cli.md, docs/tutorials/getting-started.md, and both explanation docs (concurrency.md, security-model.md) all said "14" or "14+" -- now 16. The getting-started enumeration was also missing Zalo Personal, macOS Native, and the local CLI; it now lists all 16. Plus a few internal-consistency fixes: - README.md test count line said "91 test files, 2642 tests"; the badge directly above already said 2711. Both now say "102 test files, 2711 tests" (the file count was also stale). - CONTRIBUTING.md required Node >= 22 but package.json engines say >= 20.0.0. Lowered to 20 to match. - CONTRIBUTING.md test command comment said "(2 449+)"; now (2711+). - SECURITY.md "Supported versions" table only listed 0.1.x. Now lists 0.5.x as supported and explicitly marks <0.5 as not supported, with a sentence explaining the policy (latest minor only). False positives caught during the audit (left as-is): - "claude-sonnet-4-6" in docs/how-to/use-routing.md is the correct current model id (see packages/providers/src/anthropic.ts:49), not a typo. --- CONTRIBUTING.md | 4 ++-- README.md | 5 +++-- SECURITY.md | 5 ++++- docs/explanation/architecture.md | 6 ++++-- docs/explanation/concurrency.md | 2 +- docs/explanation/security-model.md | 4 ++-- docs/index.md | 2 ++ docs/reference/cli.md | 4 ++-- docs/tutorials/getting-started.md | 6 +++--- 9 files changed, 23 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 21a4bdb..8b99035 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ Thanks for your interest in contributing! This guide covers everything you need ## Prerequisites -- **Node.js** ≥ 22 +- **Node.js** ≥ 20 - **corepack** enabled (`corepack enable`) - **pnpm** is managed via corepack — do not install it globally @@ -26,7 +26,7 @@ npx vitest run # verify all tests pass ```bash corepack pnpm -r build # build all packages -npx vitest run # run all tests (2 449+) +npx vitest run # run all tests (2711+) corepack pnpm lint # ESLint (0 errors required) corepack pnpm -r exec tsc --noEmit # typecheck corepack pnpm audit # 0 vulnerabilities required diff --git a/README.md b/README.md index f33ef8f..63c7e4a 100644 --- a/README.md +++ b/README.md @@ -66,12 +66,13 @@ Engine ─── native LLM · echo · CLI subprocess Provider ─── Anthropic · OpenAI · Google · OpenRouter · Ollama · Bedrock ``` -Three modes: +Four modes: | Mode | Command | Description | |------|---------|-------------| | **REPL** | `ch4p agent` | Interactive chat with teal-branded UI and optional `--voice` wake | | **Gateway** | `ch4p gateway` | Multi-channel server on port 18789 | +| **GUI** | `ch4p gui` | Desktop graphical interface — auto-starts the gateway, native chat, live terminal, themed config UI (port 4810) | | **Canvas** | `ch4p canvas` | Spatial browser workspace with infinite tldraw canvas | Every subsystem is a trait interface — swap any component via config, zero code changes. @@ -191,7 +192,7 @@ corepack pnpm --filter @ch4p/core build # Build single package - TypeScript strict mode, ES2023 target, NodeNext module resolution - ESM-only (all imports use `.js` extension) - Zero required external runtime dependencies for core, security, and CLI -- 91 test files, 2642 tests, 0 vulnerabilities +- 102 test files, 2711 tests, 0 vulnerabilities ## Configuration diff --git a/SECURITY.md b/SECURITY.md index c44f467..105abdb 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,9 +2,12 @@ ## Supported versions +Only the latest minor release receives security fixes. Older versions are not patched — upgrade if you are running anything below the row marked **Yes**. + | Version | Supported | |---------|-----------| -| 0.1.x | Yes | +| 0.5.x | Yes | +| < 0.5 | No | ## Reporting a vulnerability diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md index 7721203..3487539 100644 --- a/docs/explanation/architecture.md +++ b/docs/explanation/architecture.md @@ -10,7 +10,7 @@ ch4p separates concerns into six layers. Each layer has a single job, talks only ``` ┌─────────────────────────────────────────────────────────────────┐ -│ Channels (CLI, Telegram, Discord, …) Canvas (tldraw, A2UI) │ ← Surface +│ Channels (CLI, Telegram, Discord, …) GUI app Canvas (A2UI) │ ← Surface ├─────────────────────────────────────────────────────────────────┤ │ Gateway (HTTP server, WS upgrade, session routing) │ ← Routing ├─────────────────────────────────────────────────────────────────┤ @@ -26,7 +26,9 @@ ch4p separates concerns into six layers. Each layer has a single job, talks only ### Channels (Surface) -Channels are the user-facing endpoints. Each channel implements the IChannel interface: receive messages from a platform, normalize them into a common InboundMessage format, and send responses back. The CLI terminal, Telegram, Discord, Slack, Matrix, and 12 other adapters all sit here. So does the Canvas, which translates spatial interactions (button clicks, form submissions) into the same message format. +Channels are the user-facing endpoints. Each channel implements the IChannel interface: receive messages from a platform, normalize them into a common InboundMessage format, and send responses back. The CLI terminal, Telegram, Discord, Slack, Matrix, and 11 other adapters all sit here. So does the Canvas, which translates spatial interactions (button clicks, form submissions) into the same message format. + +The GUI app (`apps/gui`, launched with `ch4p gui`) is a separate surface that lives alongside the channels rather than inside them. It is a desktop application: a React client built by Vite, a small Node server built by tsup, and a shared protocol layer between them. When the user runs `ch4p gui`, the CLI loads the GUI server bundle, which boots the gateway in-process, auto-pairs against it, and then opens a browser to the local UI on port 4810. The chat in the GUI talks to the agent through the same gateway routes the messaging channels use, so anything you can do over Telegram you can also do in the GUI without a separate code path. Channels know nothing about LLMs, tools, or memory. They convert platform-specific I/O into a common shape and hand it to the gateway. diff --git a/docs/explanation/concurrency.md b/docs/explanation/concurrency.md index 907f65e..8bf1763 100644 --- a/docs/explanation/concurrency.md +++ b/docs/explanation/concurrency.md @@ -6,7 +6,7 @@ This document explains why ch4p uses BEAM-inspired concurrency patterns, what pr ## The Problem -A personal AI assistant connected to 14+ messaging channels has a concurrency problem that most Node.js applications do not face. +A personal AI assistant connected to 16 messaging channels has a concurrency problem that most Node.js applications do not face. Consider what happens when messages arrive from Telegram, Discord, and Slack simultaneously. Each message triggers a conversation with an LLM that may involve multiple tool calls. Each tool call may read files, run commands, or query memory. Some of these operations are fast (memory lookup), some are slow (LLM completion), and some are unpredictable (shell commands). diff --git a/docs/explanation/security-model.md b/docs/explanation/security-model.md index a8cc7e6..7e41259 100644 --- a/docs/explanation/security-model.md +++ b/docs/explanation/security-model.md @@ -10,7 +10,7 @@ Most developer tools treat security as opt-in. You install the tool, everything This is not a philosophical preference. It is a response to a specific risk profile. -An AI assistant that can read files, execute commands, and broadcast to messaging channels is, by construction, a remote code execution engine with a natural language interface. If the defaults are permissive, a single prompt injection through any of 14+ messaging channels could read your SSH keys, execute arbitrary commands, and exfiltrate the results through the same channel. The attack surface is the union of every connected messaging platform's attack surface. +An AI assistant that can read files, execute commands, and broadcast to messaging channels is, by construction, a remote code execution engine with a natural language interface. If the defaults are permissive, a single prompt injection through any of 16 messaging channels could read your SSH keys, execute arbitrary commands, and exfiltrate the results through the same channel. The attack surface is the union of every connected messaging platform's attack surface. Starting locked and opening selectively means the blast radius of any single failure is bounded by what you have explicitly allowed. @@ -92,7 +92,7 @@ No data moves between trust domains without passing through a guard. This is not A traditional CLI tool has one input surface: the terminal. The user is the only person who can send input. There is inherent trust in a single-user, single-input system. -ch4p is fundamentally different. It has 14+ input surfaces, each accessible by different people, each with different authentication models, each operated by a different platform with its own vulnerabilities. A Telegram bot is accessible to anyone who discovers its username. A Discord bot is accessible to anyone in the server. A Slack bot is accessible to anyone in the workspace. +ch4p is fundamentally different. It has 16 input surfaces, each accessible by different people, each with different authentication models, each operated by a different platform with its own vulnerabilities. A Telegram bot is accessible to anyone who discovers its username. A Discord bot is accessible to anyone in the server. A Slack bot is accessible to anyone in the workspace. Each of these surfaces is a potential entry point for: diff --git a/docs/index.md b/docs/index.md index f5276ad..188626c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,6 +10,8 @@ Built in TypeScript on Node.js, ch4p combines BEAM-inspired concurrency, a zero- **New to ch4p?** Begin with the [Getting Started tutorial](tutorials/getting-started.md). You will install ch4p, run the onboard wizard, send your first message, and watch a tool execute — all in about ten minutes. +**Prefer a desktop app?** Run `ch4p gui` to launch the graphical interface — a native chat window with live terminal, themed configuration UI, and an auto-started gateway underneath. It bundles every CLI capability in a desktop surface and runs on port 4810. + **Want a visual workspace?** Run `ch4p canvas` to launch the interactive canvas — a browser-based spatial workspace where the agent renders cards, charts, forms, and more on an infinite tldraw canvas. See the [Use Canvas](how-to/use-canvas.md) guide. **Want to connect a channel?** The [First Channel tutorial](tutorials/first-channel.md) walks you through wiring up Telegram. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index f29cd4f..9ca67f2 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -60,7 +60,7 @@ The wizard adapts to your environment. If CLI engines (Claude Code, Codex, Ollam 4. **Autonomy level** — read-only, supervised, or full 5. **Additional features** — ~20 individually skippable categories in 4 groups: - **Providers** — Google/Gemini, OpenRouter, AWS Bedrock - - **Channels** — multi-select from 14 messaging channels with per-channel config + - **Channels** — multi-select from 16 messaging channels with per-channel config - **Services** — web search, browser, voice STT/TTS, MCP servers, cron jobs - **System** — memory, verification, gateway, security, commands, tunnel, canvas, observability, skills 6. **Save** — writes config and runs a security audit @@ -222,7 +222,7 @@ ch4p status --memory ch4p Status ──────────────────────────────────────────────────── - Version 0.1.0 + Version 0.5.0 Config ~/.ch4p/config.json Data dir ~/.ch4p Provider anthropic diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md index a5350af..6dbfcae 100644 --- a/docs/tutorials/getting-started.md +++ b/docs/tutorials/getting-started.md @@ -29,7 +29,7 @@ node apps/cli/dist/index.js --version You should see output like: ``` -ch4p v0.1.3 +ch4p v0.5.0 ``` --- @@ -81,7 +81,7 @@ You'll see the ch4p welcome banner, then the wizard walks you through setup. The **If you answer Yes** to "Additional Features," the wizard expands into ~20 individually skippable categories organized into four groups: - **Providers** — Google/Gemini, OpenRouter, AWS Bedrock API keys -- **Channels** — multi-select from 14 messaging channels (Telegram, Discord, Slack, Matrix, Teams, WhatsApp, Signal, iMessage, IRC, Zalo OA, BlueBubbles, Google Chat, WebChat, Zalo Personal) with per-channel token prompts +- **Channels** — multi-select from 16 messaging channels (Telegram, Discord, Slack, Matrix, Teams, WhatsApp, Signal, iMessage, IRC, Zalo OA, Zalo Personal, BlueBubbles, Google Chat, WebChat, macOS Native, plus the local CLI) with per-channel token prompts - **Services** — web search (Brave API), browser (Playwright), voice STT/TTS, MCP servers, cron jobs - **System** — memory backend, verification, gateway port, security, allowed commands, tunnel, canvas, observability, skills @@ -102,7 +102,7 @@ node apps/cli/dist/index.js agent You'll see the ch4p splash followed by the REPL status: ``` - ch4p v0.1.3 ready. + ch4p v0.5.0 ready. Interactive mode. Type /help for commands, /exit to quit. Engine: Native Engine | Model: claude-sonnet-4-20250514 | Autonomy: supervised