docs-validation: expand curated markdown scope to include all documentation hubs

Add all documentation subdirectories to the curated markdown linting targets, replacing the previous exclusion-based approach with comprehensive coverage. Update validation to check for required README files across all hubs and verify priority documentation metadata markers. Implement lazy loading for optional dependencies (numpy, redis, bcrypt, jwt, websockets) in agent-coordinator and related modules to improve startup

.gitea/workflows/docs-validation.yml

@@ -55,18 +55,41 @@ jobs:
             targets=(
               *.md
               docs/*.md
+              docs/about/**/*.md
               docs/11_agents/**/*.md
               docs/agent-sdk/**/*.md
+              docs/advanced/**/*.md
+              docs/analytics/**/*.md
+              docs/apps/**/*.md
+              docs/archive/**/*.md
+              docs/backend/**/*.md
+              docs/beginner/**/*.md
               docs/blockchain/**/*.md
+              docs/completed/**/*.md
+              docs/contracts/**/*.md
               docs/deployment/**/*.md
               docs/development/**/*.md
+              docs/exchange/**/*.md
+              docs/expert/**/*.md
               docs/general/**/*.md
               docs/governance/**/*.md
+              docs/guides/**/*.md
               docs/implementation/**/*.md
               docs/infrastructure/**/*.md
+              docs/intermediate/**/*.md
+              docs/mobile/**/*.md
+              docs/nodes/**/*.md
+              docs/maintenance/**/*.md
               docs/openclaw/**/*.md
               docs/policies/**/*.md
+              docs/reference/**/*.md
+              docs/releases/**/*.md
+              docs/reports/**/*.md
+              docs/project/**/*.md
               docs/security/**/*.md
+              docs/summaries/**/*.md
+              docs/trail/**/*.md
+              docs/website/**/*.md
               docs/workflows/**/*.md
             )
 
@@ -74,7 +97,7 @@ jobs:
               echo "⚠️ No curated Markdown targets matched"
             else
               echo "Curated advisory scope: ${#targets[@]} Markdown files"
-              echo "Excluded high-noise areas: about, advanced, archive, backend, beginner, completed, expert, intermediate, project, reports, summaries, trail"
+              echo "Included the docs home, about hub, learning paths, and the top-level operational hubs added during remediation"
               markdownlint "${targets[@]}" --ignore "node_modules/**" || echo "⚠️ Markdown linting warnings in curated docs scope"
             fi
           else
@@ -86,14 +109,97 @@ jobs:
         run: |
           cd /var/lib/aitbc-workspaces/docs-validation/repo
           echo "=== Documentation Structure ==="
-          for f in docs/README.md docs/MASTER_INDEX.md; do
+          required_files=(
+            docs/README.md
+            docs/MASTER_INDEX.md
+            docs/about/README.md
+            docs/11_agents/README.md
+            docs/advanced/README.md
+            docs/analytics/README.md
+            docs/agent-sdk/README.md
+            docs/apps/README.md
+            docs/archive/README.md
+            docs/backend/README.md
+            docs/beginner/README.md
+            docs/completed/README.md
+            docs/blockchain/README.md
+            docs/contracts/README.md
+            docs/deployment/README.md
+            docs/development/README.md
+            docs/exchange/README.md
+            docs/expert/README.md
+            docs/general/README.md
+            docs/guides/README.md
+            docs/governance/README.md
+            docs/implementation/README.md
+            docs/infrastructure/README.md
+            docs/intermediate/README.md
+            docs/maintenance/README.md
+            docs/mobile/README.md
+            docs/nodes/README.md
+            docs/openclaw/README.md
+            docs/packages/README.md
+            docs/policies/README.md
+            docs/project/README.md
+            docs/reference/README.md
+            docs/releases/README.md
+            docs/reports/README.md
+            docs/security/README.md
+            docs/summaries/README.md
+            docs/trail/README.md
+            docs/website/README.md
+            docs/workflows/README.md
+          )
+
+          for f in "${required_files[@]}"; do
             if [[ -f "$f" ]]; then
-              echo "  ✅ $f exists"
+              echo "  $f exists"
             else
+              echo "  $f missing"
               echo "  ❌ $f missing"
+              exit 1
             fi
           done
 
+      - name: Validate priority docs metadata
+        run: |
+          cd /var/lib/aitbc-workspaces/docs-validation/repo
+          echo "=== Priority Documentation Metadata ==="
+
+          priority_docs=(
+            docs/README.md
+            docs/MASTER_INDEX.md
+            docs/beginner/README.md
+            docs/intermediate/README.md
+            docs/expert/README.md
+          )
+
+          required_markers=(
+            "## 🧭 **Navigation Path:**"
+            "## 🎯 **See Also:**"
+            "**Level**:"
+            "**Prerequisites**:"
+            "**Estimated Time**:"
+            "**Last Updated**:"
+            "**Version**:"
+          )
+
+          for f in "${priority_docs[@]}"; do
+            if [[ ! -f "$f" ]]; then
+              echo "  ❌ $f missing"
+              exit 1
+            fi
+
+            for marker in "${required_markers[@]}"; do
+              if ! grep -qF "$marker" "$f"; then
+                echo "  ❌ $f missing required marker: $marker"
+                exit 1
+              fi
+            done
+          done
+
+          echo "✅ Priority documentation metadata validated"
+
       - name: Documentation stats
         if: always()
         run: |

apps/agent-coordinator/src/app/ai/advanced_ai.py

@@ -3,8 +3,13 @@ Advanced AI/ML Integration for AITBC Agent Coordinator
 Implements machine learning models, neural networks, and intelligent decision making
 """
 
+from __future__ import annotations
+
 import asyncio
-import numpy as np
+try:
+    import numpy as np
+except ImportError:  # pragma: no cover - optional dependency for runtime AI features
+    np = None
 from datetime import datetime, timedelta
 from typing import Dict, List, Any, Optional, Tuple
 from dataclasses import dataclass, field

apps/agent-coordinator/src/app/auth/jwt_handler.py

@@ -3,8 +3,6 @@ JWT Authentication Handler for AITBC Agent Coordinator
 Implements JWT token generation, validation, and management
 """
 
-import jwt
-import bcrypt
 from datetime import datetime, timedelta
 from typing import Dict, Any, Optional, List
 import secrets
@@ -24,6 +22,8 @@ class JWTHandler:
         
     def generate_token(self, payload: Dict[str, Any], expires_delta: timedelta = None) -> Dict[str, Any]:
         """Generate JWT token with specified payload"""
+        import jwt
+
         try:
             if expires_delta:
                 expire = datetime.utcnow() + expires_delta
@@ -54,6 +54,8 @@ class JWTHandler:
     
     def generate_refresh_token(self, payload: Dict[str, Any]) -> Dict[str, Any]:
         """Generate refresh token for token renewal"""
+        import jwt
+
         try:
             expire = datetime.utcnow() + self.refresh_expiry
             
@@ -78,6 +80,8 @@ class JWTHandler:
     
     def validate_token(self, token: str) -> Dict[str, Any]:
         """Validate JWT token and return payload"""
+        import jwt
+
         try:
             # Decode and validate token
             payload = jwt.decode(
@@ -143,6 +147,8 @@ class JWTHandler:
     
     def decode_token_without_validation(self, token: str) -> Dict[str, Any]:
         """Decode token without expiration validation (for debugging)"""
+        import jwt
+
         try:
             payload = jwt.decode(
                 token, 
@@ -168,6 +174,8 @@ class PasswordManager:
     @staticmethod
     def hash_password(password: str) -> Dict[str, Any]:
         """Hash password using bcrypt"""
+        import bcrypt
+
         try:
             # Generate salt and hash password
             salt = bcrypt.gensalt()
@@ -185,9 +193,10 @@ class PasswordManager:
     
     @staticmethod
     def verify_password(password: str, hashed_password: str) -> Dict[str, Any]:
-        """Verify password against hashed password"""
+        """Verify password against hash"""
         try:
-            # Check password
+            import bcrypt
+
             hashed_bytes = hashed_password.encode('utf-8')
             password_bytes = password.encode('utf-8')
             

apps/agent-coordinator/src/app/lifespan.py

@@ -5,10 +5,6 @@ from aitbc import get_logger
 from fastapi import FastAPI
 
 from . import state
-from .protocols.communication import CommunicationManager
-from .protocols.message_types import MessageProcessor
-from .routing.agent_discovery import AgentDiscoveryService, AgentRegistry
-from .routing.load_balancer import LoadBalancer, LoadBalancingStrategy, TaskDistributor
 
 logger = get_logger(__name__)
 
@@ -17,6 +13,11 @@ logger = get_logger(__name__)
 async def lifespan(app: FastAPI):
     logger.info("Starting AITBC Agent Coordinator...")
 
+    from .protocols.communication import CommunicationManager
+    from .protocols.message_types import MessageProcessor
+    from .routing.agent_discovery import AgentDiscoveryService, AgentRegistry
+    from .routing.load_balancer import LoadBalancer, LoadBalancingStrategy, TaskDistributor
+
     state.agent_registry = AgentRegistry()
     await state.agent_registry.start()
 

apps/agent-coordinator/src/app/protocols/communication.py

@@ -9,7 +9,6 @@ from typing import Dict, List, Optional, Any, Callable
 from dataclasses import dataclass, field
 from datetime import datetime
 import uuid
-import websockets
 from pydantic import BaseModel, Field
 
 from aitbc import get_logger
@@ -338,6 +337,8 @@ class WebSocketHandler:
         
     async def handle_connection(self, websocket, agent_id: str):
         """Handle WebSocket connection from agent"""
+        import websockets
+
         self.websocket_connections[agent_id] = websocket
         logger.info(f"WebSocket connection established for agent {agent_id}")
         

apps/agent-coordinator/src/app/routing/agent_discovery.py

@@ -2,6 +2,8 @@
 Agent Discovery and Registration System for AITBC Agent Coordination
 """
 
+from __future__ import annotations
+
 import asyncio
 import json
 from typing import Dict, List, Optional, Set, Callable, Any
@@ -10,7 +12,10 @@ from datetime import datetime, timedelta
 import uuid
 import hashlib
 from enum import Enum
-import redis.asyncio as redis
+try:
+    import redis.asyncio as redis
+except ImportError:  # pragma: no cover - optional dependency for runtime agent registry
+    redis = None
 from pydantic import BaseModel, Field
 
 from aitbc import get_logger

apps/agent-coordinator/src/app/state.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
-from typing import Optional
+from typing import TYPE_CHECKING, Optional
 
-from .protocols.communication import CommunicationManager
-from .protocols.message_types import MessageProcessor
-from .routing.agent_discovery import AgentDiscoveryService, AgentRegistry
-from .routing.load_balancer import LoadBalancer, TaskDistributor
+if TYPE_CHECKING:
+    from .protocols.communication import CommunicationManager
+    from .protocols.message_types import MessageProcessor
+    from .routing.agent_discovery import AgentDiscoveryService, AgentRegistry
+    from .routing.load_balancer import LoadBalancer, TaskDistributor
 
 agent_registry: Optional[AgentRegistry] = None
 discovery_service: Optional[AgentDiscoveryService] = None

apps/wallet/src/app/models/__init__.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from typing import Any, Dict, List, Optional
 
-from aitbc_sdk import SignatureValidation
+from aitbc_sdk.receipts import SignatureValidation
 
 from pydantic import BaseModel
 

apps/wallet/src/app/receipts/service.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import List, Optional
 
-from aitbc_sdk import (
+from aitbc_sdk.receipts import (
     CoordinatorReceiptClient,
     ReceiptVerification,
     SignatureValidation,

cli/aitbc_cli.py

@@ -37,12 +37,13 @@ import requests
 from typing import Optional, Dict, Any, List
 
 # Import shared modules
-from aitbc import (
-    KEYSTORE_DIR, BLOCKCHAIN_RPC_PORT, DATA_DIR,
-    AITBCHTTPClient, NetworkError, ValidationError, ConfigurationError,
-    get_logger, get_keystore_path, ensure_dir, validate_address, validate_url
-)
+from aitbc.aitbc_logging import get_logger
+from aitbc.constants import BLOCKCHAIN_RPC_PORT, DATA_DIR, KEYSTORE_DIR
+from aitbc.exceptions import ConfigurationError, NetworkError, ValidationError
+from aitbc.http_client import AITBCHTTPClient
 from aitbc.paths import get_blockchain_data_path, get_data_path
+from aitbc.paths import ensure_dir, get_keystore_path
+from aitbc.validation import validate_address, validate_url
 
 # Initialize logger
 logger = get_logger(__name__)

cli/docs/README.md

@@ -1,15 +1,73 @@
-# AITBC CLI
+# AITBC CLI Technical Documentation
 
-Command Line Interface for AITBC Network
+**Level**: Intermediate<br>
+**Prerequisites**: Basic CLI familiarity, shell usage, and AITBC project context<br>
+**Estimated Time**: 10-15 minutes<br>
+**Last Updated**: 2026-04-27<br>
+**Version**: 1.0
 
-## Installation
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **👛 CLI Technical** → *You are here*
+
+**breadcrumb**: Home → CLI Technical → Overview
+
+---
+
+## 🎯 **See Also:**
+- **📚 Docs Home**: [Documentation Home](../README.md) - Main docs landing page
+- **📖 About Docs**: [About Documentation](../about/README.md) - Template standard and audit checklist
+- **🎯 Beginner CLI**: [Beginner Documentation](../beginner/README.md) - CLI basics and user workflows
+- **🧪 Testing Docs**: [Testing Documentation](../testing/README.md) - Validation and regression testing
+- **📋 Project Docs**: [Project Documentation](../project/README.md) - Project context
+
+---
+
+## 📚 **What lives here**
+
+This directory provides the technical CLI entry point mirrored by the top-level docs symlink.
+It contains installation and usage notes for the AITBC CLI and related technical references.
+
+---
+
+## 🚀 **Quick Start**
+
+### Installation
 
 ```bash
 pip install -e .
 ```
 
-## Usage
+### Usage
 
 ```bash
 aitbc --help
 ```
+
+---
+
+## 🔗 **Related Resources**
+
+### 📚 **Further Reading:**
+- [Documentation Home](../README.md) - Main docs landing page
+- [About Documentation](../about/README.md) - Template standard and audit checklist
+- [Beginner Documentation](../beginner/README.md) - CLI basics and user workflows
+- [Testing Documentation](../testing/README.md) - Validation and regression testing
+
+### 🆘 **Help & Support:**
+- **Documentation Issues**: [Report Issues](https://github.com/oib/AITBC/issues)
+- **Community Forum**: [AITBC Forum](https://forum.aitbc.net)
+- **Technical Support**: [AITBC Support](https://support.aitbc.net)
+
+---
+
+## 📊 **Quality Metrics**
+- **Structure**: 10/10 - Template-compliant landing page with clear navigation.
+- **Content**: 10/10 - Short and focused CLI technical entry point.
+- **Navigation**: 10/10 - Links to the docs home, beginner CLI, and testing docs.
+- **Status**: Active index page.
+
+---
+
+*Last updated: 2026-04-27*<br>
+*Version: 1.0*<br>
+*Status: Active index for CLI technical documentation*

cli/unified_cli.py

@@ -790,9 +790,16 @@ def handle_bridge_restart(args):
     bridge_handlers.handle_bridge_restart(args)
 
 def main(argv=None):
-    from aitbc_cli import main as cli_main
+    import importlib.util
+    from pathlib import Path
 
-    return cli_main(argv)
+    cli_path = Path(__file__).with_name("aitbc_cli.py")
+    spec = importlib.util.spec_from_file_location("aitbc_cli_script_entry", cli_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Unable to load CLI entrypoint from {cli_path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.main(argv)
 
 
 if __name__ == "__main__":

contracts/docs/README.md

@@ -0,0 +1,57 @@
+# AITBC Contract Documentation
+
+**Level**: Advanced  
+**Prerequisites**: Beginner blockchain concepts, AITBC project documentation, and basic smart contract familiarity  
+**Estimated Time**: 20-40 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **📜 Contracts** → *You are here*
+
+**breadcrumb**: Home → Contracts → Overview
+
+---
+
+## 🎯 **See Also:**
+- **⛓️ Blockchain Docs**: [Blockchain Documentation](../blockchain/README.md) - Core chain implementation and operations
+- **🔒 Security Docs**: [Security Documentation](../security/README.md) - Security and verification context
+- **📋 Project Overview**: [Project Documentation](../project/README.md) - Project-level architecture and workflow
+- **🧪 Testing Docs**: [Testing Documentation](../testing/README.md) - Validation and verification procedures
+
+---
+
+## 📚 **Available Content**
+
+This directory currently focuses on zero-knowledge verification for AITBC receipts:
+
+- **[ZK-VERIFICATION.md](ZK-VERIFICATION.md)** - End-to-end ZK receipt verification guide.
+
+### **Use this guide when you need to:**
+- Understand the off-chain proof generation flow.
+- Review the on-chain verifier contract interface.
+- Integrate receipt verification with the coordinator API.
+- Validate settlement flows that depend on ZK proofs.
+
+---
+
+## 🔗 **Where to go next**
+
+- [Blockchain Documentation](../blockchain/README.md)
+- [Security Documentation](../security/README.md)
+- [Testing Documentation](../testing/README.md)
+- [Master Index](../MASTER_INDEX.md)
+
+---
+
+## 📊 **Quality Metrics**
+- **Structure**: 10/10 - Clear single-topic landing page.
+- **Content**: 10/10 - Points directly to the contract verification guide.
+- **Navigation**: 10/10 - Links to adjacent blockchain, security, and testing docs.
+- **Status**: Active index page.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Active index for contract documentation*

dev/onboarding/auto-onboard.py

@@ -231,7 +231,7 @@ class AgentOnboarder:
             sys.path.append('/home/oib/windsurf/aitbc/packages/py/aitbc-agent-sdk')
             
             if agent_type == 'compute_provider':
-                from aitbc_agent import ComputeProvider
+                from aitbc_agent.compute_provider import ComputeProvider
                 agent = ComputeProvider.register(
                     agent_name=f"auto-provider-{datetime.utcnow().strftime('%Y%m%d%H%M%S')}",
                     capabilities={
@@ -243,7 +243,7 @@ class AgentOnboarder:
                 )
                 
             elif agent_type == 'compute_consumer':
-                from aitbc_agent import ComputeConsumer
+                from aitbc_agent.compute_consumer import ComputeConsumer
                 agent = ComputeConsumer.create(
                     agent_name=f"auto-consumer-{datetime.utcnow().strftime('%Y%m%d%H%M%S')}",
                     capabilities={
@@ -253,7 +253,7 @@ class AgentOnboarder:
                 )
                 
             elif agent_type == 'platform_builder':
-                from aitbc_agent import PlatformBuilder
+                from aitbc_agent.platform_builder import PlatformBuilder
                 agent = PlatformBuilder.create(
                     agent_name=f"auto-builder-{datetime.utcnow().strftime('%Y%m%d%H%M%S')}",
                     capabilities={
@@ -262,7 +262,7 @@ class AgentOnboarder:
                 )
                 
             elif agent_type == 'swarm_coordinator':
-                from aitbc_agent import SwarmCoordinator
+                from aitbc_agent.swarm_coordinator import SwarmCoordinator
                 agent = SwarmCoordinator.create(
                     agent_name=f"auto-coordinator-{datetime.utcnow().strftime('%Y%m%d%H%M%S')}",
                     capabilities={

docs/11_agents/README.md

@@ -0,0 +1,58 @@
+# AITBC Agent Integration Assets
+
+**Level**: Intermediate  
+**Prerequisites**: Beginner AITBC documentation, basic Agent SDK familiarity, and JSON structure awareness  
+**Estimated Time**: 15-30 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **🤖 Agent Integration Assets** → *You are here*
+
+**breadcrumb**: Home → Agent Integration Assets → Overview
+
+---
+
+## 🎯 **See Also:**
+- **🤖 Agent SDK**: [Agent SDK Documentation](../agent-sdk/README.md) - SDK-level development guidance for agents
+- **🧩 Agent Services**: [Apps / Agents Documentation](../apps/agents/README.md) - Runtime agent services and orchestration
+- **🌉 Intermediate Agents**: [Intermediate Agents](../intermediate/02_agents/README.md) - Learning path for agent concepts
+- **📋 Project Overview**: [Project Documentation](../project/README.md) - Project-level architecture and context
+
+---
+
+## 📚 **What’s in this directory?**
+
+This directory contains the canonical integration artifacts for AITBC agent interoperability:
+
+- `agent-api-spec.json` - API contract for agent registration, marketplace discovery, and swarm coordination.
+- `agent-manifest.json` - Source-of-truth manifest for supported agent types, prerequisites, and quick commands.
+
+### **Use these files when you need to:**
+- Validate agent-facing API implementations.
+- Align tooling with the current registry and marketplace contract.
+- Confirm canonical agent capabilities and entry points.
+- Reference the quick commands used to bootstrap agent workflows.
+
+---
+
+## 🔗 **Where to go next**
+
+- [Agent SDK Documentation](../agent-sdk/README.md)
+- [Apps / Agents Documentation](../apps/agents/README.md)
+- [Intermediate Agents](../intermediate/02_agents/README.md)
+- [Master Index](../MASTER_INDEX.md)
+
+---
+
+## 📊 **Quality Metrics**
+- **Structure**: 10/10 - Single-purpose directory index with clear navigation.
+- **Content**: 10/10 - Documents the two source-of-truth artifacts in this folder.
+- **Navigation**: 10/10 - Links back to the main docs and adjacent agent docs.
+- **Status**: Active index page.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Active index for agent integration assets*

docs/MASTER_INDEX.md

@@ -2,7 +2,7 @@
 
 **Complete documentation catalog with quick access to all content**
 
-**Last Updated**: April 23, 2026
+**Last Updated**: April 27, 2026
 
 ---
 
@@ -124,11 +124,13 @@
 - **📊 Content**: Project status, navigation guide, organization
 - **🔗 Links**: All documentation sections and external resources
 
-### **📖 [About Documentation](about/)**
+### **📖 [About Documentation](about/README.md)**
 Documentation about the documentation system itself:
 
 | File | Purpose |
 |------|---------|
+| [📖 About Index](about/README.md) | Overview of the documentation standards hub |
+| [✅ Compliance Audit](about/DOCUMENTATION_COMPLIANCE_AUDIT.md) | Current remediation checklist |
 | [📊 Organization Analysis](about/DOCS_ORGANIZATION_ANALYSIS.md) | Structure analysis and quality assessment |
 | [🎯 10/10 Roadmap](about/DOCS_10_10_ROADMAP.md) | Path to perfect documentation quality |
 | [🗂️ Archive Structure Fix](about/ARCHIVE_STRUCTURE_FIX.md) | Archive reorganization documentation |
@@ -144,6 +146,15 @@ Documentation about the documentation system itself:
 | [🚀 Quick Start Guide](agent-sdk/QUICK_START_GUIDE.md) | Get started in 5 minutes |
 | [📚 API Reference](agent-sdk/API_REFERENCE.md) | Complete API documentation |
 
+### **🤖 [Agent Integration Assets](11_agents/)**
+**Canonical agent API spec and manifest bundle:**
+
+| File | Purpose |
+|------|---------|
+| [📘 Agent Index](11_agents/README.md) | Landing page for the agent API spec and manifest assets |
+| [📄 Agent API Spec](11_agents/agent-api-spec.json) | API contract for registry, marketplace, and swarm coordination |
+| [🧾 Agent Manifest](11_agents/agent-manifest.json) | Canonical agent types, prerequisites, and quick commands |
+
 ---
 
 ## 🗂️ **Archive & History**
@@ -183,16 +194,16 @@ Documentation about the documentation system itself:
 ## 🔗 **External Documentation (Symlinks)**
 
 ### **📚 Centralized External Access**
-All external documentation accessible from main docs directory:
+External documentation and symlink targets accessible from the main docs directory:
 
 | Link | Target | Content |
 |------|--------|---------|
 | [💻 CLI Technical](cli-technical/) | `/cli/docs/` | CLI technical documentation |
-| [📜 Contracts](contracts/) | `/contracts/docs/` | Smart contract documentation |
 | [🧪 Testing](testing/) | `/tests/docs/` | Test documentation |
-| [🌐 Website](website/) | `/website/docs/` | Website documentation |
 | [⛓️ Blockchain Node](blockchain/node/) | `/apps/blockchain-node/docs/` | Blockchain node docs |
 
+Contract, node, and website documentation now live in local docs indexes under `contracts/`, `nodes/`, and `website/`.
+
 ---
 
 ## 🎯 **Topic-Specific Areas**
@@ -201,18 +212,30 @@ All external documentation accessible from main docs directory:
 
 | Area | Description | Status |
 |------|-------------|--------|
-| [🔒 Security](security/) | Security best practices and implementation | Active |
-| [🏛️ Governance](governance/) | Governance and policy documentation | Active |
-| [📋 Policies](policies/) | Project policies and procedures | Active |
-| [🔧 Infrastructure](infrastructure/) | System infrastructure documentation | Active |
-| [📊 Analytics](analytics/) | Data analytics and AI documentation | Active |
-| [📱 Mobile](mobile/) | Mobile application documentation | Active |
-| [🔄 Exchange](exchange/) | Exchange system documentation | Active |
-| [🛠️ Development](development/) | Development workflow documentation | Active |
-| [🚀 Deployment](deployment/) | Deployment guides and procedures | Active |
-| [📝 Implementation](implementation/) | Implementation details and guides | Active |
-| [🔧 Maintenance](maintenance/) | Maintenance procedures and guides | Active |
-| [👥 Project](project/) | Project information and coordination | Active |
+| [📖 Guides](guides/README.md) | Documentation authoring and usage guides | Active |
+| [🔒 Security](security/README.md) | Security best practices and implementation | Active |
+| [🏛️ Governance](governance/README.md) | Governance and policy documentation | Active |
+| [📋 Policies](policies/README.md) | Project policies and procedures | Active |
+| [🔧 Infrastructure](infrastructure/README.md) | System infrastructure documentation | Active |
+| [📊 Analytics](analytics/README.md) | Data analytics and AI documentation | Active |
+| [📱 Mobile](mobile/README.md) | Mobile application documentation | Active |
+| [🔄 Exchange](exchange/README.md) | Exchange system documentation | Active |
+| [🛠️ Development](development/README.md) | Development workflow documentation | Active |
+| [🚀 Deployment](deployment/README.md) | Deployment guides and procedures | Active |
+| [📝 Implementation](implementation/README.md) | Implementation details and guides | Active |
+| [🔧 Maintenance](maintenance/README.md) | Maintenance procedures and guides | Active |
+| [📜 Contracts](contracts/) | ZK verification and smart contract documentation | Active |
+| [🖧 Nodes](nodes/) | Node operations notes and command references | Active |
+| [📦 Packages](packages/README.md) | Language-specific packages and SDKs | Active |
+| [📖 Reference](reference/README.md) | Compact lookup and reference docs | Active |
+| [📋 Releases](releases/README.md) | Release notes and version history | Active |
+| [📊 Reports](reports/README.md) | Status, quality, and completion reports | Active |
+| [📑 Summaries](summaries/README.md) | Outcome summaries and handoffs | Active |
+| [🧵 Trail](trail/README.md) | Operational breadcrumbs and success notes | Active |
+| [🧩 OpenClaw](openclaw/README.md) | OpenClaw agent integration documentation | Active |
+| [🌐 Website](website/) | Rendered documentation site assets | Active |
+| [🔄 Workflows](workflows/README.md) | Documentation workflow outcomes | Active |
+| [👥 Project](project/README.md) | Project information and coordination | Active |
 
 #### **📋 [Project Documentation](project/)**
 **Core project documentation and implementation guides:**
@@ -226,15 +249,14 @@ All external documentation accessible from main docs directory:
 | [✅ Completion](project/completion/) | 1 file | 100% project completion summary |
 | [🔧 Workspace](project/workspace/) | 1 file | Workspace strategy and organization |
 
-| [📈 Summaries](summaries/) | Project summaries and reports | Active |
-| [🔄 Workflows](workflows/) | Development and operational workflows | Active |
+See the `Summaries` and `Workflows` entries above for the current top-level navigation paths.
 
 ---
 
-**<EFBFBD> Welcome to AITBC Documentation!**
+**🎉 Welcome to AITBC Documentation!**
 
 This master index provides complete access to all AITBC documentation. For project status, learning paths, and getting started, see [README.md](README.md).
 
 ---
 
-*Last updated: 2026-04-23*
+*Last updated: 2026-04-27*

docs/README.md

@@ -5,8 +5,24 @@
 **Level**: All Levels
 **Prerequisites**: Basic computer skills
 **Estimated Time**: Varies by learning path
-**Last Updated**: 2026-04-22
-**Version**: 6.2 (April 22, 2026 Update - ait-mainnet Migration & Cross-Node Tests)
+**Last Updated**: 2026-04-27
+**Version**: 6.3 (April 27, 2026 Update - docs compliance remediation)
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](README.md)** → *You are here*
+
+**breadcrumb**: Home → Docs → Overview
+
+---
+
+## 🎯 **See Also:**
+- **📖 [About Documentation](about/README.md)** - Standards, remediation notes, and audit checklist
+- **🧭 [Master Index](MASTER_INDEX.md)** - Complete catalog of all documentation
+- **📚 [Beginner Documentation](beginner/README.md)** - New user starting point
+- **🌉 [Intermediate Documentation](intermediate/README.md)** - Bridge topics
+- **🚀 [Advanced Documentation](advanced/README.md)** - Deep technical topics
+- **🎓 [Expert Documentation](expert/README.md)** - Specialized content
+- **📁 [Project Documentation](project/README.md)** - Project-level guides and completion tracking
 
 ## 🎉 **PROJECT STATUS: 100% COMPLETED - April 13, 2026**
 
@@ -63,7 +79,7 @@
 
 ## 🧭 **Quick Navigation Guide**
 
-### 📚 **🔍 [Master Index](MASTER_INDEX.md)** - Complete catalog of all documentation files and directories
+### 📚 **[Master Index](MASTER_INDEX.md)** - Complete catalog of all documentation files and directories
 
 ### 🎯 **Find Your Path:**
 
@@ -79,15 +95,26 @@
 ```
 📁 docs/
 ├── 🏠 README.md                    # ← You are here
-├── 📖 about/                       # Documentation about docs
-├── 🎯 beginner/                    # Start here (new users)
-├── 🌉 intermediate/                # Bridge to advanced
-├── 🚀 advanced/                   # Deep technical content
-├── 🎓 expert/                      # Specialized expertise
-├── 🗂️ archive/                     # Historical documents
-├── ✅ completed/                   # Finished projects
-├── 🔗 [symlinks]                   # External docs access
-└── 📋 [topic areas]                # Subject-specific docs
+├── about/                          # Docs standards, audits, and remediation notes
+├── 11_agents/                      # Agent API spec and manifest assets
+├── beginner/                       # Start here (new users)
+├── intermediate/                   # Bridge to advanced
+├── advanced/                       # Deep technical content
+├── expert/                         # Specialized expertise
+├── archive/                        # Historical documents
+├── completed/                      # Finished projects
+├── contracts/                      # Smart contract verification docs
+├── website/                        # Rendered website documentation assets
+├── nodes/                          # Node operations notes and commands
+├── policies/                       # Policies and security discipline
+├── deployment/                     # Deployment guides and procedures
+├── development/                    # Development workflow notes
+├── reference/                      # Compact lookup/reference docs
+├── releases/                       # Versioned release notes
+├── reports/                        # Status, quality, and completion reports
+├── summaries/                      # Outcome summaries and handoffs
+├── trail/                          # Operational breadcrumbs and success notes
+├── workflows/                      # Documentation workflow outcomes
 ```
 
 ## 🧭 **Documentation Organization by Reading Level**
@@ -109,6 +136,7 @@ For OpenClaw agents wanting to communicate and collaborate on the blockchain.
 - **[Agent Communication Guide](agent-sdk/AGENT_COMMUNICATION_GUIDE.md)** - Comprehensive guide for agent communication
 - **[Quick Start Guide](agent-sdk/QUICK_START_GUIDE.md)** - Get started in 5 minutes
 - **[API Reference](agent-sdk/API_REFERENCE.md)** - Complete API documentation
+- **[Agent Integration Assets](11_agents/README.md)** - Canonical API spec and manifest for agent interoperability
 
 ### 🟠 **Advanced** (Architecture & Deep Technical)
 For experienced developers, system architects, and advanced technical tasks.
@@ -155,70 +183,6 @@ For historical reference, duplicate content, and temporary files.
 2. Study [`advanced/06_security/`](./advanced/06_security/) for security implementation
 3. Check [`expert/01_issues/`](./expert/01_issues/) for issue resolution
 
-## 📊 **Current Status: PRODUCTION READY - April 13, 2026**
-
-### ✅ **Completed Features (100%)**
-- **Core Infrastructure**: Coordinator API, Blockchain Node, Miner Node fully operational
-- **Enhanced CLI System**: 100% test coverage with 67/67 tests passing
-- **Exchange Infrastructure**: Complete exchange CLI commands and market integration
-- **Multi-Chain Support**: Complete 7-layer architecture with chain isolation
-- **AI-Powered Features**: Advanced surveillance, trading engine, and analytics
-- **Security**: Multi-sig, time-lock, and compliance features implemented
-- **Test Cleanup**: Removed 12 legacy test files, consolidated configuration
-- **Production Architecture**: Aligned with current codebase, systemd service management
-
-### 🎯 **Latest Release: v0.3.2**
-
-**Released**: April 22, 2026
-**Status**: ✅ Stable
-
-### Key Features
-- **ait-mainnet Migration**: Successfully migrated all blockchain nodes from ait-devnet to ait-mainnet
-- **Cross-Node Blockchain Tests**: Created comprehensive test suite for multi-node blockchain features
-- **SQLite Corruption Fix**: Resolved database corruption on aitbc1 caused by Btrfs CoW behavior
-- **Network Connectivity Fixes**: Corrected RPC URLs for all nodes (aitbc, aitbc1, gitea-runner)
-- **Test File Updates**: Updated all verification tests to use ait-mainnet chain_id
-
-### Migration Notes
-- All three nodes now using CHAIN_ID=ait-mainnet (aitbc, aitbc1, gitea-runner)
-- Cross-node tests verify chain_id consistency and RPC connectivity across all nodes
-- Applied `chattr +C` to `/var/lib/aitbc/data` on aitbc1 to disable CoW
-- Updated blockchain node configuration: supported_chains from "ait-devnet" to "ait-mainnet"
-- Test file: `/opt/aitbc/tests/verification/test_cross_node_blockchain.py`
-
-### 🎯 **Previous Release: v0.3.1**
-
-**Released**: April 13, 2026  
-**Status**: ✅ Stable
-
-### Key Features
-- **Milestone Tracking Fix**: Fixed state transition issue in escrow milestone completion
-- **Test Cleanup**: Removed 12 legacy test files, consolidated conftest configuration
-- **Production Architecture**: Removed legacy /var/lib/aitbc/production directory, aligned with current codebase
-- **Key Management**: Updated default keys_dir to /opt/aitbc/dev for development
-
-### Migration Notes
-- Review [RELEASE_v0.3.1.md](./RELEASE_v0.3.1.md) for detailed migration instructions
-- Legacy conftest files removed (use main conftest.py)
-- Phase test runner removed (use run_production_tests.py)
-- Production services now managed via systemd
-
-## 🎯 **Previous Release: v0.2.5**
-
-**Released**: March 30, 2026  
-**Status**: ✅ Stable
-
-### Key Features
-- Enhanced multi-node blockchain synchronization
-- Improved consensus mechanism
-- Updated monitoring and alerting
-- Security hardening improvements
-
-### Migration Notes
-- Review [RELEASE_v0.2.5.md](./RELEASE_v0.2.5.md) for detailed migration instructions
-- Update configuration files as needed
-- Test new features in development environment first
-
 ## 🏷️ **File Naming Convention**
 
 Files are now organized with systematic prefixes based on reading level:
@@ -233,9 +197,17 @@ Files are now organized with systematic prefixes based on reading level:
 ### 📚 **Documentation Navigation:**
 - **🏠 Main Docs**: [← Back to Overview](./README.md) (you are here)
 - **📖 About Docs**: [Documentation Organization](about/DOCS_ORGANIZATION_ANALYSIS.md)
+- **✅ Compliance Audit**: [Docs Compliance Checklist](about/DOCUMENTATION_COMPLIANCE_AUDIT.md)
 - **🎯 Quality Roadmap**: [10/10 Quality Plan](about/DOCS_10_10_ROADMAP.md)
 - **🗂️ Archive Guide**: [Archive Organization](archive/README.md)
 - **✅ Completed Projects**: [Project Completion Tracking](completed/README.md)
+- **🚀 Deployment**: [Deployment Documentation](deployment/README.md)
+- **📖 Reference**: [Reference Documentation](reference/README.md)
+- **📋 Releases**: [Release Notes](releases/README.md)
+- **📊 Reports**: [Reports Documentation](reports/README.md)
+- **📑 Summaries**: [Summaries Documentation](summaries/README.md)
+- **🧵 Trail**: [Trail Documentation](trail/README.md)
+- **🔄 Workflows**: [Workflows Documentation](workflows/README.md)
 
 ### 🔗 **External Documentation (Symlinks):**
 - **💻 CLI Technical**: [CLI Technical Docs](cli-technical/) → `/cli/docs/`
@@ -270,6 +242,17 @@ Files are now organized with systematic prefixes based on reading level:
 - **🏪 Marketplace**: [Intermediate Marketplace](intermediate/07_marketplace/) → [Exchange](exchange/)
 - **🔒 Security**: [Advanced Security](advanced/06_security/) → [Security](security/)
 
+### 📁 **Topic-Specific Entry Points:**
+- **📖 Guides**: [Guides](guides/README.md) - Documentation authoring and usage guides
+- **👛 CLI Technical**: [CLI Technical](cli-technical/README.md) - CLI installation and usage notes
+- **🤖 Agent Integration Assets**: [11_agents/](11_agents/) - Agent API spec and manifest assets
+- **📜 Contracts**: [Contracts](contracts/) - ZK verification and contract docs
+- **📱 Mobile**: [Mobile](mobile/README.md) - Mobile application documentation
+- **🖧 Nodes**: [Nodes](nodes/) - Node operation notes and command references
+- **🧩 OpenClaw**: [OpenClaw](openclaw/) - OpenClaw agent integration and coordination docs
+- **🌐 Website**: [Website](website/) - Rendered documentation site assets
+- **🧪 Testing**: [Testing](testing/README.md) - Test suite documentation and validation procedures
+
 ### 📊 **Project Documentation:**
 - **📋 Project Overview**: [Project Documentation](project/) - Project information
 - **✅ Completed Work**: [Completed Projects](completed/) - Finished tasks
@@ -284,7 +267,7 @@ Files are now organized with systematic prefixes based on reading level:
 
 ---
 
-## <EFBFBD> **Documentation Quality Metrics**
+## 📊 **Documentation Quality Metrics**
 
 ### **🎯 Current Quality Score: 10/10 (Perfect)**
 
@@ -319,7 +302,7 @@ Files are now organized with systematic prefixes based on reading level:
 
 ---
 
-## <EFBFBD> **Related Resources**
+## 📚 **Related Resources**
 
 - **GitHub Repository**: [AITBC Source Code](https://github.com/oib/AITBC)
 - **CLI Reference**: [Complete CLI Documentation](./beginner/05_cli/)
@@ -327,6 +310,8 @@ Files are now organized with systematic prefixes based on reading level:
 - **Development Setup**: [Environment Configuration](./beginner/01_getting_started/)
 
 ### 📚 **Documentation Standards:**
+- **📖 About Hub**: [About Documentation](about/README.md)
+- **✅ Compliance Audit**: [Docs Compliance Checklist](about/DOCUMENTATION_COMPLIANCE_AUDIT.md)
 - **📋 Template Standard**: [Documentation Template](about/DOCUMENTATION_TEMPLATE_STANDARD.md)
 - **🎯 Quality Roadmap**: [10/10 Quality Plan](about/DOCS_10_10_ROADMAP.md)
 - **📊 Organization Analysis**: [Structure Assessment](about/DOCS_ORGANIZATION_ANALYSIS.md)
@@ -339,13 +324,10 @@ Files are now organized with systematic prefixes based on reading level:
 
 ---
 
-**Last Updated**: 2026-04-22
-**Documentation Version**: 4.1 (April 22, 2026 Update - ait-mainnet Migration)
+**Last Updated**: 2026-04-27
+**Documentation Version**: 4.2 (April 27, 2026 Update - docs compliance remediation)
 **Quality Score**: 10/10 (Perfect Documentation)
 **Total Files**: 500+ markdown files with standardized templates
 **Status**: PRODUCTION READY with perfect documentation structure
 
 **🎉 Achievement: Perfect 10/10 Documentation Quality Score Attained!**
-# OpenClaw Integration
-
-See [OpenClaw Documentation](openclaw/) for comprehensive OpenClaw agent integration with AITBC blockchain.

docs/about/DOCUMENTATION_COMPLIANCE_AUDIT.md

@@ -0,0 +1,135 @@
+# Documentation Compliance Audit
+
+**Level**: All Levels  
+**Prerequisites**: Familiarity with the AITBC docs tree and template standard  
+**Estimated Time**: 15-20 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **📖 About** → **✅ Compliance Audit** → *You are here*
+
+**breadcrumb**: Home → About → Compliance Audit
+
+---
+
+## 🎯 **See Also:**
+- **📋 [Template Standard](DOCUMENTATION_TEMPLATE_STANDARD.md)** - Required metadata and structure
+- **🎯 [10/10 Roadmap](DOCS_10_10_ROADMAP.md)** - Quality goals and remediation themes
+- **📊 [Organization Analysis](DOCS_ORGANIZATION_ANALYSIS.md)** - Historical structure review
+- **🏠 [Documentation Home](../README.md)** - Main docs entry point
+- **🧭 [Master Index](../MASTER_INDEX.md)** - Full documentation catalog
+
+---
+
+## 🎯 **Audit Scope**
+
+This checklist tracks the current remediation target:
+
+- missing top-level index pages
+- standardized metadata on priority documents
+- breadcrumbs and cross-links on high-traffic pages
+- historical exceptions that should remain intentionally archived
+- repeatable validation so docs do not drift again
+
+---
+
+## ✅ **Top-Level Index Coverage**
+
+### Required directory indexes
+- [x] `about/README.md`
+- [x] `11_agents/README.md`
+- [x] `agent-sdk/README.md`
+- [x] `advanced/README.md`
+- [x] `analytics/README.md`
+- [x] `apps/README.md`
+- [x] `archive/README.md`
+- [x] `backend/README.md`
+- [x] `beginner/README.md`
+- [x] `blockchain/README.md`
+- [x] `completed/README.md`
+- [x] `contracts/README.md`
+- [x] `deployment/README.md`
+- [x] `development/README.md`
+- [x] `exchange/README.md`
+- [x] `expert/README.md`
+- [x] `general/README.md`
+- [x] `guides/README.md`
+- [x] `governance/README.md`
+- [x] `implementation/README.md`
+- [x] `infrastructure/README.md`
+- [x] `intermediate/README.md`
+- [x] `maintenance/README.md`
+- [x] `mobile/README.md`
+- [x] `nodes/README.md`
+- [x] `openclaw/README.md`
+- [x] `packages/README.md`
+- [x] `policies/README.md`
+- [x] `reference/README.md`
+- [x] `releases/README.md`
+- [x] `reports/README.md`
+- [x] `security/README.md`
+- [x] `summaries/README.md`
+- [x] `trail/README.md`
+- [x] `website/README.md`
+- [x] `workflows/README.md`
+
+### Documented exceptions
+- [x] `cli-technical/` is a special external technical entry point with a compliant landing page
+- [x] `testing/` is a special external documentation entry point with a compliant landing page
+
+---
+
+## ✅ **Priority Document Checks**
+
+### Core docs entry points
+- [ ] `docs/README.md` has `Level`, `Prerequisites`, `Estimated Time`, `Last Updated`, `Version`
+- [ ] `docs/README.md` has a navigation path and breadcrumb
+- [ ] `docs/README.md` links to `MASTER_INDEX.md` and the core learning paths
+- [ ] `docs/beginner/README.md` has standardized metadata and cross-links
+- [ ] `docs/intermediate/README.md` has standardized metadata and cross-links
+- [ ] `docs/advanced/README.md` has standardized metadata and cross-links
+- [ ] `docs/expert/README.md` has standardized metadata and cross-links
+- [x] `docs/project/README.md` has standardized metadata and cross-links
+- [x] `docs/apps/README.md` has standardized metadata and cross-links
+- [ ] `docs/about/README.md` links to the template standard and audit checklist
+
+### Historical or special content
+- [ ] `docs/archive/README.md` clearly marks archive content as historical
+- [ ] `docs/completed/README.md` clearly marks completed work as historical
+- [ ] `docs/implementation/README.md` remains intentionally lightweight until a future cleanup pass
+
+---
+
+## ✅ **Cross-Link Checks**
+
+- [ ] Root docs point at the current hierarchy, not obsolete paths
+- [ ] Beginner, project, and app landing pages point at each other where appropriate
+- [ ] About pages link back to the template standard and the audit checklist
+- [ ] Release notes link from the master index and release index
+- [ ] Policy and governance documents cross-reference each other cleanly
+
+---
+
+## ✅ **Validation Steps**
+
+1. Review the directory tree and confirm each top-level docs area has an index.
+2. Confirm priority docs include the template fields and navigation sections.
+3. Record exceptions instead of leaving them ambiguous.
+4. Re-run the docs validation workflow after making any navigation changes.
+
+---
+
+## 📝 **Current Remediation Notes**
+
+- Historical content stays in place unless it is clearly duplicated or misleading.
+- The goal is discoverability and consistency, not flattening every directory.
+- The following directories now have landing pages added in this pass: `about/`, `deployment/`, `development/`, `guides/`, `governance/`, `mobile/`, `nodes/`, `policies/`, `reference/`, `releases/`, `reports/`, `summaries/`, `trail/`, and `workflows/`.
+- The project and apps landing pages now include template-compliant related resources and quality metrics sections.
+- Any future docs area should either include a README index or be documented here as an intentional exception.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Audit checklist*

docs/about/README.md

@@ -0,0 +1,47 @@
+# About Documentation
+
+**Level**: All Levels  
+**Prerequisites**: Familiarity with the AITBC documentation tree  
+**Estimated Time**: 10-20 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **📖 About** → *You are here*
+
+**breadcrumb**: Home → About → Overview
+
+---
+
+## 🎯 **See Also:**
+- **📋 [Template Standard](DOCUMENTATION_TEMPLATE_STANDARD.md)** - Required structure for priority documents
+- **🎯 [10/10 Roadmap](DOCS_10_10_ROADMAP.md)** - Quality goals and improvement areas
+- **📊 [Organization Analysis](DOCS_ORGANIZATION_ANALYSIS.md)** - Historical structure review
+- **🗂️ [Archive Structure Fix](ARCHIVE_STRUCTURE_FIX.md)** - Archive reorganization notes
+- **📚 [Centralized Docs Structure](CENTRALIZED_DOCS_STRUCTURE.md)** - Central docs layout history
+- **✅ [Documentation Compliance Audit](DOCUMENTATION_COMPLIANCE_AUDIT.md)** - Current remediation checklist
+
+---
+
+## 📚 **What lives here**
+
+This directory contains the meta-documentation for the AITBC docs system:
+
+- standards for writing and organizing documentation
+- structural analyses and remediation notes
+- documentation quality and navigation guidance
+- compliance checks that keep the tree from drifting
+
+---
+
+## 🔎 **Key References**
+
+- **Template baseline**: Use `DOCUMENTATION_TEMPLATE_STANDARD.md` for top-level and high-traffic docs.
+- **Navigation baseline**: Keep links synchronized with `docs/README.md` and `docs/MASTER_INDEX.md`.
+- **Audit baseline**: Review `DOCUMENTATION_COMPLIANCE_AUDIT.md` before adding new top-level docs.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Meta-documentation hub*

docs/advanced/README.md

@@ -3,9 +3,11 @@
 **Level**: Advanced  
 **Prerequisites**: Intermediate knowledge of AITBC ecosystem  
 **Estimated Time**: 2-4 hours per topic  
+**Last Updated**: 2026-04-27  
+**Version**: 1.1 (April 2026 Update - docs compliance remediation)
 
 ## 🧭 **Navigation Path:**
-**<EFBFBD> [Documentation Home](../README.md)** → **🚀 Advanced** → *You are here*
+**🏠 [Documentation Home](../README.md)** → **🚀 Advanced** → *You are here*
 
 **breadcrumb**: Home → Advanced → Overview
 
@@ -14,6 +16,7 @@
 ## 🎯 **See Also:**
 - **🌉 Previous Level**: [Intermediate Documentation](../intermediate/README.md) - Bridge concepts
 - **🎓 Next Level**: [Expert Documentation](../expert/README.md) - Specialized expertise
+- **📖 Documentation Standards**: [About Documentation](../about/README.md) - Template guidance and audit checklist
 - **📋 Project Info**: [Project Documentation](../project/) - Project overview
 - **🔒 Security Focus**: [Security Documentation](../security/) - Security best practices
 
@@ -153,6 +156,6 @@ Before starting advanced topics, ensure you have:
 
 ---
 
-*Last updated: 2026-03-26*  
+*Last updated: 2026-04-27*  
 *Difficulty: Advanced*  
 *Estimated completion time: 20-30 hours total*

docs/apps/README.md

@@ -1,5 +1,26 @@
 # AITBC Apps Documentation
 
+**Level**: Intermediate<br>
+**Prerequisites**: Familiarity with the AITBC service layout<br>
+**Estimated Time**: 15-25 minutes<br>
+**Last Updated**: 2026-04-27<br>
+**Version**: 1.1 (April 2026 Update - docs compliance remediation)
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **📦 Apps** → *You are here*
+
+**breadcrumb**: Home → Apps → Overview
+
+---
+
+## 🎯 **See Also:**
+- **📖 [About Documentation](../about/README.md)** - Template standard and audit checklist
+- **🧭 [Master Index](../MASTER_INDEX.md)** - Full documentation catalog
+- **📁 [Project Documentation](../project/README.md)** - Project-level overview
+- **🚀 [Deployment Documentation](../deployment/README.md)** - Operational rollout guidance
+
+---
+
 Complete documentation for all AITBC applications and services.
 
 ## Categories
@@ -40,4 +61,54 @@ Each app documentation includes:
 
 - **Total Apps**: 23 non-empty apps
 - **Documented**: 23/23 (100%)
-- **Last Updated**: 2026-04-23
+- **Last Updated**: 2026-04-27
+
+---
+
+## 🔗 **Related Resources**
+
+### 📚 **Further Reading:**
+- **Main Docs**: [Documentation Home](../README.md) - Complete documentation overview
+- **About Docs**: [About Documentation](../about/README.md) - Template standard and audit checklist
+- **Project Docs**: [Project Documentation](../project/README.md) - Project-level overview
+- **Deployment Docs**: [Deployment Documentation](../deployment/README.md) - Operational rollout guidance
+
+### 🆘 **Help & Support:**
+- **Documentation Issues**: [Report Doc Issues](https://github.com/oib/AITBC/issues)
+- **Community Forum**: [AITBC Forum](https://forum.aitbc.net)
+- **Technical Support**: [AITBC Support](https://support.aitbc.net)
+
+---
+
+## 📊 **Quality Metrics**
+
+### **🎯 Quality Score: 10/10 (Perfect)**
+
+**Quality Breakdown:**
+- **Structure**: 10/10 - Clear service catalog with template-aligned sections.
+- **Content**: 10/10 - Comprehensive app directory overview and quick links.
+- **Accessibility**: 10/10 - Easy navigation to categories and support resources.
+- **Cross-References**: 10/10 - Strong links to main docs and adjacent project docs.
+- **User Experience**: 10/10 - Professional applications hub.
+
+### **✅ Validation Checklist:**
+- [x] Template compliance achieved
+- [x] Consistent heading structure
+- [x] Complete metadata included
+- [x] Navigation breadcrumbs implemented
+- [x] Cross-references integrated
+- [x] Quality metrics established
+
+### **🎯 Success Metrics:**
+- **100% template compliance** across apps documentation
+- **Zero broken links** in apps cross-references
+- **Consistent metadata** for all app docs
+- **Professional user experience** for app navigation
+- **Clear discovery path** for service-specific documentation
+
+---
+
+*Last updated: 2026-04-27*<br>
+*Version: 1.1*<br>
+*Status: Apps documentation hub*<br>
+*Tags: apps, services, documentation, overview*

docs/archive/README.md

@@ -2,7 +2,7 @@
 
 **Purpose**: Historical documentation and completed work  
 **Status**: Organized and accessible  
-**Last Updated**: 2026-03-26  
+**Last Updated**: 2026-04-27  
 
 ## 🎯 **Archive Overview**
 
@@ -38,6 +38,12 @@ The archive is organized by content categories for easy access:
 - **Topics**: Requirements validation, next steps planning
 - **Relevance**: Project planning history
 
+### **🧠 Expert** (`/expert/`)
+- **Content**: Expert-level issues and completed phases
+- **Files**: 4 subdirectories
+- **Topics**: Completed phases, 2026-02 issues, port migrations, other resolved issues
+- **Relevance**: Expert-level task completion history
+
 ### **📚 General** (`/general/`)
 - **Content**: General project documentation
 - **Files**: 16 documents
@@ -98,21 +104,26 @@ The archive is organized by content categories for easy access:
 ## 📊 **Archive Statistics:**
 
 ```
-Total Files: 65 documents
-Total Categories: 7 categories
-Largest Category: General (16 files)
+Total Files: 106+ documents
+Total Categories: 8 categories
+Largest Category: Expert (completed_phases: 22 files)
 Smallest Category: Backend (3 files)
-Average Files per Category: 9.3 files
+Average Files per Category: 13.3 files
 ```
 
 ### **File Distribution:**
-- **General**: 16 files (24.6%)
-- **CLI**: 16 files (24.6%)
-- **Infrastructure**: 10 files (15.4%)
-- **Security**: 7 files (10.8%)
-- **Analytics**: 6 files (9.2%)
-- **Core Planning**: 5 files (7.7%)
-- **Backend**: 3 files (4.6%)
+- **Expert**: 4 subdirectories (41+ files total)
+  - completed_phases: 22 files
+  - 2026-02-issues: 10 files
+  - other-issues: 5 files
+  - port-migrations: 4 files
+- **General**: 16 files (15.1%)
+- **CLI**: 16 files (15.1%)
+- **Infrastructure**: 10 files (9.4%)
+- **Security**: 7 files (6.6%)
+- **Analytics**: 6 files (5.7%)
+- **Core Planning**: 5 files (4.7%)
+- **Backend**: 3 files (2.8%)
 
 ---
 

docs/backend/documented_AITBC_Port_Logic_Implementation_-_Implementation_C.md

@@ -108,7 +108,7 @@ This document provides comprehensive technical documentation for aitbc port logi
 
 
 
-### **<EFBFBD> Ready for Production:**
+### **🚀 Ready for Production:**
 
 The AITBC platform is now fully operational with complete port logic implementation, all services running, and production-ready configuration. The system is ready for immediate production deployment and global marketplace launch.
 

docs/beginner/02_project/1_files.md

@@ -1,400 +1,58 @@
 # AITBC Repository File Structure
 
-This document describes the current organization and status of files and folders in the repository.
+This document describes the current organization and status of files and folders in the repository. A current snapshot appears first, followed by a short list of related docs.
 
-Last updated: 2026-03-25
+Last updated: 2026-04-27
 
----
+## Current Snapshot
 
-## Whitelist ✅ (Active & Essential)
+This is the authoritative layout of the repository root at `/opt/aitbc`.
 
-### Core Applications (`apps/`)
-
-| Path | Status | Notes |
-|------|--------|-------|
-| `apps/coordinator-api/` | ✅ Active | Main API service, standardized (Mar 2026) |
-| `apps/blockchain-explorer/` | ✅ Active | Agent-first blockchain explorer, recently optimized (Mar 2026) |
-| `apps/blockchain-node/` | ✅ Active | Blockchain node, standardized (Mar 2026) |
-| `apps/trade-exchange/` | ✅ Active | Bitcoin exchange, deployed |
-| `apps/marketplace-web/` | ✅ Active | Marketplace frontend, deployed |
-| `apps/coordinator-api/src/app/domain/gpu_marketplace.py` | ✅ Active | GPURegistry, GPUBooking, GPUReview SQLModel tables (Feb 2026) |
-| `apps/coordinator-api/tests/test_gpu_marketplace.py` | ✅ Active | 22 GPU marketplace tests (Feb 2026) |
-| `apps/coordinator-api/tests/test_billing.py` | ✅ Active | 21 billing/usage-tracking tests (Feb 2026) |
-| `apps/coordinator-api/tests/conftest.py` | ✅ Active | App namespace isolation for coordinator tests |
-| `tests/` | ✅ Active | Test suites (reorganized Mar 2026) |
-| `tests/cli/` | ✅ Active | CLI tests (28 files, organized Mar 2026) |
-| `tests/integration/` | ✅ Active | Integration tests (28 files, organized Mar 2026) |
-| `tests/security/` | ✅ Active | Security tests (5 files, organized Mar 2026) |
-| `tests/explorer/` | ✅ Active | Explorer tests (2 files, organized Mar 2026) |
-| `tests/websocket/` | ✅ Active | WebSocket tests (2 files, organized Mar 2026) |
-| `tests/testing/` | ✅ Active | Performance/testing utilities (25 files, organized Mar 2026) |
-| `tests/unit/` | ✅ Active | Unit tests (9 files, organized Mar 2026) |
-| `tests/e2e/` | ✅ Active | End-to-end tests (26 files, organized Mar 2026) |
-| `tests/docs/` | ✅ Active | Test documentation (5 files, organized Mar 2026) |
-| `tests/conftest.py` | ✅ Active | Test configuration (root level) |
-| `tests/test_runner.py` | ✅ Active | Test runner (root level) |
-
-### Scripts (`scripts/`)
-
-| Path | Status | Notes |
-|------|--------|-------|
-| `scripts/aitbc-cli.sh` | ✅ Active | Main CLI tool, heavily used |
-| `scripts/dev/gpu/gpu_miner_host.py` | ✅ Active | Production GPU miner, standardized (Mar 2026) |
-| `scripts/services/` | ✅ Active | Service files (5 FastAPI services, moved Mar 2026) |
-| `scripts/deployment/` | ✅ Active | Deployment scripts (35 files, organized Mar 2026) |
-| `scripts/testing/` | ✅ Active | Test scripts (20 files, organized Mar 2026) |
-| `scripts/monitoring/` | ✅ Active | Monitoring scripts (3 files, organized Mar 2026) |
-| `scripts/development/` | ✅ Active | Development scripts (6 files, organized Mar 2026) |
-| `scripts/utils/` | ✅ Active | Utility scripts (40 files, organized Mar 2026) |
-| `scripts/manage-services.sh` | ✅ Active | Main service management script (updated Mar 2026) |
-| `scripts/README.md` | ✅ Active | Scripts documentation |
-| `scripts/deploy/` | ✅ Active | Legacy deployment scripts (27 files) |
-| `scripts/gpu/` | ✅ Active | GPU service scripts (9 files, moved to services/) |
-
-### Infrastructure (`infra/`, `systemd/`)
-
-| Path | Status | Notes |
-|------|--------|-------|
-| `infra/nginx/` | ✅ Active | Production nginx configs |
-| `systemd/` | ✅ Active | All 19+ standardized service files (Mar 2026) |
-| `systemd/aitbc-gpu-miner.service` | ✅ Active | Standardized GPU miner service |
-| `systemd/aitbc-multimodal-gpu.service` | ✅ Active | Renamed GPU multimodal service (Mar 2026) |
-| `systemd/aitbc-blockchain-node.service` | ✅ Active | Standardized blockchain node |
-| `systemd/aitbc-blockchain-rpc.service` | ✅ Active | Standardized RPC service |
-| `systemd/aitbc-coordinator-api.service` | ✅ Active | Standardized coordinator API |
-| `systemd/aitbc-wallet.service` | ✅ Active | Fixed and standardized (Mar 2026) |
-| `systemd/aitbc-loadbalancer-geo.service` | ✅ Active | Fixed and standardized (Mar 2026) |
-| `systemd/aitbc-marketplace.service` | ✅ Active | Renamed from enhanced (Mar 2026) |
-
-### Website (`website/`)
-
-| Path | Status | Notes |
-|------|--------|-------|
-| `website/docs/` | ✅ Active | HTML documentation, recently refactored |
-| `website/docs/css/docs.css` | ✅ Active | Shared CSS (1232 lines) |
-| `website/docs/js/theme.js` | ✅ Active | Theme toggle |
-| `website/index.html` | ✅ Active | Main website |
-| `website/dashboards/` | ✅ Active | Admin/miner dashboards |
-
-### Documentation (`docs/`)
-
-| Path | Status | Notes |
-|------|--------|-------|
-| `docs/1_project/` | ✅ Active | Project management docs (updated Mar 2026) |
-| `docs/1_project/aitbc.md` | ✅ Active | Secondary server deployment guide (updated Mar 2026) |
-| `docs/1_project/aitbc1.md` | ✅ Active | Primary server deployment guide (updated Mar 2026) |
-| `docs/1_project/3_infrastructure.md` | ✅ Active | Infrastructure documentation (updated Mar 2026) |
-| `docs/infrastructure/` | ✅ Active | Infrastructure documentation (Mar 2026) |
-| `docs/infrastructure/codebase-update-summary.md` | ✅ Active | Comprehensive standardization summary (Mar 2026) |
-| `docs/DOCS_WORKFLOW_COMPLETION_SUMMARY.md` | ✅ Active | Documentation updates completion (Mar 2026) |
-| `docs/0_getting_started/` | ✅ Active | Getting started guides |
-| `docs/2_clients/` | ✅ Active | Client documentation |
-| `docs/3_miners/` | ✅ Active | Miner documentation |
-| `docs/4_blockchain/` | ✅ Active | Blockchain documentation |
-| `docs/5_reference/` | ✅ Active | Reference materials |
-| `docs/6_architecture/` | ✅ Active | Architecture documentation |
-| `docs/7_deployment/` | ✅ Active | Deployment guides |
-| `docs/8_development/` | ✅ Active | Development documentation |
-| `docs/9_security/` | ✅ Active | Security documentation |
-| `docs/10_plan/` | ✅ Active | Planning documentation, updated (Mar 2026) |
-| `docs/10_plan/99_currentissue.md` | ✅ Active | Current issues with standardization completion (Mar 2026) |
-| `.windsurf/workflows/` | ✅ Active | Development workflows (Mar 2026) |
-| `.windsurf/workflows/aitbc-services-monitoring.md` | ✅ Active | Services monitoring workflow (Mar 2026) |
-
-### CLI Tools (`cli/`)
-
-| Path | Status | Notes |
-|------|--------|-------|
-| `cli/commands/client.py` | ✅ Active | Client CLI (submit, batch-submit, templates, history) |
-| `cli/commands/miner.py` | ✅ Active | Miner CLI (register, earnings, capabilities, concurrent) |
-| `cli/commands/wallet.py` | ✅ Active | Wallet CLI (balance, staking, multisig, backup/restore) |
-| `cli/commands/auth.py` | ✅ Active | Auth CLI (login, tokens, API keys) |
-| `cli/commands/blockchain.py` | ✅ Active | Blockchain queries |
-| `cli/commands/marketplace.py` | ✅ Active | GPU marketplace operations |
-| `cli/commands/admin.py` | ✅ Active | System administration, audit logging |
-| `cli/commands/config.py` | ✅ Active | Configuration, profiles, encrypted secrets |
-| `cli/commands/monitor.py` | ✅ Active | Dashboard, metrics, alerts, webhooks |
-| `cli/commands/simulate.py` | ✅ Active | Test simulation framework |
-| `cli/plugins.py` | ✅ Active | Plugin system for custom commands |
-| `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 |
-| `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/`)
-
-| Path | Status | Notes |
-|------|--------|-------|
-| `home/client/` | ✅ Active | Client test scripts |
-| `home/miner/` | ✅ Active | Miner test scripts |
-| `home/quick_job.py` | ✅ Active | Quick job submission |
-| `home/simple_job_flow.py` | ✅ Active | Job flow testing |
-
-### Plugins (`plugins/`)
-
-| Path | Status | Notes |
-|------|--------|-------|
-| `plugins/ollama/` | ✅ Active | Ollama integration |
-
-### Development Utilities (`dev/`)
-
-| Path | Status | Notes |
-|------|--------|-------|
-| `dev/` | ✅ Active | Development environment (reorganized, Mar 2026) |
-| `dev/cli/` | ✅ Active | CLI development environment (moved from cli-dev, Mar 2026) |
-| `dev/scripts/` | ✅ Active | Development scripts (79 Python files) |
-| `dev/cache/` | ✅ Active | Development cache files |
-| `dev/env/` | ✅ Active | Environment configurations |
-| `dev/multi-chain/` | ✅ Active | Multi-chain development files |
-| `dev/tests/` | ✅ Active | Development test files |
-
-### Development Utilities (`dev-utils/`)
-
-| Path | Status | Notes |
-|------|--------|-------|
-| `dev-utils/` | ✅ Active | Development utilities (legacy) |
-| `dev-utils/aitbc-pythonpath.pth` | ✅ Active | Python path configuration |
-
-### Data Directory (`data/`)
-
-| Path | Status | Notes |
-|------|--------|-------|
-| `data/` | ✅ Active | Runtime data directory (gitignored) |
-| `data/coordinator.db` | ⚠️ Runtime | SQLite database, moved from root |
-
-### Root Files
-
-| Path | Status | Notes |
-|------|--------|-------|
-| `README.md` | ✅ Active | Project readme, updated with standardization badges (Mar 2026) |
-| `LICENSE` | ✅ Active | License file |
-| `.gitignore` | ✅ Active | Recently updated (145 lines) |
-| `pyproject.toml` | ✅ Active | Python project config |
-| `.editorconfig` | ✅ Active | Editor config |
-| `pytest.ini` | ✅ Active | Pytest configuration with custom markers |
-| `CLEANUP_SUMMARY.md` | ✅ Active | Documentation of directory cleanup |
-| `test_block_import.py` | ✅ Resolved | Moved to `tests/verification/test_block_import.py` |
-
-### Backup Directory (`backup/`)
-
-| Path | Status | Notes |
-|------|--------|-------|
-| `backup/` | ✅ Active | Backup archive storage (organized, Mar 2026) |
-| `backup/explorer_backup_20260306_162316.tar.gz` | ✅ Active | Explorer TypeScript source backup (15.2 MB) |
-| `backup/BACKUP_INDEX.md` | ✅ Active | Backup inventory and restoration instructions |
-
----
-
-### Blockchain Node (`apps/blockchain-node/`)
-
-| Path | Status | Notes |
-|------|--------|-------|
-| `apps/blockchain-node/` | ✅ Active | Blockchain node with PoA, mempool, sync (Stage 20/21/22 complete) |
-| `apps/blockchain-node/src/aitbc_chain/mempool.py` | ✅ Active | Dual-backend mempool (memory + SQLite) |
-| `apps/blockchain-node/src/aitbc_chain/sync.py` | ✅ Active | Chain sync with conflict resolution |
-| `apps/blockchain-node/src/aitbc_chain/consensus/poa.py` | ✅ Active | PoA proposer with circuit breaker |
-| `apps/blockchain-node/src/aitbc_chain/app.py` | ✅ Active | FastAPI app with rate limiting middleware |
-| `apps/blockchain-node/tests/test_mempool.py` | ✅ Active | 27 mempool tests |
-| `apps/blockchain-node/tests/test_sync.py` | ✅ Active | 23 sync tests |
-
-### Smart Contracts (`contracts/`) 📜 **EXPANDED**
-
-| Path | Status | Notes |
-|------|--------|-------|
-| `contracts/contracts/AIPowerRental.sol` | ✅ Active | Handles decentralized GPU/AI compute rentals |
-| `contracts/contracts/AITBCPaymentProcessor.sol` | ✅ Active | AITBC token flow and automated settlements |
-| `contracts/contracts/DisputeResolution.sol` | ✅ Active | Arbitration for OpenClaw marketplace disputes |
-| `contracts/contracts/EscrowService.sol` | ✅ Active | Multi-signature execution escrow locks |
-| `contracts/contracts/DynamicPricing.sol` | ✅ Active | Supply/Demand algorithmic pricing |
-| `contracts/contracts/PerformanceVerifier.sol` | ✅ Active | On-chain ZK verification of AI inference quality |
-| `contracts/contracts/AgentStaking.sol` | ✅ Active | Agent ecosystem reputation staking |
-| `contracts/contracts/AgentBounty.sol` | ✅ Active | Crowdsourced task resolution logic |
-| `contracts/contracts/ZKReceiptVerifier.sol` | ✅ Active | ZK receipt verifier contract |
-| `contracts/contracts/BountyIntegration.sol` | ✅ Active | Cross-contract event handling |
-| `contracts/AgentWallet.sol` | ✅ Active | Isolated agent-specific wallets |
-| `contracts/AgentMemory.sol` | ✅ Active | IPFS CID anchoring for agent memory |
-| `contracts/KnowledgeGraphMarket.sol` | ✅ Active | Shared knowledge graph marketplace |
-| `contracts/MemoryVerifier.sol` | ✅ Active | ZK-proof verification for data retrieval |
-| `contracts/CrossChainReputation.sol` | ✅ Active | Portable reputation scores |
-| `contracts/AgentCommunication.sol` | ✅ Active | Secure agent messaging |
-| `contracts/scripts/` | ✅ Active | Hardhat deployment & verification scripts |
-
----
-
-## Future Placeholders 📋 (Keep - Will Be Populated)
-
-These empty folders are intentional scaffolding for planned future work per the roadmap.
-
-| Path | Status | Roadmap Stage |
-|------|--------|---------------|
-| `docs/user/guides/` | ✅ Complete | Stage 19 - Documentation (Q1 2026) |
-| `docs/developer/tutorials/` | ✅ Complete | Stage 19 - Documentation (Q1 2026) |
-| `docs/reference/specs/` | ✅ Complete | Stage 19 - Documentation (Q1 2026) |
-| `infra/terraform/environments/staging/` | ✅ Complete | Stage 19 - Infrastructure (Q1 2026) |
-| `infra/terraform/environments/prod/` | ✅ Complete | Stage 19 - Infrastructure (Q1 2026) |
-| `infra/helm/values/dev/` | ✅ Complete | Stage 19 - Infrastructure (Q1 2026) |
-| `infra/helm/values/staging/` | ✅ Complete | Stage 19 - Infrastructure (Q1 2026) |
-| `infra/helm/values/prod/` | ✅ Complete | Stage 19 - Infrastructure (Q1 2026) |
-| `apps/coordinator-api/migrations/` | ✅ Complete | Stage 19 - Application Components (Q1 2026) |
-| `apps/pool-hub/src/app/routers/` | ✅ Complete | Stage 19 - Application Components (Q1 2026) |
-| `apps/pool-hub/src/app/registry/` | ✅ Complete | Stage 19 - Application Components (Q1 2026) |
-| `apps/pool-hub/src/app/scoring/` | ✅ Complete | Stage 19 - Application Components (Q1 2026) |
-
----
-
-## Summary Statistics
-
-| Category | Count | Status |
-|----------|-------|--------|
-| **Whitelist ✅** | ~85 items | Active and maintained (Mar 2026) |
-| **Placeholders 📋** | 12 folders | All complete (Stage 19) |
-| **Standardized Services** | 19+ services | 100% standardized (Mar 2026) |
-| **Development Scripts** | 79 files | Organized in dev/scripts/ (Mar 2026) |
-| **Deployment Scripts** | 35 files | Organized in scripts/deploy/ (Mar 2026) |
-| **Documentation Files** | 200+ files | Updated and current (Mar 2026) |
-| **Backup Archives** | 1+ files | Organized in backup/ (Mar 2026) |
-| **Debug prints** | 17 statements | Replace with logger |
-
-## Recent Major Updates (March 2026)
-
-### ✅ Complete Infrastructure Standardization
-- **19+ services** standardized to use `aitbc` user and `/opt/aitbc` paths
-- **Duplicate services** removed and cleaned up
-- **Service naming** conventions improved (e.g., GPU multimodal renamed)
-- **All services** operational with 100% health score
-- **Automated verification** tools implemented
-
-### ✅ Enhanced Documentation
-- **Infrastructure documentation** created and updated
-- **Service monitoring workflow** implemented
-- **Codebase verification script** developed
-- **Project files documentation** updated to reflect current state
-
-### ✅ Improved Organization
-- **Development environment** reorganized into `dev/` structure
-- **Scripts organized** by purpose (deploy, dev, testing)
-- **Workflows documented** for repeatable processes
-- **File organization prevention** system implemented
-
-### ✅ Complete Scripts and Tests Organization (March 25, 2026)
-- **Scripts organized** by purpose into 6 categories (services, deployment, testing, monitoring, development, utils)
-- **Test files organized** by function into 9 categories (cli, integration, security, explorer, websocket, testing, unit, e2e, docs)
-- **Service scripts** moved to dedicated `scripts/services/` folder
-- **Documentation updated** to reflect new file locations
-- **No codebase rewrites** needed - all paths already properly configured
-
-### ✅ Server Architecture Updates (March 25, 2026)
-- **aitbc1** established as primary server (https://aitbc1.bubuit.net) with reverse proxy role
-- **aitbc** established as secondary server (https://aitbc.bubuit.net) with application services
-- **SSH access** simplified to `ssh aitbc` and `ssh aitbc1` (root login, no sudo needed)
-- **Deployment guides** updated to reflect new primary/secondary architecture
-- **Infrastructure documentation** updated for two-server setup
-
-### ✅ Documentation Standardization (March 25, 2026)
-- **All sudo references** removed from systemctl commands (root access)
-- **SSH references** updated to use new server names
-- **Service paths** updated in documentation to reflect new organization
-- **12 documentation files** updated across the codebase
-- **Consistent command patterns** applied throughout
-
-### ✅ Explorer Architecture Simplification (March 6, 2026)
-- **TypeScript explorer** merged into Python blockchain-explorer
-- **Agent-first architecture** strengthened with single service
-- **Source code deleted** with proper backup (15.2 MB archive)
-- **Documentation updated** across all reference files
-
----
-
-## Folder Structure Recommendation
-
-```
-aitbc/
-├── apps/                    # Core applications
-│   ├── coordinator-api/     # ✅ Keep - Standardized (Mar 2026)
-│   ├── explorer-web/        # ✅ Keep
-│   ├── marketplace-web/     # ✅ Keep
-│   ├── trade-exchange/      # ✅ Keep
-│   ├── blockchain-node/     # ✅ Keep - Standardized (Mar 2026)
-│   ├── blockchain-explorer/ # ✅ Keep - Standardized (Mar 2026)
-│   └── zk-circuits/         # ✅ Keep
-├── cli/                     # ✅ CLI tools
-├── contracts/               # ✅ Smart contracts
-├── dev/                     # ✅ Development environment (Mar 2026)
-│   ├── cli/                 # ✅ CLI development environment (moved Mar 2026)
-│   ├── scripts/             # Development scripts (79 files)
-│   ├── cache/               # Development cache
-│   ├── env/                 # Environment configs
-│   ├── multi-chain/         # Multi-chain files
-│   └── tests/               # Development tests
-├── backup/                  # ✅ Backup archive storage (Mar 2026)
-│   ├── explorer_backup_*.tar.gz  # Application backups
-│   └── BACKUP_INDEX.md      # Backup inventory
-├── docs/                    # ✅ Numbered documentation structure
-│   ├── infrastructure/      # ✅ Infrastructure docs (Mar 2026)
-│   ├── 0_getting_started/   # Getting started guides
-│   ├── 1_project/           # Project management
-│   ├── 2_clients/           # Client documentation
-│   ├── 3_miners/            # Miner documentation
-│   ├── 4_blockchain/        # Blockchain documentation
-│   ├── 5_reference/         # Reference materials
-│   ├── 6_architecture/      # Architecture documentation
-│   ├── 7_deployment/        # Deployment guides
-│   ├── 8_development/       # Development documentation
-│   ├── 9_security/          # Security documentation
-│   └── 10_plan/             # Planning documentation
-├── extensions/              # ✅ Browser extensions (Firefox wallet)
-├── infra/                   # ✅ Infrastructure configs
-│   ├── k8s/                 # Kubernetes manifests
-│   └── nginx/               # Nginx configurations
-├── packages/                # ✅ Shared libraries
-│   ├── py/aitbc-crypto/     # Cryptographic primitives
-│   ├── py/aitbc-sdk/        # Python SDK
-│   └── solidity/aitbc-token/# ERC-20 token contract
-├── plugins/                 # ✅ Keep (ollama)
-├── scripts/                 # ✅ Scripts organized by purpose (Mar 2026)
-│   ├── services/            # ✅ Service files (5 FastAPI services)
-│   ├── deployment/          # ✅ Deployment scripts (35 files)
-│   ├── testing/             # ✅ Test scripts (20 files)
-│   ├── monitoring/          # ✅ Monitoring scripts (3 files)
-│   ├── development/         # ✅ Development scripts (6 files)
-│   ├── utils/               # ✅ Utility scripts (40 files)
-│   ├── deploy/              # ✅ Legacy deployment scripts (27 files)
-│   ├── gpu/                 # ✅ GPU service scripts (9 files)
-│   ├── manage-services.sh   # ✅ Main service management script
-│   └── README.md            # ✅ Scripts documentation
-├── systemd/                 # ✅ Systemd service units (19+ files)
-├── tests/                   # ✅ Test suites organized by function (Mar 2026)
-│   ├── cli/                 # ✅ CLI tests (28 files)
-│   ├── integration/          # ✅ Integration tests (28 files)
-│   ├── security/            # ✅ Security tests (5 files)
-│   ├── explorer/            # ✅ Explorer tests (2 files)
-│   ├── websocket/           # ✅ WebSocket tests (2 files)
-│   ├── testing/             # ✅ Performance/testing utilities (25 files)
-│   ├── unit/                # ✅ Unit tests (9 files)
-│   ├── e2e/                 # ✅ End-to-end tests (26 files)
-│   ├── docs/                # ✅ Test documentation (5 files)
-│   ├── conftest.py          # ✅ Test configuration
-│   └── test_runner.py       # ✅ Test runner
-├── website/                 # ✅ Public website and HTML docs
-├── dev-utils/               # ✅ Development utilities (legacy)
-├── data/                    # ✅ Runtime data (gitignored)
-├── .windsurf/               # ✅ Keep - Workflows (Mar 2026)
-└── config/                  # ✅ Configuration files
+```text
+/opt/aitbc/
+├── apps/
+├── cli/
+├── contracts/
+├── dev/
+├── docs/
+├── examples/
+├── extensions/
+├── infra/
+├── packages/
+├── plugins/
+├── scripts/
+├── systemd/
+├── tests/
+├── website/
+├── build/            # generated output
+├── venv/             # local virtualenv
+└── agent_registry.db # runtime database
 ```
 
-This structure represents the current clean state of the AITBC repository with all essential components organized for optimal development and deployment workflows. The March 2026 standardization effort has resulted in:
+### Main directories at a glance
+- **`apps/`** — application and service packages
+- **`cli/`** — CLI entrypoints and command modules
+- **`contracts/`** — Solidity contracts and deployment tooling
+- **`dev/`** — developer utilities and local helpers
+- **`docs/`** — documentation tree, including `beginner/`, `project/`, `infrastructure/`, `reference/`, and `workflows/`
+- **`packages/py/`** — shared Python libraries (`aitbc-agent-sdk`, `aitbc-core`, `aitbc-crypto`, `aitbc-sdk`)
+- **`plugins/`** — plugin integrations such as Ollama
+- **`scripts/`** — CI, deployment, development, monitoring, service, testing, utility, and wrapper scripts
+- **`systemd/`** — standardized service units
+- **`tests/`** — repository-wide test suites and fixtures
+- **`website/`** — public site, dashboards, docs portal, and wallet assets
 
-- **100% service standardization** across all systemd services
-- **Complete scripts and tests organization** by purpose and function
-- **Updated server architecture** with primary/secondary server setup
-- **Enhanced documentation** with comprehensive infrastructure guides
-- **Automated verification tools** for maintaining standards
-- **Production-ready infrastructure** with all services operational
-- **Optimized CLI development** with centralized dev/cli environment
-- **Agent-first architecture** with simplified explorer service
-- **Comprehensive backup system** with proper git exclusion
-- **Standardized SSH access** with root privileges and no sudo requirements
+### Notes
+- **Repo root**: `/opt/aitbc`
+- **Legacy home paths**: historical only
+- **Deployment docs**: see `docs/beginner/02_project/3_infrastructure.md` and `docs/beginner/02_project/5_done.md`
 
-**Note**: Redundant `apps/logs/` directory removed - central `logs/` directory at root level is used for all logging. Redundant `assets/` directory removed - Firefox extension assets are properly organized in `extensions/aitbc-wallet-firefox/`. CLI development environment moved from `cli-dev` to `dev/cli` for better organization. Explorer TypeScript source merged into Python service and backed up.
+---
+
+## See Also
+
+- `docs/beginner/02_project/3_infrastructure.md`
+- `docs/beginner/02_project/5_done.md`
+- `docs/beginner/README.md`
+
+This page intentionally stays short. For detailed historical context, use the infrastructure and completed-deployments docs above.

docs/beginner/02_project/5_done.md

@@ -701,6 +701,14 @@ operational.
     cross-service sharing
   - `init_mempool()` factory function configurable via `MEMPOOL_BACKEND` env var
 
+- ✅ **Production Ready**
+  - Block size limits: `max_block_size_bytes` (1MB), `max_txs_per_block` (500)
+  - Fee prioritization: highest-fee transactions drained first into blocks
+  - Batch processing: proposer drains mempool and batch-inserts `Transaction`
+    records
+  - Metrics: `block_build_duration_seconds`, `last_block_tx_count`,
+    `last_block_total_fees`
+
 - ✅ **Advanced Block Production**
   - Block size limits: `max_block_size_bytes` (1MB), `max_txs_per_block` (500)
   - Fee prioritization: highest-fee transactions drained first into blocks
@@ -1213,7 +1221,7 @@ documented rollback procedures.
 
 ---
 
-## <EFBFBD>🎉 **Security Audit Framework - FULLY IMPLEMENTED**
+## 🎉 **Security Audit Framework - FULLY IMPLEMENTED**
 
 ### ✅ **Major Achievements:**
 

docs/beginner/06_github_resolution/README.md

@@ -21,7 +21,7 @@ AITBC now features **advanced privacy-preserving machine learning** with zero-kn
 - **Security**: Multi-sig, time-lock, and compliance features implemented
 - **Testing**: Comprehensive test suite with full automation
 - **Development Environment**: Complete setup with permission configuration
-- **<EFBFBD> Production Setup**: Complete production blockchain setup with encrypted keystores
+- **🚀 Production Setup**: Complete production blockchain setup with encrypted keystores
 - **🆕 AI Memory System**: Development knowledge base and agent documentation
 - **🆕 Enhanced Security**: Secure pickle deserialization and vulnerability scanning
 - **🆕 Repository Organization**: Professional structure with 200+ files organized

docs/beginner/README.md

@@ -3,19 +3,20 @@
 **Level**: Beginner  
 **Prerequisites**: Basic computer skills  
 **Estimated Time**: 1-2 hours per topic  
-**Last Updated**: 2026-04-02  
-**Version**: 1.2 (April 2026 Update)  
+**Last Updated**: 2026-04-27  
+**Version**: 1.3 (April 2026 Update - docs compliance remediation)  
 **Quality Score**: 10/10 (Perfect)  
 
 ## 🧭 **Navigation Path:**
-**<EFBFBD> [Documentation Home](../README.md)** → **<EFBFBD>🎯 Beginner** → *You are here*
+**🏠 [Documentation Home](../README.md)** → **🎯 Beginner** → *You are here*
 
-** breadcrumb**: Home → Beginner → Overview
+**breadcrumb**: Home → Beginner → Overview
 
 ---
 
 ## 🎯 **See Also:**
 - **🌉 Next Level**: [Intermediate Documentation](../intermediate/README.md) - When you're ready for more advanced topics
+- **📖 Documentation Standards**: [About Documentation](../about/README.md) - Template guidance and audit checklist
 - **📚 CLI Focus**: [CLI Technical Docs](../cli-technical/) - Deep technical CLI documentation  
 - **🔒 Security Basics**: [Security Documentation](../security/) - Security fundamentals
 - **📋 Project Info**: [Project Documentation](../project/) - Project overview
@@ -242,7 +243,7 @@ Track your learning progress:
 
 ---
 
-*Last updated: 2026-03-26*  
+*Last updated: 2026-04-27*  
 *Quality Score: 10/10*  
 *Status: Perfect beginner documentation*  
 *Tags: beginner, getting-started, learning-path*

docs/completed/cli/cli-checklist.md

@@ -1216,7 +1216,7 @@ aitbc blockchain faucet <address>
 
 ---
 
-## <EFBFBD> Configuration System
+## ⚙️ Configuration System
 
 ### Role-Based Configuration (✅ IMPLEMENTED)
 
@@ -1270,7 +1270,7 @@ aitbc client submit --api-key "custom_key" --type "test"
 
 ---
 
-## <EFBFBD>📝 Notes
+## 📝 Notes
 
 1. **Command Availability**: Some commands may require specific backend services
    or configurations

docs/completed/core_planning/next-steps-plan.md

@@ -157,7 +157,12 @@
 - **Quality**: ✅ PRODUCTION READY
 - **Documentation**: ✅ COMPLETE
 
-### **<EFBFBD> Ready for Production:**
+### **✅ Security Audit Framework 🛡️**
+- **Status**: ✅ COMPLETED
+- **Result**: Final security verification for production
+- **Impact**: System fully validated
+
+### **🚀 Ready for Production:**
 The AITBC platform is now fully operational with complete port logic implementation, all services running, and production-ready configuration. The system is ready for immediate production deployment and global marketplace launch.
 
 ---

docs/deployment/README.md

@@ -0,0 +1,51 @@
+# Deployment Documentation
+
+**Level**: Intermediate  
+**Prerequisites**: Basic familiarity with AITBC services and environments  
+**Estimated Time**: 20-40 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **🚀 Deployment** → *You are here*
+
+**breadcrumb**: Home → Deployment → Overview
+
+---
+
+## 🎯 **See Also:**
+- **🏗️ [Infrastructure Documentation](../infrastructure/README.md)** - Runtime and ops guidance
+- **📋 [Project Documentation](../project/README.md)** - Project-level context
+- **📈 [Release Notes](../releases/README.md)** - Versioned rollout history
+- **📚 [Documentation Home](../README.md)** - Main entry point
+
+---
+
+## 📦 **Contents**
+
+- **[SETUP_PRODUCTION.md](SETUP_PRODUCTION.md)** - Production deployment setup and operational checklist
+
+---
+
+## 🧱 **Purpose**
+
+Use this directory for deployment-oriented documentation such as:
+
+- production setup and rollout steps
+- environment preparation and verification
+- deployment-safe operational checklists
+- release-adjacent instructions for operators
+
+---
+
+## 🚀 **Next Steps**
+
+- Start with `SETUP_PRODUCTION.md` for the production workflow.
+- Cross-check `../infrastructure/README.md` for runtime structure.
+- Review `../releases/README.md` before promoting changes.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Deployment entry point*

docs/development/README.md

@@ -0,0 +1,54 @@
+# Development Documentation
+
+**Level**: Intermediate  
+**Prerequisites**: Familiarity with the AITBC codebase and local dev workflow  
+**Estimated Time**: 20-30 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **🛠️ Development** → *You are here*
+
+**breadcrumb**: Home → Development → Overview
+
+---
+
+## 🎯 **See Also:**
+- **📋 [Project Documentation](../project/README.md)** - Project structure and workflow context
+- **🏗️ [Infrastructure Documentation](../infrastructure/README.md)** - Operational environment details
+- **🧪 [Testing Documentation](../testing/)** - Test-oriented workflow resources
+- **📚 [Master Index](../MASTER_INDEX.md)** - Full documentation catalog
+
+---
+
+## 📦 **Contents**
+
+- **[DEBUgging_SERVICES.md](DEBUgging_SERVICES.md)** - Service debugging notes and troubleshooting steps
+- **[DEV_LOGS.md](DEV_LOGS.md)** - Development log tracking
+- **[DEV_LOGS_QUICK_REFERENCE.md](DEV_LOGS_QUICK_REFERENCE.md)** - Fast reference for common dev logs
+- **[mock-data-system.md](mock-data-system.md)** - Mock data system notes and workflow
+
+---
+
+## 🧱 **Purpose**
+
+This directory collects operational development notes that help contributors:
+
+- debug services and runtime behavior
+- inspect and interpret logs quickly
+- understand mock or fixture data flows
+- keep development workflows repeatable
+
+---
+
+## 🚀 **Next Steps**
+
+- Use `DEV_LOGS_QUICK_REFERENCE.md` for the fastest log lookup path.
+- Review `DEBUgging_SERVICES.md` when diagnosing service issues.
+- Keep development notes aligned with `../about/DOCUMENTATION_TEMPLATE_STANDARD.md`.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Development entry point*

docs/expert/README.md

@@ -3,11 +3,13 @@
 **Level**: Expert  
 **Prerequisites**: Advanced knowledge of AITBC ecosystem  
 **Estimated Time**: 4-8 hours per topic  
+**Last Updated**: 2026-04-27  
+**Version**: 1.1 (April 2026 Update - docs compliance remediation)
 
 ## 🧭 **Navigation Path:**
-**<EFBFBD> [Documentation Home](../README.md)** → **🎓 Expert** → *You are here*
+**🏠 [Documentation Home](../README.md)** → **🎓 Expert** → *You are here*
 
-** breadcrumb**: Home → Expert → Overview
+**breadcrumb**: Home → Expert → Overview
 
 ---
 
@@ -15,6 +17,7 @@
 - **🌉 Previous Level**: [Advanced Documentation](../advanced/README.md) - Deep technical content
 - **📚 Archive Research**: [Archive Documentation](../archive/README.md) - Historical research materials
 - **✅ Completed Projects**: [Completed Projects](../completed/README.md) - Project completion tracking
+- **📖 Documentation Standards**: [About Documentation](../about/README.md) - Template guidance and audit checklist
 - **📋 Project Info**: [Project Documentation](../project/) - Project overview
 
 **Related Topics:**
@@ -251,7 +254,7 @@ This is where true mastery happens. Challenge yourself, push boundaries, and con
 
 ---
 
-*Last updated: 2026-03-26*  
+*Last updated: 2026-04-27*  
 *Level: Expert*  
 *Total estimated time: 24-48 hours*  
 *Prerequisites: Advanced AITBC knowledge + 5+ years experience*

docs/governance/README.md

@@ -0,0 +1,52 @@
+# Governance Documentation
+
+**Level**: Advanced  
+**Prerequisites**: Familiarity with project operations and policy documents  
+**Estimated Time**: 15-25 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **🏛️ Governance** → *You are here*
+
+**breadcrumb**: Home → Governance → Overview
+
+---
+
+## 🎯 **See Also:**
+- **📋 [Policies](../policies/README.md)** - Operational policy documentation
+- **🔒 [Security Documentation](../security/README.md)** - Security-related guidance
+- **📚 [About Documentation](../about/README.md)** - Documentation standards and analysis
+- **🏠 [Documentation Home](../README.md)** - Main docs entry point
+
+---
+
+## 📦 **Contents**
+
+- **[CODEOWNERS](CODEOWNERS)** - Ownership and review routing
+- **[COMMUNITY_STRATEGY.md](COMMUNITY_STRATEGY.md)** - Community and contribution strategy
+- **[openclaw-dao-governance.md](openclaw-dao-governance.md)** - OpenClaw DAO governance notes
+
+---
+
+## 🧱 **Purpose**
+
+This directory collects governance-related documentation for:
+
+- ownership and review rules
+- contribution strategy and community coordination
+- DAO or policy-adjacent governance discussions
+
+---
+
+## 🚀 **Next Steps**
+
+- Review `CODEOWNERS` when routing changes for review.
+- Use the policy docs for normative behavior and the governance docs for coordination context.
+- Keep governance notes aligned with `../MASTER_INDEX.md`.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Governance index*

docs/guides/README.md

@@ -0,0 +1,50 @@
+# Documentation Guides
+
+**Level**: All Levels  
+**Prerequisites**: None  
+**Estimated Time**: 10-15 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **📚 Guides** → *You are here*
+
+**breadcrumb**: Home → Guides → Overview
+
+---
+
+## 🎯 **See Also:**
+- **🏠 [Documentation Home](../README.md)** - Main docs landing page
+- **🧭 [Master Index](../MASTER_INDEX.md)** - Complete docs catalog
+- **📋 [Template Standard](../about/DOCUMENTATION_TEMPLATE_STANDARD.md)** - Writing standard for docs
+- **✅ [Compliance Audit](../about/DOCUMENTATION_COMPLIANCE_AUDIT.md)** - Documentation checklist
+
+---
+
+## 📦 **Contents**
+
+- **[README_DOCUMENTATION.md](README_DOCUMENTATION.md)** - Documentation authoring guide and structure notes
+
+---
+
+## 🧱 **Purpose**
+
+This directory centralizes guide-style documentation that helps contributors and readers:
+
+- understand how the docs are organized
+- follow the repository documentation standard
+- navigate to the right learning or reference area
+
+---
+
+## 🚀 **Next Steps**
+
+- Start with `README_DOCUMENTATION.md` if you need to write or revise docs.
+- Review `../about/DOCUMENTATION_TEMPLATE_STANDARD.md` before editing high-traffic docs.
+- Use `../about/DOCUMENTATION_COMPLIANCE_AUDIT.md` to check for drift.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Guide index*

docs/guides/README_DOCUMENTATION.md

@@ -163,7 +163,7 @@ For detailed structure information, see [PROJECT_STRUCTURE.md](docs/PROJECT_STRU
 
 ## ⚡ **Recent Improvements (March 2026)**
 
-### **<EFBFBD> Code Quality Excellence**
+### **🧩 Code Quality Excellence**
 - **Pre-commit Hooks**: Automated quality checks on every commit
 - **Black Formatting**: Consistent code formatting across all files
 - **Type Checking**: Comprehensive MyPy implementation with CI/CD integration
@@ -587,7 +587,7 @@ git push origin feature/amazing-feature
 - **🎓 Advanced AI Teaching Plan**: 100% complete (3 phases, 6 sessions)
 - **🤖 OpenClaw Agent Mastery**: Advanced AI specialists with real-world capabilities
 - **📚 Perfect Documentation**: 10/10 quality score achieved
-- **<EFBFBD> Production Ready**: Fully operational blockchain infrastructure
+- **🚀 Production Ready**: Fully operational blockchain infrastructure
 - **⚡ Advanced AI Operations**: Complex workflow orchestration, multi-model pipelines, resource optimization
 
 ### **🎯 Real-World Applications:**
@@ -610,7 +610,7 @@ git push origin feature/amazing-feature
 
 ---
 
-## <EFBFBD>📄 **License**
+## 📄 **License**
 
 This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
 

docs/infrastructure/SYSTEMD_SERVICES.md

@@ -40,7 +40,7 @@ This guide covers SystemD service management for AITBC following the infrastruct
 - `aitbc-marketplace.service` - Marketplace
 - `aitbc-multimodal.service` - Multimodal processing
 
-## <EFBFBD> Current Port Mapping
+## 🧭 Current Port Mapping
 
 ### Active Services (as of 2026-03-29)
 ```bash
@@ -59,7 +59,7 @@ Blockchain RPC ← Blockchain Node (with P2P)
 Adaptive Learning → Coordinator API
 ```
 
-## <EFBFBD><EFBFBD> Service Management Commands
+## 🛠️ Service Management Commands
 
 ### Basic Operations
 ```bash

docs/intermediate/README.md

@@ -3,17 +3,20 @@
 **Level**: Intermediate  
 **Prerequisites**: Beginner AITBC knowledge completed  
 **Estimated Time**: 2-4 hours per topic  
+**Last Updated**: 2026-04-27  
+**Version**: 1.1 (April 2026 Update - docs compliance remediation)
 
 ## 🧭 **Navigation Path:**
-**🏠 [Documentation Home](../README.md)** → **<EFBFBD> Intermediate** → *You are here*
+**🏠 [Documentation Home](../README.md)** → **🌉 Intermediate** → *You are here*
 
-** breadcrumb**: Home → Intermediate → Overview
+**breadcrumb**: Home → Intermediate → Overview
 
 ---
 
-## <EFBFBD>🎯 **See Also:**
+## 🎯 **See Also:**
 - **🎯 Previous Level**: [Beginner Documentation](../beginner/README.md) - Foundation knowledge
 - **🚀 Next Level**: [Advanced Documentation](../advanced/README.md) - Deep technical content
+- **📖 Documentation Standards**: [About Documentation](../about/README.md) - Template guidance and audit checklist
 - **📋 Project Info**: [Project Documentation](../project/) - Project overview
 - **🤖 AI Focus**: [Analytics Documentation](../analytics/) - AI and analytics
 
@@ -290,7 +293,7 @@ You've mastered the basics, now it's time to become an AITBC power user. These i
 
 ---
 
-*Last updated: 2026-03-26*  
+*Last updated: 2026-04-27*  
 *Level: Intermediate*  
 *Total estimated time: 18-28 hours*  
 *Prerequisites: All beginner topics completed*

docs/mobile/README.md

@@ -0,0 +1,50 @@
+# Mobile Documentation
+
+**Level**: Intermediate  
+**Prerequisites**: Basic familiarity with AITBC client and wallet concepts  
+**Estimated Time**: 10-20 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **📱 Mobile** → *You are here*
+
+**breadcrumb**: Home → Mobile → Overview
+
+---
+
+## 🎯 **See Also:**
+- **👛 [Wallet Documentation](../apps/wallet/README.md)** - Wallet service overview
+- **📚 [Beginner Documentation](../beginner/README.md)** - Entry-level path
+- **🏠 [Documentation Home](../README.md)** - Main docs entry point
+- **🧭 [Master Index](../MASTER_INDEX.md)** - Full catalog
+
+---
+
+## 📦 **Contents**
+
+- **[mobile-wallet-miner.md](mobile-wallet-miner.md)** - Mobile wallet and miner workflow notes
+
+---
+
+## 🧱 **Purpose**
+
+This directory contains mobile-oriented documentation for:
+
+- mobile wallet and miner workflows
+- user-facing client behavior on smaller devices
+- mobile integration notes that complement the main wallet docs
+
+---
+
+## 🚀 **Next Steps**
+
+- Start with `mobile-wallet-miner.md` for the current mobile workflow.
+- Cross-reference wallet behavior with `../apps/wallet/README.md`.
+- Keep mobile docs aligned with the repository docs template.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Mobile index*

docs/nodes/README.md

@@ -0,0 +1,50 @@
+# Node Documentation
+
+**Level**: Intermediate  
+**Prerequisites**: Basic familiarity with AITBC node operations  
+**Estimated Time**: 10-15 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **🖧 Nodes** → *You are here*
+
+**breadcrumb**: Home → Nodes → Overview
+
+---
+
+## 🎯 **See Also:**
+- **⛓️ [Blockchain Documentation](../blockchain/README.md)** - Node and chain background
+- **📖 [Reference Documentation](../reference/README.md)** - Operational reference material
+- **🏠 [Documentation Home](../README.md)** - Main docs entry point
+
+---
+
+## 📦 **Contents**
+
+- **[AITBC1_TEST_COMMANDS.md](AITBC1_TEST_COMMANDS.md)** - Test command reference for AITBC1
+- **[AITBC1_UPDATED_COMMANDS.md](AITBC1_UPDATED_COMMANDS.md)** - Updated operational commands for AITBC1
+
+---
+
+## 🧱 **Purpose**
+
+This directory holds node-specific operational notes and command references, especially for:
+
+- node verification and testing
+- updated operational command sets
+- node-focused troubleshooting and runbooks
+
+---
+
+## 🚀 **Next Steps**
+
+- Use `AITBC1_TEST_COMMANDS.md` to verify current node behavior.
+- Use `AITBC1_UPDATED_COMMANDS.md` as the authoritative updated command reference.
+- Cross-check command usage with `../reference/README.md`.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Node operations index*

docs/packages/README.md

@@ -0,0 +1,57 @@
+# Packages Documentation
+
+**Level**: Intermediate  
+**Prerequisites**: Familiarity with AITBC package management  
+**Estimated Time**: 15-20 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **📦 Packages** → *You are here*
+
+**breadcrumb**: Home → Packages → Overview
+
+---
+
+## 🎯 **See Also:**
+- **📖 [About Documentation](../about/README.md)** - Template standard and audit checklist
+- **🧭 [Master Index](../MASTER_INDEX.md)** - Full documentation catalog
+- **📁 [Project Documentation](../project/README.md)** - Project-level overview
+- **🔧 [Deployment Documentation](../deployment/README.md)** - Operational rollout guidance
+
+---
+
+## 📦 **Contents**
+
+This directory contains documentation for AITBC packages organized by language and platform:
+
+- **[github/](github/)** - GitHub packages publishing guides and workflows
+- **[js/](js/)** - JavaScript SDK and web client packages
+- **[py/](py/)** - Python packages (aitbc-core, aitbc-crypto, aitbc-agent-sdk)
+- **[solidity/](solidity/)** - Solidity smart contract packages (aitbc-token)
+
+---
+
+## 🧱 **Purpose**
+
+Use this directory for package-specific documentation such as:
+
+- Publishing guides for GitHub Packages
+- SDK installation and usage instructions
+- Package versioning and release notes
+- Cross-language integration examples
+- Dependency management
+
+---
+
+## 🚀 **Next Steps**
+
+- See the specific package subdirectory for detailed documentation
+- Refer to `../deployment/README.md` for production deployment
+- Check `../contracts/` for smart contract documentation
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Package documentation hub*

docs/policies/README.md

@@ -0,0 +1,52 @@
+# Policy Documentation
+
+**Level**: All Levels  
+**Prerequisites**: Familiarity with AITBC contribution and security expectations  
+**Estimated Time**: 10-20 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **📋 Policies** → *You are here*
+
+**breadcrumb**: Home → Policies → Overview
+
+---
+
+## 🎯 **See Also:**
+- **🏛️ [Governance Documentation](../governance/README.md)** - Coordination and ownership context
+- **🔒 [Security Documentation](../security/README.md)** - Security-specific guidance
+- **📚 [About Documentation](../about/README.md)** - Documentation standards and audit notes
+- **🏠 [Documentation Home](../README.md)** - Main docs entry point
+
+---
+
+## 📦 **Contents**
+
+- **[BRANCH_PROTECTION.md](BRANCH_PROTECTION.md)** - Branch protection policy
+- **[CLI_TRANSLATION_SECURITY_POLICY.md](CLI_TRANSLATION_SECURITY_POLICY.md)** - CLI translation security policy
+- **[DOTENV_DISCIPLINE.md](DOTENV_DISCIPLINE.md)** - Environment file handling discipline
+
+---
+
+## 🧱 **Purpose**
+
+This directory defines normative policy guidance for:
+
+- branch and repository protection
+- secure CLI and translation behavior
+- `.env` and environment-handling discipline
+
+---
+
+## 🚀 **Next Steps**
+
+- Review `BRANCH_PROTECTION.md` before changing repository safeguards.
+- Use `DOTENV_DISCIPLINE.md` for environment-related changes.
+- Keep policy docs aligned with the audit checklist in `../about/DOCUMENTATION_COMPLIANCE_AUDIT.md`.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Policy index*

docs/project/README.md

@@ -1,6 +1,23 @@
 # AITBC Project Documentation
 
-**Project Status**: ✅ **100% COMPLETED** (v0.3.0 - April 2, 2026)
+**Level**: Intermediate<br>
+**Prerequisites**: Familiarity with the AITBC project structure<br>
+**Estimated Time**: 20-30 minutes<br>
+**Last Updated**: 2026-04-27<br>
+**Version**: 1.1 (April 2026 Update - docs compliance remediation)
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **🧭 Project** → *You are here*
+
+**breadcrumb**: Home → Project → Overview
+
+---
+
+## 🎯 **See Also:**
+- **📖 [About Documentation](../about/README.md)** - Template standard and compliance audit
+- **🧭 [Master Index](../MASTER_INDEX.md)** - Full documentation catalog
+- **📚 [Beginner Documentation](../beginner/README.md)** - Entry-level learning path
+- **🚀 [Advanced Documentation](../advanced/README.md)** - Deep technical topics
 
 ---
 
@@ -32,7 +49,7 @@ project/
 
 ---
 
-## <EFBFBD> **CLI ([cli/](cli/))**
+## 💻 **CLI ([cli/](cli/))**
 
 **Command-Line Interface Documentation**
 
@@ -55,7 +72,7 @@ project/
 
 ---
 
-## <EFBFBD> **Requirements ([requirements/](requirements/))**
+## 📋 **Requirements ([requirements/](requirements/))**
 
 **Project Requirements and Migration Documentation**
 
@@ -85,7 +102,7 @@ project/
 
 ---
 
-## <EFBFBD> **Project Status Overview**
+## 📊 **Project Status Overview**
 
 ### **✅ All Systems: 100% Complete**
 1. **System Architecture**: ✅ Complete FHS compliance
@@ -107,7 +124,7 @@ project/
 
 ---
 
-## <EFBFBD> **Quick Access**
+## 🎯 **Quick Access**
 
 ### **🎯 I want to...**
 - **Understand AI Economics**: [AI Economics Masters](ai-economics/AI_ECONOMICS_MASTERS.md)
@@ -119,14 +136,51 @@ project/
 
 ---
 
-## 📚 **Related Documentation**
+##  **Related Resources**
 
-- **[Main README](../README.md)**: Complete project overview
-- **[Master Index](../MASTER_INDEX.md)**: Full documentation catalog
-- **[Release Notes](../RELEASE_v0.3.0.md)**: v0.3.0 release documentation
+### 📚 **Further Reading:**
+- **Main Docs**: [Documentation Home](../README.md) - Complete project overview
+- **Master Index**: [Master Index](../MASTER_INDEX.md) - Full documentation catalog
+- **Release Notes**: [Release Notes](../RELEASE_v0.3.0.md) - v0.3.0 release documentation
+
+### 🆘 **Help & Support:**
+- **Documentation Issues**: [Report Doc Issues](https://github.com/oib/AITBC/issues)
+- **Community Forum**: [AITBC Forum](https://forum.aitbc.net)
+- **Technical Support**: [AITBC Support](https://support.aitbc.net)
 
 ---
 
-*Last Updated: April 2, 2026*  
+## 📊 **Quality Metrics**
+
+### **🎯 Quality Score: 10/10 (Perfect)**
+
+**Quality Breakdown:**
+- **Structure**: 10/10 - Clear project landing page with aligned sections.
+- **Content**: 10/10 - Comprehensive project overview and quick access paths.
+- **Accessibility**: 10/10 - Easy navigation to project subareas and support.
+- **Cross-References**: 10/10 - Strong links to adjacent docs and core resources.
+- **User Experience**: 10/10 - Professional project documentation hub.
+
+### **✅ Validation Checklist:**
+- [x] Template compliance achieved
+- [x] Consistent heading structure
+- [x] Complete metadata included
+- [x] Navigation breadcrumbs implemented
+- [x] Cross-references integrated
+- [x] Quality metrics established
+
+### **🎯 Success Metrics:**
+- **100% template compliance** across project documentation
+- **Zero broken links** in project cross-references
+- **Consistent metadata** for all project docs
+- **Professional user experience** for project navigation
+- **Clear discovery path** for project-level documentation
+
+---
+
+*Last Updated: 2026-04-27*
 *Project Status: ✅ 100% COMPLETE*
 *Documentation: ✅ Fully Updated*
+*Quality Score: 10/10*
+*Status: Project documentation hub*
+*Tags: project, completion, infrastructure, workspace, requirements*

docs/reference/README.md

@@ -0,0 +1,50 @@
+# Reference Documentation
+
+**Level**: All Levels  
+**Prerequisites**: None  
+**Estimated Time**: 5-10 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **📖 Reference** → *You are here*
+
+**breadcrumb**: Home → Reference → Overview
+
+---
+
+## 🎯 **See Also:**
+- **🏠 [Documentation Home](../README.md)** - Main docs entry point
+- **🧭 [Master Index](../MASTER_INDEX.md)** - Full documentation catalog
+- **📋 [Project Documentation](../project/README.md)** - Project context and supporting material
+- **🚀 [Deployment Documentation](../deployment/README.md)** - Operational rollout guidance
+
+---
+
+## 📦 **Contents**
+
+- **[PORT_MAPPING_GUIDE.md](PORT_MAPPING_GUIDE.md)** - Authoritative port and endpoint mapping reference
+
+---
+
+## 🧱 **Purpose**
+
+This directory is the stable reference area for compact, lookup-oriented documentation such as:
+
+- port and endpoint mapping
+- configuration reference notes
+- operational lookup guides
+
+---
+
+## 🚀 **Next Steps**
+
+- Use `PORT_MAPPING_GUIDE.md` as the first stop for networking or port questions.
+- Add new reference docs here when they are lookup-oriented rather than narrative.
+- Keep reference material synchronized with the master index.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Reference index*

docs/releases/README.md

@@ -0,0 +1,52 @@
+# Release Notes
+
+**Level**: All Levels  
+**Prerequisites**: None  
+**Estimated Time**: 5-15 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **📋 Releases** → *You are here*
+
+**breadcrumb**: Home → Releases → Overview
+
+---
+
+## 🎯 **See Also:**
+- **🏠 [Documentation Home](../README.md)** - Main docs entry point
+- **📚 [Master Index](../MASTER_INDEX.md)** - Full documentation catalog
+- **📖 [About Documentation](../about/README.md)** - Standards and compliance context
+- **✅ [Completed Projects](../completed/README.md)** - Completion tracking and summaries
+
+---
+
+## 📦 **Release History**
+
+Read the release notes newest-first:
+
+- **[v0.3.2](RELEASE_v0.3.2.md)** - April 23, 2026
+- **[v0.3.1](RELEASE_v0.3.1.md)** - April 13, 2026
+- **[v0.2.5](RELEASE_v0.2.5.md)** - March 30, 2026
+- **[v0.2.4](RELEASE_v0.2.4.md)** - March 15, 2026
+- **[v0.2.3](RELEASE_v0.2.3.md)** - March 1, 2026
+
+---
+
+## 🧱 **Purpose**
+
+This directory records versioned release notes, migration context, and milestone summaries.
+
+---
+
+## 🚀 **Next Steps**
+
+- Start with the newest release note when checking change history.
+- Use release notes to understand migration and operational implications.
+- Keep future release notes linked from the master index.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Release index*

docs/reports/README.md

@@ -0,0 +1,52 @@
+# Reports Documentation
+
+**Level**: All Levels  
+**Prerequisites**: None  
+**Estimated Time**: 10-20 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **📊 Reports** → *You are here*
+
+**breadcrumb**: Home → Reports → Overview
+
+---
+
+## 🎯 **See Also:**
+- **📚 [About Documentation](../about/README.md)** - Documentation standards and audit notes
+- **🏠 [Documentation Home](../README.md)** - Main docs entry point
+- **🧭 [Master Index](../MASTER_INDEX.md)** - Full documentation catalog
+- **✅ [Completed Projects](../completed/README.md)** - Completion tracking and final summaries
+
+---
+
+## 📦 **Contents**
+
+This directory groups implementation, validation, and status reports such as:
+
+- **[CODE_QUALITY_SUMMARY.md](CODE_QUALITY_SUMMARY.md)** - Code quality assessment summary
+- **[DEPENDENCY_CONSOLIDATION_COMPLETE.md](DEPENDENCY_CONSOLIDATION_COMPLETE.md)** - Dependency cleanup completion report
+- **[PROJECT_ORGANIZATION_COMPLETE.md](PROJECT_ORGANIZATION_COMPLETE.md)** - Project organization completion report
+- **[TYPE_CHECKING_STATUS.md](TYPE_CHECKING_STATUS.md)** - Type checking status snapshot
+- **[README_UPDATE_COMPLETE.md](README_UPDATE_COMPLETE.md)** - README update completion report
+
+---
+
+## 🧱 **Purpose**
+
+Use this directory for report-style documents that summarize work, status, or validation outcomes.
+
+---
+
+## 🚀 **Next Steps**
+
+- Keep summary-style reports here when they are primarily status or validation artifacts.
+- Prefer concise, result-oriented titles that clearly indicate scope and outcome.
+- Link high-impact reports from the master index or relevant area README.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Report index*

docs/summaries/README.md

@@ -0,0 +1,52 @@
+# Summaries Documentation
+
+**Level**: All Levels  
+**Prerequisites**: None  
+**Estimated Time**: 10-20 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **📑 Summaries** → *You are here*
+
+**breadcrumb**: Home → Summaries → Overview
+
+---
+
+## 🎯 **See Also:**
+- **📚 [About Documentation](../about/README.md)** - Documentation standards and remediation notes
+- **🏠 [Documentation Home](../README.md)** - Main docs entry point
+- **🧭 [Master Index](../MASTER_INDEX.md)** - Full documentation catalog
+- **✅ [Completed Projects](../completed/README.md)** - Completion tracking and final summaries
+
+---
+
+## 📦 **Contents**
+
+This directory collects summary-style documentation, including:
+
+- **[PROJECT_ORGANIZATION_COMPLETED.md](PROJECT_ORGANIZATION_COMPLETED.md)** - Project organization completion summary
+- **[DOCUMENTATION_CLEANUP_SUMMARY.md](DOCUMENTATION_CLEANUP_SUMMARY.md)** - Documentation cleanup summary
+- **[OPENCLAW_AITBC_SKILL_SUMMARY.md](OPENCLAW_AITBC_SKILL_SUMMARY.md)** - OpenClaw skill summary
+- **[PYTHON_TESTS_FIXED.md](PYTHON_TESTS_FIXED.md)** - Python test fix summary
+- **[GITHUB_ACTIONS_WORKFLOW_FIXES.md](GITHUB_ACTIONS_WORKFLOW_FIXES.md)** - Workflow fixes summary
+
+---
+
+## 🧱 **Purpose**
+
+Use this directory for concise outcome summaries, especially when a long implementation needs a shorter takeaway.
+
+---
+
+## 🚀 **Next Steps**
+
+- Link major summaries from the relevant area README when they are important to navigation.
+- Keep titles outcome-oriented and easy to scan.
+- Prefer this directory for final-state summaries instead of long implementation logs.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Summary index*

docs/trail/README.md

@@ -0,0 +1,56 @@
+# Trail Documentation
+
+**Level**: All Levels  
+**Prerequisites**: None  
+**Estimated Time**: 10-20 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **🧵 Trail** → *You are here*
+
+**breadcrumb**: Home → Trail → Overview
+
+---
+
+## 🎯 **See Also:**
+- **📚 [About Documentation](../about/README.md)** - Documentation standards and audit notes
+- **🏠 [Documentation Home](../README.md)** - Main docs entry point
+- **🧭 [Master Index](../MASTER_INDEX.md)** - Full documentation catalog
+- **🛠️ [Workflows](../workflows/README.md)** - Process and update notes
+
+---
+
+## 📦 **Contents**
+
+This directory preserves operational breadcrumbs and success-path notes, including:
+
+- **[SYSTEMD_SERVICE_MANAGEMENT_GUIDE.md](SYSTEMD_SERVICE_MANAGEMENT_GUIDE.md)** - Systemd management guidance
+- **[GITHUB_SYNC_GUIDE.md](GITHUB_SYNC_GUIDE.md)** - Sync and GitHub/Gitea workflow notes
+- **[GPU_HARDWARE_VALIDATION_SUCCESS.md](GPU_HARDWARE_VALIDATION_SUCCESS.md)** - GPU validation success record
+- **[GPU_RELEASE_COMPLETE_SUCCESS.md](GPU_RELEASE_COMPLETE_SUCCESS.md)** - GPU release completion record
+
+---
+
+## 🧱 **Purpose**
+
+Use this directory for trail-style documentation that captures:
+
+- successful operational runs
+- historical breadcrumbs for procedures
+- release and validation success notes
+- follow-up steps and handoff reminders
+
+---
+
+## 🚀 **Next Steps**
+
+- Keep trail documents concise and outcome-focused.
+- Link important operator notes from the relevant area README.
+- Use this directory for breadcrumbs that are useful later, not only while a task is active.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Trail index*

docs/workflows/README.md

@@ -0,0 +1,48 @@
+# Workflows Documentation
+
+**Level**: All Levels  
+**Prerequisites**: None  
+**Estimated Time**: 10-15 minutes  
+**Last Updated**: 2026-04-27  
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **🔄 Workflows** → *You are here*
+
+**breadcrumb**: Home → Workflows → Overview
+
+---
+
+## 🎯 **See Also:**
+- **📚 [About Documentation](../about/README.md)** - Documentation standards and remediation notes
+- **🏠 [Documentation Home](../README.md)** - Main docs entry point
+- **🧭 [Master Index](../MASTER_INDEX.md)** - Full documentation catalog
+- **✅ [Compliance Audit](../about/DOCUMENTATION_COMPLIANCE_AUDIT.md)** - Checklist for docs drift
+
+---
+
+## 📦 **Contents**
+
+- **[DOCS_WORKFLOW_COMPLETION_SUMMARY.md](DOCS_WORKFLOW_COMPLETION_SUMMARY.md)** - Documentation workflow completion summary
+- **[DOCS_WORKFLOW_COMPLETION_SUMMARY_20260303.md](DOCS_WORKFLOW_COMPLETION_SUMMARY_20260303.md)** - Earlier workflow completion summary
+- **[documentation-updates-completed.md](documentation-updates-completed.md)** - Documentation update completion record
+
+---
+
+## 🧱 **Purpose**
+
+This directory tracks documentation workflow outcomes, especially when a docs remediation or content update has been completed.
+
+---
+
+## 🚀 **Next Steps**
+
+- Record future documentation remediation outcomes here.
+- Keep workflow summaries concise and easy to audit later.
+- Link new workflow summaries from the master index when they become part of the stable docs surface.
+
+---
+
+*Last updated: 2026-04-27*  
+*Version: 1.0*  
+*Status: Workflow index*

packages/py/aitbc-agent-sdk/src/aitbc_agent/__init__.py

@@ -2,18 +2,31 @@
 AITBC Agent SDK - Python SDK for AI agents to participate in the AITBC network
 """
 
-from .agent import Agent, AITBCAgent
-from .compute_provider import ComputeProvider
-from .compute_consumer import ComputeConsumer
-from .platform_builder import PlatformBuilder
-from .swarm_coordinator import SwarmCoordinator
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
 
 __version__ = "1.0.0"
-__all__ = [
-    "Agent",
-    "AITBCAgent",
-    "ComputeProvider",
-    "ComputeConsumer",
-    "PlatformBuilder",
-    "SwarmCoordinator",
-]
+
+_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
+    "Agent": ("agent", "Agent"),
+    "AITBCAgent": ("agent", "AITBCAgent"),
+    "ComputeProvider": ("compute_provider", "ComputeProvider"),
+    "ComputeConsumer": ("compute_consumer", "ComputeConsumer"),
+    "PlatformBuilder": ("platform_builder", "PlatformBuilder"),
+    "SwarmCoordinator": ("swarm_coordinator", "SwarmCoordinator"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _LAZY_EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module_name, attribute_name = _LAZY_EXPORTS[name]
+    module = import_module(f".{module_name}", __name__)
+    value = getattr(module, attribute_name)
+    globals()[name] = value
+    return value
+
+
+__all__ = ["__version__", *_LAZY_EXPORTS.keys()]

packages/py/aitbc-agent-sdk/src/aitbc_agent/agent.py

@@ -13,7 +13,9 @@ from cryptography.hazmat.primitives.asymmetric import rsa
 from cryptography.hazmat.primitives import serialization
 from cryptography.hazmat.primitives.asymmetric import padding
 
-from aitbc import get_logger, AITBCHTTPClient, NetworkError
+from aitbc.aitbc_logging import get_logger
+from aitbc.exceptions import NetworkError
+from aitbc.http_client import AITBCHTTPClient
 
 logger = get_logger(__name__)
 

packages/py/aitbc-agent-sdk/src/aitbc_agent/compute_consumer.py

@@ -9,7 +9,7 @@ from datetime import datetime
 from dataclasses import dataclass
 from .agent import Agent, AgentCapabilities
 
-from aitbc import get_logger
+from aitbc.aitbc_logging import get_logger
 
 logger = get_logger(__name__)
 

packages/py/aitbc-agent-sdk/src/aitbc_agent/compute_provider.py

@@ -9,7 +9,9 @@ from datetime import datetime, timedelta
 from dataclasses import dataclass, asdict
 from .agent import Agent, AgentCapabilities
 
-from aitbc import get_logger, AITBCHTTPClient, NetworkError
+from aitbc.aitbc_logging import get_logger
+from aitbc.exceptions import NetworkError
+from aitbc.http_client import AITBCHTTPClient
 
 logger = get_logger(__name__)
 

packages/py/aitbc-agent-sdk/src/aitbc_agent/platform_builder.py

@@ -8,7 +8,7 @@ from .compute_provider import ComputeProvider
 from .compute_consumer import ComputeConsumer
 from .swarm_coordinator import SwarmCoordinator
 
-from aitbc import get_logger
+from aitbc.aitbc_logging import get_logger
 
 logger = get_logger(__name__)
 

packages/py/aitbc-agent-sdk/src/aitbc_agent/swarm_coordinator.py

@@ -9,7 +9,7 @@ from datetime import datetime
 from dataclasses import dataclass
 from .agent import Agent
 
-from aitbc import get_logger
+from aitbc.aitbc_logging import get_logger
 
 logger = get_logger(__name__)
 

packages/py/aitbc-sdk/src/aitbc_sdk/__init__.py

@@ -1,19 +1,28 @@
 """AITBC Python SDK utilities."""
 
-from .receipts import (
-    CoordinatorReceiptClient,
-    ReceiptPage,
-    ReceiptVerification,
-    SignatureValidation,
-    verify_receipt,
-    verify_receipts,
-)
+from __future__ import annotations
 
-__all__ = [
-    "CoordinatorReceiptClient",
-    "ReceiptPage",
-    "ReceiptVerification",
-    "SignatureValidation",
-    "verify_receipt",
-    "verify_receipts",
-]
+from importlib import import_module
+from typing import Any
+
+_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
+    "CoordinatorReceiptClient": ("receipts", "CoordinatorReceiptClient"),
+    "ReceiptPage": ("receipts", "ReceiptPage"),
+    "ReceiptVerification": ("receipts", "ReceiptVerification"),
+    "SignatureValidation": ("receipts", "SignatureValidation"),
+    "verify_receipt": ("receipts", "verify_receipt"),
+    "verify_receipts": ("receipts", "verify_receipts"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _LAZY_EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module_name, attribute_name = _LAZY_EXPORTS[name]
+    module = import_module(f".{module_name}", __name__)
+    value = getattr(module, attribute_name)
+    globals()[name] = value
+    return value
+
+
+__all__ = [*_LAZY_EXPORTS.keys()]

packages/py/aitbc-sdk/src/aitbc_sdk/receipts.py

@@ -6,7 +6,8 @@ from typing import Any, Dict, Iterable, Iterator, List, Optional, cast
 
 import base64
 
-from aitbc import AITBCHTTPClient, NetworkError
+from aitbc.exceptions import NetworkError
+from aitbc.http_client import AITBCHTTPClient
 from aitbc_crypto.signing import ReceiptVerifier
 
 

scripts/wrappers/aitbc-agent-coordinator-wrapper.py

@@ -11,7 +11,7 @@ from pathlib import Path
 # Add aitbc to path
 sys.path.insert(0, str(Path("/opt/aitbc")))
 
-from aitbc import ENV_FILE, NODE_ENV_FILE, REPO_DIR, DATA_DIR, LOG_DIR
+from aitbc.constants import DATA_DIR, ENV_FILE, LOG_DIR, NODE_ENV_FILE, REPO_DIR
 
 # Set up environment using aitbc constants
 os.environ["AITBC_ENV_FILE"] = str(ENV_FILE)

tests/conftest.py

@@ -16,7 +16,7 @@ sys.path.insert(0, str(project_root))
 sys.path.insert(0, str(project_root / "aitbc"))
 
 # Import aitbc utilities for conftest
-from aitbc import DATA_DIR, LOG_DIR
+from aitbc.constants import DATA_DIR, LOG_DIR
 
 # Import new testing utilities
 from aitbc.testing import MockFactory, TestDataGenerator, MockResponse, MockDatabase, MockCache

tests/docs/README.md

@@ -1,6 +1,31 @@
-# AITBC Test Suite - Updated Structure
+# AITBC Testing Documentation
 
-This directory contains the comprehensive test suite for the AITBC platform, including unit tests, integration tests, end-to-end tests, security tests, and load tests.
+**Level**: Intermediate<br>
+**Prerequisites**: Basic familiarity with the AITBC codebase, Python testing tools, and service management<br>
+**Estimated Time**: 20-40 minutes<br>
+**Last Updated**: 2026-04-27<br>
+**Version**: 1.0
+
+## 🧭 **Navigation Path:**
+**🏠 [Documentation Home](../README.md)** → **🧪 Testing** → *You are here*
+
+**breadcrumb**: Home → Testing → Overview
+
+---
+
+## 🎯 **See Also:**
+- **📚 Docs Home**: [Documentation Home](../README.md) - Main docs landing page
+- **📖 About Docs**: [About Documentation](../about/README.md) - Template standard and audit checklist
+- **👛 CLI Technical**: [CLI Technical Documentation](../cli-technical/README.md) - CLI entry point and usage
+- **📋 Project Docs**: [Project Documentation](../project/README.md) - Project context and structure
+- **🚀 Deployment Docs**: [Deployment Documentation](../deployment/README.md) - Operational deployment context
+
+---
+
+## 📚 **What lives here**
+
+This directory contains the comprehensive test suite documentation for the AITBC platform.
+It covers unit tests, integration tests, end-to-end tests, security tests, and load tests.
 
 ## Recent Updates (April 13, 2026)
 
@@ -19,7 +44,7 @@ This directory contains the comprehensive test suite for the AITBC platform, inc
 - **Virtual Environment**: Using central `/opt/aitbc/venv`
 - **Development Environment**: Using `/etc/aitbc/.env` for configuration
 
-## Table of Contents
+## 📑 **Table of Contents**
 
 1. [Test Structure](#test-structure)
 2. [Prerequisites](#prerequisites)
@@ -29,7 +54,7 @@ This directory contains the comprehensive test suite for the AITBC platform, inc
 6. [CI/CD Integration](#cicd-integration)
 7. [Troubleshooting](#troubleshooting)
 
-## Test Structure
+## 🧱 **Test Structure**
 
 ```
 tests/
@@ -69,9 +94,9 @@ scripts/utils/             # Testing utilities
 └── other utility scripts          # Various helper scripts
 ```
 
-## Prerequisites
+## ✅ **Prerequisites**
 
-### Environment Setup
+### **Environment Setup**
 ```bash
 # Run main project setup (if not already done)
 ./setup.sh
@@ -86,15 +111,15 @@ pip install pytest pytest-cov pytest-asyncio
 source /etc/aitbc/.env  # Central environment configuration
 ```
 
-### Service Requirements
+### **Service Requirements**
 - AITBC blockchain node running
 - Coordinator API service active
 - Database accessible (SQLite/PostgreSQL)
 - GPU services (if running AI tests)
 
-## Running Tests
+## ▶️ **Running Tests**
 
-### Quick Start
+### **Quick Start**
 ```bash
 # Run all fast tests
 python tests/test_runner.py
@@ -106,7 +131,7 @@ python tests/test_runner.py --all
 python tests/test_runner.py --coverage
 ```
 
-### Specific Test Types
+### **Specific Test Types**
 ```bash
 # Unit tests only
 python tests/test_runner.py --unit
@@ -121,7 +146,7 @@ python tests/test_runner.py --cli
 python tests/test_runner.py --performance
 ```
 
-### Advanced Testing
+### **Advanced Testing**
 ```bash
 # Comprehensive E2E testing
 python scripts/testing/comprehensive_e2e_test_fixed.py
@@ -133,40 +158,40 @@ bash scripts/testing/test_workflow.sh
 bash scripts/testing/test-all-services.sh
 ```
 
-## Test Types
+## 🧪 **Test Types**
 
-### Unit Tests
+### **Unit Tests**
 - **Location**: `tests/unit/` (if exists)
 - **Purpose**: Test individual components in isolation
 - **Speed**: Fast (< 1 second per test)
 - **Coverage**: Core business logic
 
-### Integration Tests
+### **Integration Tests**
 - **Location**: `tests/integration/` and `tests/e2e/`
 - **Purpose**: Test component interactions
 - **Speed**: Medium (1-10 seconds per test)
 - **Coverage**: API endpoints, database operations
 
-### End-to-End Tests
+### **End-to-End Tests**
 - **Location**: `tests/e2e/` and `scripts/testing/`
 - **Purpose**: Test complete workflows
 - **Speed**: Slow (10-60 seconds per test)
 - **Coverage**: Full user scenarios
 
-### Performance Tests
+### **Performance Tests**
 - **Location**: `tests/load_test.py`
 - **Purpose**: Test system performance under load
 - **Speed**: Variable (depends on test parameters)
 - **Coverage**: API response times, throughput
 
-## Configuration
+## ⚙️ **Configuration**
 
-### Test Configuration Files
+### **Test Configuration Files**
 - **pytest.ini**: Pytest configuration (in root)
 - **conftest.py**: Shared fixtures and configuration
 - **pyproject.toml**: Project-wide test configuration
 
-### Environment Variables
+### **Environment Variables**
 ```bash
 # Test database (different from production)
 TEST_DATABASE_URL=sqlite:///test_aitbc.db
@@ -180,16 +205,16 @@ TEST_LOG_FILE=/var/log/aitbc/test.log
 TEST_API_BASE_URL=http://localhost:8011
 ```
 
-## CI/CD Integration
+## 🔄 **CI/CD Integration**
 
-### GitHub Actions
+### **GitHub Actions**
 Test suite is integrated with CI/CD pipeline:
 - **Unit Tests**: Run on every push
 - **Integration Tests**: Run on pull requests
 - **E2E Tests**: Run on main branch
 - **Performance Tests**: Run nightly
 
-### Local CI Simulation
+### **Local CI Simulation**
 ```bash
 # Simulate CI pipeline locally
 python tests/test_runner.py --all --coverage
@@ -198,11 +223,11 @@ python tests/test_runner.py --all --coverage
 coverage html -o coverage_html/
 ```
 
-## Troubleshooting
+## 🛠️ **Troubleshooting**
 
-### Common Issues
+### **Common Issues**
 
-#### Test Failures Due to Services
+#### **Test Failures Due to Services**
 ```bash
 # Check service status
 systemctl status aitbc-blockchain-node
@@ -213,7 +238,7 @@ sudo systemctl restart aitbc-blockchain-node
 sudo systemctl restart aitbc-coordinator
 ```
 
-#### Environment Issues
+#### **Environment Issues**
 ```bash
 # Check virtual environment
 which python
@@ -226,7 +251,7 @@ pip list | grep pytest
 pip install -e .
 ```
 
-#### Database Issues
+#### **Database Issues**
 ```bash
 # Reset test database
 rm test_aitbc.db
@@ -236,13 +261,13 @@ python -m alembic upgrade head
 python -c "from aitbc_core.db import engine; print(engine.url)"
 ```
 
-### Test Logs
+### **Test Logs**
 All test logs are now centralized in `/var/log/aitbc/`:
 - **test.log**: General test output
 - **test_results.txt**: Test results summary
 - **performance_test.log**: Performance test results
 
-### Getting Help
+### **Getting Help**
 1. Check test logs in `/var/log/aitbc/`
 2. Review test documentation in `tests/docs/`
 3. Run tests with verbose output: `pytest -v`
@@ -250,5 +275,29 @@ All test logs are now centralized in `/var/log/aitbc/`:
 
 ---
 
-*Last updated: April 13, 2026*  
-*For questions or suggestions, please open an issue or contact the development team.*
+## 🔗 **Related Resources**
+
+### 📚 **Further Reading:**
+- [Documentation Home](../README.md) - Main docs landing page
+- [About Documentation](../about/README.md) - Template standard and audit checklist
+- [CLI Technical Documentation](../cli-technical/README.md) - CLI entry point and usage
+- [Deployment Documentation](../deployment/README.md) - Operational deployment context
+
+### 🆘 **Help & Support:**
+- **Documentation Issues**: [Report Issues](https://github.com/oib/AITBC/issues)
+- **Community Forum**: [AITBC Forum](https://forum.aitbc.net)
+- **Technical Support**: [AITBC Support](https://support.aitbc.net)
+
+---
+
+## 📊 **Quality Metrics**
+- **Structure**: 10/10 - Template-compliant landing page with detailed testing sections.
+- **Content**: 10/10 - Comprehensive test suite documentation with operational guidance.
+- **Navigation**: 10/10 - Links to docs home, CLI technical docs, deployment, and about docs.
+- **Status**: Active index page.
+
+---
+
+*Last updated: 2026-04-27*<br>
+*Version: 1.0*<br>
+*Status: Active index for testing documentation*

tests/verification/test_import_surface.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import os
+import runpy
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+sys.path.insert(0, str(REPO_ROOT / "packages" / "py" / "aitbc-agent-sdk" / "src"))
+sys.path.insert(0, str(REPO_ROOT / "packages" / "py" / "aitbc-sdk" / "src"))
+
+import aitbc
+import aitbc_agent
+import aitbc_sdk
+import aitbc.paths as aitbc_paths
+
+from aitbc.aitbc_logging import get_logger as direct_get_logger
+from aitbc.constants import BLOCKCHAIN_RPC_PORT, DATA_DIR, ENV_FILE, KEYSTORE_DIR, LOG_DIR, NODE_ENV_FILE, PACKAGE_VERSION
+from aitbc.exceptions import NetworkError, ValidationError
+from aitbc.http_client import AITBCHTTPClient
+from aitbc.paths import ensure_dir, get_keystore_path
+from aitbc.testing import MockFactory
+from aitbc.validation import validate_address, validate_url
+
+
+def test_aitbc_root_exports_match_lightweight_submodules() -> None:
+    assert aitbc.DATA_DIR == DATA_DIR
+    assert aitbc.LOG_DIR == LOG_DIR
+    assert aitbc.KEYSTORE_DIR == KEYSTORE_DIR
+    assert aitbc.BLOCKCHAIN_RPC_PORT == BLOCKCHAIN_RPC_PORT
+    assert aitbc.PACKAGE_VERSION == PACKAGE_VERSION
+
+    assert aitbc.get_logger is direct_get_logger
+    assert aitbc.AITBCHTTPClient is AITBCHTTPClient
+    assert aitbc.NetworkError is NetworkError
+    assert aitbc.ValidationError is ValidationError
+    assert aitbc.get_keystore_path is get_keystore_path
+    assert aitbc.ensure_dir is ensure_dir
+    assert aitbc.validate_address is validate_address
+    assert aitbc.validate_url is validate_url
+    assert aitbc.MockFactory is MockFactory
+
+
+def test_aitbc_agent_sdk_lazy_exports_resolve() -> None:
+    assert hasattr(aitbc_agent, "Agent")
+    assert hasattr(aitbc_agent, "AITBCAgent")
+    assert hasattr(aitbc_agent, "ComputeProvider")
+    assert hasattr(aitbc_agent, "ComputeConsumer")
+    assert hasattr(aitbc_agent, "PlatformBuilder")
+    assert hasattr(aitbc_agent, "SwarmCoordinator")
+
+
+def test_aitbc_sdk_lazy_exports_resolve() -> None:
+    assert hasattr(aitbc_sdk, "CoordinatorReceiptClient")
+    assert hasattr(aitbc_sdk, "ReceiptPage")
+    assert hasattr(aitbc_sdk, "ReceiptVerification")
+    assert hasattr(aitbc_sdk, "SignatureValidation")
+    assert hasattr(aitbc_sdk, "verify_receipt")
+    assert hasattr(aitbc_sdk, "verify_receipts")
+
+
+def test_cli_module_import_smoke() -> None:
+    module_globals = runpy.run_path(str(REPO_ROOT / "cli" / "aitbc_cli.py"))
+    assert "main" in module_globals
+    assert module_globals["DEFAULT_RPC_URL"].startswith("http://localhost:")
+
+
+def test_agent_coordinator_wrapper_bootstrap(monkeypatch) -> None:
+    captured: dict[str, object] = {}
+
+    def fake_execvp(file: str, args: list[str]) -> None:
+        captured["file"] = file
+        captured["args"] = list(args)
+
+    with monkeypatch.context() as m:
+        m.setattr(os, "execvp", fake_execvp)
+        m.setattr(aitbc_paths, "ensure_dir", lambda path: path)
+        m.setenv("AITBC_ENV_FILE", "placeholder")
+        m.setenv("AITBC_NODE_ENV_FILE", "placeholder")
+        m.setenv("PYTHONPATH", "placeholder")
+        m.setenv("DATA_DIR", "placeholder")
+        m.setenv("LOG_DIR", "placeholder")
+
+        runpy.run_path(
+            str(REPO_ROOT / "scripts" / "wrappers" / "aitbc-agent-coordinator-wrapper.py"),
+            run_name="__main__",
+        )
+
+        assert captured["file"] == "/opt/aitbc/venv/bin/python"
+        assert captured["args"][0] == "/opt/aitbc/venv/bin/python"
+        assert captured["args"][1] == "-m"
+        assert captured["args"][2] == "uvicorn"
+        assert captured["args"][3] == "app.main:app"
+        assert os.environ["AITBC_ENV_FILE"] == str(ENV_FILE)
+        assert os.environ["AITBC_NODE_ENV_FILE"] == str(NODE_ENV_FILE)