docs: consolidate CLI documentation and purge legacy structure

MERGE OPERATIONS:
- Merged /opt/aitbc/cli/docs into /opt/aitbc/docs/cli
- Eliminated duplicate CLI documentation locations
- Created single source of truth for CLI docs

ORGANIZATION IMPROVEMENTS:
- Created structured subdirectories:
  • implementation/ - Core implementation summaries
  • analysis/ - Analysis reports and integration summaries
  • guides/ - Installation and setup guides
  • legacy/ - Historical documentation (archived)

- Updated main README.md with:
  • New consolidated structure overview
  • Updated installation instructions for flat CLI structure
  • Recent CLI design principles changes
  • Proper navigation to subdirectories

- Created legacy/README.md with:
  • Clear deprecation notice
  • File categorization
  • Purge candidates identification
  • Migration notes from old to new structure

FILE MOVES:
- 15 implementation summaries → implementation/
- 5 analysis reports → analysis/
- 3 setup guides → guides/
- 19 legacy documented files → legacy/
- 1 demonstration file → root (active reference)

PROJECT DOCUMENTATION UPDATES:
- Updated /docs/beginner/02_project/1_files.md
- Reflected flattened CLI structure (cli/commands/ vs cli/aitbc_cli/commands/)
- Added docs/cli/ as consolidated documentation location
- Updated Python version requirement to 3.13.5 only

BENEFITS:
- Single location for all CLI documentation
- Clear separation of current vs legacy information
- Better organization and discoverability
- Easier maintenance and updates
- Proper archival of historical documentation

STATUS:
✅ Consolidation complete
✅ Legacy properly archived
✅ Structure organized
✅ Documentation updated

docs/beginner/02_project/1_files.md

@@ -105,22 +105,23 @@ Last updated: 2026-03-25
 
 | Path | Status | Notes |
 |------|--------|-------|
-| `cli/aitbc_cli/commands/client.py` | ✅ Active | Client CLI (submit, batch-submit, templates, history) |
+| `cli/commands/client.py` | ✅ Active | Client CLI (submit, batch-submit, templates, history) |
-| `cli/aitbc_cli/commands/miner.py` | ✅ Active | Miner CLI (register, earnings, capabilities, concurrent) |
+| `cli/commands/miner.py` | ✅ Active | Miner CLI (register, earnings, capabilities, concurrent) |
-| `cli/aitbc_cli/commands/wallet.py` | ✅ Active | Wallet CLI (balance, staking, multisig, backup/restore) |
+| `cli/commands/wallet.py` | ✅ Active | Wallet CLI (balance, staking, multisig, backup/restore) |
-| `cli/aitbc_cli/commands/auth.py` | ✅ Active | Auth CLI (login, tokens, API keys) |
+| `cli/commands/auth.py` | ✅ Active | Auth CLI (login, tokens, API keys) |
-| `cli/aitbc_cli/commands/blockchain.py` | ✅ Active | Blockchain queries |
+| `cli/commands/blockchain.py` | ✅ Active | Blockchain queries |
-| `cli/aitbc_cli/commands/marketplace.py` | ✅ Active | GPU marketplace operations |
+| `cli/commands/marketplace.py` | ✅ Active | GPU marketplace operations |
-| `cli/aitbc_cli/commands/admin.py` | ✅ Active | System administration, audit logging |
+| `cli/commands/admin.py` | ✅ Active | System administration, audit logging |
-| `cli/aitbc_cli/commands/config.py` | ✅ Active | Configuration, profiles, encrypted secrets |
+| `cli/commands/config.py` | ✅ Active | Configuration, profiles, encrypted secrets |
-| `cli/aitbc_cli/commands/monitor.py` | ✅ Active | Dashboard, metrics, alerts, webhooks |
+| `cli/commands/monitor.py` | ✅ Active | Dashboard, metrics, alerts, webhooks |
-| `cli/aitbc_cli/commands/simulate.py` | ✅ Active | Test simulation framework |
+| `cli/commands/simulate.py` | ✅ Active | Test simulation framework |
-| `cli/aitbc_cli/plugins.py` | ✅ Active | Plugin system for custom commands |
+| `cli/plugins.py` | ✅ Active | Plugin system for custom commands |
-| `cli/aitbc_cli/main.py` | ✅ Active | CLI entry point (12 command groups) |
+| `cli/main.py` | ✅ Active | CLI entry point (flattened structure, Mar 2026) |
 | `cli/man/aitbc.1` | ✅ Active | Man page |
 | `cli/aitbc_shell_completion.sh` | ✅ Active | Shell completion script |
 | `cli/test_ollama_gpu_provider.py` | ✅ Active | GPU testing |
-| `.github/workflows/cli-tests.yml` | ✅ Active | CI/CD for CLI tests (Python 3.11/3.12/3.13) |
+| `docs/cli/` | ✅ Active | Consolidated CLI documentation (Mar 2026) |
+| `.github/workflows/cli-tests.yml` | ✅ Active | CI/CD for CLI tests (Python 3.13.5 only) |
 
 ### Home Scripts (`home/`)
 

docs/cli/README.md

@@ -1,39 +1,107 @@
-# CLI Documentation
+# AITBC CLI Documentation
 
-**Generated**: 2026-03-08 13:06:38
+**Updated**: 2026-03-26  
-**Total Files**: 20
+**Status**: Active Development - CLI Design Principles Applied  
-**Documented Files**: 19
+**Structure**: Consolidated and Organized  
-**Other Files**: 1
 
-## Documented Files (Converted from Analysis)
+## 📁 Documentation Structure
 
-- [AITBC CLI Command Checklist](documented_AITBC_CLI_Command_Checklist.md)
+### 🚀 [Main CLI Guide](README.md)
-- [AITBC Exchange Infrastructure & Market Ecosystem Implementation Strategy](documented_AITBC_Exchange_Infrastructure___Market_Ecosystem_I.md)
+- Installation and setup
-- [API Endpoint Fixes Summary](documented_API_Endpoint_Fixes_Summary.md)
+- Quick start guide
-- [Advanced Analytics Platform - Technical Implementation Analysis](documented_Advanced_Analytics_Platform_-_Technical_Implementa.md)
+- Command reference
-- [Backend Implementation Status - March 5, 2026](documented_Backend_Implementation_Status_-_March_5__2026.md)
+- Configuration
-- [Blockchain Balance Multi-Chain Enhancement](documented_Blockchain_Balance_Multi-Chain_Enhancement.md)
-- [CLI Command Fixes Summary - March 5, 2026](documented_CLI_Command_Fixes_Summary_-_March_5__2026.md)
-- [CLI Help Availability Update Summary](documented_CLI_Help_Availability_Update_Summary.md)
-- [CLI Test Execution Results - March 5, 2026](documented_CLI_Test_Execution_Results_-_March_5__2026.md)
-- [Complete Multi-Chain Fixes Needed Analysis](documented_Complete_Multi-Chain_Fixes_Needed_Analysis.md)
-- [Current Issues - Phase 8: Global AI Power Marketplace Expansion](documented_Current_Issues_-_Phase_8__Global_AI_Power_Marketpl.md)
-- [Current Issues Update - Exchange Infrastructure Gap Identified](documented_Current_Issues_Update_-_Exchange_Infrastructure_Ga.md)
-- [Nginx Configuration Update Summary - March 5, 2026](documented_Nginx_Configuration_Update_Summary_-_March_5__2026.md)
-- [Phase 1 Multi-Chain Enhancement Completion](documented_Phase_1_Multi-Chain_Enhancement_Completion.md)
-- [Phase 2 Multi-Chain Enhancement Completion](documented_Phase_2_Multi-Chain_Enhancement_Completion.md)
-- [Phase 3 Multi-Chain Enhancement Completion](documented_Phase_3_Multi-Chain_Enhancement_Completion.md)
-- [Production Monitoring & Observability - Technical Implementation Analysis](documented_Production_Monitoring___Observability_-_Technical_.md)
-- [Real Exchange Integration - Technical Implementation Analysis](documented_Real_Exchange_Integration_-_Technical_Implementati.md)
-- [Trading Surveillance System - Technical Implementation Analysis](documented_Trading_Surveillance_System_-_Technical_Implementa.md)
 
-## Other Documentation Files
+### 📚 [Implementation Documentation](implementation/)
+- [Agent Communication Implementation](implementation/AGENT_COMMUNICATION_IMPLEMENTATION_SUMMARY.md)
+- [Analytics Implementation](implementation/ANALYTICS_IMPLEMENTATION_SUMMARY.md)  
+- [Deployment Implementation](implementation/DEPLOYMENT_IMPLEMENTATION_SUMMARY.md)
+- [Marketplace Implementation](implementation/MARKETPLACE_IMPLEMENTATION_SUMMARY.md)
+- [Multi-Chain Implementation](implementation/MULTICHAIN_IMPLEMENTATION_SUMMARY.md)
 
-- [CLI Documentation](README.md)
+### 📊 [Analysis & Reports](analysis/)
+- [CLI Wallet Daemon Integration](analysis/CLI_WALLET_DAEMON_INTEGRATION_SUMMARY.md)
+- [Implementation Complete Summary](analysis/IMPLEMENTATION_COMPLETE_SUMMARY.md)
+- [Localhost Only Enforcement](analysis/LOCALHOST_ONLY_ENFORCEMENT_SUMMARY.md)
+- [Node Integration](analysis/NODE_INTEGRATION_SUMMARY.md)
+- [Wallet Chain Connection](analysis/WALLET_CHAIN_CONNECTION_SUMMARY.md)
 
+### 🛠️ [Installation & Setup Guides](guides/)
+- [Quick Install Guide](guides/QUICK_INSTALL_GUIDE.md)
+- [Local Package README](guides/LOCAL_PACKAGE_README.md)
+- [CLI Test Results](guides/CLI_TEST_RESULTS.md)
 
-## Category Overview
+### 🗃️ [Legacy Documentation](legacy/)
-This section contains all documentation related to cli documentation. The documented files have been automatically converted from completed planning analysis files.
+Historical documentation from previous development phases. Retained for reference but may contain outdated information.
 
 ---
-*Auto-generated index*
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/aitbc/aitbc.git
+cd aitbc/cli
+
+# Install in development mode (flat structure)
+pip install -e .
+
+# Or use the virtual environment
+python3 -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+### Basic Usage
+
+```bash
+# Check CLI is working
+aitbc --help
+
+# Set up API key
+export AITBC_API_KEY=your_api_key_here
+aitbc config set api_key your_api_key_here
+
+# Check wallet balance
+aitbc wallet balance
+
+# Submit a job
+aitbc client submit --prompt "Generate an image" --model llama2
+
+# Check miner status
+aitbc miner status
+```
+
+---
+
+## 🎯 Recent Changes (2026-03-26)
+
+### ✅ CLI Design Principles Applied
+- **Removed embedded servers** - CLI now controls services instead of hosting them
+- **Flattened directory structure** - Eliminated "box in a box" nesting
+- **Simplified HTTP clients** - Replaced async pools with basic calls
+- **Removed blocking loops** - Single status checks instead of infinite monitoring
+- **No auto-opening browsers** - Provides URLs for user control
+- **Removed system calls** - CLI provides instructions instead of executing
+
+### 📁 Documentation Consolidation
+- **Merged** `/cli/docs` into `/docs/cli` for single source of truth
+- **Organized** into implementation, analysis, guides, and legacy sections
+- **Updated** installation instructions for flat structure
+- **Purged** duplicate and outdated documentation
+
+---
+
+## 🔗 Related Documentation
+
+- [Main AITBC Documentation](../README.md)
+- [Project File Structure](../1_project/1_files.md)
+- [Development Roadmap](../1_project/2_roadmap.md)
+
+---
+
+*Last updated: 2026-03-26*  
+*CLI Version: 0.2.0*  
+*Python: 3.13.5+*

docs/cli/legacy/README.md

@@ -0,0 +1,76 @@
+# Legacy Documentation
+
+**Status**: Archived - For Reference Only  
+**Last Updated**: Various dates (mostly March 2026)  
+**Purpose**: Historical documentation from previous development phases
+
+## ⚠️ Important Notice
+
+This documentation contains **outdated information** and may reference:
+- Old CLI structures (before flattening)
+- Removed features (embedded servers, blocking loops)
+- Deprecated commands
+- Previous implementation approaches
+
+**For current documentation, see the parent directory.**
+
+---
+
+## 📂 Legacy Files
+
+### Phase Documentation (March 2026)
+- `Phase_1_Multi-Chain_Enhancement_Completion.md`
+- `Phase_2_Multi-Chain_Enhancement_Completion.md` 
+- `Phase_3_Multi-Chain_Enhancement_Completion.md`
+
+### Issue Tracking
+- `Current_Issues_-_Phase_8__Global_AI_Power_Marketpl.md`
+- `Current_Issues_Update_-_Exchange_Infrastructure_Ga.md`
+- `Complete_Multi-Chain_Fixes_Needed_Analysis.md`
+
+### Technical Analysis
+- `documented_Advanced_Analytics_Platform_-_Technical_Implementa.md`
+- `documented_Production_Monitoring___Observability_-_Technical_.md`
+- `documented_Real_Exchange_Integration_-_Technical_Implementati.md`
+- `documented_Trading_Surveillance_System_-_Technical_Implementa.md`
+
+### Implementation Status
+- `documented_Backend_Implementation_Status_-_March_5__2026.md`
+- `documented_AITBC_Exchange_Infrastructure___Market_Ecosystem_I.md`
+
+### Quick Fixes & Updates
+- `documented_CLI_Command_Fixes_Summary_-_March_5__2026.md`
+- `documented_API_Endpoint_Fixes_Summary.md`
+- `documented_Nginx_Configuration_Update_Summary_-_March_5__2026.md`
+- `documented_CLI_Help_Availability_Update_Summary.md`
+- `documented_CLI_Test_Execution_Results_-_March_5__2026.md`
+- `documented_Blockchain_Balance_Multi-Chain_Enhancement.md`
+
+### Checklists & Reference
+- `documented_AITBC_CLI_Command_Checklist.md`
+
+---
+
+## 🗑️ Purge Candidates
+
+The following files are likely candidates for removal in future cleanup:
+
+- **Phase completion files** - Historical milestones completed
+- **Issue tracking files** - Issues likely resolved in current implementation
+- **Quick fix summaries** - Temporary fixes now integrated
+- **Old implementation analysis** - Superseded by current implementation
+
+---
+
+## 🔍 Migration Notes
+
+Key changes from legacy to current implementation:
+
+1. **CLI Structure**: Flattened from `cli/aitbc_cli/` to `cli/`
+2. **Design Principles**: Removed embedded servers, blocking loops, system calls
+3. **Dependencies**: Simplified from async pools to basic HTTP clients
+4. **Documentation**: Consolidated and organized by category
+
+---
+
+*This folder is maintained for historical reference only. Current development documentation is in the parent directories.*