cli-jaw 2.0.5 → 2.0.6

package/README.md

@@ -1,8 +1,8 @@
-<div align="center">
+<div align=”center”>
 
 # CLI-JAW
 
-### Stop juggling AI coding tools. Use all of them at once.
+### Your personal AI agent. 2 lines to install. 7 AI engines in one dashboard.
 
 [![npm](https://img.shields.io/npm/v/cli-jaw)](https://npmjs.com/package/cli-jaw)
 [![Version](https://img.shields.io/badge/v2.0.0-GA-brightgreen)](https://github.com/lidge-jun/cli-jaw/releases)
@@ -13,168 +13,88 @@
 
 **English** / [한국어](README.ko.md) / [中文](README.zh-CN.md) / [日本語](README.ja.md)
 
-![CLI-JAW Manager Dashboard](docs/screenshots/manager-dashboard-light.png)
-
 </div>
 
----
-
-## What is CLI-JAW?
-
-CLI-JAW is an open-source platform that unifies every AI coding CLI you already use — Claude, Codex, Gemini CLI, OpenCode, Copilot CLI — into one assistant with one memory and one dashboard. Your main CLI calls the others as "employees" (sub-agents), so you stop copy-pasting between heavy apps and start giving orders from a single place.
-
-It routes through the subscriptions you already pay for. No per-token API billing. No rate limits on top of what you already have.
-
-One developer is managing 100k+ lines of code with this thing. It's basically a super-app: multi-instance manager + mini-Obsidian notes + Kanban board + browser automation, running locally on your machine.
-
----
-
-## What's New in 2.0.0
-
-This is the general availability release. Here's what landed:
+## Install
 
-| Feature | What it means |
-|---|---|
-| **Manager Dashboard** | A super-app control plane. See every running JAW instance, start/stop/restart them, preview live Web UIs, inspect settings — all from one browser tab |
-| **Notes Workspace** | A mini-Obsidian baked into the dashboard. Folders, rename/move, split editor+preview, KaTeX math, Mermaid diagrams, syntax-highlighted code blocks |
-| **Kanban Board** | Drag running instances into lanes. Card editor for tracking what each instance is working on |
-| **Employee System** | Your main CLI dispatches other CLIs as workers. "Fix the frontend" goes to OpenCode. "Update the API" goes to Codex. You approve the results |
-| **Responsive Mobile Layout** | Sidebar overlay, touch-friendly controls. Manage your fleet from your phone |
-
-Plus: explicit PABCD orchestration (`/orchestrate`, `/pabcd`, `/continue`), 230+ reference skills, SQLite FTS5 memory search, cron/every heartbeat jobs, and Computer Use desktop automation.
-
----
-
-## Recent Architecture Updates
-
-| Area | Update |
-|---|---|
-| **PABCD** | Worklog resume is explicit: use `/continue`. Natural language “continue” stays a normal prompt |
-| **Gemini CLI** | Full-access Gemini runs use `--skip-trust --approval-mode yolo` plus `--include-directories` for OS home access; WSL also includes the Windows user home when discoverable |
-| **Messaging** | `/api/channel/send` is the canonical Telegram/Discord outbound path; legacy channel-specific endpoints remain |
-| **Heartbeat** | Jobs support `every` and `cron` schedules with optional IANA time zones |
-| **Browser web-AI** | Runtime diagnostics/orphan cleanup, persistent tab lifecycle, session reattach, and ChatGPT/Gemini/Grok vendor paths are documented in `structure/` |
-| **Release gates** | `npm run gate:all` runs named release/doc parity checks when developing locally |
-
----
-
-## Two-Line Install
-
-Existing users who already manage Codex, Gemini, Claude, MCP servers, OfficeCLI, or other tools can run a safe update first. Safe install creates `~/.cli-jaw` only, skips optional tool/runtime setup, and lets you run `jaw init` later when you want interactive setup.
+<details>
+<summary><b>Safe install</b> — for existing users who want minimal changes</summary>
 
 ```bash
-# macOS/Linux safe update
-JAW_SAFE=1 npm install -g cli-jaw
-```
+# macOS / Linux
+JAW_SAFE=1 npm install -g cli-jaw    # skips optional tool/runtime setup
+jaw init                              # interactive setup later when you're ready
 
-```powershell
-# Windows PowerShell safe update
+# Windows PowerShell
 $env:JAW_SAFE="1"; npm install -g cli-jaw
+jaw init
 ```
 
-Normal install performs the full setup:
+</details>
 
 ```bash
 npm install -g cli-jaw
 jaw dashboard
 ```
 
-That's it. Open **http://localhost:3457**. Requires Node.js 22+.
+That's it. Open **http://localhost:3457** and you have a personal AI agent. Requires [Node.js 22+](https://nodejs.org).
 
-> `jaw serve` also works if you prefer the classic server mode.
->
-> Auto-start on boot: `jaw service install` (auto-detects systemd / launchd / Docker).
-
----
-
-## Platform Setup
+> **First time?** The installer automatically sets up Claude, Codex, Gemini, Copilot, and OpenCode CLIs for you. Just authenticate one of them (see [Authenticate](#authenticate)) and you're ready to go.
 
 <details>
-<summary><b>macOS</b> — one-click script</summary>
-
-1. Open **Terminal** (`Cmd + Space` → type `Terminal`)
-2. Paste and hit Enter:
+<summary><b>macOS one-click</b> — don't have Node.js? This installs everything</summary>
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/lidge-jun/cli-jaw/master/scripts/install.sh | bash
 ```
 
-3. Authenticate (see below) and launch:
-
-```bash
-jaw dashboard
-```
-
 </details>
 
 <details>
-<summary><b>Windows / WSL</b> — one-click script</summary>
-
-**Step 1: Install WSL** (PowerShell as Admin)
+<summary><b>Windows (WSL — Windows Subsystem for Linux)</b> — one-click from scratch</summary>
 
 ```powershell
+# 1. Install WSL (PowerShell as Admin)
 wsl --install
 ```
 
-Restart, then open **Ubuntu** from the Start Menu.
-
-**Step 2: Install CLI-JAW**
+Restart, open **Ubuntu**, then:
 
 ```bash
+# 2. Install CLI-JAW + all dependencies
 curl -fsSL https://raw.githubusercontent.com/lidge-jun/cli-jaw/master/scripts/install-wsl.sh | bash
-```
-
-**Step 3: Reload and start**
-
-```bash
 source ~/.bashrc
 jaw dashboard
 ```
 
-The installer uses the user-local npm prefix (`~/.local`) and writes
-`~/.local/bin` to both `~/.bashrc` and `~/.profile`, so new Ubuntu shells can
-find `jaw` and the bundled CLI tools.
-
-The WSL script is the integrated Linux setup path: it verifies `jaw --version`,
-requests bundled CLI tools in strict mode, installs OfficeCLI, and verifies
-`officecli --version` before reporting success. Browser support is checked after
-Chromium/Windows Chrome detection; if no runnable browser is found, the installer
-prints a warning instead of pretending web-ai/browser automation is fully ready.
+</details>
 
 <details>
-<summary>WSL Troubleshooting</summary>
+<summary><b>Docker</b></summary>
 
-| Problem | Fix |
-|---|---|
-| `unzip: command not found` | Rerun the installer |
-| `jaw: command not found` | Run `source ~/.bashrc` or `export PATH="$HOME/.local/bin:$PATH"` |
-| `officecli: command not found` | Rerun the WSL installer or `bash "$(npm root -g)/cli-jaw/scripts/install-officecli.sh"` |
-| Permission errors | `sudo chown -R $USER $(npm config get prefix)` |
+```bash
+docker compose up -d       # → http://localhost:3457
+```
 
-</details>
 </details>
 
-<details>
-<summary><b>Linux</b></summary>
+---
 
-You know what to do.
+## What is CLI-JAW?
 
-```bash
-npm install -g cli-jaw
-jaw dashboard
-```
+CLI-JAW is an open-source platform that unifies the AI coding CLIs you already use — Claude, Codex, Gemini, Grok, OpenCode, Copilot — into **one assistant with one memory and one dashboard**.
 
-Generic Linux `npm install -g cli-jaw` keeps optional helper installs
-best-effort for compatibility. Use the WSL one-click script when you want the
-stricter integrated setup guarantees, or verify manually with:
+Your main CLI (the “Boss”) calls the others as “employees.” You stop copy-pasting between apps and start giving orders from a single place.
 
-```bash
-jaw --version
-officecli --version
-jaw doctor
-```
+- **No API keys needed** — routes through subscriptions you already pay for
+- **No per-token billing** — flat monthly cost, same as what you already have
+- **Runs locally** — your code never leaves your machine
 
-</details>
+<div align=”center”>
+
+![CLI-JAW Manager Dashboard](docs/screenshots/manager-dashboard-light.png)
+
+</div>
 
 ---
 
@@ -183,7 +103,7 @@ jaw doctor
 You only need **one**. Pick whichever subscription you already have:
 
 ```bash
-# Free options
+# Free options (no credit card needed)
 copilot login        # GitHub Copilot (free tier available)
 opencode             # OpenCode — free models available
 
@@ -191,9 +111,10 @@ opencode             # OpenCode — free models available
 claude auth login    # Anthropic Claude Max
 codex login          # OpenAI ChatGPT Pro
 gemini               # Google Gemini Advanced
+grok login --oauth   # xAI Grok / Grok Heavy
 ```
 
-Check everything at once: `claude auth status && jaw doctor`
+Check everything at once: `jaw doctor`
 
 <details>
 <summary>Example jaw doctor output</summary>
@@ -209,7 +130,7 @@ Check everything at once: `claude auth status && jaw doctor`
  ✅ Copilot CLI     installed
  ✅ Database        jaw.db OK
  ✅ Skills          32 active, 194 reference
- ✅ MCP             3 servers configured
+ ✅ MCP (plugins)   3 servers configured
  ✅ Memory          structured/ exists
  ✅ Server          port 3457 available
 ```
@@ -220,37 +141,57 @@ Check everything at once: `claude auth status && jaw doctor`
 
 ## The Dashboard
 
-The dashboard is the main way to use CLI-JAW 2.0. It's a local web app that acts as command center for all your AI instances.
+The dashboard is your command center. It's a local web app at `http://localhost:3457`.
+
+### Instance Manager
+
+See every running AI instance — start, stop, restart with one click. Preview live Web UIs directly in the dashboard.
+
+<div align=”center”>
+
+![Dashboard Navigator](docs/screenshots/dashboard-navigator.png)
+
+</div>
+
+### Kanban Board
+
+Drag instance cards into lanes (Backlog → Ready → In Progress → Review → Done). Track what each AI session is working on.
+
+<div align=”center”>
+
+![Kanban Board](docs/screenshots/dashboard-kanban.png)
 
-### Instance Management
+</div>
+
+### Priority Matrix
 
-The navigator panel shows every JAW instance — running, stopped, or offline. For each one you can:
+Eisenhower matrix for your tasks and reminders. Prioritize what matters.
 
-- **Start / Stop / Restart** with one click
-- See the active CLI engine, model, port, and working directory
-- Use **perm mode** for persistent instances that survive reboots
-- Launch new instances pointed at different project directories
+<div align=”center”>
 
-### Live Preview
+![Priority Matrix](docs/screenshots/priority-matrix.png)
 
-Select any running instance and its Web UI embeds directly in the dashboard via a preview proxy. Chat with your AI, see streaming responses, drag-and-drop files — all without leaving the manager.
+</div>
 
 ### Notes
 
-A markdown vault lives inside the dashboard. Think mini-Obsidian:
+A mini-Obsidian inside the dashboard. Folders, visual (WYSIWYG) + raw + split editing, KaTeX (math rendering), Mermaid (diagram-as-code), syntax-highlighted code blocks.
 
-- Folder tree with create/rename/move/delete
-- Raw, split, and preview editing modes
-- Dirty-state markers so you don't lose unsaved work
-- KaTeX math rendering, Mermaid diagrams, syntax-highlighted code blocks
+<div align=”center”>
 
-### Kanban Board
+![Notes Editor](docs/screenshots/notes-wysiwyg.png)
+
+</div>
+
+### Agent Status
 
-Drag instance cards into lanes (Backlog / Ready / Active / Review / Done). Each card links to the live instance and has an editor for notes. Good for tracking what each AI session is working on when you're running multiple instances.
+Monitor each AI engine's health and usage at a glance.
 
-### Settings Inspector
+<div align=”center”>
 
-View and edit runtime settings for any selected instance: active CLI, model, reasoning effort, permission mode, working directory, employees, skills, MCP servers.
+![Claude Status](docs/screenshots/claude-status-widget.png)
+
+</div>
 
 ---
 
@@ -290,7 +231,7 @@ Use employees for "Frontend does CSS, Backend does API." Use sub-agents for "rea
 
 ---
 
-## Five AI Engines
+## AI Runtime Surfaces
 
 No per-token API billing. Route through subscriptions you already pay for.
 
@@ -298,21 +239,23 @@ No per-token API billing. Route through subscriptions you already pay for.
 |---|---|---|---|
 | **Claude** | `opus-4-6` | `claude auth login` | Claude Max subscription |
 | **Codex** | `gpt-5.5` | `codex login` | ChatGPT Pro subscription |
+| **Codex App** | `gpt-5.4` | `codex login` | ChatGPT Pro subscription |
 | **Gemini** | `gemini-3.1-pro-preview` | `gemini` | Gemini Advanced subscription |
+| **Grok** | `grok-build` | `grok login --oauth` | Grok subscription; quota is auth/status-only |
 | **OpenCode** | `minimax-m2.7` | `opencode` | Free models available |
 | **Copilot** | `gpt-5-mini` | `copilot login` | Free tier available |
 
 **Fallback chain**: if one engine is rate-limited, the next picks up. Configure with `/fallback [cli1 cli2...]`.
 
-**OpenCode wildcard**: connect any model endpoint — OpenRouter, local LLMs, any OpenAI-compatible API.
+**OpenCode wildcard**: connect any model endpoint — OpenRouter, local LLMs (Large Language Models), any OpenAI-compatible API.
 
 > Switch engines live: `/cli codex`. Switch models: `/model gpt-5.5`. Works from Web, Terminal, Telegram, or Discord.
 
 ---
 
-## PABCD Orchestration
+## PABCD Orchestration (Plan → Audit → Build → Check → Done)
 
-For complex tasks, CLI-JAW uses a 5-phase workflow. You approve every transition.
+For complex tasks, CLI-JAW uses a structured 5-phase workflow. You approve every transition — nothing ships without your OK.
 
 ```
 P (Plan) → A (Audit) → B (Build) → C (Check) → D (Done) → IDLE
@@ -327,7 +270,7 @@ P (Plan) → A (Audit) → B (Build) → C (Check) → D (Done) → IDLE
 | **C — Check** | Type-check (`tsc --noEmit`), docs update, consistency check |
 | **D — Done** | Summary of all changes. Returns to idle |
 
-State is DB-persisted and survives restarts. Workers cannot modify files — only verify. Activate with `jaw orchestrate`, `/orchestrate`, or `/pabcd`; resume an active worklog explicitly with `/continue`.
+State is database-persisted and survives restarts. Workers cannot modify files — only verify. Activate with `jaw orchestrate`, `/orchestrate`, or `/pabcd`; resume an active worklog explicitly with `/continue`.
 
 ---
 
@@ -339,7 +282,7 @@ Three layers, each covering a different recall horizon.
 |---|---|---|
 | **History Block** | Recent session context | Last 10 sessions, max 8000 chars, scoped to working directory. Injected at prompt start |
 | **Memory Flush** | Structured knowledge from conversations | Triggered after threshold (default 10 turns). Extracts episodes, daily logs, semantic notes as markdown |
-| **Soul + Task Snapshot** | Identity and semantic recall | Core values, tone, boundaries. FTS5 index returns up to 4 semantically relevant hits per prompt |
+| **Soul + Task Snapshot** | Identity and semantic recall | Core values, tone, boundaries. Full-text search index returns up to 4 semantically relevant hits per prompt |
 
 All three layers feed into the system prompt automatically. Memory is searchable:
 
@@ -355,8 +298,8 @@ jaw memory search "how did we set up the API auth?"
 
 | Category | Skills | What they cover |
 |---|---|---|
-| **Office** | `pdf`, `docx`, `xlsx`, `pptx`, `hwp` | Read, create, edit documents. Korean HWP/HWPX via OfficeCLI |
-| **Automation** | `browser`, `vision-click`, `screen-capture`, `desktop-control` | Chrome CDP, AI-powered coordinate click, macOS screenshots, Computer Use |
+| **Office** | `pdf`, `docx`, `xlsx`, `pptx`, `hwp` | Read, create, edit documents. HWP/HWPX (Korean word-processor formats) supported natively |
+| **Automation** | `browser`, `vision-click`, `screen-capture`, `desktop-control` | Chrome DevTools Protocol (CDP) browser control, AI-powered coordinate click, macOS screenshots, Computer Use |
 | **Media** | `video`, `imagegen`, `lecture-stt`, `tts` | Remotion video, OpenAI image generation, lecture transcription, text-to-speech |
 | **Integration** | `github`, `notion`, `telegram-send`, `memory` | Issues/PRs/CI, Notion pages, Telegram media delivery, persistent memory |
 | **Visualization** | `diagram` | SVG diagrams, charts, interactive visualizations rendered in chat |
@@ -375,9 +318,9 @@ jaw skill list              # see what's available
 
 | Capability | How it works |
 |---|---|
-| **Chrome CDP** | Navigate, click, type, screenshot, evaluate JS, scroll, press keys — full DevTools Protocol control |
+| **Chrome DevTools Protocol** | Navigate, click, type, screenshot, evaluate JS, scroll, press keys — remote control for Chrome |
 | **Vision-click** | Screenshot the screen → AI extracts target coordinates → clicks. `jaw browser vision-click "Login button"` |
-| **Computer Use** | Desktop app automation via Codex Computer Use MCP. Use Safari for localhost and it feels like the Codex app |
+| **Computer Use** | Desktop app automation via Codex Computer Use. Use Safari for localhost and it feels like the Codex app |
 | **Web-AI vendors** | `jaw browser web-ai --vendor chatgpt\|gemini\|grok` with session lifecycle, diagnostics, and source-audit/answer-artifact support where implemented |
 | **Diagram Skill** | Generate SVG diagrams and interactive visualizations, rendered inline in chat |
 
@@ -393,7 +336,7 @@ Computer Use lets you control any macOS app — Finder, Safari, System Settings,
 📱 Telegram ←→ 🦈 CLI-JAW ←→ 🤖 AI Engines
 ```
 
-Text chat, voice messages (auto-transcribed via multi-provider STT), file/photo upload, slash commands (`/cli`, `/model`, `/status`), scheduled task delivery via `every`/`cron` heartbeat jobs.
+Text chat, voice messages (auto-transcribed via STT — speech-to-text), file/photo upload, slash commands (`/cli`, `/model`, `/status`), scheduled task delivery via `every`/`cron` (recurring schedule) heartbeat jobs.
 
 <details>
 <summary>Setup (3 steps)</summary>
@@ -414,16 +357,16 @@ Voice input works on Web (mic button), Telegram (voice messages), and Discord. P
 
 ---
 
-## MCP
+## MCP (Model Context Protocol)
 
-[Model Context Protocol](https://modelcontextprotocol.io) lets AI agents use external tools. CLI-JAW manages MCP config for all five engines from one file.
+[MCP](https://modelcontextprotocol.io) is a standard that lets AI tools share capabilities — like plugins for AI agents. CLI-JAW manages MCP config for all your engines from one file.
 
 ```bash
 jaw mcp install @anthropic/context7
 # → syncs to Claude, Codex, Gemini, OpenCode, Copilot config files simultaneously
 ```
 
-No more editing five different JSON files. Install once, every engine gets it.
+No more editing several different JSON files. Install once, every MCP-aware engine gets it. Grok CLI is a standard runtime here, but it is not counted as MCP-sync capable until Grok exposes a compatible config surface.
 
 ```bash
 jaw mcp sync       # re-sync after manual edits
@@ -437,7 +380,7 @@ jaw mcp sync       # re-sync after manual edits
 # Core
 jaw dashboard                     # launch manager dashboard
 jaw serve                         # start server (http://localhost:3457)
-jaw chat                          # terminal TUI
+jaw chat                          # terminal chat UI
 jaw doctor                        # 12-point diagnostics
 
 # Instances
@@ -453,7 +396,7 @@ jaw orchestrate                   # enter/control PABCD workflow
 # Skills & MCP
 jaw skill install <name>          # activate a skill
 jaw skill list                    # list available skills
-jaw mcp install <package>         # install MCP → syncs to 5 engines
+jaw mcp install <package>         # install MCP → syncs supported MCP-aware engines
 jaw mcp sync                      # re-sync MCP configs
 
 # Memory
@@ -461,7 +404,8 @@ jaw memory search <query>         # search across all memory layers
 jaw memory save <file> <content>  # save to structured memory
 
 # Browser
-jaw browser start                 # launch Chrome (CDP)
+jaw browser start                 # launch Chrome automation
+jaw browser fetch "https://example.com" --json --trace  # adaptive URL reader
 jaw browser snapshot              # capture page state
 jaw browser vision-click "Login"  # AI-powered click
 
@@ -471,9 +415,7 @@ jaw reset                         # full reset
 
 ---
 
-## Multi-Instance & Docker
-
-### Multi-Instance
+## Multi-Instance
 
 Run isolated instances with separate settings, memory, and database:
 
@@ -484,31 +426,6 @@ jaw --home ~/my-project serve --port 3458
 
 Each instance is fully independent — different working directory, different memory, different MCP config. The manager dashboard sees them all.
 
-### Docker
-
-```bash
-docker compose up -d       # → http://localhost:3457
-```
-
-Non-root `jaw` user, Chromium sandbox enabled. Data persists in `jaw-data` named volume.
-
-<details>
-<summary>Docker details</summary>
-
-```bash
-# Dev build
-docker build -f Dockerfile.dev -t cli-jaw:dev .
-docker run -d -p 3457:3457 --env-file .env cli-jaw:dev
-
-# Pin version
-docker build --build-arg CLI_JAW_VERSION=2.0.0 -t cli-jaw:2.0.0 .
-
-# If Chromium sandbox fails
-docker run -e CHROME_NO_SANDBOX=1 -p 3457:3457 cli-jaw
-```
-
-</details>
-
 ---
 
 ## Development
@@ -528,17 +445,17 @@ Architecture details: [ARCHITECTURE.md](docs/ARCHITECTURE.md) · Test coverage:
 
 | | CLI-JAW 2.0 | Hermes Agent | Claude Code |
 |---|---|---|---|
-| **Model access** | 5 CLIs via OAuth (Claude Max, ChatGPT Pro, Copilot, Gemini) + OpenCode wildcard | API keys (OpenRouter 200+, Nous Portal) | Anthropic only |
+| **Model access** | Claude, Codex, Codex App, Gemini, Grok, OpenCode, and Copilot through vendor auth where supported | API keys (OpenRouter 200+, Nous Portal) | Anthropic only |
 | **Cost model** | Monthly subscriptions you already pay for | Per-token API billing | Anthropic subscription |
-| **Primary UI** | Manager dashboard + Web PWA + Mac app + TUI | TUI only | CLI + IDE plugins |
+| **Primary UI** | Manager dashboard + Web app + Mac app + terminal UI | Terminal only | CLI + IDE plugins |
 | **Dashboard** | Multi-instance manager, Kanban, Notes workspace | None | None |
 | **Messaging** | Telegram (voice) + Discord | Telegram/Discord/Slack/WhatsApp/Signal | None |
-| **Memory** | 3-layer (History/Flush/Soul) + SQLite FTS5 | Self-improving loop + Honcho | File-based auto-memory |
+| **Memory** | 3-layer (History/Flush/Soul) + full-text search | Self-improving loop + Honcho | File-based auto-memory |
 | **Multi-agent** | Employee system (dispatch other CLIs) + PABCD | Subagent spawn | Task tool |
-| **Browser automation** | Chrome CDP + vision-click + Computer Use | Limited | Via MCP |
+| **Browser automation** | Chrome DevTools + vision-click + Computer Use | Limited | Via MCP |
 | **Execution** | Local + Docker | Local/Docker/SSH/Daytona/Modal | Local |
 | **Skills** | 230+ bundled | Self-creating + agentskills.io | User-configured |
-| **i18n** | English, Korean, Chinese, Japanese | English | English |
+| **Languages** | English, Korean, Chinese, Japanese | English | English |
 
 ---