docs: update installation instructions and remove outdated scripts

- Replace docker-compose approach with ephemeral container commands
- Update README.md to use claude mcp add-json for Claude Code setup
- Fix Docker image references to use ghcr.io registry
- Remove outdated scripts that used persistent containers:
  - build-and-run-detached.bat, build-and-run.sh
  - check-container.bat/sh, debug-container.bat
- Update documentation to align with MCP --rm container usage
- Add latest tag generation to GitHub Actions workflow

🤖 Generated with [Claude Code](https://claude.ai/code)

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

Author: jpicklyk

.github/workflows/docker-publish.yml

@@ -1,49 +1,50 @@
-name: Build and Push Docker Image
-
-on:
-  push:
-    branches: [ main ]
-    tags: [ 'v*' ]
-  pull_request:
-    branches: [ main ]
-
-env:
-  REGISTRY: ghcr.io
-  IMAGE_NAME: ${{ github.repository }}
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-
-    - name: Log in to Container Registry
-      uses: docker/login-action@v3
-      with:
-        registry: ${{ env.REGISTRY }}
-        username: ${{ github.actor }}
-        password: ${{ secrets.GITHUB_TOKEN }}
-
-    - name: Extract metadata
-      id: meta
-      uses: docker/metadata-action@v5
-      with:
-        images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-        tags: |
-          type=ref,event=branch
-          type=ref,event=pr
-          type=semver,pattern={{version}}
-          type=semver,pattern={{major}}.{{minor}}
-
-    - name: Build and push Docker image
-      uses: docker/build-push-action@v5
-      with:
-        context: .
-        push: true
-        tags: ${{ steps.meta.outputs.tags }}
-        labels: ${{ steps.meta.outputs.labels }}
+name: Build and Push Docker Image
+
+on:
+  push:
+    branches: [ main ]
+    tags: [ 'v*' ]
+  pull_request:
+    branches: [ main ]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Log in to Container Registry
+      uses: docker/login-action@v3
+      with:
+        registry: ${{ env.REGISTRY }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Extract metadata
+      id: meta
+      uses: docker/metadata-action@v5
+      with:
+        images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+        tags: |
+          type=ref,event=branch
+          type=ref,event=pr
+          type=semver,pattern={{version}}
+          type=semver,pattern={{major}}.{{minor}}
+          type=raw,value=latest,enable=${{ github.ref_type == 'tag' }}
+
+    - name: Build and push Docker image
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        push: true
+        tags: ${{ steps.meta.outputs.tags }}
+        labels: ${{ steps.meta.outputs.labels }}

README.md

@@ -27,17 +27,33 @@ A Kotlin implementation of the Model Context Protocol (MCP) server for comprehen
 
 ## Quick Start (2 Minutes)
 
-### 1. Run with Docker
+### 1. Pull or Build Docker Image
+
+#### Option A: Production Image (Recommended)
 ```bash
-# Quick test run
-docker run --rm -i -v mcp-task-data:/app/data mcp-task-orchestrator
+# Pull latest release
+docker pull ghcr.io/jpicklyk/task-orchestrator:latest
+
+# Or specific version
+docker pull ghcr.io/jpicklyk/task-orchestrator:1.0.0
+
+# Or latest build from main branch
+docker pull ghcr.io/jpicklyk/task-orchestrator:main
+```
 
-# Or build locally
+#### Option B: Build Locally (Development)
+```bash
+# Build locally
 ./scripts/docker-clean-and-build.bat  # Windows
+# Or manually: docker build -t mcp-task-orchestrator:dev .
 ```
 
-### 2. Configure Claude Desktop
+### 2. Configure Claude Desktop or Claude Code
+
+#### For Claude Desktop
 Add to your `claude_desktop_config.json`:
+
+**Production Configuration**
 ```json
 {
   "mcpServers": {
@@ -46,14 +62,56 @@ Add to your `claude_desktop_config.json`:
       "args": [
         "run", "--rm", "-i",
         "--volume", "mcp-task-data:/app/data",
-        "mcp-task-orchestrator"
+        "ghcr.io/jpicklyk/task-orchestrator:latest"
       ]
     }
   }
 }
 ```
 
-### 3. Start Using
+**Local Development Configuration**
+```json
+{
+  "mcpServers": {
+    "task-orchestrator": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "--volume", "mcp-task-data:/app/data",
+        "mcp-task-orchestrator:dev"
+      ]
+    }
+  }
+}
+```
+
+#### For Claude Code
+Use the JSON configuration command:
+
+```bash
+# Production version (latest release)
+claude mcp add-json task-orchestrator '{"type":"stdio","command":"docker","args":["run","--rm","-i","-v","mcp-task-data:/app/data","ghcr.io/jpicklyk/task-orchestrator:latest"]}'
+
+# Specific version
+claude mcp add-json task-orchestrator '{"type":"stdio","command":"docker","args":["run","--rm","-i","-v","mcp-task-data:/app/data","ghcr.io/jpicklyk/task-orchestrator:1.0.0"]}'
+
+# Latest from main branch
+claude mcp add-json task-orchestrator '{"type":"stdio","command":"docker","args":["run","--rm","-i","-v","mcp-task-data:/app/data","ghcr.io/jpicklyk/task-orchestrator:main"]}'
+
+# Local development version (after building locally)
+claude mcp add-json task-orchestrator '{"type":"stdio","command":"docker","args":["run","--rm","-i","-v","mcp-task-data:/app/data","mcp-task-orchestrator:dev"]}'
+```
+
+### 3. Test Connection (Optional)
+```bash
+# Test the Docker container runs correctly
+docker run --rm -i -v mcp-task-data:/app/data ghcr.io/jpicklyk/task-orchestrator:latest
+
+# Test MCP connection (requires Node.js)
+node scripts/test-mcp-connection.js
+```
+
+### 4. Start Using
 Ask Claude:
 - "Create a new project for my web application"
 - "Show me the project overview"
@@ -97,20 +155,9 @@ Project (optional)
 - **9 Section Management Tools** - Rich documentation
 - **9 Template Management Tools** - Workflow automation
 
-## Installation Options
+## Alternative Installation Options
 
-### Option 1: Docker (Recommended)
-```bash
-# Build and run
-./scripts/docker-clean-and-build.bat
-
-# Configure environment
-MCP_TRANSPORT=stdio
-DATABASE_PATH=data/tasks.db
-USE_FLYWAY=true
-```
-
-### Option 2: Direct JAR
+### Option 1: Direct JAR (Without Docker)
 ```bash
 # Build
 ./gradlew build
@@ -119,6 +166,15 @@ USE_FLYWAY=true
 java -jar build/libs/mcp-task-orchestrator-*.jar
 ```
 
+### Option 2: Development Environment Variables
+```bash
+# Configure environment for local development
+MCP_TRANSPORT=stdio
+DATABASE_PATH=data/tasks.db
+USE_FLYWAY=true
+MCP_DEBUG=true  # Enable debug logging
+```
+
 ## Configuration
 
 | Variable | Description | Default |

docs/database-migrations.md

@@ -234,17 +234,20 @@ Flyway Community Edition doesn't support automatic rollbacks. For complex migrat
 
 ### Manual Rollback Process
 ```bash
-# 1. Stop the application
-docker-compose down
+# 1. Stop the application (if running in background)
+docker stop mcp-task-orchestrator 2>/dev/null || true
 
 # 2. Connect to database and run rollback SQL
 sqlite3 data/tasks.db < rollback_v5.sql
 
 # 3. Update Flyway history
 sqlite3 data/tasks.db "DELETE FROM flyway_schema_history WHERE version = '5';"
 
-# 4. Restart application
-docker-compose up
+# 4. Restart application (production)
+docker run --rm -i -v mcp-task-data:/app/data ghcr.io/jpicklyk/task-orchestrator:latest
+
+# Or restart local development
+docker run --rm -i -v mcp-task-data:/app/data mcp-task-orchestrator:dev
 ```
 
 ## Troubleshooting
@@ -275,8 +278,11 @@ EXPLAIN QUERY PLAN SELECT * FROM table_name WHERE condition;
 ### Debugging Migrations
 
 ```bash
-# Enable debug logging
-LOG_LEVEL=debug USE_FLYWAY=true docker-compose up
+# Enable debug logging (production)
+docker run --rm -i -v mcp-task-data:/app/data -e LOG_LEVEL=debug -e USE_FLYWAY=true ghcr.io/jpicklyk/task-orchestrator:latest
+
+# Or with local development
+docker run --rm -i -v mcp-task-data:/app/data -e LOG_LEVEL=debug -e USE_FLYWAY=true mcp-task-orchestrator:dev
 
 # Check Flyway schema history
 sqlite3 data/tasks.db "SELECT * FROM flyway_schema_history ORDER BY installed_rank;"

docs/quick-start.md

@@ -19,24 +19,29 @@ Get MCP Task Orchestrator running with Claude Desktop in under 2 minutes. This g
 
 ## Step 1: Get the Docker Image
 
-### Option A: Pull Pre-built Image (Fastest)
+### Option A: Pull Production Image (Fastest)
 ```bash
-# Pull the latest image
-docker pull mcp-task-orchestrator:latest
+# Pull the latest release
+docker pull ghcr.io/jpicklyk/task-orchestrator:latest
+
+# Or specific version
+docker pull ghcr.io/jpicklyk/task-orchestrator:1.0.0
+
+# Or latest build from main branch
+docker pull ghcr.io/jpicklyk/task-orchestrator:main
 ```
 
-### Option B: Build Locally (Recommended for Development)
+### Option B: Build Locally (Development)
 ```bash
 # Clone the repository
 git clone https://github.com/jpicklyk/task-orchestrator.git
 cd task-orchestrator
 
-# Build using the provided script
-# Windows
+# Build using the provided script (Windows)
 ./scripts/docker-clean-and-build.bat
 
-# Linux/Mac
-./scripts/docker-clean-and-build.sh
+# Or manually
+docker build -t mcp-task-orchestrator:dev .
 ```
 
 ---
@@ -46,8 +51,11 @@ cd task-orchestrator
 Verify the container works:
 
 ```bash
-# Quick test run
-docker run --rm -i -v mcp-task-data:/app/data mcp-task-orchestrator
+# Quick test run (production image)
+docker run --rm -i -v mcp-task-data:/app/data ghcr.io/jpicklyk/task-orchestrator:latest
+
+# Or test local build
+docker run --rm -i -v mcp-task-data:/app/data mcp-task-orchestrator:dev
 ```
 
 You should see MCP server startup messages. Press `Ctrl+C` to stop.
@@ -66,6 +74,26 @@ You should see MCP server startup messages. Press `Ctrl+C` to stop.
 
 Open `claude_desktop_config.json` and add:
 
+#### Production Configuration (Recommended)
+```json
+{
+  "mcpServers": {
+    "task-orchestrator": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "--volume",
+        "mcp-task-data:/app/data",
+        "ghcr.io/jpicklyk/task-orchestrator:latest"
+      ]
+    }
+  }
+}
+```
+
+#### Local Development Configuration
 ```json
 {
   "mcpServers": {
@@ -77,7 +105,7 @@ Open `claude_desktop_config.json` and add:
         "-i",
         "--volume",
         "mcp-task-data:/app/data",
-        "mcp-task-orchestrator"
+        "mcp-task-orchestrator:dev"
       ]
     }
   }
@@ -227,9 +255,13 @@ docker system prune
 Verify your setup with this simple test:
 
 ```bash
-# Test the container directly
+# Test the container directly (production)
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
+docker run --rm -i -v mcp-task-data:/app/data ghcr.io/jpicklyk/task-orchestrator:latest
+
+# Or test local build
 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
-docker run --rm -i -v mcp-task-data:/app/data mcp-task-orchestrator
+docker run --rm -i -v mcp-task-data:/app/data mcp-task-orchestrator:dev
 ```
 
 You should see a list of available tools.
@@ -250,7 +282,7 @@ Customize behavior with environment variables:
         "--volume", "mcp-task-data:/app/data",
         "--env", "MCP_DEBUG=true",
         "--env", "DATABASE_PATH=/app/data/my-tasks.db",
-        "mcp-task-orchestrator"
+        "ghcr.io/jpicklyk/task-orchestrator:latest"
       ]
     }
   }