wispy-cli 2.7.4 → 2.7.5

package/README.md

@@ -1,571 +1,486 @@
-# 🌿 Wispy CLI
+# Wispy CLI
 
-> Your personal AI assistant — chat, automate, and orchestrate from the terminal.
+Wispy CLI is a terminal-first AI workspace assistant for operators who want one place to chat, delegate, automate, audit, remember, and hand work across local and remote sessions.
 
-[![npm version](https://img.shields.io/npm/v/wispy-cli.svg)](https://www.npmjs.com/package/wispy-cli)
-[![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+Version `2.7.4` centers the product around an interactive workflow: onboarding, setup, and operator-facing commands guide you through menus instead of dropping you into brittle flag-heavy flows. The chat stack combines a REPL, a six-view TUI workspace, long-term memory, sub-agent orchestration, MCP, multi-channel messaging, scheduling, and a trust model built for real execution.
 
-Wispy is a powerful terminal AI assistant that talks to your files, runs commands, orchestrates sub-agents, sends messages to Telegram/Discord/Slack, and remembers things across sessions — all from a single `wispy` command.
+## Highlights
 
-## ✨ Features
+| Area | What ships in v2.7.4 |
+| --- | --- |
+| Model access | 29 AI providers across hosted, aggregator, OAuth, and local/self-hosted routes, including Google, Anthropic, OpenAI, Groq, DeepSeek, Ollama, OpenRouter, Mistral, Cohere, Perplexity, Together, Fireworks, Replicate, Anyscale, and GitHub Copilot |
+| Auth | API key flows plus OAuth-based auth, including GitHub Copilot support introduced in `v2.6.0` |
+| Interaction | Interactive command flows since `v2.7.0`; no-arg command entry routes into menus instead of dead-ending |
+| Terminal UX | REPL with autocomplete and inline preview hints, plus shell completion auto-installed during setup |
+| TUI | Multi-panel workspace OS with 6 views: `chat`, `overview`, `agents`, `memory`, `audit`, `settings` |
+| Trust | `careful`, `balanced`, `yolo`, dry-run previews, receipts, approval prompts, permissions, audit trail, replay |
+| Continuity | `where`, `handoff`, `sync` for local/remote awareness and state transfer |
+| Memory | `remember`, `recall`, `forget`, `memories` plus persistent memory files |
+| Skills | `teach`, `improve`, skill loading, reusable learned workflows |
+| Orchestration | Agents, sub-agents, pipeline-style delegation, MCP integration, 18+ built-in tools |
+| Channels | Telegram, Discord, Slack, WhatsApp, Signal, Email |
+| Scheduling | Cron-based task scheduling with persisted jobs and history |
+| Quality | Test suite passing: `91/91` |
 
-- 💬 **Interactive REPL + TUI** — chat mode, slash commands, streaming responses
-- 🤖 **7 AI providers** — Gemini, Claude, OpenAI, Groq, DeepSeek, Ollama, OpenRouter
-- 🔧 **18+ built-in tools** — files, shell commands, git, web search, and more
-- 🔌 **MCP server integration** — connect any Model Context Protocol server
-- 📱 **Multi-channel bot** — Telegram, Discord, Slack with session isolation
-- 🧠 **Long-term memory** — persistent facts, daily logs, project notes
-- ⏰ **Cron scheduler** — scheduled tasks with channel delivery
-- 🤝 **Sub-agent orchestration** — spawn parallel agents, steer them, collect results
-- 📂 **Workstream isolation** — separate contexts per project
+## Installation
 
----
+### Requirements
+
+| Requirement | Version |
+| --- | --- |
+| Node.js | `>= 18` |
+| Package manager | `npm` |
 
-## 🚀 Quick Start
+### Install globally
 
 ```bash
-# Install globally
 npm install -g wispy-cli
+```
 
-# Set your API key (any of these)
-export GOOGLE_AI_KEY=your_key          # Gemini (recommended, has free tier)
-export ANTHROPIC_API_KEY=your_key      # Claude
-export OPENAI_API_KEY=your_key         # OpenAI / GPT
+### Run
 
-# Start chatting
+```bash
 wispy
 ```
 
-Wispy auto-detects your API key and starts the REPL immediately.
+On first run, Wispy launches guided setup, helps configure a provider, and installs shell completion automatically for supported shells.
 
----
+## Quick Start
 
-## 📦 Installation
+### Start the main REPL
 
-### Requirements
-- **Node.js >= 18** (ESM modules required)
-
-### Global install
 ```bash
-npm install -g wispy-cli
+wispy
 ```
 
-### Local install
+### Send a one-shot message
+
 ```bash
-npm install wispy-cli
-npx wispy
+wispy "Summarize the current repository and suggest next steps."
 ```
 
----
+### Open a specific workstream
 
-## 🗣️ Chat Modes
-
-### REPL (default)
 ```bash
-wispy                    # start interactive chat
-wispy -w myproject       # start in a specific workstream
-wispy --session my-ses   # resume a named session
+wispy -w infra
 ```
 
-**REPL slash commands:**
-```
-/help         — show all slash commands
-/clear        — reset conversation history
-/sessions     — list recent sessions
-/memory       — show memory files
-/tools        — list available tools
-/model        — show current AI model
-/workstream   — show active workstream
-/exit         — exit Wispy
-```
+### Launch the full terminal UI
 
-### TUI (Ink-based)
 ```bash
-wispy-tui                # full terminal UI with scrollable history
-wispy-tui -w myproject   # workstream-specific TUI
+wispy-tui
 ```
 
-### One-shot (non-interactive)
-```bash
-wispy ask "What files are in the current directory?"
-wispy exec "summarize README.md"
-```
+### Check current execution context
 
-### Overview
 ```bash
-wispy overview           # show all workstreams and recent activity
+wispy where
 ```
 
----
+### Inspect configuration
 
-## 🤖 AI Providers
-
-Wispy detects your configured provider automatically. Priority order:
-
-| Provider | Env Var | Default Model |
-|----------|---------|---------------|
-| **Google AI** (Gemini) | `GOOGLE_AI_KEY` or `GEMINI_API_KEY` | `gemini-2.5-flash` |
-| **Anthropic** (Claude) | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
-| **OpenAI** | `OPENAI_API_KEY` | `gpt-4o` |
-| **OpenRouter** | `OPENROUTER_API_KEY` | `anthropic/claude-sonnet-4` |
-| **Groq** | `GROQ_API_KEY` | `llama-3.3-70b-versatile` |
-| **DeepSeek** | `DEEPSEEK_API_KEY` | `deepseek-chat` |
-| **Ollama** (local) | `OLLAMA_HOST` | `llama3.2` |
-
-### Override provider
 ```bash
-WISPY_PROVIDER=anthropic wispy
-WISPY_MODEL=claude-3-5-haiku wispy
+wispy config show
+wispy config get provider
+wispy config set provider openai
+wispy config delete apiKey
+wispy config reset
+wispy config path
+wispy config edit
 ```
 
-### Config file
-```json
-// ~/.wispy/config.json
-{
-  "provider": "google",
-  "model": "gemini-2.5-flash",
-  "apiKey": "optional-if-not-in-env"
-}
-```
+## Provider Support
 
----
+Wispy v2.7.4 is positioned as a multi-provider workspace client with support spanning hosted APIs, local runtimes, aggregators, and OAuth-backed access.
 
-## 🔧 Built-in Tools
+| Category | Examples |
+| --- | --- |
+| Hosted frontier APIs | Google, Anthropic, OpenAI, xAI, Mistral, Cohere, Perplexity |
+| Fast and cost-focused | Groq, DeepSeek, Together, Fireworks, Replicate, Anyscale |
+| Aggregators and gateways | OpenRouter, Vercel AI Gateway |
+| Regional and specialist providers | Kimi, MiniMax, Z.AI/GLM, DashScope, Volcengine, BytePlus, Xiaomi |
+| Local and self-hosted | Ollama, vLLM, SGLang, LiteLLM |
+| OAuth-backed access | GitHub Copilot |
 
-Wispy gives the AI access to these tools automatically:
+### Authentication
 
-| Tool | Description |
-|------|-------------|
-| `read_file` | Read any file's contents |
-| `write_file` | Write or create files |
-| `file_edit` | Edit files with find-and-replace |
-| `file_search` | Search files with regex (like grep) |
-| `list_directory` | List directory contents |
-| `run_command` | Execute shell commands |
-| `git_status` / `git_diff` / `git_log` | Git operations |
-| `web_search` | Search the web |
-| `memory_save` | Save facts to persistent memory |
-| `memory_get` | Retrieve a memory by key |
-| `memory_search` | Full-text search across all memories |
-| `memory_list` | List all memory files |
-| `memory_append` | Append to a memory file |
-| `memory_delete` | Delete a memory file |
-| `spawn_subagent` | Launch a parallel sub-agent |
-| `list_subagents` | List running sub-agents |
-| `get_subagent_result` | Get a sub-agent's result |
-| `kill_subagent` | Cancel a sub-agent |
+| Mode | Notes |
+| --- | --- |
+| API keys | Standard provider key flow |
+| OAuth | Device flow support, including GitHub Copilot |
+| Local runtimes | Host/base URL driven for local inference stacks |
 
----
+Examples:
 
-## 📱 Channel Setup
-
-Run Wispy as a multi-platform bot that responds to messages in Telegram, Discord, or Slack.
-
-### Start the bot server
 ```bash
-wispy channels start              # start all configured channels
-wispy channels start --telegram   # start only Telegram
+export GOOGLE_AI_KEY=...
+wispy
 ```
 
-### Telegram
-1. Create a bot via [@BotFather](https://t.me/BotFather)
-2. Copy the bot token
-3. Configure:
 ```bash
-# Option 1: env var
-export WISPY_TELEGRAM_TOKEN=your_bot_token
-
-# Option 2: config file
-# ~/.wispy/channels.json
-{
-  "telegram": {
-    "enabled": true,
-    "token": "your_bot_token"
-  }
-}
+wispy auth github-copilot
+wispy
 ```
 
-### Discord
-1. Create a bot at [discord.com/developers](https://discord.com/developers/applications)
-2. Install peer dependency: `npm install -g discord.js`
-3. Configure:
-```json
-{
-  "discord": {
-    "enabled": true,
-    "token": "your_discord_token",
-    "clientId": "your_client_id",
-    "guildId": "optional_guild_id"
-  }
-}
+```bash
+export OLLAMA_HOST=http://localhost:11434
+wispy
 ```
 
-### Slack
-1. Create a Slack app at [api.slack.com](https://api.slack.com/apps)
-2. Install peer dependency: `npm install -g @slack/bolt`
-3. Configure:
-```json
-{
-  "slack": {
-    "enabled": true,
-    "botToken": "xoxb-your-token",
-    "appToken": "xapp-your-token",
-    "signingSecret": "your-signing-secret"
-  }
-}
-```
+## Interfaces
 
-Each chat/user gets an isolated session — Wispy remembers context per conversation.
+### REPL
 
----
+The default `wispy` interface is a conversational REPL with:
 
-## 🧠 Memory System
+- slash commands
+- command autocomplete
+- inline preview hints
+- one-shot and persistent workstream usage
+- token and cost visibility
 
-Wispy has a file-based long-term memory stored in `~/.wispy/memory/`.
+Examples:
 
-### Using memory in chat
-Just ask Wispy to remember things:
-```
-You: Remember that my project uses TypeScript and Next.js 15
-Wispy: Got it! I'll remember that. 🌿
+```bash
+wispy
+wispy -w product
+wispy "Search this repo for sync-related code paths."
 ```
 
-Or use memory tools explicitly:
-```
-You: Save this to memory: the deployment command is `vercel --prod`
-```
+### TUI Workspace OS
 
-### Memory structure
-```
-~/.wispy/memory/
-├── MEMORY.md           — main persistent memory (auto-included in every chat)
-├── user.md             — user preferences
-├── daily/
-│   └── 2026-04-03.md  — daily logs
-└── projects/
-    └── myapp.md        — project-specific notes
-```
+`wispy-tui` is a multi-panel terminal workspace with six built-in views.
 
-### Memory CLI
-```bash
-wispy memory list                    # list all memory files
-wispy memory get MEMORY              # show main memory
-wispy memory save user "I prefer TypeScript"
-wispy memory search "deployment"     # full-text search
-wispy memory delete daily/old-date
-```
+| View | Purpose |
+| --- | --- |
+| `chat` | Main conversation and tool execution surface |
+| `overview` | Cross-workstream status and recent activity |
+| `agents` | Running and recent agent/sub-agent activity |
+| `memory` | Search and inspect persistent memories |
+| `audit` | Execution timeline, approvals, and receipts |
+| `settings` | Model, provider, and runtime status surface |
+
+## Trust and Execution Model
 
----
+Wispy is built around trustworthy execution rather than blind automation.
 
-## ⏰ Cron Scheduler
+| Capability | Description |
+| --- | --- |
+| Trust modes | `careful`, `balanced`, `yolo` |
+| Dry-run | Preview actions before execution |
+| Receipts | Inspect recent execution details |
+| Approval prompts | Human-in-the-loop confirmation for sensitive actions |
+| Audit trail | Persisted audit log and replayable session history |
+| Permissions | Per-tool policy visibility and overrides |
 
-Schedule tasks to run automatically and optionally deliver results to a channel.
+Examples:
 
-### Add a scheduled job
 ```bash
-# Every morning briefing
-wispy cron add \
-  --name "Morning Briefing" \
-  --schedule "0 9 * * *" \
-  --task "Summarize my pending tasks and give me a morning overview" \
-  --channel "telegram:YOUR_CHAT_ID"
-
-# Every 30 minutes
-wispy cron add \
-  --name "Price Check" \
-  --schedule every:1800000 \
-  --task "Check the current price of BTC and ETH"
-
-# One-shot at specific time
-wispy cron add \
-  --name "Reminder" \
-  --schedule "at:2026-12-31T09:00:00Z" \
-  --task "Remind me it's New Year's Eve!"
+wispy trust
+wispy trust level careful
+wispy trust log --today
+wispy trust receipt <session-id>
+wispy trust replay <session-id>
 ```
 
-### Schedule formats
-| Format | Example | Description |
-|--------|---------|-------------|
-| Cron expression | `0 9 * * *` | Standard 5-field cron (daily at 9am) |
-| Interval | `every:1800000` | Every N milliseconds (30 min) |
-| One-shot | `at:2026-12-31T09:00:00Z` | Specific ISO timestamp |
+## Continuity
 
-### Manage jobs
-```bash
-wispy cron list           # list all jobs
-wispy cron run <id>       # run a job immediately
-wispy cron remove <id>    # delete a job
-wispy cron history <id>   # view execution history
-```
+Wispy keeps workspace state portable across local and remote environments.
+
+| Command | Purpose |
+| --- | --- |
+| `where` | Show current mode, provider, workstream, sync, memory, and session context |
+| `handoff` | Push or pull state and generate a handoff summary |
+| `sync` | Sync sessions, memory, workstreams, cron metadata, and permissions |
+
+Examples:
 
-### Start the scheduler
 ```bash
-wispy cron start          # start the cron scheduler daemon
+wispy where
+wispy handoff cloud
+wispy handoff local
+wispy sync
 ```
 
----
+## Memory, Skills, and Agents
 
-## 🤝 Sub-agents
+### Memory
 
-Delegate complex tasks to parallel sub-agents and collect results.
+Wispy stores long-term memory under `~/.wispy/memory/` and exposes both natural-language and command-driven memory operations.
 
-### From chat
-```
-You: Spawn a sub-agent to analyze all TypeScript files in src/ and report issues
-Wispy: Spawning sub-agent 'code-review'... 🌿
-```
+| Command | Purpose |
+| --- | --- |
+| `remember` | Save something important |
+| `recall` | Search memories |
+| `memories` | List saved memories |
+| `forget` | Remove a memory |
 
-### Sub-agent tools (available to Wispy in chat)
-- `spawn_subagent` — start a sub-agent with a task
-- `list_subagents` — see all active/recent sub-agents
-- `get_subagent_result` — wait for and retrieve results
-- `kill_subagent` — cancel a running sub-agent
-- `steer_subagent` — send mid-task guidance
+Examples:
 
-### Sub-agent lifecycle
-```
-pending → running → completed
-                 ↘ failed
-                 ↘ killed
-                 ↘ timeout
+```text
+/remember The staging server runs on port 8090.
+/recall staging server
+/memories
+/forget old-note
 ```
 
-Sub-agent results persist to `~/.wispy/subagents/` for later retrieval.
-
----
-
-## 🔌 MCP Integration
-
-Connect any [Model Context Protocol](https://modelcontextprotocol.io) server and Wispy will automatically use its tools.
-
-### Configuration
-```json
-// ~/.wispy/mcp.json
-{
-  "servers": {
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
-    },
-    "github": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": { "GITHUB_TOKEN": "your_token" }
-    }
-  }
-}
-```
+### Skills
+
+Skills turn successful workflows into reusable commands.
+
+| Command | Purpose |
+| --- | --- |
+| `skills` | List learned skills |
+| `teach` | Create a skill from recent conversation context |
+| `improve` | Refine an existing skill |
+
+Examples:
 
-### MCP CLI
 ```bash
-wispy mcp list         # list configured servers
-wispy mcp status       # show connected servers and their tools
-wispy mcp add          # interactive server setup
+wispy skill
+wispy teach release-checklist
+wispy improve release-checklist "Make it verify cron and channel health."
 ```
 
----
+### Agents and sub-agents
 
-## ⚙️ Configuration
+Wispy supports delegated execution through agent and sub-agent orchestration.
 
-All configuration lives in `~/.wispy/`:
+| Capability | Description |
+| --- | --- |
+| Agent listing | Inspect active and recent workers |
+| Agent detail | Pull status and results |
+| Agent termination | Kill a running task |
+| Parallel delegation | Spawn task-specific workers |
+| Pipelines | Chain role-based execution stages |
 
-```
-~/.wispy/
-├── config.json         — main config (provider, model, apiKey)
-├── channels.json       — channel bot configuration
-├── mcp.json            — MCP server configuration
-├── sessions/           — conversation history
-├── memory/             — long-term memory files
-├── cron/               — scheduler jobs and history
-├── subagents/          — sub-agent results
-└── audit/              — audit log (JSONL per day)
-```
+Examples:
 
-### config.json reference
-```json
-{
-  "provider": "google",           // auto-detected if omitted
-  "model": "gemini-2.5-flash",   // defaults to provider's default
-  "apiKey": "...",                // env var takes precedence
-  "workstream": "default"         // default workstream
-}
+```text
+/agents
+/agent agent-123
+/kill agent-123
 ```
 
-### Environment variables
-```bash
-WISPY_PROVIDER=google           # force provider
-WISPY_MODEL=gemini-2.5-flash    # force model
-WISPY_WORKSTREAM=myproject      # set active workstream
-WISPY_DEBUG=1                   # enable debug output
-```
-
----
+## MCP and Built-in Tools
 
-## 📂 Workstream Isolation
+Wispy can merge Model Context Protocol tools with its own built-in tool registry.
 
-Workstreams let you maintain separate AI contexts for different projects.
+### MCP
 
 ```bash
-wispy -w frontend       # chat in "frontend" workstream
-wispy -w backend        # completely separate context
-wispy overview          # see all workstreams
+wispy mcp
+wispy mcp list
+wispy mcp connect
+wispy mcp disconnect
+wispy mcp reload
+wispy mcp config
 ```
 
-Each workstream has its own:
-- Conversation sessions
-- Context/memory scope
-- Sub-agent history
+### Built-in tools
 
----
+Wispy ships with 18+ built-in tools across file operations, shell execution, git, web access, memory, planning, and delegation.
 
-## 🏗️ Architecture
+| Tool family | Examples |
+| --- | --- |
+| Files | `read_file`, `write_file`, `file_edit`, `file_search`, `list_directory` |
+| Execution | `run_command`, `git`, `web_search`, `web_fetch` |
+| System | `keychain`, `clipboard` |
+| Planning | `update_plan`, `pipeline`, `ralph_loop` |
+| Agents | `spawn_agent`, `spawn_async_agent`, `spawn_subagent`, `list_agents`, `list_subagents`, `get_agent_result`, `get_subagent_result`, `kill_subagent` |
 
-```
-                         ┌─────────────────────────────┐
-                         │         WispyEngine          │
-                         │   core/engine.mjs            │
-                         │   processMessage() ─────────┐│
-                         └─────────────────────────────┘│
-                                     │                  │
-          ┌──────────────────────────┼──────────┐       │
-          │              │           │          │       │
-    REPL          TUI          channels    server.mjs   │
- (bin/wispy)  (bin/wispy-tui) (lib/channels/)          │
-                                                        │
-                              ┌─────────────────────────┘
-                              │
-          ┌───────────────────┼──────────────────────────┐
-          │                   │                          │
-   ProviderRegistry    ToolRegistry              SessionManager
-   core/providers.mjs  core/tools.mjs            core/session.mjs
-   (Gemini/Claude/     (18+ built-in +            (file-based,
-    OpenAI/Groq/        MCP tools)                per-channel)
-    DeepSeek/Ollama/
-    OpenRouter)
-          │
-          └── MemoryManager     CronManager     SubAgentManager
-              core/memory.mjs   core/cron.mjs   core/subagents.mjs
-              (~/.wispy/        (~/.wispy/       (~/.wispy/
-               memory/)          cron/)           subagents/)
-```
+## Channels and Scheduling
 
-All surfaces (REPL, TUI, channels) call `WispyEngine.processMessage()` — one core, many interfaces.
+### Messaging channels
 
----
+| Channel | Status in repo |
+| --- | --- |
+| Telegram | Built-in adapter |
+| Discord | Built-in adapter |
+| Slack | Built-in adapter |
+| WhatsApp | Built-in adapter |
+| Signal | Built-in adapter |
+| Email | Built-in adapter |
 
-## 🛠️ Development
+Example setup paths:
 
 ```bash
-# Clone
-git clone https://github.com/mindsurf0176-ui/poropo-workspace
-cd wispy-cli
+wispy channel setup telegram
+wispy channel setup discord
+wispy channel setup slack
+```
 
-# Install
-npm install
+### Cron scheduler
 
-# Run tests (91 integration tests)
-npm test
+Use Wispy as an operator that wakes itself up and delivers work on schedule.
 
-# Development REPL
-node bin/wispy.mjs
-```
-
-### Running tests
 ```bash
-npm test                    # run all integration tests
-npm run test:verbose        # run with spec reporter
-npm run test:basic          # run basic smoke tests only
-```
-
-### Project structure
-```
+wispy cron add
+wispy cron list
+wispy cron run <job-id>
+wispy cron remove <job-id>
+wispy cron history <job-id>
+wispy cron start
+```
+
+## Slash Commands
+
+The shared command registry powers REPL completion, the TUI command palette, and shell completion.
+
+### By category
+
+| Category | Commands |
+| --- | --- |
+| Workstream | `/ws`, `/ws new <name>`, `/ws <name>`, `/ws status`, `/ws search <query>`, `/ws archive <name>`, `/ws delete <name>` |
+| Trust | `/trust`, `/trust <level>`, `/trust log`, `/dry`, `/receipt`, `/replay`, `/permissions`, `/permit <tool> <level>`, `/audit` |
+| Continuity | `/where`, `/handoff`, `/sync` |
+| Skills | `/skills`, `/teach <name>`, `/improve <name>` |
+| Session | `/clear`, `/model`, `/cost`, `/compact`, `/sessions`, `/history` |
+| Memory | `/remember <text>`, `/recall <query>`, `/memories`, `/forget <key>` |
+| Agents | `/agents`, `/agent <id>`, `/kill <id>` |
+| MCP | `/mcp`, `/mcp list`, `/mcp connect`, `/mcp disconnect`, `/mcp reload`, `/mcp config` |
+| Quick aliases | `/o`, `/w`, `/a`, `/m`, `/t`, `/s`, `/d` |
+| Meta | `/help`, `/quit`, `/exit`, `/provider`, `/overview`, `/search <keyword>` |
+
+### Full scan list
+
+```text
+/ws
+/trust
+/dry
+/receipt
+/replay
+/where
+/handoff
+/sync
+/skills
+/teach
+/improve
+/clear
+/model
+/cost
+/compact
+/sessions
+/history
+/remember
+/recall
+/memories
+/forget
+/agents
+/agent
+/kill
+/mcp
+/permissions
+/permit
+/audit
+/o
+/w
+/a
+/m
+/t
+/s
+/d
+/help
+/quit
+/exit
+/provider
+/overview
+/search
+```
+
+## Architecture
+
+The repository is organized around two entrypoints, a core runtime, user-facing command modules, channel adapters, and a focused test suite.
+
+```text
 wispy-cli/
 ├── bin/
-│   ├── wispy.mjs           — main CLI entry point
-│   └── wispy-tui.mjs       — TUI entry point (Ink)
+│   ├── wispy.mjs
+│   ├── wispy-tui.mjs
 ├── core/
-│   ├── engine.mjs          — WispyEngine (main chat loop)
-│   ├── session.mjs         — SessionManager
-│   ├── providers.mjs       — ProviderRegistry (7 AI providers)
-│   ├── tools.mjs           — ToolRegistry (18+ built-in tools)
-│   ├── memory.mjs          — MemoryManager
-│   ├── cron.mjs            — CronManager (scheduler)
-│   ├── subagents.mjs       — SubAgentManager
-│   ├── mcp.mjs             — MCP client/manager
-│   ├── config.mjs          — config loader + provider detection
-│   └── index.mjs           — public API exports
+│   ├── engine.mjs
+│   ├── providers.mjs
+│   ├── auth.mjs
+│   ├── config.mjs
+│   ├── permissions.mjs
+│   ├── audit.mjs
+│   ├── session.mjs
+│   ├── memory.mjs
+│   ├── skills.mjs
+│   ├── subagents.mjs
+│   ├── mcp.mjs
+│   ├── cron.mjs
+│   ├── sync.mjs
+│   ├── onboarding.mjs
+│   └── ...
 ├── lib/
-│   ├── wispy-repl.mjs      — REPL implementation
-│   ├── wispy-tui.mjs       — TUI implementation (Ink/React)
-│   └── channels/
-│       ├── index.mjs       — ChannelManager
-│       ├── telegram.mjs    — Telegram adapter (grammY)
-│       ├── discord.mjs     — Discord adapter (discord.js)
-│       ├── slack.mjs       — Slack adapter (@slack/bolt)
-│       └── base.mjs        — ChannelAdapter base class
+│   ├── wispy-repl.mjs
+│   ├── wispy-tui.mjs
+│   ├── command-registry.mjs
+│   ├── channels/
+│   │   ├── index.mjs
+│   │   ├── telegram.mjs
+│   │   ├── discord.mjs
+│   │   ├── slack.mjs
+│   │   ├── whatsapp.mjs
+│   │   ├── signal.mjs
+│   │   ├── email.mjs
+│   │   └── base.mjs
+│   └── commands/
+│       ├── ws.mjs
+│       ├── trust.mjs
+│       ├── continuity.mjs
+│       ├── skills-cmd.mjs
+│       └── ws-interactive-enhancement.js
 └── tests/
+    ├── channels.test.mjs
     ├── core-engine.test.mjs
-    ├── core-session.test.mjs
+    ├── core-tools.test.mjs
     ├── core-memory.test.mjs
-    ├── core-cron.test.mjs
+    ├── core-session.test.mjs
     ├── core-subagents.test.mjs
-    ├── core-tools.test.mjs
-    └── channels.test.mjs
+    └── core-cron.test.mjs
 ```
 
----
+### Runtime flow
 
-## 📋 CLI Reference
+```text
+bin/wispy.mjs
+  -> lib/wispy-repl.mjs
+  -> core/engine.mjs
+     -> core/providers.mjs
+     -> core/tools.mjs
+     -> core/session.mjs
+     -> core/memory.mjs
+     -> core/subagents.mjs
+     -> core/mcp.mjs
+     -> core/audit.mjs
+     -> core/permissions.mjs
 
+bin/wispy-tui.mjs
+  -> lib/wispy-tui.mjs
+  -> core/engine.mjs
 ```
-Usage: wispy [options] [command]
-
-Commands:
-  wispy                    — start interactive REPL
-  wispy ask <message>      — one-shot chat
-  wispy exec <message>     — one-shot execution
-  wispy overview           — show workstream overview
-  wispy sessions           — list recent sessions
-  wispy memory <cmd>       — manage long-term memory
-  wispy cron <cmd>         — manage scheduled jobs
-  wispy channels <cmd>     — manage channel bots
-  wispy mcp <cmd>          — manage MCP servers
-  wispy server <cmd>       — start/stop HTTP/WS server
-  wispy audit <cmd>        — view audit log
-
-Options:
-  -w, --workstream <name>   — set active workstream
-  --session <id>            — resume a specific session
-  --model <name>            — override AI model
-  --provider <name>         — override AI provider
-  --help                    — show help
-  --version                 — show version
-```
-
----
 
-## 🔑 API Keys
+## Development
 
-Get free/paid API keys from:
-- **Google AI (Gemini)** — [aistudio.google.com/apikey](https://aistudio.google.com/apikey) *(free tier available)*
-- **Anthropic (Claude)** — [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)
-- **OpenAI** — [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
-- **OpenRouter** — [openrouter.ai/keys](https://openrouter.ai/keys) *(free credits)*
-- **Groq** — [console.groq.com/keys](https://console.groq.com/keys) *(free tier)*
-- **DeepSeek** — [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys)
-- **Ollama** — [ollama.ai](https://ollama.ai) *(fully local, no key needed)*
+### Tests
 
----
+```bash
+npm test
+```
 
-## 📝 License
+Current status:
 
-MIT — see [LICENSE](LICENSE)
+| Metric | Value |
+| --- | --- |
+| Test suites | `8` |
+| Tests | `91` |
+| Passing | `91` |
+| Failing | `0` |
 
----
+## License
 
-## 🙌 Credits
+MIT
 
 Built by Minseo & Poropo 🫧
-
-*Wispy is a small ghost that lives in terminals — floating between code, files, and servers.*

package/bin/wispy-mjs

@@ -0,0 +1,3 @@
+case "ws":
+    if (args.length > 1 && !['start-client', 'run-debug'].includes(args[1])) {
+      console.error(`Error: Unrecognized option \${args[1]}`}

package/bin/wispy.mjs

@@ -7,10 +7,16 @@
 (async () => {
   const { fileURLToPath } = await import('url');
   const { dirname } = await import('path');
+  const { readFile } = await import('fs/promises');
   const baseDir = dirname(fileURLToPath(import.meta.url));
 
   const args = process.argv.slice(2);
 
+  if (args.includes('--help')) {
+    console.log(`\nWispy CLI Help:\n\nCommands:\n  ws      - Execute WebSocket operations\n  help    - Interactive help guide\n  --help  - Show this message\n  --version - Display version\n\n`);
+    process.exit(0);
+  }
+
   async function handleCommand(command) {
     const inquirer = (await import('inquirer')).default;
 
@@ -23,38 +29,95 @@
             name: 'selectedCommand',
             message: 'What would you like to do?',
             choices: [
-              { name: 'Run WebSocket command', value: 'ws' },
-              { name: 'Get help', value: 'help' },
-              { name: 'Exit', value: null }
+              { name: 'Run WebSocket command - Execute and debug WebSocket operations', value: 'ws' },
+              { name: 'Get help - Learn about available commands and usage', value: 'help' },
+              { name: 'Exit - Close the interactive prompt', value: null }
             ],
           }
         ]);
       } catch (error) {
-        if (error.isTtyError) {
-          console.error("Prompt couldn't be rendered in the current environment.");
-        } else {
-          console.log("Prompt closed by the user. Exiting gracefully.");
-        }
+        console.error("TTY Prompt failed. Need help? Run 'node bin/wispy.mjs --help'. Restarting interactivity...");
         process.exit(0);
       }
       command = answers.selectedCommand;
     }
 
     switch (command) {
+      case "--version":
+        try {
+          const packageJson = JSON.parse(await readFile(`${baseDir}/../package.json`, 'utf8'));
+          console.log(`Wispy CLI version: ${packageJson.version}`);
+        } catch {
+          console.error('Failed to read version information from package.json.');
+        }
+        break;
       case "ws":
+        if (!args[1]) {
+          let subcommand;
+          try {
+            const { subcommand: chosenSubcommand } = await inquirer.prompt([
+              {
+                type: 'list',
+                name: 'subcommand',
+                message: 'Choose a WebSocket subcommand:',
+                choices: [
+                  { name: 'Start WebSocket Client', value: 'start-client' },
+                  { name: 'Run WebSocket Server Debug Mode', value: 'run-debug' }
+                ]
+              }
+            ]);
+            subcommand = chosenSubcommand;
+          } catch (error) {
+            console.error('Interactive prompt was cancelled or closed. Exiting gracefully.');
+            process.exit(0);
+          }
+          args[1] = subcommand;
+        } else if (!['start-client', 'run-debug'].includes(args[1])) {
+          console.error(`Error: Unrecognized argument '${args[1]}'.`);
+          const { retry } = await inquirer.prompt([
+            {
+              type: 'confirm',
+              name: 'retry',
+              message: 'Would you like to re-enter the WebSocket command?',
+              default: true,
+            }
+          ]);
+          if (retry) return await handleCommand('ws');
+          process.exit(1);
+        }
         const { handleWsCommand } = await import(baseDir + '/../lib/commands/ws.mjs');
         return await handleWsCommand(args);
       case "help":
-        console.log(`\nWispy CLI Help:\n\nCommands:\n  ws   - Run WebSocket command (e.g., 'node bin/wispy.mjs ws')\n  help - Show this help message (e.g., 'node bin/wispy.mjs --help')\n\nExamples:\n  $ node bin/wispy.mjs ws\n  $ node bin/wispy.mjs --help\n\nTip: Run 'node bin/wispy.mjs' with no arguments for an interactive prompt.\n`);
+        if (args.length > 1) {
+          console.error(`Invalid arguments provided for 'help': ${args.slice(1).join(' ')}\n`);
+          console.log(`Usage: node bin/wispy.mjs help\n\nAvailable Commands:\n  ws   - Run WebSocket command (debug operations)\n  help - Show this message\n\nTip: Run 'node bin/wispy.mjs' with no args for interactive guidance!\n`);
+        } else {
+          console.log(`\nWispy CLI Help:\n\nCommands:\n  ws  - Run WebSocket command (e.g., 'node bin/wispy.mjs ws')\n  help - Show this help message (e.g., 'node bin/wispy.mjs --help')\n  --version - Show the CLI version (e.g., 'node bin/wispy.mjs --version')\n\nExamples:\n  $ node bin/wispy.mjs ws\n  $ node bin/wispy.mjs --help\n  $ node bin/wispy.mjs --version\n\nTip: Use no args for full interactivity.\n`);
+        }
         break;
       case null:
         console.log("Goodbye!");
         break;
       default:
+        const { getCommandsWithSkills } = await import(baseDir + '/../lib/command-registry.mjs');
+        const validCommands = getCommandsWithSkills(null);
+        const prompt = (await import('inquirer')).default;
         console.error(`Unknown command: ${command}`);
-        console.log("Try one of the available commands: ws, help");
+        try {
+          const { choice } = await prompt.prompt([{
+            type: 'list',
+            name: 'choice',
+            message: 'Unknown command. Need help? Select a valid command:',
+            choices: validCommands.map(c => `${c.cmd} - ${c.desc}`),
+          }]);
+          const selectedCmd = choice.split(' ')[0];
+          console.log(`Executing '${selectedCmd}'...`);
+          await handleCommand(selectedCmd);
+        } catch (err) {
+          console.log('Prompt exited. No command executed. Goodbye!');
+        }
     }
   }
 
-  await handleCommand(args[0] === '--help' ? 'help' : args[0]);
+  await handleCommand(args[0]);
 })();

package/lib/commands/ws.mjs

@@ -1,32 +1,41 @@
 import { select } from '@inquirer/prompts';
 
-export async function handleWsCommand() {
-  try {
-    const action = await select({
-      message: 'What WebSocket action would you like to perform?',
-      choices: [
-        { name: 'Start WebSocket Client', value: 'startClient' },
-        { name: 'Run WebSocket Server Debug Mode', value: 'runServerDebug' },
-        { name: 'Exit', value: 'exit' }
-      ]
-    });
+export async function handleWsCommand(args = []) {
+    try {
+        if (args.length > 0 && !['startClient', 'runServerDebug'].includes(args[0])) {
+            console.error(`\nError: Invalid WebSocket subcommand '${args[0]}'.\n`);
+            console.log('Available subcommands:');
+            console.log('  startClient       Start WebSocket Client');
+            console.log('  runServerDebug    Run WebSocket Server Debug Mode');
+            console.log('\nTip: Use no arguments to enter interactive mode.\n');
+            return;
+        }
 
-    switch (action) {
-      case 'startClient':
-        console.log('Starting WebSocket client...');
-        break;
-      case 'runServerDebug':
-        console.log('Running server in debug mode...');
-        break;
-      case 'exit':
-        console.log('Exiting WebSocket command.');
-        return;
-    }
-  } catch (err) {
-    if (err.name === 'ExitPromptError') {
-      console.log('Prompt closed. Exiting command gracefully.');
-    } else {
-      console.error('Unexpected error:', err);
+        const action = args[0] || await select({
+            message: 'What WebSocket action would you like to perform?',
+            choices: [
+                { name: 'Start WebSocket Client', value: 'startClient' },
+                { name: 'Run WebSocket Server Debug Mode', value: 'runServerDebug' },
+                { name: 'Exit', value: 'exit' }
+            ]
+        });
+
+        switch (action) {
+            case 'startClient':
+                console.log('Starting WebSocket client...');
+                break;
+            case 'runServerDebug':
+                console.log('Running server in debug mode...');
+                break;
+            case 'exit':
+                console.log('Exiting WebSocket command.');
+                return;
+        }
+    } catch (err) {
+        if (err.name === 'ExitPromptError') {
+            console.log('Prompt closed. Exiting command gracefully.');
+        } else {
+            console.error('Unexpected error:', err);
+        }
     }
-  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wispy-cli",
-  "version": "2.7.4",
+  "version": "2.7.5",
   "description": "🌿 Wispy — AI workspace assistant with trustworthy execution (harness, receipts, approvals, diffs)",
   "license": "MIT",
   "author": "Minseo & Poropo",