resolve-solo 0.3.0 → 0.5.0

package/README.md

@@ -1,42 +1,120 @@
 # Resolve Solo
 
-A local-first CLI on-call assistant for individual developers. Natural language investigation support with timeline analysis, incident recall, and reporting—all demo-grade with mock data.
+A local-first on-call assistant for individual developers. Natural language investigation support with timeline analysis, incident recall, and reporting—powered by demo data, ready for Claude Code integration.
 
-## Quick Start
+## Three Ways to Use Resolve Solo
+
+### 1. Claude Code Integration (Recommended)
 
-Try the demo with a single command:
+Talk naturally to Claude Code, and it automatically invokes resolve-solo when you need incident investigation:
 
 ```bash
-npx resolve-solo demo
+# One-time setup
+npm install -g resolve-solo
+resolveai setup
+
+# Then in Claude Code, just talk naturally:
+"investigate timeout issues in payment service"
+"what changed in the last hour?"
+"show me similar past incidents"
 ```
 
-This will:
-- Seed realistic demo data (incidents, deploys, logs, services)
-- Run an automated investigation
-- Show you what Resolve Solo can do
+**How it works**: Resolve Solo exposes MCP (Model Context Protocol) tools that Claude Code automatically discovers and uses when you ask incident-related questions.
 
-## Installation
+👉 See [CLAUDE_CODE_INTEGRATION.md](./CLAUDE_CODE_INTEGRATION.md) for detailed setup
 
-### Option 1: Run directly via npx (Recommended)
+### 2. Interactive REPL Mode
 
-No installation needed! Just run:
+Type commands without the `resolveai` prefix in an interactive session:
 
 ```bash
-npx resolve-solo <command>
+# Start interactive mode
+resolveai
+
+# Now you're in the REPL
+resolve-ai> investigate database errors
+resolve-ai [abc12345]> show details for item 1
+resolve-ai [abc12345]> note found connection pool leak
+resolve-ai [abc12345]> close fixed by increasing pool size
+resolve-ai> exit
 ```
 
-### Option 2: Install globally from npm
+**Benefits**: Session-aware prompts, command history, no need to type `resolveai` every time.
+
+### 3. Single-Command CLI Mode
+
+Traditional CLI mode for one-off commands or scripts:
+
+```bash
+resolveai demo
+resolveai investigate timeouts
+resolveai show details for item 3
+resolveai help
+```
+
+**Benefits**: Perfect for scripts, automation, or if you prefer traditional CLI workflows.
+
+## Quick Start
+
+### Install
 
 ```bash
 npm install -g resolve-solo
 ```
 
-Then use the `resolveai` command:
+### Option A: Setup for Claude Code
+
+```bash
+resolveai setup
+# ✓ Configured Claude Code integration
+# ✓ Restart Claude Code and start investigating!
+```
+
+Then in Claude Code:
+```
+User: "investigate timeout issues in payment service"
+Claude: [Automatically calls resolve-solo investigation tool]
+```
+
+### Option B: Try the Demo (CLI or REPL)
 
+**CLI mode**:
 ```bash
 resolveai demo
 ```
 
+**REPL mode**:
+```bash
+resolveai
+resolve-ai> demo
+```
+
+This will:
+- Seed realistic demo data (incidents, deploys, logs, services)
+- Run an automated investigation
+- Show you what Resolve Solo can do
+
+## Installation Options
+
+### Option 1: Install globally from npm (Recommended)
+
+```bash
+npm install -g resolve-solo
+```
+
+Then use the short `resolveai` command in any of the three modes.
+
+### Option 2: Run directly via npx (No install)
+
+Try it without installing:
+
+```bash
+npx resolve-solo demo
+npx resolve-solo investigate timeouts
+```
+
+**Note**: `npx` doesn't support REPL or Claude Code modes. For those, install globally.
+
 ### Option 3: Install from GitHub (Enterprise)
 
 For development or enterprise GitHub:
@@ -46,11 +124,11 @@ npm install -g git+https://github.cbhq.net/srinath-sinha/resolve-solo
 resolveai demo
 ```
 
-## Usage
+## Commands
 
 Resolve Solo uses **natural language** commands—no flags needed.
 
-### Try these commands:
+### Common Commands
 
 ```bash
 # See what Resolve Solo can do
@@ -59,8 +137,12 @@ resolveai demo
 # Get help
 resolveai help
 
+# Configure Claude Code integration
+resolveai setup
+
 # Investigate an issue (demo mode)
-resolveai investigate timeouts
+resolveai investigate timeouts in payment service
+resolveai investigate database connection errors
 
 # Show details for a timeline item
 resolveai show details for item 3
@@ -71,19 +153,27 @@ resolveai note checking database connection pool
 # Close an investigation
 resolveai close fixed connection pool size
 
-# Generate weekly report
+# Generate demo data
+resolveai demo seed
+resolveai demo reset
+```
+
+### Advanced Commands (Coming Soon)
+
+```bash
+# Generate weekly report (M8)
 resolveai report weekly
 
-# Check system health
+# Check system health (M10)
 resolveai doctor
 
-# Uninstall
+# Uninstall (M9)
 resolveai uninstall
 ```
 
 ## What You'll See
 
-When you run `resolveai demo`, you'll get:
+When you run `resolveai demo` or use the investigate tool from Claude Code:
 
 **A) What changed recently** - Timeline of deploys, errors, and past incidents
 **B) Where to look next** - Investigation paths with confidence levels
@@ -99,28 +189,56 @@ Resolve Solo stores all data locally in `./.resolveai/`:
 ```
 .resolveai/
 ├── demo-data/       # Demo dataset (services, deploys, logs, incidents)
-├── runs/            # Investigation sessions (created in M6+)
-├── memory.sqlite    # Incident recall database (created in M6+)
-└── reports/         # Weekly reports (created in M8+)
+└── memory.sqlite    # Investigation sessions and incident recall
 ```
 
-Export your demo data:
+The data is local-first and portable:
 
 ```bash
-# See where demo data is stored
-resolveai doctor
+# See storage location
+ls -la .resolveai/
 
-# Copy demo data elsewhere
-cp -r .resolveai/demo-data ~/my-demo-backup/
+# Copy data elsewhere
+cp -r .resolveai ~/my-backup/
 
 # Reset demo data
 resolveai demo reset
 ```
 
+## Architecture
+
+### Mode Detection
+
+```
+resolveai --mcp          → MCP Server (Claude Code integration)
+resolveai                → Interactive REPL
+resolveai <command>      → Single-command CLI
+```
+
+### Shared Handler Architecture
+
+All three modes call the same business logic handlers, ensuring consistent behavior:
+
+```
+CLI Mode    →
+REPL Mode   → Shared Handlers → Database/Storage
+MCP Mode    →
+```
+
+### Technology Stack
+
+- **Language**: TypeScript (compiled to ESM JavaScript)
+- **Test Framework**: Vitest
+- **MCP Integration**: @modelcontextprotocol/sdk
+- **CLI**: Natural language parser (no flag dependencies)
+- **Data**: Deterministic mock generation + SQLite persistence
+- **Storage**: JSON files + SQLite
+
 ## Requirements
 
 - **Node.js 18+** (uses ES modules)
 - Runs on macOS, Linux, Windows
+- **Claude Code** (optional, for MCP integration)
 
 ## Development
 
@@ -149,47 +267,79 @@ npm run typecheck
 
 ## Current Status
 
-**Version**: 0.1.0 (Demo Release)
-**Milestones Complete**: M1-M4 (4/12)
+**Version**: 0.4.0 (in development)
+**Milestones Complete**: M1-M7, M12 (8/12)
 
-- ✅ M1: Project Foundation
-- ✅ M2: CLI Entry & Help
-- ✅ M3: Demo Data System
-- ✅ M4: Flow A - First-Time Demo
-- 🚧 M5-M11: Interactive investigation, sessions, reports (planned)
+### Completed Features
+
+- ✅ **M1-M4**: Foundation, CLI, Demo Data, First-Time Demo
+- ✅ **M5-M6**: Investigation Core, Session Persistence
+- ✅ **M7**: Dual-Mode UX (REPL + MCP Server)
+- ✅ **M12**: Distribution & Publishing
+
+### What Works Now
+
+- ✅ Complete investigation workflow with session tracking
+- ✅ Timeline analysis with relevance filtering
+- ✅ Investigation notes and session closure
+- ✅ Persistent storage with SQLite
+- ✅ **Interactive REPL mode with session awareness**
+- ✅ **Claude Code integration via MCP**
+- ✅ **Automatic setup command**
+
+### Coming Soon
+
+- 🚧 **M8**: Weekly Reports (IT/Security value proof)
+- 🚧 **M9**: Uninstall Experience
+- 🚧 **M10**: Doctor Command (system health)
+- 🚧 **M11**: Polish & Testing
 
 **This is a demo release** - all investigations use mock data. Real integrations with observability tools (Datadog, Sentry, PagerDuty, etc.) are planned for future releases.
 
+## Claude Code Integration
+
+The MCP server exposes 5 tools to Claude Code:
+
+1. **investigate** - Start investigation for an incident
+2. **get_details** - Show timeline item details
+3. **add_note** - Add note to investigation
+4. **close_incident** - Close investigation with resolution
+5. **generate_report** - Weekly incident report (coming in M8)
+
+When properly configured, Claude Code automatically calls these tools when you ask incident-related questions in natural language.
+
+See [CLAUDE_CODE_INTEGRATION.md](./CLAUDE_CODE_INTEGRATION.md) for:
+- How tool discovery works
+- Setup instructions (automatic + manual)
+- Troubleshooting guide
+- Examples of what triggers the tools
+
 ## Uninstall
 
 To remove Resolve Solo:
 
 ```bash
-# If installed globally
+# Run uninstall command (M9 - coming soon)
 resolveai uninstall
 
 # Or manually
-npm uninstall -g resolve-solo  # or github:srinathsinha/resolve-solo
+npm uninstall -g resolve-solo
+
+# Remove Claude Code integration
+resolveai setup  # Will detect and offer to remove
 
 # Remove local data (optional)
 rm -rf .resolveai
 ```
 
-## Architecture
-
-- **Language**: TypeScript (compiled to ESM JavaScript)
-- **Test Framework**: Vitest
-- **CLI**: Natural language parser (no flag dependencies)
-- **Data**: Deterministic mock generation (same seed = identical output)
-- **Storage**: JSON files + SQLite (planned)
-
 ## Documentation
 
+- **[CLAUDE_CODE_INTEGRATION.md](./CLAUDE_CODE_INTEGRATION.md)** - Complete MCP integration guide
 - `SPEC.md` - Requirements specification
 - `PLAN.md` - Implementation milestones
 - `DECISIONS.md` - Key technical decisions
 - `CHANGELOG.md` - Progress log
-- `BUGLOG.md` - Bug tracking
+- `STATUS.md` - Current status
 - `CONTEXT.md` - Cross-session context
 
 ## License

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;GAIG;AA6BH,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,iBAgEhE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;GAIG;AAeH,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,iBAmBhE"}