feat: organize documentation into logical subdirectories

✅ Created organized project documentation structure - project/ai-economics/: AI Economics Masters documentation - project/cli/: Command-line interface documentation - project/infrastructure/: System infrastructure and deployment docs - project/requirements/: Project requirements and migration docs - project/completion/: 100% project completion summary - project/workspace/: Workspace strategy and organization ✅ Updated MASTER_INDEX.md to reflect new organization - Added project documentation section with detailed breakdown - Updated navigation to include new subdirectory structure - Maintained existing documentation hierarchy ✅ Updated project/README.md for new organization - Complete project documentation overview - Directory structure explanation - Quick access guide for each subdirectory - Links to related documentation 📊 Documentation Organization Results: - 10 files moved into 6 logical subdirectories - Improved navigation and discoverability - Maintained all existing content and links - Enhanced project documentation structure 🎯 Documentation Status: 100% Organized and Complete
2026-04-02 15:51:32 +02:00
parent eac687bfb5
commit 17839419b7
12 changed files with 107 additions and 291 deletions
--- a/docs/project/cli/CLI_DOCUMENTATION.md
+++ b/docs/project/cli/CLI_DOCUMENTATION.md
@@ -0,0 +1,433 @@
+# AITBC CLI Documentation
+
+**Project Status**: ✅ **100% COMPLETED** (v0.3.0 - April 2, 2026)
+
+## Overview
+
+The AITBC CLI (Command Line Interface) is a comprehensive tool for managing the AITBC blockchain network, AI operations, marketplace interactions, agent workflows, and advanced economic intelligence operations. With the 100% project completion, the CLI now provides complete system management capabilities with enterprise-grade security, monitoring, and type safety.
+
+## 🎉 **100% Project Completion Status**
+
+### **✅ All CLI Systems: Fully Operational**
+- **System Architecture Commands**: FHS compliance and directory management
+- **Service Management Commands**: Single marketplace service control
+- **Security Commands**: JWT authentication and API key management
+- **Agent System Commands**: Multi-agent coordination and AI/ML operations
+- **API Commands**: 17 endpoints with full functionality
+- **Test Commands**: Comprehensive test suite execution
+- **Monitoring Commands**: Prometheus metrics and alerting
+- **Type Safety Commands**: MyPy checking and validation
+
+### **🚀 Production CLI Features**
+- **Authentication Management**: JWT token operations
+- **Service Control**: Start/stop/restart services
+- **Monitoring**: Real-time metrics and health checks
+- **Security**: API key generation and validation
+- **Testing**: Complete test suite execution
+- **System Status**: Comprehensive system health reporting
+
+## 🚀 **New in v0.3.0: Complete System Integration**
+
+### **Enterprise Security Commands**
+- **JWT Authentication**: Token generation, validation, refresh
+- **RBAC Management**: Role assignment and permission control
+- **API Key Management**: Generation, validation, revocation
+- **Rate Limiting**: User-specific quota management
+
+### **Production Monitoring Commands**
+- **Metrics Collection**: Prometheus metrics retrieval
+- **Alert Management**: Rule configuration and notification setup
+- **SLA Monitoring**: Compliance tracking and reporting
+- **Health Monitoring**: System and service health checks
+
+### **Type Safety Commands**
+- **MyPy Checking**: Strict type validation
+- **Coverage Reports**: Type coverage analysis
+- **Code Quality**: Formatting and linting
+
+## Installation
+
+### Prerequisites
+- Python 3.13+
+- Virtual environment at `/opt/aitbc/venv`
+- AITBC services running on ports 8000, 8001, 8006
+
+### Setup
+```bash
+cd /opt/aitbc
+source venv/bin/activate
+./aitbc-cli --version
+```
+
+## Command Structure
+
+### Core Commands
+
+#### Wallet Management
+```bash
+# Create new wallet
+./aitbc-cli create --name wallet-name --password your-password
+
+# List all wallets
+./aitbc-cli list
+
+# Get wallet balance
+./aitbc-cli balance --name wallet-name
+
+# Send AIT
+./aitbc-cli send --from from-wallet --to to-wallet --amount 100 --password your-password
+
+# Get wallet transactions
+./aitbc-cli transactions --name wallet-name --limit 10
+```
+
+#### Blockchain Operations
+```bash
+# Get blockchain information
+./aitbc-cli chain [--rpc-url http://localhost:8006]
+
+# Get network status
+./aitbc-cli network
+
+# Get blockchain analytics
+./aitbc-cli analytics
+```
+
+#### AI Operations
+```bash
+# Submit AI job
+./aitbc-cli ai-submit --wallet wallet-name --type inference --prompt "Generate image" --payment 100
+
+# Check AI job status
+./aitbc-cli ai-ops --action status --job-id job-id
+
+# Get AI job results
+./aitbc-cli ai-ops --action results --job-id job-id
+
+# Advanced AI Operations - Phase 1 Completed
+./aitbc-cli ai-submit --wallet genesis-ops --type parallel --prompt "Complex AI pipeline for medical diagnosis" --payment 500
+./aitbc-cli ai-submit --wallet genesis-ops --type ensemble --prompt "Parallel AI processing with ensemble validation" --payment 600
+
+# Advanced AI Operations - Phase 2 Completed
+./aitbc-cli ai-submit --wallet genesis-ops --type multimodal --prompt "Multi-modal customer feedback analysis with cross-modal attention" --payment 1000
+./aitbc-cli ai-submit --wallet genesis-ops --type fusion --prompt "Cross-modal fusion with joint reasoning and consensus validation" --payment 1200
+
+# Advanced AI Operations - Phase 3 Completed
+./aitbc-cli ai-submit --wallet genesis-ops --type resource-allocation --prompt "Dynamic resource allocation system with GPU pools and demand forecasting" --payment 800
+./aitbc-cli ai-submit --wallet genesis-ops --type performance-tuning --prompt "AI performance optimization for sub-100ms inference latency" --payment 1000
+```
+
+#### Marketplace Operations
+```bash
+# List marketplace items
+./aitbc-cli marketplace --action list
+
+# Create marketplace listing
+./aitbc-cli marketplace --action create --name "Service Name" --price 100 --description "Description" --wallet wallet-name
+
+# Search marketplace
+./aitbc-cli marketplace --action search --query "search term"
+
+# View my listings
+./aitbc-cli marketplace --action my-listings --wallet wallet-name
+```
+
+#### Resource Management
+```bash
+# Get resource status
+./aitbc-cli resource --action status
+
+# Allocate resources
+./aitbc-cli resource --action allocate --agent-id agent-name --cpu 4 --memory 8192 --duration 3600
+```
+
+#### Mining Operations
+```bash
+# Start mining
+./aitbc-cli mine-start
+
+# Stop mining
+./aitbc-cli mine-stop
+
+# Check mining status
+./aitbc-cli mine-status
+```
+
+### Advanced Commands
+
+#### Agent Operations
+```bash
+# Run agent workflow
+./aitbc-cli agent --agent agent-name --message "Task description" --thinking high
+
+# OpenClaw operations
+./aitbc-cli openclaw --action status
+```
+
+#### Workflow Operations
+```bash
+# Run workflow
+./aitbc-cli workflow --name workflow-name --parameters "param1=value1,param2=value2"
+```
+
+#### Simulation Commands
+```bash
+# Simulate blockchain
+./aitbc-cli simulate blockchain --blocks 10 --transactions 50 --delay 1.0
+
+# Simulate wallets
+./aitbc-cli simulate wallets --wallets 5 --balance 1000 --transactions 20
+
+# Simulate price movements
+./aitbc-cli simulate price --price 100 --volatility 0.05 --timesteps 100
+
+# Simulate network
+./aitbc-cli simulate network --nodes 3 --network-delay 0.1 --failure-rate 0.05
+
+# Simulate AI jobs
+./aitbc-cli simulate ai-jobs --jobs 10 --models "text-generation,image-generation" --duration-range "30-300"
+```
+
+## Configuration
+
+### Environment Variables
+```bash
+export AITBC_COORDINATOR_URL="http://localhost:8000"
+export AITBC_API_KEY="your-api-key"
+export AITBC_RPC_URL="http://localhost:8006"
+```
+
+### Configuration File
+The CLI uses configuration from `/etc/aitbc/.env` by default.
+
+### Command Line Options
+```bash
+# Output format
+./aitbc-cli --output table|json|yaml|csv command
+
+# Verbose output
+./aitbc-cli --verbose command
+
+# Debug mode
+./aitbc-cli --debug command
+
+# Test mode
+./aitbc-cli --test-mode command
+
+# Dry run
+./aitbc-cli --dry-run command
+
+# Custom timeout
+./aitbc-cli --timeout 60 command
+
+# Skip SSL verification (testing only)
+./aitbc-cli --no-verify command
+```
+
+## Service Integration
+
+### Service Endpoints
+- **Coordinator API**: http://localhost:8000
+- **Exchange API**: http://localhost:8001
+- **Blockchain RPC**: http://localhost:8006
+- **Ollama**: http://localhost:11434
+
+### Health Checks
+```bash
+# Check all services
+curl -s http://localhost:8000/health
+curl -s http://localhost:8001/api/health
+curl -s http://localhost:8006/health
+curl -s http://localhost:11434/api/tags
+```
+
+## Examples
+
+### Basic Workflow
+```bash
+# 1. Create wallet
+./aitbc-cli create --name my-wallet --password my-password
+
+# 2. Fund wallet (from existing wallet)
+./aitbc-cli send --from genesis-ops --to my-wallet --amount 1000 --password 123
+
+# 3. Submit AI job
+./aitbc-cli ai-submit --wallet my-wallet --type inference --prompt "Generate a landscape image" --payment 50
+
+# 4. Check job status
+./aitbc-cli ai-ops --action status --job-id latest
+
+# 5. Get results
+./aitbc-cli ai-ops --action results --job-id latest
+```
+
+### Marketplace Operations
+```bash
+# 1. Create service listing
+./aitbc-cli marketplace --action create --name "AI Image Generation" --price 100 --description "High-quality image generation service" --wallet provider-wallet
+
+# 2. List available services
+./aitbc-cli marketplace --action list
+
+# 3. Bid on service
+./aitbc-cli marketplace --action bid --service-id service-id --amount 120 --wallet customer-wallet
+
+# 4. Accept bid
+./aitbc-cli marketplace --action accept-bid --service-id service-id --bid-id bid-id --wallet provider-wallet
+```
+
+### Simulation Examples
+```bash
+# Simulate blockchain with 100 blocks
+./aitbc-cli simulate blockchain --blocks 100 --transactions 100 --delay 0.1
+
+# Simulate price volatility
+./aitbc-cli simulate price --price 100 --volatility 0.1 --timesteps 1000
+
+# Simulate network failures
+./aitbc-cli simulate network --nodes 5 --failure-rate 0.1 --network-delay 0.5
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Command Not Found
+```bash
+# Check CLI installation
+./aitbc-cli --version
+
+# Check virtual environment
+source venv/bin/activate
+```
+
+#### Service Connection Errors
+```bash
+# Check service status
+systemctl status aitbc-coordinator-api.service
+systemctl status aitbc-exchange-api.service
+systemctl status aitbc-blockchain-node.service
+
+# Check network connectivity
+curl -s http://localhost:8000/health
+```
+
+#### Permission Errors
+```bash
+# Check file permissions
+ls -la /opt/aitbc/aitbc-cli
+
+# Fix permissions
+chmod +x /opt/aitbc/aitbc-cli
+```
+
+### Debug Mode
+```bash
+# Enable debug output
+./aitbc-cli --debug --verbose command
+
+# Test with mock data
+./aitbc-cli --test-mode command
+```
+
+## Development
+
+### Running Tests
+```bash
+# Run all tests
+cd /opt/aitbc
+source venv/bin/activate
+python -m pytest cli/tests/ -v
+
+# Run specific test
+python -m pytest cli/tests/test_cli_comprehensive.py::TestSimulateCommand -v
+
+# Run with coverage
+python -m pytest cli/tests/ --cov=cli --cov-report=html
+```
+
+### Adding New Commands
+1. Create command file in `cli/aitbc_cli/commands/`
+2. Import command in `cli/core/main.py`
+3. Add tests in `cli/tests/`
+4. Update documentation
+
+### Code Style
+```bash
+# Format code
+black cli/
+
+# Lint code
+flake8 cli/
+
+# Type checking
+mypy cli/
+```
+
+## API Reference
+
+### Command Options
+
+#### Global Options
+- `--url`: Override coordinator URL
+- `--api-key`: Set API key
+- `--output`: Set output format (table, json, yaml, csv)
+- `--verbose`: Increase verbosity
+- `--debug`: Enable debug mode
+- `--test-mode`: Use test endpoints
+- `--dry-run`: Show what would be done
+- `--timeout`: Set request timeout
+- `--no-verify`: Skip SSL verification
+
+#### Command-Specific Options
+Each command has specific options documented in the help:
+```bash
+./aitbc-cli command --help
+```
+
+### Exit Codes
+- `0`: Success
+- `1`: General error
+- `2`: Command line error
+
+## Version History
+
+### v0.2.2 (Current)
+- Unified CLI with 20+ commands
+- Enhanced output formatting
+- AI operations integration
+- Marketplace functionality
+- Resource management
+- Simulation commands
+- OpenClaw agent integration
+
+### v0.2.1
+- Project consolidation to `/opt/aitbc`
+- Enhanced service integration
+- Improved error handling
+
+### v0.2.0
+- Modular command structure
+- Enhanced configuration management
+- Performance improvements
+
+### v0.1.0
+- Initial CLI implementation
+- Basic wallet and blockchain operations
+
+## Support
+
+For issues and questions:
+1. Check troubleshooting section
+2. Run with `--debug --verbose` for detailed output
+3. Check service health status
+4. Review logs in `/var/log/aitbc/`
+
+## Contributing
+
+1. Fork the repository
+2. Create feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Update documentation
+6. Submit pull request