coaia-visualizer 1.5.9 → 1.6.0

package/QUICK_START_MCP_TESTING.md

@@ -1,236 +0,0 @@
-# Quick Start: MCP Testing Environment
-
-## TL;DR - Run Tests in 3 Steps
-
-### 1. Navigate to Project
-```bash
-cd /workspace/repos/jgwill/coaia-visualizer-feat-4
-```
-
-### 2. Run All Tests
-```bash
-./run-mcp-tests.sh
-```
-
-### 3. Check Results
-```bash
-cat test-results/test-summary.txt
-```
-
-**Done!** ✅ All tests run automatically.
-
----
-
-## What This Does
-
-- ✅ Builds Docker images (visualizer app + MCP server + test runner)
-- ✅ Starts all services in isolated Docker network
-- ✅ Runs complete test suite non-interactively
-- ✅ Generates results in `test-results/` directory
-- ✅ Cleans up all containers
-
-## Test Results
-
-The suite validates:
-
-| Test        | What It Tests            | Validates                                  |
-| ----------- | ------------------------ | ------------------------------------------ |
-| **Test 01** | Chart creation & listing | API connectivity, CRUD operations          |
-| **Test 02** | Telescope functionality  | Sub-chart creation, both telescope methods |
-| **Test 03** | Navigation & hierarchy   | Parent-child relationships, search         |
-
-## Files Overview
-
-```
-Key Files Created:
-├── docker-compose.test.yml        # Docker orchestration
-├── Dockerfile.app                  # Next.js build
-├── Dockerfile.test                 # Test runner
-├── mcp/Dockerfile                  # MCP server build
-├── run-mcp-tests.sh                # Main test script
-├── test-scripts/                   # Individual tests
-│   ├── run-all-tests.sh
-│   ├── test-01-basic-operations.sh
-│   ├── test-02-telescope-creation.sh
-│   ├── test-03-navigation.sh
-│   └── README.md                   # Detailed guide
-├── test-data/                      # Test fixtures
-├── validate-mcp.sh                 # Quick validation
-└── MCP_TESTING_COMPLETE.md         # Full documentation
-```
-
-## Quick Commands
-
-### Run full test suite
-```bash
-./run-mcp-tests.sh
-```
-
-### Quick validation (no Docker)
-```bash
-bash validate-mcp.sh
-```
-
-### View test results
-```bash
-cat test-results/test-summary.txt
-```
-
-### See individual test output
-```bash
-cat test-results/test-02/telescope-existing-action.json | jq .
-```
-
-### Start services manually
-```bash
-docker-compose -f docker-compose.test.yml up -d visualizer-app mcp-server
-```
-
-### Run single test manually
-```bash
-docker-compose -f docker-compose.test.yml run --rm test-runner \
-  /test-scripts/test-02-telescope-creation.sh
-```
-
-### Stop services
-```bash
-docker-compose -f docker-compose.test.yml down
-```
-
-### View service logs
-```bash
-docker-compose -f docker-compose.test.yml logs visualizer-app
-docker-compose -f docker-compose.test.yml logs mcp-server
-```
-
-## MCP Tools Available
-
-After deployment with Claude Desktop, you can use:
-
-- `create_chart` - Create new structural tension chart
-- `update_chart` - Update existing chart
-- `delete_chart` - Remove chart
-- `search_charts` - Search charts
-- `add_action_step` - Add action (optionally telescoped)
-- `create_telescoped_chart` - **NEW** Telescope existing action
-
-## Using with Claude Desktop
-
-1. **Start visualizer:**
-   ```bash
-   npm run dev
-   ```
-
-2. **Configure Claude** with MCP server path
-
-3. **Restart Claude Desktop**
-
-4. **Use telescope tool in conversation:**
-   - "Create a sub-chart for action X"
-   - "Telescope this action"
-   - "Drill down into this step"
-
-## Troubleshooting
-
-| Issue              | Solution                                                     |
-| ------------------ | ------------------------------------------------------------ |
-| Docker build fails | `docker-compose -f docker-compose.test.yml build --no-cache` |
-| Tests don't run    | Check Docker is running: `docker ps`                         |
-| API not responding | Check logs: `docker-compose -f docker-compose.test.yml logs` |
-| Empty test results | Verify API endpoint: `curl http://localhost:4321/api/charts` |
-
-## Environment Notes
-
-### Optional API Keys
-- `ANTHROPIC_API_KEY` - For claude-code CLI testing
-- `GOOGLE_API_KEY` - For gemini-cli testing
-
-Tests work fine without these - they use direct HTTP calls instead.
-
-### System Requirements
-- Docker & Docker Compose
-- Node.js 20+
-- npm/pnpm
-- ~5GB disk space for Docker images
-- ~5-10 minutes for first run (builds images)
-
-## Test Results Locations
-
-```
-test-results/
-├── test-01/                        # Basic operations
-│   ├── create-response.json       # Chart creation response
-│   ├── list-response.json         # List charts response
-│   └── chart-id.txt               # ID for next test
-│
-├── test-02/                        # Telescope operations
-│   ├── telescope-existing-action.json
-│   ├── final-chart-state.json
-│   └── telescoped-chart-id.txt    # ID for test-03
-│
-├── test-03/                        # Navigation
-│   ├── parent-chart.json          # Parent chart state
-│   ├── navigation-summary.txt     # Navigation results
-│
-└── test-summary.txt               # Overall pass/fail
-```
-
-## Docker Network Details
-
-All services run in isolated Docker network:
-
-```
-Network: test-network
-├── visualizer-app:4321    (Next.js app)
-├── mcp-server             (stdin/stdout)
-└── test-runner            (bash/curl)
-
-Data Flow:
-Test Scripts --HTTP--> API:4321 <--HTTP--> MCP Server
-```
-
-## CI/CD Integration
-
-To add to your CI pipeline:
-
-```yaml
-# GitHub Actions example
-- name: Run MCP Tests
-  run: |
-    cd /workspace/repos/jgwill/coaia-visualizer-feat-4
-    chmod +x run-mcp-tests.sh
-    ./run-mcp-tests.sh
-```
-
-Results automatically saved to `test-results/` for review.
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────┐
-│   run-mcp-tests.sh              │
-│   (Main Orchestrator)           │
-└──────────────┬──────────────────┘
-               │
-               ├─ Builds Docker images
-               ├─ Starts services
-               ├─ Runs test suite
-               ├─ Generates results
-               └─ Cleans up
-```
-
-## Full Documentation
-
-For detailed information, see:
-- `MCP_TESTING_COMPLETE.md` - Complete guide
-- `MCP_TESTING_SETUP.md` - Setup details
-- `test-scripts/README.md` - Test documentation
-- `MCP_TESTING_IMPLEMENTATION_SUMMARY.md` - Implementation details
-
----
-
-## Status
-
-✅ **Ready to Use**
-
-All infrastructure is in place. Run `./run-mcp-tests.sh` to test!

package/README_TELESCOPED_NAVIGATION.md

@@ -1,247 +0,0 @@
-# 🎯 Telescoped Chart Navigation - User Guide
-
-## Quick Start
-
-### What are Telescoped Charts?
-
-In structural tension methodology, **every action step is actually a full structural tension chart** with its own:
-- Desired outcome (what you want to create)
-- Current reality (where you actually are)
-- Action steps (which are also charts)
-
-This creates an **infinite fractal structure** where you can zoom into any action and work on it as a complete chart.
-
-### Visual Indicators
-
-When viewing a master chart's actions, you'll see two types:
-
-**Regular Actions** (simple todo items):
-\`\`\`
-┌──────────────────────────┐
-│ ○ Action 1               │
-│   Do something simple    │
-└──────────────────────────┘
-\`\`\`
-
-**Telescoped Charts** (full structural tension charts):
-\`\`\`
-┌─────────────────────────────────────┐
-│ ○ Action 1  📊 Chart  [👁 Open ›] │ ← Gradient background
-│   Complex multi-step task         ▓ │ ← Colored border
-└─────────────────────────────────────┘ ← Hover for shadow
-\`\`\`
-
-Key visual differences:
-- 🎨 **Gradient background** (subtle primary color)
-- 🔲 **Colored border** (primary color, brightens on hover)
-- 📊 **"Chart" badge** (bold, with icon)
-- 👁 **"Open" button** (prominent, with icons)
-
-## How to Use
-
-### 1. Navigate Into a Telescoped Chart
-
-1. Find an action with the **"📊 Chart"** badge
-2. Click the **"👁 Open ›"** button on the right
-3. You'll navigate into that action as a full chart
-
-### 2. Work Within the Sub-Chart
-
-Once inside, you can:
-- ✏️ **Edit the desired outcome** (click the pencil icon)
-- 📝 **Edit current reality** (add observations)
-- ➕ **Add action steps** (these become Level 2 charts)
-- ✅ **Mark complete** (advances parent's current reality)
-- 📅 **Set due dates**
-- 🗑️ **Delete the chart**
-
-### 3. Navigate Deeper
-
-Any action steps you add to the sub-chart can themselves be opened as charts:
-- Add an action to a Level 1 chart → creates Level 2 chart
-- Add an action to a Level 2 chart → creates Level 3 chart
-- Continue infinitely...
-
-### 4. Navigate Back
-
-Click **"← Back to Parent Chart"** at the top to return to the previous level.
-
-The app maintains a navigation stack, so you can:
-\`\`\`
-Level 0 (Master)
-  → Level 1 (First action)
-     → Level 2 (Sub-action)
-        → Level 3 (Sub-sub-action)
-\`\`\`
-
-Press back repeatedly to climb back up the hierarchy.
-
-## Example Workflow
-
-### Creating a Multi-Level Chart
-
-**Step 1: Create Master Chart**
-\`\`\`
-Chart: "Build COAIA Feature"
-Desired Outcome: Complete feature implementation
-Current Reality: Have basic structure, need details
-\`\`\`
-
-**Step 2: Add Action Steps**
-\`\`\`
-Action 1: "Implement core logic"
-  Current Reality: "Have file structure, need methods"
-  → Creates chart_2 as Level 1
-
-Action 2: "Add UI components"
-  Current Reality: "UI design done, need implementation"
-  → Creates chart_3 as Level 1
-\`\`\`
-
-**Step 3: Navigate Into "Implement core logic"**
-
-Click **"👁 Open ›"** on Action 1
-
-Now viewing chart_2 as a full chart:
-\`\`\`
-Chart 2 (Level 1)
-Desired Outcome: Implement core logic
-Current Reality: Have file structure, need methods
-
-You can now add sub-actions:
-  Action 1: "Write parser methods"
-  Action 2: "Add validation logic"
-\`\`\`
-
-**Step 4: Navigate Deeper**
-
-Click **"👁 Open ›"** on "Write parser methods"
-
-Now viewing chart_3 (Level 2):
-\`\`\`
-Chart 3 (Level 2)
-Desired Outcome: Write parser methods
-Current Reality: Have empty functions, need implementation
-\`\`\`
-
-**Step 5: Navigate Back**
-
-- Click **"← Back"** once → returns to chart_2 (Level 1)
-- Click **"← Back"** again → returns to chart_1 (Level 0)
-
-## Design Features
-
-### Color Coding
-
-**Light Mode**:
-- Telescoped charts: Light blue/primary gradient
-- Border: Blue, brightens on hover
-- Badge: Solid blue with white text
-- Button: Blue with white icons
-
-**Dark Mode**:
-- Telescoped charts: Subtle colored gradient
-- Border: Colored, brightens on hover  
-- Badge: Solid color with dark text
-- Button: Colored with appropriate contrast
-
-### Interactive States
-
-**Hover**:
-- Border color intensifies
-- Shadow appears underneath card
-- Button shadow deepens
-
-**Focus** (keyboard navigation):
-- Visible focus ring around buttons
-- High contrast for accessibility
-
-**Completed**:
-- Muted background
-- Text has line-through
-- Can still be opened to view details
-
-## Keyboard Shortcuts
-
-- **Tab**: Navigate between actions
-- **Enter/Space**: Click focused button
-- **Shift+Tab**: Navigate backwards
-
-## Mobile Experience
-
-On mobile devices:
-- **Touch targets** are large enough for easy tapping
-- **Badge wraps** to next line if needed
-- **"Open" button** maintains size for easy access
-- **Scrolling** works smoothly through action lists
-
-## Tips & Tricks
-
-### When to Create Telescoped Charts
-
-Create a telescoped chart (action step) when:
-- ✅ The task has multiple sub-steps
-- ✅ You need to track progress on sub-components
-- ✅ The task has its own structural tension
-- ✅ You want to maintain the advancing pattern at multiple levels
-
-Use simple actions when:
-- ✅ The task is genuinely atomic
-- ✅ No sub-planning needed
-- ✅ Quick checkbox completion is sufficient
-
-### Organizing Deep Hierarchies
-
-For complex projects:
-\`\`\`
-Level 0: Project goal
-Level 1: Major features/phases
-Level 2: Specific implementation tasks
-Level 3: Detailed sub-tasks
-Level 4: Implementation details
-\`\`\`
-
-### Completing Charts at Different Levels
-
-When you mark a Level 2 action complete:
-- ✅ The Level 2 chart's desired outcome is marked complete
-- ✅ The Level 1 chart's current reality gets "Completed: {action}" added
-- ✅ This creates momentum up the hierarchy
-
-## Troubleshooting
-
-**Q: I don't see the "Open" button**
-
-A: The action might not be a telescoped chart. Only actions with the "📊 Chart" badge can be opened. Regular actions don't have this button.
-
-**Q: The "Open" button doesn't work**
-
-A: Make sure you've loaded a file with properly structured telescoped charts. The test file `feat-4-mcp-api/test-telescoped-charts.jsonl` has examples.
-
-**Q: I can't find the back button**
-
-A: The "← Back to Parent Chart" button only appears when you're viewing a sub-chart (Level 1+). It won't show on Level 0 (master) charts.
-
-**Q: How deep can I nest charts?**
-
-A: Infinitely! The system supports unlimited nesting levels (0 → 1 → 2 → 3 → ...).
-
-## Screenshots
-
-Check the `screenshots/` directory for visual examples:
-- `improved-01-actions.png`: Action list with telescoped charts
-- `improved-02-action-detail.png`: Close-up of telescoped action
-- `improved-03-after-open.png`: Sub-chart view after navigation
-
-## Related Documentation
-
-- **UI_GUIDE.md**: Detailed design specifications
-- **TELESCOPED_CHART_NAVIGATION.md**: Technical implementation
-- **IMPLEMENTATION_COMPLETE.md**: Development summary
-- **FEATURE_4_COMPLETE.md**: Full Feature 4 documentation
-
-## Support
-
-The telescoped chart navigation has been fully tested and verified with automated Playwright tests. All functionality is production-ready.
-
-**Version: 1.4.0**