docs: update documentation for new CLI structure

- Update README.md with new multica command examples
- Update CLAUDE.md common commands section
- Document all subcommands and their usage

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CLAUDE.md

@@ -22,18 +22,24 @@ Super Multica is a distributed AI agent framework with a monorepo architecture.
 # Install dependencies
 pnpm install
 
-# Development (all services concurrently: gateway:3000, console, web:3001)
-pnpm dev
+# Multica CLI (unified entry point)
+multica                   # Interactive mode (default)
+multica run "<prompt>"    # Run a single prompt
+multica chat              # Interactive REPL mode
+multica session list      # List sessions
+multica profile list      # List profiles
+multica skills list       # List skills
+multica tools list        # List tools
+multica credentials init  # Initialize credentials
+multica dev               # Start all dev services
+multica help              # Show help
 
-# Individual services
-pnpm dev:gateway          # WebSocket gateway only
-pnpm dev:console          # NestJS console with agent
-pnpm dev:web              # Next.js web app
-pnpm dev:desktop          # Electron desktop app
-
-# Agent CLI
-pnpm agent:cli            # Non-interactive agent
-pnpm agent:interactive    # Interactive REPL mode
+# Development servers
+multica dev               # All services (gateway:3000, console:4000, web:3001)
+multica dev gateway       # WebSocket gateway only
+multica dev console       # NestJS console with agent
+multica dev web           # Next.js web app
+multica dev desktop       # Electron desktop app
 
 # Build (turbo-orchestrated)
 pnpm build
@@ -57,7 +63,7 @@ Frontend (web:3001 / desktop)
         → Agent Engine (LLM runner, sessions, skills, tools)
 ```
 
-**Agent Engine** (`src/agent/`): Orchestrates LLM interactions with multi-provider support (OpenAI, Anthropic, DeepSeek, Kimi, Groq, Mistral, Google, Together). Features session management (JSONL-based, UUIDv7 IDs), profile system (`~/.super-multica/agent-profiles/`), modular skills with hot-reload, and token-aware context window guards (compaction modes: tokens, count, summary). CLI tools are organized in `src/agent/cli/` (interactive, non-interactive, profile, skills, tools).
+**Agent Engine** (`src/agent/`): Orchestrates LLM interactions with multi-provider support (OpenAI, Anthropic, DeepSeek, Kimi, Groq, Mistral, Google, Together). Features session management (JSONL-based, UUIDv7 IDs), profile system (`~/.super-multica/agent-profiles/`), modular skills with hot-reload, and token-aware context window guards (compaction modes: tokens, count, summary). Unified CLI in `src/agent/cli/index.ts` with subcommands in `src/agent/cli/commands/`.
 
 **Gateway** (`src/gateway/`): NestJS WebSocket server with Socket.io for real-time message passing, RPC request/response, and streaming.
 
@@ -82,7 +88,7 @@ Frontend (web:3001 / desktop)
 Use JSON5 credential files instead of `.env`:
 
 ```bash
-pnpm credentials:cli init
+multica credentials init
 ```
 
 This creates:

README.md

@@ -42,7 +42,7 @@ The Agent reads credentials from JSON5 files (no `.env` required).
 Create empty templates:
 
 ```bash
-pnpm credentials:cli init
+multica credentials init
 ```
 
 This creates:
@@ -85,9 +85,9 @@ Example `skills.env.json5` (dynamic keys):
 Start services directly (no `source .env`):
 
 ```bash
-pnpm dev:console
-pnpm agent:cli "hello"
-pnpm dev:gateway
+multica dev console
+multica run "hello"
+multica dev gateway
 ```
 
 Optional overrides:
@@ -104,32 +104,52 @@ Each setting is resolved in order (first match wins):
 3. **Session metadata** — restored from previous session
 4. **Default** — `kimi-coding` provider with `kimi-k2-thinking` model
 
-## Agent CLI
+## Multica CLI
 
-Use the agent module directly from the CLI for isolated testing.
+The unified CLI provides access to all agent features through a single command.
 
 ```bash
-# New sessions get a UUIDv7 ID (shown on start)
-pnpm agent:cli "hello"
-# [session: 019c0b0a-b111-765c-8bbd-f4149beac9c4]
+# Interactive mode (default)
+multica
+multica chat
+multica chat --profile my-agent
+
+# Run a single prompt
+multica run "hello"
+multica run --session demo "remember my name is Alice"
+
+# Session management
+multica session list
+multica session show abc12345
+multica session delete abc12345
 
 # Continue a session
-pnpm agent:cli --session 019c0b0a-b111-765c-8bbd-f4149beac9c4 "what did I say?"
-
-# Or use a custom session name
-pnpm agent:cli --session demo "remember my name is Alice"
-pnpm agent:cli --session demo "what's my name?"
+multica --session abc12345
+multica run --session abc12345 "what did I say?"
 
 # Override provider/model
-pnpm agent:cli --provider openai --model gpt-4o-mini "hi"
+multica run --provider openai --model gpt-4o-mini "hi"
 
 # Use an agent profile
-pnpm agent:cli --profile my-agent "hello"
+multica chat --profile my-agent
 
 # Set thinking level
-pnpm agent:cli --thinking high "solve this complex problem"
+multica run --thinking high "solve this complex problem"
+
+# Development servers
+multica dev                # Start all services
+multica dev gateway        # Gateway only (:3000)
+multica dev console        # Console only (:4000)
+multica dev web            # Web app only (:3001)
+
+# Help
+multica help
+multica run --help
+multica session --help
 ```
 
+Short alias: `mu` (same as `multica`)
+
 ## Sessions
 
 Sessions persist conversation history to `~/.super-multica/sessions/<id>/`. Each session includes:
@@ -156,16 +176,19 @@ Agent profiles define identity, personality, tools, and memory for an agent. Pro
 
 ```bash
 # Create a new profile with default templates
-pnpm agent:profile new my-agent
+multica profile new my-agent
 
 # List all profiles
-pnpm agent:profile list
+multica profile list
 
 # Show profile contents
-pnpm agent:profile show my-agent
+multica profile show my-agent
 
 # Open profile directory in file manager
-pnpm agent:profile edit my-agent
+multica profile edit my-agent
+
+# Delete a profile
+multica profile delete my-agent
 ```
 
 ### Profile Structure
@@ -194,17 +217,20 @@ Skills are modular capabilities that extend agent functionality through `SKILL.m
 
 ```bash
 # List all skills
-pnpm skills:cli list
+multica skills list
 
 # Install skills from GitHub
-pnpm skills:cli add anthropics/skills
+multica skills add anthropics/skills
 
 # Check skill status with diagnostics
-pnpm skills:cli status
-pnpm skills:cli status pdf -v
+multica skills status
+multica skills status pdf -v
+
+# Install skill dependencies
+multica skills install nano-pdf
 
 # Remove installed skills
-pnpm skills:cli remove skills
+multica skills remove skills
 ```
 
 ### Built-in Skills
@@ -320,22 +346,31 @@ The Hub manages multiple agents and gateway connections:
 
 ## Scripts
 
-### Agent Commands
+### Multica CLI Commands
 
-- `pnpm agent:cli` - Run the agent CLI for module-level testing
-- `pnpm agent:interactive` - Interactive REPL mode
-- `pnpm agent:profile` - Manage agent profiles
+- `multica` / `mu` - Unified CLI entry point
+- `multica run <prompt>` - Run a single prompt
+- `multica chat` - Interactive REPL mode
+- `multica session <cmd>` - Session management
+- `multica profile <cmd>` - Profile management
+- `multica skills <cmd>` - Skills management
+- `multica tools <cmd>` - Tool policy inspection
+- `multica credentials <cmd>` - Credentials management
+- `multica dev [service]` - Development servers
+- `multica help` - Show help
 
-### Development
+### Development (shortcuts)
 
-- `pnpm dev` - Run full stack in development mode
+- `pnpm dev` - Run full stack (gateway + console + web)
 - `pnpm dev:gateway` - Run gateway only
 - `pnpm dev:console` - Run console only
 - `pnpm dev:web` - Run web app only
+- `pnpm dev:desktop` - Run desktop app
 
 ### Build & Test
 
 - `pnpm build` - Build for production
 - `pnpm build:sdk` - Build SDK package
+- `pnpm build:cli` - Build CLI binary
 - `pnpm start` - Run production build
 - `pnpm typecheck` - Type check without emitting