Move blockchain app READMEs to centralized documentation

- Relocate blockchain-event-bridge README content to docs/apps/blockchain/blockchain-event-bridge.md
- Relocate blockchain-explorer README content to docs/apps/blockchain/blockchain-explorer.md
- Replace app READMEs with redirect notices pointing to new documentation location
- Consolidate documentation in central docs/ directory for better organization

docs/apps/coordinator/README.md

@@ -0,0 +1,16 @@
+# Coordinator Applications
+
+Job coordination and agent management services.
+
+## Applications
+
+- [Coordinator API](coordinator-api.md) - FastAPI service for job coordination and matching
+- [Agent Coordinator](agent-coordinator.md) - Agent coordination and management
+
+## Features
+
+- Job submission and lifecycle tracking
+- Miner matching
+- Marketplace endpoints
+- Explorer data endpoints
+- Signed receipts support

docs/apps/coordinator/agent-coordinator.md

@@ -0,0 +1,214 @@
+# Agent Coordinator
+
+## Status
+✅ Operational
+
+## Overview
+FastAPI-based agent coordination service that manages agent discovery, load balancing, and task distribution across the AITBC network.
+
+## Architecture
+
+### Core Components
+- **Agent Registry**: Central registry for tracking available agents
+- **Agent Discovery Service**: Service for discovering and registering agents
+- **Load Balancer**: Distributes tasks across agents using various strategies
+- **Task Distributor**: Manages task assignment and priority queues
+- **Communication Manager**: Handles inter-agent communication protocols
+- **Message Processor**: Processes and routes messages between agents
+
+### AI Integration
+- **Real-time Learning**: Adaptive learning system for task optimization
+- **Advanced AI**: AI integration for decision making and coordination
+- **Distributed Consensus**: Consensus mechanism for agent coordination decisions
+
+### Security
+- **JWT Authentication**: Token-based authentication for API access
+- **Password Management**: Secure password handling and validation
+- **API Key Management**: API key generation and validation
+- **Role-Based Access Control**: Fine-grained permissions and roles
+- **Security Headers**: Security middleware for HTTP headers
+
+### Monitoring
+- **Prometheus Metrics**: Performance metrics and monitoring
+- **Performance Monitor**: Real-time performance tracking
+- **Alert Manager**: Alerting system for critical events
+- **SLA Monitor**: Service Level Agreement monitoring
+
+## Quick Start (End Users)
+
+### Prerequisites
+- Python 3.13+
+- PostgreSQL database
+- Redis for caching
+- Valid JWT token or API key
+
+### Installation
+```bash
+cd /opt/aitbc/apps/agent-coordinator
+.venv/bin/pip install -r requirements.txt
+```
+
+### Configuration
+Set environment variables in `.env`:
+```bash
+DATABASE_URL=postgresql://user:pass@localhost/agent_coordinator
+REDIS_URL=redis://localhost:6379
+JWT_SECRET_KEY=your-secret-key
+API_KEY=your-api-key
+```
+
+### Running the Service
+```bash
+.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+## Developer Guide
+
+### Development Setup
+1. Clone the repository
+2. Create virtual environment: `python -m venv .venv`
+3. Install dependencies: `pip install -r requirements.txt`
+4. Set up local database: See config.py for database settings
+5. Run tests: `pytest tests/`
+
+### Project Structure
+```
+agent-coordinator/
+├── src/app/
+│   ├── ai/              # AI integration modules
+│   ├── auth/             # Authentication and authorization
+│   ├── consensus/        # Distributed consensus
+│   ├── coordination/     # Agent coordination logic
+│   ├── decision/         # Decision making modules
+│   ├── lifecycle/        # Agent lifecycle management
+│   ├── main.py           # FastAPI application
+│   ├── monitoring/       # Monitoring and metrics
+│   ├── protocols/        # Communication protocols
+│   └── routing/          # Agent discovery and routing
+├── tests/                # Test suite
+└── pyproject.toml        # Project configuration
+```
+
+### Testing
+```bash
+# Run all tests
+pytest tests/
+
+# Run specific test
+pytest tests/test_agent_registry.py
+
+# Run with coverage
+pytest --cov=src tests/
+```
+
+## API Reference
+
+### Agent Management
+
+#### Register Agent
+```http
+POST /api/v1/agents/register
+Content-Type: application/json
+Authorization: Bearer <jwt_token>
+
+{
+  "agent_id": "string",
+  "agent_type": "string",
+  "capabilities": ["string"],
+  "endpoint": "string"
+}
+```
+
+#### Discover Agents
+```http
+GET /api/v1/agents/discover
+Authorization: Bearer <jwt_token>
+```
+
+#### Get Agent Status
+```http
+GET /api/v1/agents/{agent_id}/status
+Authorization: Bearer <jwt_token>
+```
+
+### Task Management
+
+#### Submit Task
+```http
+POST /api/v1/tasks/submit
+Content-Type: application/json
+Authorization: Bearer <jwt_token>
+
+{
+  "task_type": "string",
+  "payload": {},
+  "priority": "high|medium|low",
+  "requirements": {}
+}
+```
+
+#### Get Task Status
+```http
+GET /api/v1/tasks/{task_id}/status
+Authorization: Bearer <jwt_token>
+```
+
+#### List Tasks
+```http
+GET /api/v1/tasks?status=pending&limit=10
+Authorization: Bearer <jwt_token>
+```
+
+### Load Balancing
+
+#### Get Load Balancer Status
+```http
+GET /api/v1/loadbalancer/status
+Authorization: Bearer <jwt_token>
+```
+
+#### Configure Load Balancing Strategy
+```http
+PUT /api/v1/loadbalancer/strategy
+Content-Type: application/json
+Authorization: Bearer <jwt_token>
+
+{
+  "strategy": "round_robin|least_loaded|weighted",
+  "parameters": {}
+}
+```
+
+## Configuration
+
+### Environment Variables
+- `DATABASE_URL`: PostgreSQL connection string
+- `REDIS_URL`: Redis connection string
+- `JWT_SECRET_KEY`: Secret key for JWT token signing
+- `API_KEY`: API key for service authentication
+- `LOG_LEVEL`: Logging level (default: INFO)
+- `AGENT_DISCOVERY_INTERVAL`: Interval for agent discovery (default: 30s)
+- `TASK_TIMEOUT`: Task timeout in seconds (default: 300)
+
+### Load Balancing Strategies
+- **Round Robin**: Distributes tasks evenly across agents
+- **Least Loaded**: Assigns tasks to the agent with lowest load
+- **Weighted**: Uses agent weights for task distribution
+
+## Troubleshooting
+
+**Agent not discovered**: Check agent registration endpoint and network connectivity.
+
+**Task distribution failures**: Verify load balancer configuration and agent availability.
+
+**Authentication errors**: Ensure JWT token is valid and not expired.
+
+**Database connection errors**: Check DATABASE_URL and database server status.
+
+## Security Notes
+
+- Never expose JWT_SECRET_KEY in production
+- Use HTTPS in production environments
+- Implement rate limiting for API endpoints
+- Regularly rotate API keys and JWT secrets
+- Monitor for unauthorized access attempts

docs/apps/coordinator/coordinator-api.md

@@ -0,0 +1,55 @@
+# Coordinator API
+
+## Purpose & Scope
+
+FastAPI service that accepts client compute jobs, matches miners, and tracks job lifecycle for the AITBC network.
+
+## Marketplace Extensions
+
+Stage 2 introduces public marketplace endpoints exposed under `/v1/marketplace`:
+
+- `GET /v1/marketplace/offers` – list available provider offers (filterable by status).
+- `GET /v1/marketplace/stats` – aggregated supply/demand metrics surfaced in the marketplace web dashboard.
+- `POST /v1/marketplace/bids` – accept bid submissions for matching (mock-friendly; returns `202 Accepted`).
+
+These endpoints serve the `apps/marketplace-web/` dashboard via `VITE_MARKETPLACE_DATA_MODE=live`.
+
+## Explorer Endpoints
+
+The coordinator now exposes read-only explorer data under `/v1/explorer` for `apps/explorer-web/` live mode:
+
+- `GET /v1/explorer/blocks` – block summaries derived from recent job activity.
+- `GET /v1/explorer/transactions` – transaction-like records for coordinator jobs.
+- `GET /v1/explorer/addresses` – aggregated address activity and balances.
+- `GET /v1/explorer/receipts` – latest job receipts (filterable by `job_id`).
+
+Set `VITE_DATA_MODE=live` and `VITE_COORDINATOR_API` in the explorer web app to consume these APIs.
+
+## Development Setup
+
+1. Create a virtual environment in `apps/coordinator-api/.venv`.
+2. Install dependencies listed in `pyproject.toml` once added.
+3. Run the FastAPI app via `uvicorn app.main:app --reload`.
+
+## Configuration
+
+Expects environment variables defined in `.env` (see `docs/bootstrap/coordinator_api.md`).
+
+### Signed receipts (optional)
+
+- Generate an Ed25519 key:
+  ```bash
+  python - <<'PY'
+  from nacl.signing import SigningKey
+  sk = SigningKey.generate()
+  print(sk.encode().hex())
+  PY
+  ```
+- Set `RECEIPT_SIGNING_KEY_HEX` in the `.env` file to the printed hex string to enable signed receipts returned by `/v1/miners/{job_id}/result` and retrievable via `/v1/jobs/{job_id}/receipt`.
+- Receipt history is available at `/v1/jobs/{job_id}/receipts` (requires client API key) and returns all stored signed payloads.
+- To enable coordinator attestations, set `RECEIPT_ATTESTATION_KEY_HEX` to a separate Ed25519 private key; responses include an `attestations` array alongside the miner signature.
+- Clients can verify `signature` objects using the `aitbc_crypto` package (see `protocols/receipts/spec.md`).
+
+## Systemd
+
+Service name: `aitbc-coordinator-api` (to be defined under `configs/systemd/`).