refactor: update coordinator-api port from 9001 to 8011 and standardize naming

- Changed all coordinator service port references from 9001 to 8011 in CI workflows
- Updated PYTHONPATH references from apps/agent-coordinator to apps/coordinator-api
- Renamed log files from agent-coordinator.log to coordinator-api.log
- Updated step names and comments to use "coordinator API" instead of "agent coordinator"
- Added API versioning documentation explaining /v1 prefix structure for business logic endpoints
- Documented CLI compatibility routes (/api/v1) and infrastructure endpoints (no prefix)
- Updated architecture

.gitea/workflows/api-endpoint-tests.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches: [main, develop]
     paths:
-      - 'apps/agent-coordinator/**'
+      - 'apps/coordinator-api/**'
       - 'apps/exchange/**'
       - 'apps/wallet/**'
       - 'scripts/ci/test_api_endpoints.py'
@@ -95,13 +95,13 @@ jobs:
 
           service_host=""
           for candidate in "${host_candidates[@]}"; do
-            code=$(curl -so /dev/null -w '%{http_code}' "http://$candidate:9001/health" 2>/dev/null) || code=0
+            code=$(curl -so /dev/null -w '%{http_code}' "http://$candidate:8011/health" 2>/dev/null) || code=0
             if [ "$code" -gt 0 ] && [ "$code" -lt 600 ]; then
               service_host="$candidate"
               break
             fi
 
-            code=$(curl -so /dev/null -w '%{http_code}' "http://$candidate:9001/v1/health" 2>/dev/null) || code=0
+            code=$(curl -so /dev/null -w '%{http_code}' "http://$candidate:8011/v1/health" 2>/dev/null) || code=0
             if [ "$code" -gt 0 ] && [ "$code" -lt 600 ]; then
               service_host="$candidate"
               break
@@ -119,7 +119,7 @@ jobs:
           echo "services_available=true" > "${{ env.WORKSPACE }}/status"
 
           # Check only the services needed for API endpoint tests (exclude blockchain RPC)
-          for port in 9001 8001 8003; do
+          for port in 8011 8001 8003; do
             port_ready=0
             for i in $(seq 1 15); do
               code=$(curl -so /dev/null -w '%{http_code}' "http://$service_host:$port/health" 2>/dev/null) || code=0

.gitea/workflows/integration-tests.yml

@@ -89,7 +89,7 @@ jobs:
         run: |
           echo "Waiting for services..."
           services_available=true
-          for port in 9001 8001 8003 8006; do
+          for port in 8011 8001 8003 8006; do
             port_ready=0
             for i in $(seq 1 15); do
               code=$(curl -so /dev/null -w '%{http_code}' "http://localhost:$port/health" 2>/dev/null) || code=0
@@ -144,7 +144,7 @@ jobs:
         run: |
           cd "${{ env.WORKSPACE }}/repo"
           source venv/bin/activate
-          export PYTHONPATH="$PWD/cli:$PWD/apps/agent-coordinator/src:$PWD/apps/wallet/src:$PWD/apps/exchange/src:$PYTHONPATH"
+          export PYTHONPATH="$PWD/cli:$PWD/apps/coordinator-api/src:$PWD/apps/wallet/src:$PWD/apps/exchange/src:$PYTHONPATH"
 
           # Skip if services not available
           if [ "${{ steps.wait-services.outputs.services_available }}" != "true" ]; then

.gitea/workflows/production-tests.yml

@@ -5,7 +5,7 @@ on:
     branches: [main, develop]
     paths:
       - 'tests/production/**'
-      - 'apps/agent-coordinator/**'
+      - 'apps/coordinator-api/**'
       - '.gitea/workflows/production-tests.yml'
   pull_request:
     branches: [main, develop]
@@ -73,20 +73,20 @@ jobs:
       - name: Start agent coordinator
         run: |
           cd "${{ env.WORKSPACE }}/repo"
-          export PYTHONPATH="apps/agent-coordinator/src:$PYTHONPATH"
+          export PYTHONPATH="apps/coordinator-api/src:$PYTHONPATH"
 
-          echo "Ensuring default port 9001 is available..."
+          echo "Ensuring default port 8011 is available..."
           pkill -f "uvicorn app.main:app" 2>/dev/null || true
           if command -v lsof >/dev/null 2>&1; then
-            pids=$(lsof -tiTCP:9001 -sTCP:LISTEN || true)
+            pids=$(lsof -tiTCP:8011 -sTCP:LISTEN || true)
             if [ -n "$pids" ]; then
-              echo "⚠️ Port 9001 already in use by PID(s): $pids; terminating"
+              echo "⚠️ Port 8011 already in use by PID(s): $pids; terminating"
               kill $pids 2>/dev/null || true
               sleep 2
             fi
-            if lsof -tiTCP:9001 -sTCP:LISTEN >/dev/null 2>&1; then
-              echo "❌ Port 9001 is still in use; aborting startup"
-              lsof -iTCP:9001 -sTCP:LISTEN || true
+            if lsof -tiTCP:8011 -sTCP:LISTEN >/dev/null 2>&1; then
+              echo "❌ Port 8011 is still in use; aborting startup"
+              lsof -iTCP:8011 -sTCP:LISTEN || true
               exit 1
             fi
           fi
@@ -94,38 +94,38 @@ jobs:
           # Start agent coordinator in background
           nohup env PYTHONUNBUFFERED=1 venv/bin/uvicorn app.main:app \
             --host 0.0.0.0 \
-            --port 9001 \
+            --port 8011 \
             --log-level info \
-            > /tmp/agent-coordinator.log 2>&1 &
+            > /tmp/coordinator-api.log 2>&1 &
 
-          echo $! > /tmp/agent-coordinator.pid
+          echo $! > /tmp/coordinator-api.pid
           sleep 2
-          if ! kill -0 "$(cat /tmp/agent-coordinator.pid)" 2>/dev/null; then
-            echo "❌ Agent coordinator exited during startup"
-            cat /tmp/agent-coordinator.log
+          if ! kill -0 "$(cat /tmp/coordinator-api.pid)" 2>/dev/null; then
+            echo "❌ Coordinator API exited during startup"
+            cat /tmp/coordinator-api.log
             exit 1
           fi
-          echo "✅ Agent coordinator started (PID: $(cat /tmp/agent-coordinator.pid))"
+          echo "✅ Coordinator API started (PID: $(cat /tmp/coordinator-api.pid))"
 
-      - name: Wait for agent coordinator ready
+      - name: Wait for coordinator API ready
         run: |
-          echo "Waiting for agent coordinator on port 9001..."
+          echo "Waiting for coordinator API on port 8011..."
           for i in $(seq 1 30); do
-            code=$(curl -so /dev/null -w '%{http_code}' "http://localhost:9001/health" 2>/dev/null) || code=0
+            code=$(curl -so /dev/null -w '%{http_code}' "http://localhost:8011/health" 2>/dev/null) || code=0
             if [ "$code" -ge 200 ] && [ "$code" -lt 600 ]; then
-              echo "✅ Agent coordinator ready (HTTP $code)"
+              echo "✅ Coordinator API ready (HTTP $code)"
               exit 0
             fi
             sleep 2
           done
-          echo "❌ Agent coordinator not ready"
-          cat /tmp/agent-coordinator.log
+          echo "❌ Coordinator API not ready"
+          cat /tmp/coordinator-api.log
           exit 1
 
       - name: Run production tests
         run: |
           cd "${{ env.WORKSPACE }}/repo"
-          export PYTHONPATH="apps/agent-coordinator/src:$PYTHONPATH"
+          export PYTHONPATH="apps/coordinator-api/src:$PYTHONPATH"
 
           # Test both chains
           export CHAINS="ait-mainnet,ait-testnet"
@@ -138,20 +138,20 @@ jobs:
 
           echo "✅ Production tests completed"
 
-      - name: Agent coordinator logs
+      - name: Print coordinator API logs
         if: always()
         run: |
-          if [ -f /tmp/agent-coordinator.log ]; then
-            echo "=== Agent Coordinator Logs ==="
-            cat /tmp/agent-coordinator.log
+          if [ -f /tmp/coordinator-api.log ]; then
+            echo "=== Coordinator API Logs ==="
+            cat /tmp/coordinator-api.log
           fi
 
-      - name: Cleanup
+      - name: Cleanup coordinator API
         if: always()
         run: |
-          if [ -f /tmp/agent-coordinator.pid ]; then
-            kill $(cat /tmp/agent-coordinator.pid) 2>/dev/null || true
-            rm -f /tmp/agent-coordinator.pid
+          if [ -f /tmp/coordinator-api.pid ]; then
+            kill $(cat /tmp/coordinator-api.pid) 2>/dev/null || true
+            rm -f /tmp/coordinator-api.pid
           fi
           pkill -f "uvicorn app.main:app" 2>/dev/null || true
           redis-cli shutdown 2>/dev/null || true

.gitea/workflows/python-tests.yml

@@ -76,7 +76,7 @@ jobs:
           venv/bin/python -m pip install -e packages/py/aitbc-sdk/
           venv/bin/python -m pip install -e packages/py/aitbc-agent-sdk/
 
-          export PYTHONPATH="$PWD/apps/agent-coordinator/src:$PWD/apps/blockchain-node/src:$PWD/apps/wallet/src:$PWD/packages/py/aitbc-crypto/src:$PWD/packages/py/aitbc-sdk/src:$PWD/packages/py/aitbc-agent-sdk/src:$PWD:$PYTHONPATH"
+          export PYTHONPATH="$PWD/apps/coordinator-api/src:$PWD/apps/blockchain-node/src:$PWD/apps/wallet/src:$PWD/packages/py/aitbc-crypto/src:$PWD/packages/py/aitbc-sdk/src:$PWD/packages/py/aitbc-agent-sdk/src:$PWD:$PYTHONPATH"
 
           venv/bin/python -m pytest tests/archived_phase_tests/ \
             tests/cross_phase/ \
@@ -90,16 +90,16 @@ jobs:
         run: |
           cd "${{ env.WORKSPACE }}/repo"
 
-          export PYTHONPATH="$PWD/apps/agent-coordinator:$PWD/apps/agent-coordinator/src:$PWD/packages/py/aitbc-crypto/src:$PWD/packages/py/aitbc-sdk/src:$PWD:$PYTHONPATH"
+          export PYTHONPATH="$PWD/apps/coordinator-api:$PWD/apps/coordinator-api/src:$PWD/packages/py/aitbc-crypto/src:$PWD/packages/py/aitbc-sdk/src:$PWD:$PYTHONPATH"
 
           # Test if packages are importable
           venv/bin/python -c "import aitbc_crypto; print('✅ aitbc_crypto imported')"
           venv/bin/python -c "import aitbc_sdk; print('✅ aitbc_sdk imported')"
-          venv/bin/python -c "import src.app; print('✅ agent-coordinator src.app imported')"
-          venv/bin/python -c "import app; print('✅ agent-coordinator app imported')"
+          venv/bin/python -c "import src.app; print('✅ coordinator-api src.app imported')"
+          venv/bin/python -c "import app; print('✅ coordinator-api app imported')"
 
           venv/bin/python -m pytest \
-            apps/agent-coordinator/tests/test_communication.py \
+            apps/coordinator-api/tests/test_communication.py \
             packages/py/aitbc-crypto/tests/ \
             packages/py/aitbc-sdk/tests/ \
             -c /dev/null --rootdir "$PWD" --import-mode=importlib \

docs/apps/coordinator/coordinator-api.md

@@ -4,6 +4,18 @@
 
 FastAPI service that accepts client compute jobs, matches miners, and tracks job lifecycle for the AITBC network.
 
+## API Versioning
+
+All business logic endpoints use the `/v1` prefix for consistent versioning. The API structure follows `/v1/{router}/{endpoint}` pattern.
+
+### Endpoint Structure
+
+- **Business logic endpoints**: `/v1/{router}/{endpoint}` (e.g., `/v1/marketplace/offers`, `/v1/governance/proposals`)
+- **CLI compatibility routes**: `/api/v1/{router}/{endpoint}` (e.g., `/api/v1/agents/executions`) - for CLI tools
+- **Infrastructure endpoints**: No prefix (e.g., `/health`, `/docs`, `/metrics`) - for system operations
+
+This structure enables future versioning (`/v2`, etc.) while maintaining CLI compatibility and keeping infrastructure endpoints unversioned.
+
 ## Marketplace Extensions
 
 Stage 2 introduces public marketplace endpoints exposed under `/v1/marketplace`:

docs/architecture/3_coordinator-api.md

@@ -35,7 +35,15 @@ SQLite database with Alembic migrations
 
 ## API Reference
 
-The Coordinator API provides RESTful endpoints for all major operations.
+The Coordinator API provides RESTful endpoints for all major operations. All business logic endpoints use the `/v1` prefix for consistent versioning.
+
+### API Versioning Structure
+
+- **Business logic endpoints**: `/v1/{router}/{endpoint}` (e.g., `/v1/client/jobs`, `/v1/miner/register`)
+- **CLI compatibility routes**: `/api/v1/{router}/{endpoint}` (e.g., `/api/v1/agents/executions`) - for CLI tools
+- **Infrastructure endpoints**: No prefix (e.g., `/health`, `/docs`, `/metrics`) - for system operations
+
+This structure enables future versioning (`/v2`, etc.) while maintaining CLI compatibility.
 
 ### Client Endpoints