@cephalization/phoenix-insight 0.1.0 → 0.2.0

package/README.md

@@ -2,9 +2,9 @@
 
 [![npm version](https://img.shields.io/npm/v/@cephalization/phoenix-insight.svg)](https://www.npmjs.com/package/@cephalization/phoenix-insight)
 
-A filesystem-native AI agent CLI for querying Phoenix instances using the "bash + files" paradigm inspired by [Vercel's agent architecture](https://vercel.com/blog/how-to-build-agents-with-filesystems-and-bash).
+Phoenix Insight brings AI-powered analysis to your [Phoenix](https://github.com/Arize-ai/phoenix) observability data using the ["bash + files" paradigm](https://vercel.com/blog/how-to-build-agents-with-filesystems-and-bash). Instead of hiding data behind opaque API calls, Phoenix Insight materializes your traces, experiments, datasets, and prompts as a structured filesystem. An AI agent then explores this data using standard bash commands you already know: `cat`, `grep`, `jq`, `awk`, and more.
 
-Phoenix Insight transforms your Phoenix observability data into a structured filesystem, then uses an AI agent with bash tools to analyze it through natural language queries. This approach provides transparency, flexibility, and power that traditional APIs can't match.
+This filesystem-native approach provides transparency that traditional APIs can't match. Every query the agent runs is visible and reproducible. You can inspect the exact files it reads, copy its commands, and run them yourself. The data is just files, and the analysis is just bash, making AI-driven observability debuggable, auditable, and extensible with any tool in your Unix toolkit.
 
 ## Installation
 
@@ -22,22 +22,310 @@ npx @cephalization/phoenix-insight "your query"
 ## Quick Start
 
 ```bash
-# Start interactive mode (no arguments needed)
+# Start interactive mode
 phoenix-insight
 
-# Query Phoenix data with natural language
+# Analyze Phoenix data with natural language
 phoenix-insight "What are the most common errors in the last hour?"
 
-# Local mode with persistent storage
+# Show help
+phoenix-insight help
+```
+
+## CLI Examples
+
+This section covers all CLI usage, progressing from basic to advanced scenarios.
+
+### Basic Queries
+
+```bash
+# Ask a question about your Phoenix data
+phoenix-insight "What types of errors are occurring most frequently?"
+
+# Analyze performance patterns
+phoenix-insight "Find the slowest traces and identify patterns"
+
+# Compare experiments
+phoenix-insight "Compare success rates across recent experiments"
+
+# Explore datasets
+phoenix-insight "Show me statistics about my datasets"
+```
+
+### Interactive Mode
+
+Start an interactive REPL session for multiple queries without re-fetching data:
+
+```bash
+# Start interactive mode (default when no query is provided)
+phoenix-insight
+
+# Or explicitly with --interactive flag
+phoenix-insight --interactive
+```
+
+Within interactive mode:
+
+```
+phoenix> What projects have the most spans?
+[Agent analyzes and responds...]
+
+phoenix> Show me error patterns in the chatbot-prod project
+[Agent investigates specific project...]
+
+phoenix> px-fetch-more trace --trace-id abc123
+[Agent fetches specific trace data...]
+
+phoenix> help
+[Shows available commands and tips...]
+
+phoenix> exit
+```
+
+### Snapshot Management
+
+Create or update snapshots separately from queries:
+
+```bash
+# Create initial snapshot
+phoenix-insight snapshot
+
+# Force refresh snapshot (ignore cache)
+phoenix-insight snapshot --refresh
+
+# Snapshot from a specific Phoenix instance
+phoenix-insight snapshot --base-url https://phoenix.example.com --api-key your-api-key
+
+# Clean up local snapshots
+phoenix-insight prune
+
+# Preview what would be deleted
+phoenix-insight prune --dry-run
+```
+
+### Local Mode
+
+```bash
+# Run a query in local mode (persistent storage, full bash capabilities)
 phoenix-insight --local "analyze trace patterns"
+```
 
-# Force fresh data
-phoenix-insight --refresh "show me the slowest endpoints"
+### Connection Options
 
-# Show help
+Connect to different Phoenix instances:
+
+```bash
+# Connect to a remote Phoenix instance
+phoenix-insight --base-url https://phoenix.example.com "analyze traces"
+
+# Authenticate with an API key
+phoenix-insight --base-url https://phoenix.example.com --api-key your-api-key "show errors"
+```
+
+### Data Fetching Options
+
+```bash
+# Increase span fetch limit (default: 1000 per project)
+phoenix-insight --limit 5000 "deep trace analysis"
+
+# Force refresh of cached data
+phoenix-insight --refresh "show me the latest errors"
+```
+
+### Output Options
+
+```bash
+# Disable streaming for batch processing (streaming is enabled by default)
+phoenix-insight --no-stream "generate report" > report.txt
+```
+
+### Observability
+
+```bash
+# Enable tracing of agent operations to Phoenix
+phoenix-insight --trace "analyze performance"
+```
+
+### On-Demand Data Fetching
+
+Within interactive mode, the agent can fetch additional data during analysis:
+
+```bash
+px-fetch-more spans --project my-project --limit 500
+px-fetch-more trace --trace-id abc123
+```
+
+### Combining Options
+
+Combine multiple options for complex scenarios:
+
+```bash
+# Remote instance with authentication, local mode, and increased limit
+phoenix-insight --local --base-url https://phoenix.example.com \
+  --api-key your-api-key --limit 5000 "deep analysis of production traces"
+
+# Refresh data, enable tracing, and stream output
+phoenix-insight --refresh --trace --stream "analyze error patterns over time"
+```
+
+## Example Queries
+
+Phoenix Insight understands natural language queries about your observability data. Here are examples organized by analysis type to help you get started.
+
+### Error Analysis
+
+```bash
+# Find and categorize errors
+phoenix-insight "What are the most common errors in the last 24 hours?"
+phoenix-insight "Show me all failed spans and their error messages"
+phoenix-insight "Which services have the highest error rates?"
+phoenix-insight "Find traces that contain exceptions or timeouts"
+```
+
+### Performance & Latency
+
+```bash
+# Identify performance bottlenecks
+phoenix-insight "What are the slowest LLM calls in my application?"
+phoenix-insight "Find traces where latency exceeds 5 seconds"
+phoenix-insight "Show p50, p95, and p99 latency by endpoint"
+phoenix-insight "Which operations have the highest latency variance?"
+```
+
+### Token Usage & Costs
+
+```bash
+# Analyze LLM resource consumption
+phoenix-insight "Which LLM calls are consuming the most tokens?"
+phoenix-insight "Calculate total token usage for the chatbot project"
+phoenix-insight "Show token usage breakdown by model type"
+phoenix-insight "Find conversations that exceeded 10,000 tokens"
+```
+
+### RAG Analysis
+
+```bash
+# Examine retrieval-augmented generation patterns
+phoenix-insight "Show retrieved documents with low relevance scores"
+phoenix-insight "Find retrieval calls that returned no results"
+phoenix-insight "What's the average number of documents retrieved per query?"
+phoenix-insight "Identify queries where retrieval latency dominated total time"
+```
+
+### Evaluations & Experiments
+
+```bash
+# Review evaluation results and experiment metrics
+phoenix-insight "What's the hallucination rate across my experiments?"
+phoenix-insight "Compare accuracy scores between model versions"
+phoenix-insight "Show experiments sorted by success rate"
+phoenix-insight "Find evaluation runs where quality scores dropped below threshold"
+```
+
+### Dataset Analysis
+
+```bash
+# Explore datasets and examples
+phoenix-insight "Show statistics for my evaluation datasets"
+phoenix-insight "Find examples where the model failed quality checks"
+phoenix-insight "What's the distribution of example categories in my dataset?"
+phoenix-insight "List datasets with the most recent updates"
+```
+
+### Prompt Engineering
+
+```bash
+# Analyze prompt versions and performance
+phoenix-insight "List all prompt versions and their performance metrics"
+phoenix-insight "Compare outputs between prompt v1 and v2"
+phoenix-insight "Which prompt template has the lowest error rate?"
+phoenix-insight "Show the evolution of my summarization prompt"
+```
+
+### Session & Conversation Analysis
+
+```bash
+# Understand user interaction patterns
+phoenix-insight "Show the conversation flow for session abc123"
+phoenix-insight "Find sessions with high user abandonment"
+phoenix-insight "What's the average conversation length by project?"
+phoenix-insight "Identify sessions where users repeated similar queries"
+```
+
+### Tool & Function Calls
+
+```bash
+# Analyze agent tool usage
+phoenix-insight "Which tools are being called most frequently?"
+phoenix-insight "Find tool calls that failed or timed out"
+phoenix-insight "Show the success rate for each tool type"
+phoenix-insight "What's the average latency for function calls?"
+```
+
+## Command Reference
+
+Phoenix Insight provides several commands, each with its own options.
+
+### Query Command (Default)
+
+The default command analyzes Phoenix data with natural language queries.
+
+```bash
+phoenix-insight [options] [query]
+```
+
+| Option              | Description                                   | Default                 | Example                                        |
+| ------------------- | --------------------------------------------- | ----------------------- | ---------------------------------------------- |
+| `--config <path>`   | Custom config file path                       | `~/.phoenix-insight/config.json` | `--config ./my-config.json`           |
+| `--sandbox`         | Run in sandbox mode with in-memory filesystem | `true`                  | `phoenix-insight --sandbox "query"`            |
+| `--local`           | Run in local mode with persistent storage     | `false`                 | `phoenix-insight --local "query"`              |
+| `--base-url <url>`  | Phoenix server URL                            | `http://localhost:6006` | `--base-url https://phoenix.example.com`       |
+| `--api-key <key>`   | Phoenix API key for authentication            | (none)                  | `--api-key your-api-key`                       |
+| `--refresh`         | Force refresh of cached snapshot data         | `false`                 | `phoenix-insight --refresh "show latest data"` |
+| `--limit <n>`       | Maximum spans to fetch per project            | `1000`                  | `--limit 5000`                                 |
+| `--stream`          | Stream agent responses in real-time           | `true`                  | `--no-stream` to disable                       |
+| `-i, --interactive` | Start interactive REPL mode                   | `false`                 | `phoenix-insight -i`                           |
+| `--trace`           | Enable tracing of agent operations to Phoenix | `false`                 | `phoenix-insight --trace "query"`              |
+
+### Snapshot Command
+
+Creates or updates a data snapshot from Phoenix without running a query.
+
+```bash
+phoenix-insight snapshot [options]
+```
+
+| Option             | Description                                   | Default                 | Example                                         |
+| ------------------ | --------------------------------------------- | ----------------------- | ----------------------------------------------- |
+| `--config <path>`  | Custom config file path                       | `~/.phoenix-insight/config.json` | `--config ./my-config.json`            |
+| `--base-url <url>` | Phoenix server URL                            | `http://localhost:6006` | `--base-url https://phoenix.example.com`        |
+| `--api-key <key>`  | Phoenix API key for authentication            | (none)                  | `--api-key your-api-key`                        |
+| `--refresh`        | Force refresh (ignore existing cache)         | `false`                 | `phoenix-insight snapshot --refresh`            |
+| `--limit <n>`      | Maximum spans to fetch per project            | `1000`                  | `phoenix-insight snapshot --limit 5000`         |
+| `--trace`          | Enable tracing of snapshot operations         | `false`                 | `phoenix-insight snapshot --trace`              |
+
+### Prune Command
+
+Deletes the local snapshot directory to free up disk space.
+
+```bash
+phoenix-insight prune [options]
+```
+
+| Option      | Description                              | Default | Example                         |
+| ----------- | ---------------------------------------- | ------- | ------------------------------- |
+| `--dry-run` | Preview what would be deleted without actually deleting | `false` | `phoenix-insight prune --dry-run` |
+
+### Help Command
+
+Displays help information and available options.
+
+```bash
 phoenix-insight help
 ```
 
+No additional options. Shows usage information, all commands, and their options.
+
 ## How It Works
 
 Phoenix Insight operates in three phases:
@@ -83,134 +371,73 @@ Phoenix data is organized into an intuitive REST-like hierarchy:
     snapshot.json                   # Snapshot metadata
 ```
 
-## Execution Modes
-
-Phoenix Insight supports two execution modes:
-
-### Sandbox Mode (default)
-
-Uses [just-bash](https://github.com/vercel-labs/just-bash) for complete isolation:
-
-- **In-memory filesystem**: No disk writes
-- **Simulated bash**: 50+ built-in commands
-- **Zero risk**: Cannot access your system
-- **Perfect for**: CI/CD, demos, safe exploration
-
-### Local Mode (--local)
-
-Uses real bash and persistent storage:
-
-- **Persistent data**: Snapshots saved to `~/.phoenix-insight/`
-- **Full bash power**: All system commands available
-- **Incremental updates**: Only fetches new data
-- **Perfect for**: Power users, complex analysis, custom tools
-
-## Usage Examples
-
-### Basic Queries
-
-```bash
-# Analyze errors
-phoenix-insight "What types of errors are occurring most frequently?"
-
-# Performance analysis
-phoenix-insight "Find the slowest traces and identify patterns"
+## Examples of Agent Analysis
 
-# Experiment comparison
-phoenix-insight "Compare success rates across recent experiments"
+### Error Pattern Detection
 
-# Dataset exploration
-phoenix-insight "Show me statistics about my datasets"
 ```
+User: "What are the most common errors in my traces?"
 
-### Advanced Options
-
-```bash
-# Connect to remote Phoenix instance
-phoenix-insight "analyze traces" \
-  --base-url https://phoenix.example.com \
-  --api-key your-api-key
-
-# Increase span fetch limit (default: 1000 per project)
-phoenix-insight "deep trace analysis" --limit 5000
+Agent: I'll analyze the error patterns in your traces. Let me start by examining the context...
 
-# Stream responses in real-time
-phoenix-insight "complex analysis task" --stream
+*reads _context.md*
+*searches for error spans across projects*
+*aggregates by error type*
+*identifies patterns*
 
-# Use local mode for persistent storage
-phoenix-insight "experimental query" --local
+I found 3 main error patterns in your traces:
+1. **Database timeouts** (42% of errors): Occurring in user-service, primarily during peak hours
+2. **API rate limits** (31% of errors): Third-party integration hitting limits
+3. **Null pointer exceptions** (27% of errors): In the recommendation engine
 
-# Enable observability tracing (sends traces to Phoenix)
-phoenix-insight "analyze performance" --trace
+The database timeouts show a clear pattern during 9-10am and 2-3pm daily.
 ```
 
-### Interactive Mode
-
-Start an interactive REPL session for multiple queries:
-
-```bash
-# Start interactive mode (default when no query is provided)
-$ phoenix-insight
-
-# Or explicitly with --interactive flag
-$ phoenix-insight --interactive
+### Performance Analysis
 
-phoenix> What projects have the most spans?
-[Agent analyzes and responds...]
+```
+User: "Find the slowest API endpoints"
 
-phoenix> Show me error patterns in the chatbot-prod project
-[Agent investigates specific project...]
+Agent: I'll analyze your API endpoint performance. Let me examine the span data...
 
-phoenix> px-fetch-more trace --trace-id abc123
-[Agent fetches specific trace data...]
+*reads project spans*
+*calculates latency percentiles*
+*groups by endpoint*
+*identifies outliers*
 
-phoenix> help
-[Shows available commands and tips...]
+Here are your slowest API endpoints by p95 latency:
+1. `/api/v1/recommendations` - 3.2s p95 (8.1s p99)
+2. `/api/v1/search` - 2.8s p95 (5.2s p99)
+3. `/api/v1/user/history` - 1.9s p95 (3.1s p99)
 
-phoenix> exit
+The recommendations endpoint has high variability, suggesting cache misses.
 ```
 
-### Snapshot Management
-
-Create or update snapshots separately from queries:
-
-```bash
-# Create initial snapshot
-phoenix-insight snapshot
-
-# Force refresh (ignore cache)
-phoenix-insight snapshot --refresh
+## Tips and Best Practices
 
-# Snapshot from specific Phoenix instance
-phoenix-insight snapshot \
-  --base-url https://phoenix.example.com \
-  --api-key your-api-key
+### Query Formulation
 
-# Enable observability tracing for snapshot process
-phoenix-insight snapshot --trace
+- Be specific about what you want to analyze
+- Mention time ranges if relevant
+- Ask for patterns, not just raw data
 
-# Clean up local snapshots
-phoenix-insight prune
+### Performance
 
-# Preview what would be deleted
-phoenix-insight prune --dry-run
-```
+- Use `--limit` to control data volume
+- In sandbox mode, start with smaller datasets
+- Use local mode for production analysis
 
-### On-Demand Data Fetching
+### Security
 
-The agent can fetch additional data during analysis:
+- Use sandbox mode when trying new queries
+- Never put API keys in queries
+- Review agent actions with `--stream`
 
-```bash
-# In your query, the agent might discover it needs more data:
-"I need more spans to complete this analysis. Let me fetch them..."
-px-fetch-more spans --project my-project --limit 500
+## Advanced Topics
 
-# Or fetch a specific trace:
-"I'll get the full trace to understand the error..."
-px-fetch-more trace --trace-id abc123
-```
+The following sections cover configuration, execution modes, and internal details for power users.
 
-## Configuration
+### Configuration
 
 Phoenix Insight uses a layered configuration system with the following priority (highest to lowest):
 
@@ -218,7 +445,7 @@ Phoenix Insight uses a layered configuration system with the following priority
 2. **Environment variables** - `PHOENIX_*` environment variables
 3. **Config file** - JSON file at `~/.phoenix-insight/config.json`
 
-### Config File
+#### Config File
 
 On first run, Phoenix Insight automatically creates a default config file at `~/.phoenix-insight/config.json` with all default values. You can edit this file to customize your settings.
 
@@ -252,7 +479,7 @@ On first run, Phoenix Insight automatically creates a default config file at `~/
 | `refresh`  | boolean                  | `false`                 | Force refresh of snapshot data                |
 | `trace`    | boolean                  | `false`                 | Enable tracing of agent operations to Phoenix |
 
-### Environment Variables
+#### Environment Variables
 
 | Variable                  | Config Key | Default                 | Description                |
 | ------------------------- | ---------- | ----------------------- | -------------------------- |
@@ -266,172 +493,33 @@ On first run, Phoenix Insight automatically creates a default config file at `~/
 | `PHOENIX_INSIGHT_CONFIG`  | -          | -                       | Custom config file path    |
 | `DEBUG`                   | -          | `0`                     | Show detailed error info   |
 
-### Commands
-
-Phoenix Insight provides several commands:
-
-- **Default (interactive mode)**: `phoenix-insight` - Start interactive REPL when no query is provided
-- **Query mode**: `phoenix-insight "your query"` - Analyze Phoenix data with natural language
-- **`help`**: Show help information
-- **`snapshot`**: Create or update a data snapshot from Phoenix
-- **`prune`**: Delete local snapshot directory to free up space
-
-### Command Line Options
-
-| Option                | Description                        | Default          | Applies to     |
-| --------------------- | ---------------------------------- | ---------------- | -------------- |
-| `--config <path>`     | Custom config file path            | (auto-detected)  | all            |
-| `--sandbox`           | Run in sandbox mode (default)      | true             | query          |
-| `--local`             | Run in local mode                  | false            | query          |
-| `--base-url <url>`    | Phoenix server URL                 | env or localhost | all            |
-| `--api-key <key>`     | Phoenix API key                    | env or none      | all            |
-| `--refresh`           | Force fresh snapshot               | false            | query/snapshot |
-| `--limit <n>`         | Max spans per project              | 1000             | query          |
-| `--stream`            | Stream agent responses             | true             | query          |
-| `--interactive`, `-i` | Interactive REPL mode              | false            | query          |
-| `--trace`             | Enable tracing to Phoenix instance | false            | query/snapshot |
-| `--dry-run`           | Preview without making changes     | false            | prune          |
-
-### Local Mode Storage
+#### Local Mode Storage
 
-In local mode, data is stored in:
+In local mode (`--local`), data persists at `~/.phoenix-insight/`:
 
 ```
 ~/.phoenix-insight/
   config.json                  # Configuration (auto-created on first run)
-  /snapshots/
-    /{timestamp}/              # Each snapshot
-      /phoenix/                # Phoenix data
+  /snapshots/{timestamp}/      # Snapshot data
   /cache/                      # API response cache
 ```
 
-To clean up local storage:
-
-```bash
-# Delete all local snapshots
-phoenix-insight prune
-
-# Preview what will be deleted
-phoenix-insight prune --dry-run
-```
+Use `phoenix-insight prune` to clean up local storage.
 
-## Troubleshooting
-
-### Connection Issues
-
-```bash
-# Test connection to Phoenix
-phoenix-insight snapshot
-
-# If that fails, check your Phoenix instance:
-curl http://localhost:6006/v1/projects
-
-# Verify with explicit connection:
-phoenix-insight snapshot --base-url http://your-phoenix:6006
-```
-
-### Authentication Errors
-
-```bash
-# Set API key via environment
-export PHOENIX_API_KEY="your-key"
-phoenix-insight "your query"
-
-# Or pass directly
-phoenix-insight "your query" --api-key "your-key"
-```
-
-### Debug Mode
-
-For detailed error information:
-
-```bash
-# Enable debug output
-DEBUG=1 phoenix-insight "problematic query"
-
-# This shows:
-# - Full stack traces
-# - API request details
-# - Agent tool calls
-# - Raw responses
-```
-
-### Common Issues
-
-**"No snapshot found" in local mode**
-
-```bash
-# Create initial snapshot
-phoenix-insight snapshot
+### Execution Modes
 
-# Or use --refresh to create on-demand
-phoenix-insight "query" --refresh
-```
-
-**Out of memory in sandbox mode**
-
-```bash
-# Reduce span limit
-phoenix-insight "query" --sandbox --limit 500
-
-# Or use local mode for large datasets
-phoenix-insight "query" --local
-```
-
-**Local storage getting too large**
-
-```bash
-# Check what will be deleted
-phoenix-insight prune --dry-run
-
-# Clean up all local snapshots
-phoenix-insight prune
-```
-
-**Agent can't find expected data**
-
-```bash
-# Force refresh to get latest
-phoenix-insight "query" --refresh
-
-# Fetch more data on-demand (agent will do this automatically)
-px-fetch-more spans --project my-project --limit 2000
-```
-
-## Observability
-
-Phoenix Insight can trace its own execution back to Phoenix for monitoring and debugging:
-
-```bash
-# Enable tracing for queries
-phoenix-insight "analyze errors" --trace
-
-# Enable tracing in interactive mode
-phoenix-insight --interactive --trace
-
-# Enable tracing for snapshot creation
-phoenix-insight snapshot --trace
-```
-
-When `--trace` is enabled:
-
-- All agent operations are traced as spans
-- Tool calls and responses are captured
-- Performance metrics are recorded
-- Traces are sent to the same Phoenix instance being queried (or the one specified by --base-url)
-
-This is particularly useful for:
+Phoenix Insight supports two execution modes:
 
-- Debugging slow queries
-- Understanding agent decision-making
-- Monitoring Phoenix Insight usage
-- Optimizing performance
+| Mode | Flag | Filesystem | Bash | Use Case |
+|------|------|------------|------|----------|
+| **Sandbox** (default) | `--sandbox` | In-memory | [just-bash](https://github.com/vercel-labs/just-bash) (50+ commands) | CI/CD, demos, safe exploration |
+| **Local** | `--local` | Persistent (`~/.phoenix-insight/`) | Real system bash | Power users, complex analysis |
 
-## Agent Capabilities
+### Agent Capabilities
 
 The AI agent has access to:
 
-### Bash Commands (Sandbox Mode)
+#### Bash Commands (Sandbox Mode)
 
 - **File operations**: `cat`, `ls`, `find`, `head`, `tail`
 - **Search & filter**: `grep`, `awk`, `sed`
@@ -439,19 +527,21 @@ The AI agent has access to:
 - **Analysis**: `sort`, `uniq`, `wc`
 - **And more**: 50+ commands via just-bash
 
-### Bash Commands (Local Mode)
+#### Bash Commands (Local Mode)
 
 - All commands available on your system
 - Custom tools: `ripgrep`, `fd`, `bat`, etc.
 - Full `jq`, `awk`, `sed` features
 - Any installed CLI tools
 
-### Custom Commands
+#### Custom Commands
+
+- `px-fetch-more spans`: Fetch additional spans for deeper analysis
+- `px-fetch-more trace`: Fetch a specific trace by ID
 
-- `px-fetch-more spans`: Fetch additional spans
-- `px-fetch-more trace`: Fetch specific trace by ID
+See [On-Demand Data Fetching](#on-demand-data-fetching) for usage examples.
 
-### Understanding Context
+#### Understanding Context
 
 The agent always starts by reading `/_context.md` which provides:
 
@@ -460,9 +550,17 @@ The agent always starts by reading `/_context.md` which provides:
 - Data freshness information
 - Available commands reminder
 
-## Development
+### Observability
+
+Phoenix Insight can trace its own execution back to Phoenix using `--trace`. When enabled, all agent operations, tool calls, and responses are traced as spans and sent to the Phoenix instance being queried. This is useful for debugging slow queries and understanding agent decision-making.
 
-### Building from Source
+### Troubleshooting
+
+For connection issues, authentication errors, debug mode, and common issues, see the [Troubleshooting Guide](./TROUBLESHOOTING.md).
+
+### Development
+
+#### Building from Source
 
 ```bash
 # Clone the repository
@@ -485,7 +583,7 @@ pnpm build
 pnpm typecheck
 ```
 
-### Architecture
+#### Architecture
 
 Phoenix Insight uses:
 
@@ -495,7 +593,7 @@ Phoenix Insight uses:
 - **Phoenix Client** for data fetching
 - **TypeScript** for type safety
 
-### Testing
+#### Testing
 
 ```bash
 # Run all tests
@@ -505,79 +603,17 @@ pnpm test
 pnpm test -- --coverage
 
 # Run specific test file
-pnpm test src/modes/sandbox.test.ts
+pnpm test test/modes/sandbox.test.ts
 
 # Type checking
 pnpm typecheck
 ```
 
-## Examples of Agent Analysis
-
-### Error Pattern Detection
-
-```
-User: "What are the most common errors in my traces?"
-
-Agent: I'll analyze the error patterns in your traces. Let me start by examining the context...
-
-*reads _context.md*
-*searches for error spans across projects*
-*aggregates by error type*
-*identifies patterns*
-
-I found 3 main error patterns in your traces:
-1. **Database timeouts** (42% of errors): Occurring in user-service, primarily during peak hours
-2. **API rate limits** (31% of errors): Third-party integration hitting limits
-3. **Null pointer exceptions** (27% of errors): In the recommendation engine
-
-The database timeouts show a clear pattern during 9-10am and 2-3pm daily.
-```
-
-### Performance Analysis
-
-```
-User: "Find the slowest API endpoints"
-
-Agent: I'll analyze your API endpoint performance. Let me examine the span data...
-
-*reads project spans*
-*calculates latency percentiles*
-*groups by endpoint*
-*identifies outliers*
-
-Here are your slowest API endpoints by p95 latency:
-1. `/api/v1/recommendations` - 3.2s p95 (8.1s p99)
-2. `/api/v1/search` - 2.8s p95 (5.2s p99)
-3. `/api/v1/user/history` - 1.9s p95 (3.1s p99)
-
-The recommendations endpoint has high variability, suggesting cache misses.
-```
-
-## Tips and Best Practices
-
-### Query Formulation
-
-- Be specific about what you want to analyze
-- Mention time ranges if relevant
-- Ask for patterns, not just raw data
-
-### Performance
-
-- Use `--limit` to control data volume
-- In sandbox mode, start with smaller datasets
-- Use local mode for production analysis
-
-### Security
-
-- Use sandbox mode when trying new queries
-- Never put API keys in queries
-- Review agent actions with `--stream`
-
-## Contributing & Releases
+### Contributing & Releases
 
 Contributions are welcome! This project uses [changesets](https://github.com/changesets/changesets) for version management and automated releases.
 
-### Making Changes
+#### Making Changes
 
 1. Fork the repository and create a feature branch
 2. Make your changes and ensure tests pass (`pnpm test`)
@@ -594,7 +630,7 @@ pnpm changeset
 5. Commit the generated changeset file along with your changes
 6. Open a pull request
 
-### Release Process
+#### Release Process
 
 When your PR is merged to `main`:
 
@@ -602,19 +638,18 @@ When your PR is merged to `main`:
 2. This PR updates the version in `package.json` and generates `CHANGELOG.md` entries
 3. When the Version Packages PR is merged, the package is automatically published to npm
 
-### Changeset Guidelines
+#### Changeset Guidelines
 
 - **patch**: Bug fixes, documentation updates, internal refactoring
 - **minor**: New features, new CLI options, non-breaking enhancements
 - **major**: Breaking changes to CLI interface or behavior
 
-## Support
+### Support
 
 This software is provided "as is" without warranty of any kind. Use at your own risk.
 
 You may file GitHub issues at [https://github.com/cephalization/phoenix-insight/issues](https://github.com/cephalization/phoenix-insight/issues).
 
+### License
 
-## License
-
-Apache-2.0 - See [LICENSE](./LICENSE) for details.
+Apache-2.0 - See [LICENSE](./LICENSE) for details.

package/dist/cli.js

@@ -225,10 +225,10 @@ program
 });
 program
     .command("prune")
-    .description("Delete the local snapshot directory (~/.phoenix-insight/)")
+    .description("Delete the local snapshot directory (~/.phoenix-insight/snapshots)")
     .option("--dry-run", "Show what would be deleted without actually deleting")
     .action(async (options) => {
-    const snapshotDir = path.join(os.homedir(), ".phoenix-insight");
+    const snapshotDir = path.join(os.homedir(), ".phoenix-insight", "snapshots");
     try {
         // Check if the directory exists
         const stats = await fs.stat(snapshotDir).catch(() => null);
@@ -240,9 +240,7 @@ program
             console.log("🔍 Dry run mode - would delete:");
             console.log(`   ${snapshotDir}`);
             // Show size and count of snapshots
-            const snapshots = await fs
-                .readdir(path.join(snapshotDir, "snapshots"))
-                .catch(() => []);
+            const snapshots = await fs.readdir(snapshotDir).catch(() => []);
             console.log(`   📊 Contains ${snapshots.length} snapshot(s)`);
             return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cephalization/phoenix-insight",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A CLI for Arize AI Phoenix data analysis with AI agents",
   "type": "module",
   "exports": {

package/src/cli.ts

@@ -268,10 +268,16 @@ program
 
 program
   .command("prune")
-  .description("Delete the local snapshot directory (~/.phoenix-insight/)")
+  .description(
+    "Delete the local snapshot directory (~/.phoenix-insight/snapshots)"
+  )
   .option("--dry-run", "Show what would be deleted without actually deleting")
   .action(async (options) => {
-    const snapshotDir = path.join(os.homedir(), ".phoenix-insight");
+    const snapshotDir = path.join(
+      os.homedir(),
+      ".phoenix-insight",
+      "snapshots"
+    );
 
     try {
       // Check if the directory exists
@@ -287,9 +293,7 @@ program
         console.log(`   ${snapshotDir}`);
 
         // Show size and count of snapshots
-        const snapshots = await fs
-          .readdir(path.join(snapshotDir, "snapshots"))
-          .catch(() => []);
+        const snapshots = await fs.readdir(snapshotDir).catch(() => []);
         console.log(`   📊 Contains ${snapshots.length} snapshot(s)`);
 
         return;