ci: enforce strict exit codes in workflow tests

- Remove `|| echo "⚠️ ..."` fallbacks that masked failures
- Add explicit `exit 1` on port readiness failures and missing test directories
- Track port_ready flag in health check loops to fail if services don't start
- Replace warning emoji (⚠️) with error emoji (❌) for actual failures
- Fix docs-validation to use curated Markdown target list excluding high-noise directories
- Update rust-zk-tests paths from gpu_acceleration/research to dev

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

@@ -44,31 +44,39 @@ jobs:
         run: |
           echo "Waiting for AITBC services..."
           for port in 8000 8001 8003 8006; do
+            port_ready=0
             for i in $(seq 1 15); do
               code=$(curl -so /dev/null -w '%{http_code}' "http://localhost:$port/health" 2>/dev/null) || code=0
               if [ "$code" -gt 0 ] && [ "$code" -lt 600 ]; then
                 echo "✅ Port $port ready (HTTP $code)"
+                port_ready=1
                 break
               fi
               code=$(curl -so /dev/null -w '%{http_code}' "http://localhost:$port/api/health" 2>/dev/null) || code=0
               if [ "$code" -gt 0 ] && [ "$code" -lt 600 ]; then
                 echo "✅ Port $port ready (HTTP $code)"
+                port_ready=1
                 break
               fi
               code=$(curl -so /dev/null -w '%{http_code}' "http://localhost:$port/" 2>/dev/null) || code=0
               if [ "$code" -gt 0 ] && [ "$code" -lt 600 ]; then
                 echo "✅ Port $port ready (HTTP $code)"
+                port_ready=1
                 break
               fi
-              [ "$i" -eq 15 ] && echo "⚠️ Port $port not ready"
+              [ "$i" -eq 15 ] && echo "❌ Port $port not ready"
               sleep 2
             done
+
+            if [[ $port_ready -ne 1 ]]; then
+              exit 1
+            fi
           done
 
       - name: Run API endpoint tests
         run: |
           cd /var/lib/aitbc-workspaces/api-tests/repo
-          venv/bin/python scripts/ci/test_api_endpoints.py || echo "⚠️ Some endpoints unavailable"
+          venv/bin/python scripts/ci/test_api_endpoints.py
           echo "✅ API endpoint tests completed"
 
       - name: Cleanup

.gitea/workflows/cli-level1-tests.yml

@@ -49,7 +49,7 @@ jobs:
           source venv/bin/activate
           export PYTHONPATH="cli:packages/py/aitbc-sdk/src:packages/py/aitbc-crypto/src:."
 
-          python3 -c "from core.main import cli; print('✅ CLI imports OK')" || echo "⚠️ CLI import issues"
+          python3 -c "from core.main import cli; print('✅ CLI imports OK')"
 
       - name: Run CLI tests
         run: |
@@ -59,9 +59,10 @@ jobs:
 
           if [[ -d "cli/tests" ]]; then
             # Run the CLI test runner that uses virtual environment
-            python3 cli/tests/run_cli_tests.py || echo "⚠️ Some CLI tests failed"
+            python3 cli/tests/run_cli_tests.py
           else
-            echo "⚠️ No CLI tests directory"
+            echo "❌ No CLI tests directory"
+            exit 1
           fi
 
           echo "✅ CLI tests completed"

.gitea/workflows/docs-validation.yml

@@ -5,10 +5,14 @@ on:
     branches: [main, develop]
     paths:
       - 'docs/**'
-      - '**/*.md'
+      - '*.md'
       - '.gitea/workflows/docs-validation.yml'
   pull_request:
     branches: [main, develop]
+    paths:
+      - 'docs/**'
+      - '*.md'
+      - '.gitea/workflows/docs-validation.yml'
   workflow_dispatch:
 
 concurrency:
@@ -42,9 +46,32 @@ jobs:
           
           echo "=== Linting Markdown ==="
           if command -v markdownlint >/dev/null 2>&1; then
-            markdownlint "docs/**/*.md" "*.md" \
+            shopt -s globstar nullglob
-              --ignore "docs/archive/**" \
+            targets=(
-              --ignore "node_modules/**" || echo "⚠️ Markdown linting warnings"
+              *.md
+              docs/*.md
+              docs/11_agents/**/*.md
+              docs/agent-sdk/**/*.md
+              docs/blockchain/**/*.md
+              docs/deployment/**/*.md
+              docs/development/**/*.md
+              docs/general/**/*.md
+              docs/governance/**/*.md
+              docs/implementation/**/*.md
+              docs/infrastructure/**/*.md
+              docs/openclaw/**/*.md
+              docs/policies/**/*.md
+              docs/security/**/*.md
+              docs/workflows/**/*.md
+            )
+
+            if [[ ${#targets[@]} -eq 0 ]]; then
+              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"
+              markdownlint "${targets[@]}" --ignore "node_modules/**" || echo "⚠️ Markdown linting warnings in curated docs scope"
+            fi
           else
             echo "⚠️ markdownlint not available, skipping"
           fi

.gitea/workflows/integration-tests.yml

@@ -30,19 +30,26 @@ jobs:
           git clone --depth 1 http://gitea.bubuit.net:3000/oib/aitbc.git repo
 
       - name: Sync systemd files
+        if: github.event_name != 'pull_request'
         run: |
           cd /var/lib/aitbc-workspaces/integration-tests/repo
           if [[ -d "systemd" ]]; then
-            echo "Syncing systemd service files..."
+            echo "Linking systemd service files..."
-            for f in systemd/*.service; do
+            if [[ -x /opt/aitbc/scripts/utils/link-systemd.sh ]]; then
-              fname=$(basename "$f")
+              if [[ $EUID -eq 0 ]]; then
-              cp "$f" "/etc/systemd/system/$fname" 2>/dev/null || true
+                /opt/aitbc/scripts/utils/link-systemd.sh
-            done
+              else
-            systemctl daemon-reload
+                sudo /opt/aitbc/scripts/utils/link-systemd.sh
-            echo "✅ Systemd files synced"
+              fi
+              echo "✅ Systemd files linked"
+            else
+              echo "❌ /opt/aitbc/scripts/utils/link-systemd.sh not found"
+              exit 1
+            fi
           fi
 
       - name: Start services
+        if: github.event_name != 'pull_request'
         run: |
           echo "Starting AITBC services..."
           for svc in aitbc-coordinator-api aitbc-exchange-api aitbc-wallet aitbc-blockchain-rpc aitbc-blockchain-node; do
@@ -58,26 +65,34 @@ jobs:
         run: |
           echo "Waiting for services..."
           for port in 8000 8001 8003 8006; do
+            port_ready=0
             for i in $(seq 1 15); do
               code=$(curl -so /dev/null -w '%{http_code}' "http://localhost:$port/health" 2>/dev/null) || code=0
               if [ "$code" -gt 0 ] && [ "$code" -lt 600 ]; then
                 echo "✅ Port $port ready (HTTP $code)"
+                port_ready=1
                 break
               fi
               # Try alternate paths
               code=$(curl -so /dev/null -w '%{http_code}' "http://localhost:$port/api/health" 2>/dev/null) || code=0
               if [ "$code" -gt 0 ] && [ "$code" -lt 600 ]; then
                 echo "✅ Port $port ready (HTTP $code)"
+                port_ready=1
                 break
               fi
               code=$(curl -so /dev/null -w '%{http_code}' "http://localhost:$port/" 2>/dev/null) || code=0
               if [ "$code" -gt 0 ] && [ "$code" -lt 600 ]; then
                 echo "✅ Port $port ready (HTTP $code)"
+                port_ready=1
                 break
               fi
-              [ "$i" -eq 15 ] && echo "⚠️ Port $port not ready"
+              [ "$i" -eq 15 ] && echo "❌ Port $port not ready"
               sleep 2
             done
+
+            if [[ $port_ready -ne 1 ]]; then
+              exit 1
+            fi
           done
 
       - name: Setup test environment
@@ -97,11 +112,11 @@ jobs:
 
           # Run existing test suites
           if [[ -d "tests" ]]; then
-            pytest tests/ -x --timeout=30 -q || echo "⚠️ Some tests failed"
+            pytest tests/ -x --timeout=30 -q
           fi
 
           # Service health check integration
-          python3 scripts/ci/test_api_endpoints.py || echo "⚠️ Some endpoints unavailable"
+          python3 scripts/ci/test_api_endpoints.py
           echo "✅ Integration tests completed"
 
       - name: Service status report

.gitea/workflows/js-sdk-tests.yml

@@ -56,13 +56,16 @@ jobs:
       - name: Lint
         run: |
           cd /var/lib/aitbc-workspaces/js-sdk-tests/repo/packages/js/aitbc-sdk
-          npm run lint 2>/dev/null && echo "✅ Lint passed" || echo "⚠️ Lint skipped"
+          npm run lint
-          npx prettier --check "src/**/*.ts" 2>/dev/null && echo "✅ Prettier passed" || echo "⚠️ Prettier skipped"
+          echo "✅ Lint passed"
+          npx prettier --check "src/**/*.ts"
+          echo "✅ Prettier passed"
 
       - name: Run tests
         run: |
           cd /var/lib/aitbc-workspaces/js-sdk-tests/repo/packages/js/aitbc-sdk
-          npm test 2>/dev/null && echo "✅ Tests passed" || echo "⚠️ Tests skipped"
+          npm test
+          echo "✅ Tests passed"
 
       - name: Cleanup
         if: always()

.gitea/workflows/package-tests.yml

@@ -59,12 +59,12 @@ jobs:
 
           # Install dependencies
           if [[ -f "pyproject.toml" ]]; then
-            pip install -q -e ".[dev]" 2>/dev/null || pip install -q -e . 2>/dev/null || true
+            pip install -q -e ".[dev]" 2>/dev/null || pip install -q -e .
           fi
           if [[ -f "requirements.txt" ]]; then
-            pip install -q -r requirements.txt 2>/dev/null || true
+            pip install -q -r requirements.txt
           fi
-          pip install -q pytest mypy black 2>/dev/null || true
+          pip install -q pytest mypy black
 
           # Linting
           echo "=== Linting ==="
@@ -76,7 +76,7 @@ jobs:
           # Tests
           echo "=== Tests ==="
           if [[ -d "tests" ]]; then
-            pytest tests/ -q --tb=short || echo "⚠️ Some tests failed"
+            pytest tests/ -q --tb=short
           else
             echo "⚠️ No tests directory found"
           fi
@@ -89,10 +89,11 @@ jobs:
           cd "$WORKSPACE/repo/${{ matrix.package.path }}"
 
           if [[ -f "pyproject.toml" ]]; then
-            python3 -m venv venv 2>/dev/null || true
+            python3 -m venv venv
             source venv/bin/activate
-            pip install -q build 2>/dev/null || true
+            pip install -q build
-            python -m build 2>/dev/null && echo "✅ Package built" || echo "⚠️ Build failed"
+            python -m build
+            echo "✅ Package built"
           fi
 
       - name: Cleanup
@@ -134,7 +135,7 @@ jobs:
           node --version
           npm --version
 
-          npm install --legacy-peer-deps 2>/dev/null || npm install 2>/dev/null || true
+          npm install --legacy-peer-deps 2>/dev/null || npm install
 
           # Fix missing Hardhat dependencies for aitbc-token
           if [[ "${{ matrix.package.name }}" == "aitbc-token" ]]; then
@@ -147,13 +148,15 @@ jobs:
           fi
 
           # Build
-          npm run build && echo "✅ Build passed" || echo "⚠️ Build failed"
+          npm run build
+          echo "✅ Build passed"
 
           # Lint
           npm run lint 2>/dev/null && echo "✅ Lint passed" || echo "⚠️ Lint skipped"
 
           # Test
-          npm test && echo "✅ Tests passed" || echo "⚠️ Tests skipped"
+          npm test
+          echo "✅ Tests passed"
 
           echo "✅ ${{ matrix.package.name }} completed"
 

.gitea/workflows/python-tests.yml

@@ -69,8 +69,8 @@ jobs:
           export PYTHONPATH="apps/coordinator-api/src:apps/blockchain-node/src:apps/wallet/src:packages/py/aitbc-crypto/src:packages/py/aitbc-sdk/src:."
 
           # Test if packages are importable
-          python3 -c "import aitbc_crypto; print('✅ aitbc_crypto imported')" || echo "❌ aitbc_crypto import failed"
+          python3 -c "import aitbc_crypto; print('✅ aitbc_crypto imported')"
-          python3 -c "import aitbc_sdk; print('✅ aitbc_sdk imported')" || echo "❌ aitbc_sdk import failed"
+          python3 -c "import aitbc_sdk; print('✅ aitbc_sdk imported')"
 
           pytest tests/ \
             apps/coordinator-api/tests/ \
@@ -79,8 +79,7 @@ jobs:
             packages/py/aitbc-crypto/tests/ \
             packages/py/aitbc-sdk/tests/ \
             --tb=short -q --timeout=30 \
-            --ignore=apps/coordinator-api/tests/test_confidential*.py \
+            --ignore=apps/coordinator-api/tests/test_confidential*.py
-            || echo "⚠️ Some tests failed"
 
           echo "✅ Python tests completed"
 

.gitea/workflows/rust-zk-tests.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches: [main, develop]
     paths:
-      - 'gpu_acceleration/research/gpu_zk_research/**'
+      - 'dev/gpu/gpu_zk_research/**'
       - '.gitea/workflows/rust-zk-tests.yml'
   pull_request:
     branches: [main, develop]
@@ -40,37 +40,40 @@ jobs:
           export CARGO_HOME="$HOME/.cargo"
           export PATH="$CARGO_HOME/bin:$PATH"
 
-          if ! command -v rustc >/dev/null 2>&1; then
+          if ! command -v rustup >/dev/null 2>&1; then
             echo "Installing Rust..."
             curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
           fi
-          source "$CARGO_HOME/env" 2>/dev/null || true
+          source "$CARGO_HOME/env"
+          rustup default stable
           rustc --version
           cargo --version
-          rustup component add rustfmt clippy 2>/dev/null || true
+          rustup component add rustfmt clippy
 
       - name: Check formatting
         run: |
           export HOME=/root
           export PATH="$HOME/.cargo/bin:$PATH"
           source "$HOME/.cargo/env" 2>/dev/null || true
-          cd /var/lib/aitbc-workspaces/rust-zk-tests/repo/gpu_acceleration/research/gpu_zk_research
+          cd /var/lib/aitbc-workspaces/rust-zk-tests/repo/dev/gpu/gpu_zk_research
-          cargo fmt -- --check 2>/dev/null && echo "✅ Formatting OK" || echo "⚠️ Format warnings"
+          cargo fmt --all -- --check
+          echo "✅ Formatting OK"
 
       - name: Run Clippy
         run: |
           export HOME=/root
           export PATH="$HOME/.cargo/bin:$PATH"
           source "$HOME/.cargo/env" 2>/dev/null || true
-          cd /var/lib/aitbc-workspaces/rust-zk-tests/repo/gpu_acceleration/research/gpu_zk_research
+          cd /var/lib/aitbc-workspaces/rust-zk-tests/repo/dev/gpu/gpu_zk_research
-          cargo clippy -- -D warnings 2>/dev/null && echo "✅ Clippy OK" || echo "⚠️ Clippy warnings"
+          cargo clippy --all-targets -- -D warnings
+          echo "✅ Clippy OK"
 
       - name: Build
         run: |
           export HOME=/root
           export PATH="$HOME/.cargo/bin:$PATH"
           source "$HOME/.cargo/env" 2>/dev/null || true
-          cd /var/lib/aitbc-workspaces/rust-zk-tests/repo/gpu_acceleration/research/gpu_zk_research
+          cd /var/lib/aitbc-workspaces/rust-zk-tests/repo/dev/gpu/gpu_zk_research
           cargo build --release
           echo "✅ Build completed"
 
@@ -79,8 +82,9 @@ jobs:
           export HOME=/root
           export PATH="$HOME/.cargo/bin:$PATH"
           source "$HOME/.cargo/env" 2>/dev/null || true
-          cd /var/lib/aitbc-workspaces/rust-zk-tests/repo/gpu_acceleration/research/gpu_zk_research
+          cd /var/lib/aitbc-workspaces/rust-zk-tests/repo/dev/gpu/gpu_zk_research
-          cargo test && echo "✅ Tests passed" || echo "⚠️ Tests completed with issues"
+          cargo test --all-targets
+          echo "✅ Tests passed"
 
       - name: Cleanup
         if: always()

.gitea/workflows/security-scanning.yml

@@ -41,7 +41,7 @@ jobs:
           
           python3 -m venv venv
           source venv/bin/activate
-          pip install -q bandit safety pip-audit
+          pip install -q bandit pip-audit
           echo "✅ Security tools installed"
 
       - name: Python dependency audit
@@ -49,7 +49,7 @@ jobs:
           cd /var/lib/aitbc-workspaces/security-scan/repo
           source venv/bin/activate
           echo "=== Dependency Audit ==="
-          pip-audit -r requirements.txt --desc 2>/dev/null || echo "⚠️ Some vulnerabilities found"
+          pip-audit -r requirements.txt --desc
           echo "✅ Dependency audit completed"
 
       - name: Bandit security scan
@@ -60,7 +60,7 @@ jobs:
           bandit -r apps/ packages/py/ cli/ \
             -s B101,B311 \
             --severity-level medium \
-            -f txt -q 2>/dev/null || echo "⚠️ Bandit findings"
+            -f txt -q
           echo "✅ Bandit scan completed"
 
       - name: Check for secrets
@@ -68,8 +68,28 @@ jobs:
           cd /var/lib/aitbc-workspaces/security-scan/repo
           echo "=== Secret Detection ==="
           # Simple pattern check for leaked secrets
-          grep -rn "PRIVATE_KEY\s*=\s*['\"]" apps/ packages/ cli/ 2>/dev/null | grep -v "example\|test\|mock\|dummy" && echo "⚠️ Possible secrets found" || echo "✅ No secrets detected"
+          secret_matches=$(mktemp)
-          grep -rn "password\s*=\s*['\"][^'\"]*['\"]" apps/ packages/ cli/ 2>/dev/null | grep -v "example\|test\|mock\|dummy\|placeholder" | head -5 && echo "⚠️ Possible hardcoded passwords" || echo "✅ No hardcoded passwords"
+          password_matches=$(mktemp)
+
+          grep -RInE "PRIVATE_KEY[[:space:]]*=[[:space:]]*['\"]" apps/ packages/ cli/ 2>/dev/null | grep -v "example\|test\|mock\|dummy" > "$secret_matches" || true
+          grep -RInE "password[[:space:]]*=[[:space:]]*['\"][^'\"]*['\"]" apps/ packages/ cli/ 2>/dev/null | grep -v "example\|test\|mock\|dummy\|placeholder" > "$password_matches" || true
+
+          if [[ -s "$secret_matches" ]]; then
+            echo "❌ Possible secrets found"
+            cat "$secret_matches"
+            rm -f "$secret_matches" "$password_matches"
+            exit 1
+          fi
+
+          if [[ -s "$password_matches" ]]; then
+            echo "❌ Possible hardcoded passwords"
+            head -5 "$password_matches"
+            rm -f "$secret_matches" "$password_matches"
+            exit 1
+          fi
+
+          rm -f "$secret_matches" "$password_matches"
+          echo "✅ No hardcoded secrets detected"
 
       - name: Cleanup
         if: always()

.gitea/workflows/smart-contract-tests.yml

@@ -54,28 +54,44 @@ jobs:
           echo "Node: $(node --version), npm: $(npm --version)"
 
           # Install
-          npm install --legacy-peer-deps 2>/dev/null || npm install 2>/dev/null || true
+          npm install --legacy-peer-deps 2>/dev/null || npm install
 
           # Fix missing Hardhat dependencies for aitbc-token
           if [[ "${{ matrix.project.name }}" == "aitbc-token" ]]; then
             echo "Installing missing Hardhat dependencies..."
-            npm install --save-dev "@nomicfoundation/hardhat-ignition@^0.15.16" "@nomicfoundation/ignition-core@^0.15.15" 2>/dev/null || true
+            npm install --no-save "@nomicfoundation/hardhat-ignition@^0.15.16" "@nomicfoundation/ignition-core@^0.15.15"
-            
-            # Fix formatting issues
-            echo "Fixing formatting issues..."
-            npm run format 2>/dev/null || echo "⚠️ Format fix failed"
           fi
 
           # Compile
           if [[ -f "hardhat.config.js" ]] || [[ -f "hardhat.config.ts" ]]; then
-            npx hardhat compile && echo "✅ Compiled" || echo "⚠️ Compile failed"
+            npx hardhat compile
-            npx hardhat test && echo "✅ Tests passed" || echo "⚠️ Tests failed"
+            echo "✅ Compiled"
+            npx hardhat test
+            echo "✅ Tests passed"
           elif [[ -f "foundry.toml" ]]; then
-            forge build && echo "✅ Compiled" || echo "⚠️ Compile failed"
+            forge build
-            forge test && echo "✅ Tests passed" || echo "⚠️ Tests failed"
+            echo "✅ Compiled"
+            forge test
+            echo "✅ Tests passed"
           else
-            npm run build 2>/dev/null || echo "⚠️ No build script"
+            if node -e "const pkg=require('./package.json'); process.exit(pkg.scripts && pkg.scripts.compile ? 0 : 1)"; then
-            npm test 2>/dev/null || echo "⚠️ No test script"
+              npm run compile
+              echo "✅ Compiled"
+            elif node -e "const pkg=require('./package.json'); process.exit(pkg.scripts && pkg.scripts.build ? 0 : 1)"; then
+              npm run build
+              echo "✅ Compiled"
+            else
+              echo "❌ No compile or build script found"
+              exit 1
+            fi
+
+            if node -e "const pkg=require('./package.json'); process.exit(pkg.scripts && pkg.scripts.test ? 0 : 1)"; then
+              npm test
+              echo "✅ Tests passed"
+            else
+              echo "❌ No test script found"
+              exit 1
+            fi
           fi
 
           echo "✅ ${{ matrix.project.name }} completed"
@@ -108,19 +124,20 @@ jobs:
             if [[ -d "$project" ]] && [[ -f "$project/package.json" ]]; then
               echo "=== Linting $project ==="
               cd "$project"
-              npm install --legacy-peer-deps 2>/dev/null || npm install 2>/dev/null || true
+              npm install --legacy-peer-deps 2>/dev/null || npm install
               
               # Fix missing Hardhat dependencies and formatting for aitbc-token
               if [[ "$project" == "packages/solidity/aitbc-token" ]]; then
                 echo "Installing missing Hardhat dependencies..."
-                npm install --save-dev "@nomicfoundation/hardhat-ignition@^0.15.16" "@nomicfoundation/ignition-core@^0.15.15" 2>/dev/null || true
+                npm install --no-save "@nomicfoundation/hardhat-ignition@^0.15.16" "@nomicfoundation/ignition-core@^0.15.15"
-                
-                # Fix formatting issues
-                echo "Fixing formatting issues..."
-                npm run format 2>/dev/null || echo "⚠️ Format fix failed"
               fi
 
-              npm run lint 2>/dev/null && echo "✅ Lint passed" || echo "⚠️ Lint skipped"
+              if node -e "const pkg=require('./package.json'); process.exit(pkg.scripts && pkg.scripts.lint ? 0 : 1)"; then
+                npm run lint
+                echo "✅ Lint passed"
+              else
+                echo "⚠️ No lint script for $project, skipping"
+              fi
               cd /var/lib/aitbc-workspaces/solidity-lint/repo
             fi
           done

.gitea/workflows/staking-tests.yml

@@ -131,7 +131,8 @@ jobs:
           cd /var/lib/aitbc-workspaces/staking-contract/repo/contracts
           
           echo "🧪 Running staking contract tests..."
-          npx hardhat test test/AgentStaking.test.js || echo "⚠️ Contract tests blocked by compilation errors"
+          npx hardhat compile
+          npx hardhat test test/AgentStaking.test.js
           echo "✅ Contract tests completed"
 
       - name: Cleanup
@@ -141,7 +142,7 @@ jobs:
   run-staking-test-runner:
     runs-on: debian
     timeout-minutes: 25
-    needs: [test-staking-service, test-staking-integration]
+    needs: [test-staking-service, test-staking-integration, test-staking-contract]
 
     steps:
       - name: Clone repository

.gitea/workflows/systemd-sync.yml

@@ -57,7 +57,12 @@ jobs:
 
           echo "=== Found $(ls systemd/*.service 2>/dev/null | wc -l) service files, $errors errors ==="
 
+          if [[ $errors -gt 0 ]]; then
+            exit 1
+          fi
+
       - name: Sync service files
+        if: github.event_name != 'pull_request'
         run: |
           cd /var/lib/aitbc-workspaces/systemd-sync/repo
 
@@ -66,11 +71,16 @@ jobs:
           fi
 
           echo "=== Syncing systemd files ==="
-          for f in systemd/*.service; do
+          if [[ -x /opt/aitbc/scripts/utils/link-systemd.sh ]]; then
-            fname=$(basename "$f")
+            if [[ $EUID -eq 0 ]]; then
-            cp "$f" "/etc/systemd/system/$fname"
+              /opt/aitbc/scripts/utils/link-systemd.sh
-            echo "  ✅ $fname synced"
+            else
-          done
+              sudo /opt/aitbc/scripts/utils/link-systemd.sh
+            fi
+          else
+            echo "⚠️ /opt/aitbc/scripts/utils/link-systemd.sh not found"
+            exit 1
+          fi
 
           systemctl daemon-reload
           echo "✅ Systemd daemon reloaded"

apps/coordinator-api/src/app/services/multi_language/agent_communication.py

@@ -160,7 +160,6 @@ class MultilingualAgentCommunication:
             domain = self._get_translation_domain(message_type)
 
             # Check cache first
-            f"agent_message:{hashlib.md5(content.encode()).hexdigest()}:{source_lang}:{target_lang}"
             if self.translation_cache:
                 cached_result = await self.translation_cache.get(content, source_lang, target_lang, context, domain)
                 if cached_result:

cli/tests/run_cli_tests.py

@@ -11,19 +11,22 @@ def run_cli_test():
     print("🧪 Running CLI Tests with Virtual Environment...")
     
     # Set up environment
-    cli_dir = Path(__file__).parent.parent
+    cli_dir = Path(__file__).resolve().parent.parent
-    cli_bin = "/opt/aitbc/aitbc-cli"
+    cli_bin = cli_dir.parent / "aitbc-cli"
+
+    def run_command(*args):
+        return subprocess.run(
+            [str(cli_bin), *args],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            cwd=str(cli_dir),
+        )
     
     # Test 1: CLI help command
     print("\n1. Testing CLI help command...")
     try:
-        result = subprocess.run(
+        result = run_command("--help")
-            [cli_bin, "--help"],
-            capture_output=True,
-            text=True,
-            timeout=10,
-            cwd=str(cli_dir)
-        )
         
         if result.returncode == 0 and "AITBC CLI" in result.stdout:
             print("✅ CLI help command working")
@@ -37,13 +40,7 @@ def run_cli_test():
     # Test 2: CLI list command
     print("\n2. Testing CLI list command...")
     try:
-        result = subprocess.run(
+        result = run_command("wallet", "list")
-            [cli_bin, "wallet", "list"],
-            capture_output=True,
-            text=True,
-            timeout=10,
-            cwd=str(cli_dir)
-        )
         
         if result.returncode == 0:
             print("✅ CLI list command working")
@@ -57,13 +54,7 @@ def run_cli_test():
     # Test 3: CLI blockchain command
     print("\n3. Testing CLI blockchain command...")
     try:
-        result = subprocess.run(
+        result = run_command("blockchain", "info")
-            [cli_bin, "blockchain", "info"],
-            capture_output=True,
-            text=True,
-            timeout=10,
-            cwd=str(cli_dir)
-        )
         
         if result.returncode == 0:
             print("✅ CLI blockchain command working")
@@ -77,13 +68,7 @@ def run_cli_test():
     # Test 4: CLI invalid command handling
     print("\n4. Testing CLI invalid command handling...")
     try:
-        result = subprocess.run(
+        result = run_command("invalid-command")
-            [cli_bin, "invalid-command"],
-            capture_output=True,
-            text=True,
-            timeout=10,
-            cwd=str(cli_dir)
-        )
         
         if result.returncode != 0:
             print("✅ CLI invalid command handling working")

docs/advanced/02_reference/7_threat-modeling.md

@@ -2,9 +2,13 @@
 
 ## Overview
 
-This document provides a comprehensive threat model for AITBC's privacy-preserving features, focusing on zero-knowledge receipt attestation and confidential transactions. The analysis uses the STRIDE methodology to systematically identify threats and their mitigations.
+This document provides a comprehensive threat model for AITBC's
+privacy-preserving features, focusing on zero-knowledge receipt attestation and
+confidential transactions. The analysis uses the STRIDE methodology to
+systematically identify threats and their mitigations.
 
 ## Document Version
+
 - Version: 1.0
 - Date: December 2024
 - Status: Published - Shared with Ecosystem Partners
@@ -12,6 +16,7 @@ This document provides a comprehensive threat model for AITBC's privacy-preservi
 ## Scope
 
 ### In-Scope Components
+
 1. **ZK Receipt Attestation System**
    - Groth16 circuit implementation
    - Proof generation service
@@ -25,6 +30,7 @@ This document provides a comprehensive threat model for AITBC's privacy-preservi
    - Audit logging infrastructure
 
 ### Out-of-Scope Components
+
 - Core blockchain consensus
 - Basic transaction processing
 - Non-confidential marketplace operations
@@ -32,123 +38,136 @@ This document provides a comprehensive threat model for AITBC's privacy-preservi
 
 ## Threat Actors
 
-| Actor | Motivation | Capability | Impact |
+| Actor                   | Motivation                      | Capability                                 | Impact   |
-|-------|------------|------------|--------|
+| ----------------------- | ------------------------------- | ------------------------------------------ | -------- |
-| Malicious Miner | Financial gain, sabotage | Access to mining software, limited compute | High |
+| Malicious Miner         | Financial gain, sabotage        | Access to mining software, limited compute | High     |
-| Compromised Coordinator | Data theft, market manipulation | System access, private keys | Critical |
+| Compromised Coordinator | Data theft, market manipulation | System access, private keys                | Critical |
-| External Attacker | Financial theft, privacy breach | Public network, potential exploits | High |
+| External Attacker       | Financial theft, privacy breach | Public network, potential exploits         | High     |
-| Regulator | Compliance investigation | Legal authority, subpoenas | Medium |
+| Regulator               | Compliance investigation        | Legal authority, subpoenas                 | Medium   |
-| Insider Threat | Data exfiltration | Internal access, knowledge | High |
+| Insider Threat          | Data exfiltration               | Internal access, knowledge                 | High     |
-| Quantum Computer | Break cryptography | Future quantum capability | Future |
+| Quantum Computer        | Break cryptography              | Future quantum capability                  | Future   |
 
 ## STRIDE Analysis
 
 ### 1. Spoofing
 
 #### ZK Receipt Attestation
-| Threat | Description | Likelihood | Impact | Mitigations |
+
-|--------|-------------|------------|--------|-------------|
+| Threat                    | Description                     | Likelihood | Impact | Mitigations                                                                            |
-| Proof Forgery | Attacker creates fake ZK proofs | Medium | High | ✅ Groth16 soundness property<br>✅ Verification on-chain<br>⚠️ Trusted setup security |
+| ------------------------- | ------------------------------- | ---------- | ------ | -------------------------------------------------------------------------------------- |
-| Identity Spoofing | Miner impersonates another | Low | Medium | ✅ Miner registration with KYC<br>✅ Cryptographic signatures |
+| Proof Forgery             | Attacker creates fake ZK proofs | Medium     | High   | ✅ Groth16 soundness property<br>✅ Verification on-chain<br>⚠️ Trusted setup security |
-| Coordinator Impersonation | Fake coordinator services | Low | High | ✅ TLS certificates<br>⚠️ DNSSEC recommended |
+| Identity Spoofing         | Miner impersonates another      | Low        | Medium | ✅ Miner registration with KYC<br>✅ Cryptographic signatures                          |
+| Coordinator Impersonation | Fake coordinator services       | Low        | High   | ✅ TLS certificates<br>⚠️ DNSSEC recommended                                           |
 
 #### Confidential Transactions
-| Threat | Description | Likelihood | Impact | Mitigations |
+
-|--------|-------------|------------|--------|-------------|
+| Threat                | Description                       | Likelihood | Impact | Mitigations                                        |
-| Key Spoofing | Fake public keys for participants | Medium | High | ✅ HSM-protected keys<br>✅ Certificate validation |
+| --------------------- | --------------------------------- | ---------- | ------ | -------------------------------------------------- |
-| Authorization Forgery | Fake audit authorization | Low | High | ✅ Signed tokens<br>✅ Short expiration times |
+| Key Spoofing          | Fake public keys for participants | Medium     | High   | ✅ HSM-protected keys<br>✅ Certificate validation |
+| Authorization Forgery | Fake audit authorization          | Low        | High   | ✅ Signed tokens<br>✅ Short expiration times      |
 
 ### 2. Tampering
 
 #### ZK Receipt Attestation
-| Threat | Description | Likelihood | Impact | Mitigations |
+
-|--------|-------------|------------|--------|-------------|
+| Threat                    | Description                         | Likelihood | Impact   | Mitigations                                                            |
-| Circuit Modification | Malicious changes to circom circuit | Low | Critical | ✅ Open-source circuits<br>✅ Circuit hash verification |
+| ------------------------- | ----------------------------------- | ---------- | -------- | ---------------------------------------------------------------------- |
-| Proof Manipulation | Altering proofs during transmission | Medium | High | ✅ End-to-end encryption<br>✅ On-chain verification |
+| Circuit Modification      | Malicious changes to circom circuit | Low        | Critical | ✅ Open-source circuits<br>✅ Circuit hash verification                |
-| Setup Parameter Poisoning | Compromise trusted setup | Low | Critical | ⚠️ Multi-party ceremony needed<br>⚠️ Secure destruction of toxic waste |
+| Proof Manipulation        | Altering proofs during transmission | Medium     | High     | ✅ End-to-end encryption<br>✅ On-chain verification                   |
+| Setup Parameter Poisoning | Compromise trusted setup            | Low        | Critical | ⚠️ Multi-party ceremony needed<br>⚠️ Secure destruction of toxic waste |
 
 #### Confidential Transactions
-| Threat | Description | Likelihood | Impact | Mitigations |
+
-|--------|-------------|------------|--------|-------------|
+| Threat                | Description                       | Likelihood | Impact | Mitigations                                                     |
-| Data Tampering | Modify encrypted transaction data | Medium | High | ✅ AES-GCM authenticity<br>✅ Immutable audit logs |
+| --------------------- | --------------------------------- | ---------- | ------ | --------------------------------------------------------------- |
-| Key Substitution | Swap public keys in transit | Low | High | ✅ Certificate pinning<br>✅ HSM key validation |
+| Data Tampering        | Modify encrypted transaction data | Medium     | High   | ✅ AES-GCM authenticity<br>✅ Immutable audit logs              |
-| Access Control Bypass | Override authorization checks | Low | High | ✅ Role-based access control<br>✅ Audit logging of all changes |
+| Key Substitution      | Swap public keys in transit       | Low        | High   | ✅ Certificate pinning<br>✅ HSM key validation                 |
+| Access Control Bypass | Override authorization checks     | Low        | High   | ✅ Role-based access control<br>✅ Audit logging of all changes |
 
 ### 3. Repudiation
 
 #### ZK Receipt Attestation
-| Threat | Description | Likelihood | Impact | Mitigations |
+
-|--------|-------------|------------|--------|-------------|
+| Threat                     | Description                       | Likelihood | Impact | Mitigations                                                 |
-| Denial of Proof Generation | Miner denies creating proof | Low | Medium | ✅ On-chain proof records<br>✅ Signed proof metadata |
+| -------------------------- | --------------------------------- | ---------- | ------ | ----------------------------------------------------------- |
-| Receipt Denial | Party denies transaction occurred | Medium | Medium | ✅ Immutable blockchain ledger<br>✅ Cryptographic receipts |
+| Denial of Proof Generation | Miner denies creating proof       | Low        | Medium | ✅ On-chain proof records<br>✅ Signed proof metadata       |
+| Receipt Denial             | Party denies transaction occurred | Medium     | Medium | ✅ Immutable blockchain ledger<br>✅ Cryptographic receipts |
 
 #### Confidential Transactions
-| Threat | Description | Likelihood | Impact | Mitigations |
+
-|--------|-------------|------------|--------|-------------|
+| Threat                | Description                   | Likelihood | Impact | Mitigations                                                  |
-| Access Denial | User denies accessing data | Low | Medium | ✅ Comprehensive audit logs<br>✅ Non-repudiation signatures |
+| --------------------- | ----------------------------- | ---------- | ------ | ------------------------------------------------------------ |
-| Key Generation Denial | Deny creating encryption keys | Low | Medium | ✅ HSM audit trails<br>✅ Key rotation logs |
+| Access Denial         | User denies accessing data    | Low        | Medium | ✅ Comprehensive audit logs<br>✅ Non-repudiation signatures |
+| Key Generation Denial | Deny creating encryption keys | Low        | Medium | ✅ HSM audit trails<br>✅ Key rotation logs                  |
 
 ### 4. Information Disclosure
 
 #### ZK Receipt Attestation
-| Threat | Description | Likelihood | Impact | Mitigations |
+
-|--------|-------------|------------|--------|-------------|
+| Threat               | Description                           | Likelihood | Impact   | Mitigations                                                           |
-| Witness Extraction | Extract private inputs from proof | Low | Critical | ✅ Zero-knowledge property<br>✅ No knowledge of witness |
+| -------------------- | ------------------------------------- | ---------- | -------- | --------------------------------------------------------------------- |
-| Setup Parameter Leak | Expose toxic waste from trusted setup | Low | Critical | ⚠️ Secure multi-party setup<br>⚠️ Parameter destruction |
+| Witness Extraction   | Extract private inputs from proof     | Low        | Critical | ✅ Zero-knowledge property<br>✅ No knowledge of witness              |
-| Side-Channel Attacks | Timing/power analysis | Low | Medium | ✅ Constant-time implementations<br>⚠️ Needs hardware security review |
+| Setup Parameter Leak | Expose toxic waste from trusted setup | Low        | Critical | ⚠️ Secure multi-party setup<br>⚠️ Parameter destruction               |
+| Side-Channel Attacks | Timing/power analysis                 | Low        | Medium   | ✅ Constant-time implementations<br>⚠️ Needs hardware security review |
 
 #### Confidential Transactions
-| Threat | Description | Likelihood | Impact | Mitigations |
+
-|--------|-------------|------------|--------|-------------|
+| Threat                 | Description                     | Likelihood | Impact   | Mitigations                                               |
-| Private Key Extraction | Steal keys from HSM | Low | Critical | ✅ HSM security controls<br>✅ Hardware tamper resistance |
+| ---------------------- | ------------------------------- | ---------- | -------- | --------------------------------------------------------- |
-| Decryption Key Leak | Expose DEKs | Medium | High | ✅ Per-transaction DEKs<br>✅ Encrypted key storage |
+| Private Key Extraction | Steal keys from HSM             | Low        | Critical | ✅ HSM security controls<br>✅ Hardware tamper resistance |
-| Metadata Analysis | Infer data from access patterns | Medium | Medium | ✅ Access logging<br>⚠️ Differential privacy needed |
+| Decryption Key Leak    | Expose DEKs                     | Medium     | High     | ✅ Per-transaction DEKs<br>✅ Encrypted key storage       |
+| Metadata Analysis      | Infer data from access patterns | Medium     | Medium   | ✅ Access logging<br>⚠️ Differential privacy needed       |
 
 ### 5. Denial of Service
 
 #### ZK Receipt Attestation
-| Threat | Description | Likelihood | Impact | Mitigations |
+
-|--------|-------------|------------|--------|-------------|
+| Threat               | Description                 | Likelihood | Impact | Mitigations                                                   |
-| Proof Generation DoS | Overwhelm proof service | High | Medium | ✅ Rate limiting<br>✅ Queue management<br>⚠️ Need monitoring |
+| -------------------- | --------------------------- | ---------- | ------ | ------------------------------------------------------------- |
-| Verification Spam | Flood verification contract | High | High | ✅ Gas costs limit spam<br>⚠️ Need circuit optimization |
+| Proof Generation DoS | Overwhelm proof service     | High       | Medium | ✅ Rate limiting<br>✅ Queue management<br>⚠️ Need monitoring |
+| Verification Spam    | Flood verification contract | High       | High   | ✅ Gas costs limit spam<br>⚠️ Need circuit optimization       |
 
 #### Confidential Transactions
-| Threat | Description | Likelihood | Impact | Mitigations |
+
-|--------|-------------|------------|--------|-------------|
+| Threat             | Description                  | Likelihood | Impact | Mitigations                                    |
-| Key Exhaustion | Deplete HSM key slots | Medium | Medium | ✅ Key rotation<br>✅ Resource monitoring |
+| ------------------ | ---------------------------- | ---------- | ------ | ---------------------------------------------- |
-| Database Overload | Saturate with encrypted data | High | Medium | ✅ Connection pooling<br>✅ Query optimization |
+| Key Exhaustion     | Deplete HSM key slots        | Medium     | Medium | ✅ Key rotation<br>✅ Resource monitoring      |
-| Audit Log Flooding | Fill audit storage | Medium | Medium | ✅ Log rotation<br>✅ Storage monitoring |
+| Database Overload  | Saturate with encrypted data | High       | Medium | ✅ Connection pooling<br>✅ Query optimization |
+| Audit Log Flooding | Fill audit storage           | Medium     | Medium | ✅ Log rotation<br>✅ Storage monitoring       |
 
 ### 6. Elevation of Privilege
 
 #### ZK Receipt Attestation
-| Threat | Description | Likelihood | Impact | Mitigations |
+
-|--------|-------------|------------|--------|-------------|
+| Threat                 | Description               | Likelihood | Impact   | Mitigations                                         |
-| Setup Privilege | Gain trusted setup access | Low | Critical | ⚠️ Multi-party ceremony<br>⚠️ Independent audits |
+| ---------------------- | ------------------------- | ---------- | -------- | --------------------------------------------------- |
-| Coordinator Compromise | Full system control | Medium | Critical | ✅ Multi-sig controls<br>✅ Regular security audits |
+| Setup Privilege        | Gain trusted setup access | Low        | Critical | ⚠️ Multi-party ceremony<br>⚠️ Independent audits    |
+| Coordinator Compromise | Full system control       | Medium     | Critical | ✅ Multi-sig controls<br>✅ Regular security audits |
 
 #### Confidential Transactions
-| Threat | Description | Likelihood | Impact | Mitigations |
+
-|--------|-------------|------------|--------|-------------|
+| Threat                    | Description              | Likelihood | Impact   | Mitigations                                                  |
-| HSM Takeover | Gain HSM admin access | Low | Critical | ✅ HSM access controls<br>✅ Dual authorization |
+| ------------------------- | ------------------------ | ---------- | -------- | ------------------------------------------------------------ |
-| Access Control Escalation | Bypass role restrictions | Medium | High | ✅ Principle of least privilege<br>✅ Regular access reviews |
+| HSM Takeover              | Gain HSM admin access    | Low        | Critical | ✅ HSM access controls<br>✅ Dual authorization              |
+| Access Control Escalation | Bypass role restrictions | Medium     | High     | ✅ Principle of least privilege<br>✅ Regular access reviews |
 
 ## Risk Matrix
 
-| Threat | Likelihood | Impact | Risk Level | Priority |
+| Threat                   | Likelihood | Impact   | Risk Level | Priority |
-|--------|------------|--------|------------|----------|
+| ------------------------ | ---------- | -------- | ---------- | -------- |
-| Trusted Setup Compromise | Low | Critical | HIGH | 1 |
+| Trusted Setup Compromise | Low        | Critical | HIGH       | 1        |
-| HSM Compromise | Low | Critical | HIGH | 1 |
+| HSM Compromise           | Low        | Critical | HIGH       | 1        |
-| Proof Forgery | Medium | High | HIGH | 2 |
+| Proof Forgery            | Medium     | High     | HIGH       | 2        |
-| Private Key Extraction | Low | Critical | HIGH | 2 |
+| Private Key Extraction   | Low        | Critical | HIGH       | 2        |
-| Information Disclosure | Medium | High | MEDIUM | 3 |
+| Information Disclosure   | Medium     | High     | MEDIUM     | 3        |
-| DoS Attacks | High | Medium | MEDIUM | 3 |
+| DoS Attacks              | High       | Medium   | MEDIUM     | 3        |
-| Side-Channel Attacks | Low | Medium | LOW | 4 |
+| Side-Channel Attacks     | Low        | Medium   | LOW        | 4        |
-| Repudiation | Low | Medium | LOW | 4 |
+| Repudiation              | Low        | Medium   | LOW        | 4        |
 
 ## Implemented Mitigations
 
 ### ZK Receipt Attestation
+
 - ✅ Groth16 soundness and zero-knowledge properties
 - ✅ On-chain verification prevents tampering
 - ✅ Open-source circuit code for transparency
@@ -156,6 +175,7 @@ This document provides a comprehensive threat model for AITBC's privacy-preservi
 - ✅ Comprehensive audit logging
 
 ### Confidential Transactions
+
 - ✅ AES-256-GCM provides confidentiality and authenticity
 - ✅ HSM-backed key management prevents key extraction
 - ✅ Role-based access control with time restrictions
@@ -166,6 +186,7 @@ This document provides a comprehensive threat model for AITBC's privacy-preservi
 ## Recommended Future Improvements
 
 ### Short Term (1-3 months)
+
 1. **Trusted Setup Ceremony**
    - Implement multi-party computation (MPC) setup
    - Engage independent auditors
@@ -182,6 +203,7 @@ This document provides a comprehensive threat model for AITBC's privacy-preservi
    - Fuzzing of circuit implementations
 
 ### Medium Term (3-6 months)
+
 1. **Advanced Privacy**
    - Differential privacy for metadata
    - Secure multi-party computation
@@ -198,6 +220,7 @@ This document provides a comprehensive threat model for AITBC's privacy-preservi
    - Regulatory audit tools
 
 ### Long Term (6-12 months)
+
 1. **Formal Verification**
    - Formal proofs of circuit correctness
    - Verified smart contract deployments
@@ -211,24 +234,28 @@ This document provides a comprehensive threat model for AITBC's privacy-preservi
 ## Security Controls Summary
 
 ### Preventive Controls
+
 - Cryptographic guarantees (ZK proofs, encryption)
 - Access control mechanisms
 - Secure key management
 - Network security (TLS, certificates)
 
 ### Detective Controls
+
 - Comprehensive audit logging
 - Real-time monitoring
 - Anomaly detection
 - Security incident response
 
 ### Corrective Controls
+
 - Key rotation procedures
 - Incident response playbooks
 - Backup and recovery
 - System patching processes
 
 ### Compensating Controls
+
 - Insurance for cryptographic risks
 - Legal protections
 - Community oversight
@@ -236,23 +263,25 @@ This document provides a comprehensive threat model for AITBC's privacy-preservi
 
 ## Compliance Mapping
 
-| Regulation | Requirement | Implementation |
+| Regulation | Requirement           | Implementation                      |
-|------------|-------------|----------------|
+| ---------- | --------------------- | ----------------------------------- |
-| GDPR | Right to encryption | ✅ Opt-in confidential transactions |
+| GDPR       | Right to encryption   | ✅ Opt-in confidential transactions |
-| GDPR | Data minimization | ✅ Selective disclosure |
+| GDPR       | Data minimization     | ✅ Selective disclosure             |
-| SEC 17a-4 | Audit trail | ✅ Immutable logs |
+| SEC 17a-4  | Audit trail           | ✅ Immutable logs                   |
-| MiFID II | Transaction reporting | ✅ ZK proof verification |
+| MiFID II   | Transaction reporting | ✅ ZK proof verification            |
-| PCI DSS | Key management | ✅ HSM-backed keys |
+| PCI DSS    | Key management        | ✅ HSM-backed keys                  |
 
 ## Incident Response
 
 ### Security Event Classification
+
 1. **Critical** - HSM compromise, trusted setup breach
 2. **High** - Large-scale data breach, proof forgery
 3. **Medium** - Single key compromise, access violation
 4. **Low** - Failed authentication, minor DoS
 
 ### Response Procedures
+
 1. Immediate containment
 2. Evidence preservation
 3. Stakeholder notification
@@ -276,6 +305,7 @@ This document provides a comprehensive threat model for AITBC's privacy-preservi
 ## Acknowledgments
 
 This threat model was developed with input from:
+
 - AITBC Security Team
 - External Security Consultants
 - Community Security Researchers
@@ -283,4 +313,5 @@ This threat model was developed with input from:
 
 ---
 
-*This document is living and will be updated as new threats emerge and mitigations are implemented.*
+_This document is living and will be updated as new threats emerge and
+mitigations are implemented._

docs/expert/01_issues/On-Chain_Model_Marketplace.md

@@ -2,24 +2,31 @@
 
 ## Executive Summary
 
-This document outlines a detailed implementation plan for extending the AITBC platform with an on-chain AI model marketplace. The implementation leverages existing infrastructure (GPU marketplace, smart contracts, token economy) while introducing model-specific trading, licensing, and royalty distribution mechanisms.
+This document outlines a detailed implementation plan for extending the AITBC
+platform with an on-chain AI model marketplace. The implementation leverages
+existing infrastructure (GPU marketplace, smart contracts, token economy) while
+introducing model-specific trading, licensing, and royalty distribution
+mechanisms.
 
 ## Current Infrastructure Analysis
 
 ### Existing Components to Leverage
 
 #### 1. Smart Contract Foundation
+
 - **AIToken.sol**: ERC20 token with receipt-based minting
 - **AccessControl**: Role-based permissions (COORDINATOR_ROLE, ATTESTOR_ROLE)
 - **Signature Verification**: ECDSA-based attestation system
 - **Replay Protection**: Consumed receipt tracking
 
 #### 2. Privacy & Verification Infrastructure
+
 - **ZK Proof System** (`/apps/coordinator-api/src/app/services/zk_proofs.py`):
   - Circom circuit compilation and proof generation
   - Groth16 proof system integration
   - Receipt attestation circuits with Poseidon hashing
-- **Encryption Service** (`/apps/coordinator-api/src/app/services/encryption.py`):
+- **Encryption Service**
+  (`/apps/coordinator-api/src/app/services/encryption.py`):
   - AES-256-GCM symmetric encryption
   - X25519 asymmetric key exchange
   - Multi-party encryption with key escrow
@@ -29,6 +36,7 @@ This document outlines a detailed implementation plan for extending the AITBC pl
   - `BidRangeProof`: Range proofs for bids
 
 #### 3. Marketplace Infrastructure
+
 - **MarketplaceOffer/Bid Models**: SQLModel-based offer/bid system
 - **MarketplaceService**: Business logic for marketplace operations
 - **API Router**: RESTful endpoints (/marketplace/offers, /marketplace/bids)
@@ -36,6 +44,7 @@ This document outlines a detailed implementation plan for extending the AITBC pl
 - **Metrics Integration**: Prometheus monitoring
 
 #### 4. Coordinator API
+
 - **Database Layer**: SQLModel with PostgreSQL/SQLite
 - **Service Architecture**: Modular service design
 - **Authentication**: JWT-based auth system
@@ -46,103 +55,160 @@ This document outlines a detailed implementation plan for extending the AITBC pl
 ### Gas Optimization Strategies
 
 #### Royalty Distribution Efficiency
-- **Batch Royalty Processing**: Implement batched royalty payouts to reduce gas costs per transaction
+
-- **Layer 2 Solutions**: Consider Polygon or Optimism for lower gas fees on frequent royalty distributions
+- **Batch Royalty Processing**: Implement batched royalty payouts to reduce gas
-- **Threshold-Based Payouts**: Accumulate royalties until they exceed minimum payout thresholds
+  costs per transaction
-- **Gasless Transactions**: Implement meta-transactions for royalty claims to shift gas costs to platform
+- **Layer 2 Solutions**: Consider Polygon or Optimism for lower gas fees on
+  frequent royalty distributions
+- **Threshold-Based Payouts**: Accumulate royalties until they exceed minimum
+  payout thresholds
+- **Gasless Transactions**: Implement meta-transactions for royalty claims to
+  shift gas costs to platform
 
 #### Smart Contract Optimizations
-- **Storage Optimization**: Use efficient data structures and pack variables to minimize storage costs
+
-- **Function Selectors**: Optimize contract function signatures for gas efficiency
+- **Storage Optimization**: Use efficient data structures and pack variables to
-- **Assembly Optimization**: Use Yul assembly for critical gas-intensive operations
+  minimize storage costs
+- **Function Selectors**: Optimize contract function signatures for gas
+  efficiency
+- **Assembly Optimization**: Use Yul assembly for critical gas-intensive
+  operations
 
 ### Storage Reliability Enhancements
 
 #### Multi-Storage Backend Architecture
+
 - **IPFS Primary Storage**: Decentralized storage with pinning services
 - **Arweave Fallback**: Permanent storage with "pay once, store forever" model
-- **Automatic Failover**: Smart routing between storage backends based on availability
+- **Automatic Failover**: Smart routing between storage backends based on
-- **Content Verification**: Cross-validate content integrity across multiple storage systems
+  availability
+- **Content Verification**: Cross-validate content integrity across multiple
+  storage systems
 
 #### Storage Monitoring & Management
+
 - **Pinning Service Health Checks**: Monitor IPFS pinning service availability
-- **Replication Strategy**: Maintain multiple copies across different storage networks
+- **Replication Strategy**: Maintain multiple copies across different storage
-- **Cost Optimization**: Balance storage costs between IPFS and Arweave based on access patterns
+  networks
+- **Cost Optimization**: Balance storage costs between IPFS and Arweave based on
+  access patterns
 
 ### Legal and Liability Framework
 
 #### Model Creator Liability Management
-- **Training Data Transparency**: Require disclosure of training data sources and licenses
+
-- **Model Output Disclaimers**: Standardized disclaimers for model outputs and potential biases
+- **Training Data Transparency**: Require disclosure of training data sources
-- **Creator Verification**: KYC process for model creators with legal entity validation
+  and licenses
-- **Insurance Integration**: Platform-provided insurance options for high-risk model categories
+- **Model Output Disclaimers**: Standardized disclaimers for model outputs and
+  potential biases
+- **Creator Verification**: KYC process for model creators with legal entity
+  validation
+- **Insurance Integration**: Platform-provided insurance options for high-risk
+  model categories
 
 #### Platform Liability Protections
-- **Terms of Service**: Comprehensive ToS covering model usage, liability limitations
+
+- **Terms of Service**: Comprehensive ToS covering model usage, liability
+  limitations
 - **Indemnification Clauses**: Creator indemnification for model-related claims
-- **Jurisdiction Selection**: Clear legal jurisdiction and dispute resolution mechanisms
+- **Jurisdiction Selection**: Clear legal jurisdiction and dispute resolution
-- **Regular Legal Audits**: Periodic review of legal frameworks and compliance requirements
+  mechanisms
+- **Regular Legal Audits**: Periodic review of legal frameworks and compliance
+  requirements
 
 ### Digital Rights Management (DRM)
 
 #### Watermarking and Tracking Systems
-- **Invisible Watermarking**: Embed imperceptible watermarks in model weights for ownership tracking
+
+- **Invisible Watermarking**: Embed imperceptible watermarks in model weights
+  for ownership tracking
 - **Usage Fingerprinting**: Track model usage patterns and deployment locations
-- **License Key Management**: Cryptographic license keys tied to specific deployments
+- **License Key Management**: Cryptographic license keys tied to specific
+  deployments
 - **Tamper Detection**: Detect unauthorized modifications to model files
 
 #### Piracy Prevention Measures
+
 - **Model Encryption**: Encrypt model files with user-specific keys
 - **Access Control Lists**: Granular permissions for model access and usage
-- **Revocation Mechanisms**: Ability to revoke access to compromised or pirated models
+- **Revocation Mechanisms**: Ability to revoke access to compromised or pirated
+  models
 - **Forensic Analysis**: Tools to trace pirated model usage back to source
 
 ### Quality Assurance and Security
 
 #### Pre-Listing Validation Pipeline
+
 - **Malware Scanning**: Automated scanning for malicious code in model files
-- **Model Quality Metrics**: Automated evaluation of model performance and safety
+- **Model Quality Metrics**: Automated evaluation of model performance and
-- **Training Data Validation**: Verification of training data quality and ethical sourcing
+  safety
-- **Bias and Fairness Testing**: Automated testing for harmful biases in model outputs
+- **Training Data Validation**: Verification of training data quality and
+  ethical sourcing
+- **Bias and Fairness Testing**: Automated testing for harmful biases in model
+  outputs
 
 #### Continuous Monitoring
-- **Model Performance Tracking**: Monitor deployed model performance and accuracy
+
-- **Security Vulnerability Scanning**: Regular security audits of deployed models
+- **Model Performance Tracking**: Monitor deployed model performance and
-- **Usage Pattern Analysis**: Detect anomalous usage that may indicate security issues
+  accuracy
+- **Security Vulnerability Scanning**: Regular security audits of deployed
+  models
+- **Usage Pattern Analysis**: Detect anomalous usage that may indicate security
+  issues
 - **Automated Retraining Triggers**: Alert creators when models need updates
 
 ### GPU Inference Integration
 
 #### Automated Model Deployment
-- **One-Click GPU Deployment**: Seamless integration between marketplace purchases and GPU job scheduling
+
-- **Model Format Standardization**: Convert purchased models to optimal formats for GPU inference
+- **One-Click GPU Deployment**: Seamless integration between marketplace
-- **Resource Auto-Allocation**: Automatically allocate appropriate GPU resources based on model requirements
+  purchases and GPU job scheduling
-- **Performance Optimization**: Apply model optimizations (quantization, pruning) for target hardware
+- **Model Format Standardization**: Convert purchased models to optimal formats
+  for GPU inference
+- **Resource Auto-Allocation**: Automatically allocate appropriate GPU resources
+  based on model requirements
+- **Performance Optimization**: Apply model optimizations (quantization,
+  pruning) for target hardware
 
 #### Inference Job Orchestration
-- **Job Queue Integration**: Link purchased models to existing GPU job queue system
+
+- **Job Queue Integration**: Link purchased models to existing GPU job queue
+  system
 - **Load Balancing**: Distribute inference jobs across available GPU resources
-- **Cost Tracking**: Monitor and bill for GPU usage separate from model purchase costs
+- **Cost Tracking**: Monitor and bill for GPU usage separate from model purchase
+  costs
 - **Result Caching**: Cache inference results to reduce redundant computations
 
 ### NFT Integration Framework
 
 #### ERC-721 Model Wrappers
-- **Model Ownership NFTs**: ERC-721 tokens representing ownership of specific model versions
+
+- **Model Ownership NFTs**: ERC-721 tokens representing ownership of specific
+  model versions
 - **Metadata Standardization**: Standard metadata schema for AI model NFTs
-- **Transfer Restrictions**: Implement transfer controls based on license agreements
+- **Transfer Restrictions**: Implement transfer controls based on license
-- **Royalty Automation**: Automatic royalty distribution through NFT smart contracts
+  agreements
+- **Royalty Automation**: Automatic royalty distribution through NFT smart
+  contracts
 
 #### Soulbound Achievement Badges
-- **Creator Badges**: Non-transferable badges for verified creators and contributors
+
-- **Model Quality Badges**: Badges for models meeting quality and safety standards
+- **Creator Badges**: Non-transferable badges for verified creators and
+  contributors
+- **Model Quality Badges**: Badges for models meeting quality and safety
+  standards
 - **Community Recognition**: Badges for community contributions and model usage
-- **Verification Status**: Visual indicators of model verification and security status
+- **Verification Status**: Visual indicators of model verification and security
+  status
 
 ### FHE Marketplace Features
-- **Privacy Tier Pricing**: Different pricing tiers based on privacy level requirements
+
-- **FHE Performance Metrics**: Transparent reporting of FHE inference latency and costs
+- **Privacy Tier Pricing**: Different pricing tiers based on privacy level
-- **Compatibility Verification**: Ensure models are compatible with FHE requirements
+  requirements
+- **FHE Performance Metrics**: Transparent reporting of FHE inference latency
+  and costs
+- **Compatibility Verification**: Ensure models are compatible with FHE
+  requirements
 - **Hybrid Inference Options**: Choose between standard and FHE inference modes
 
 ## Additional Marketplace Gaps & Solutions
@@ -150,14 +216,20 @@ This document outlines a detailed implementation plan for extending the AITBC pl
 ### Security Audits & Timeline
 
 #### Smart Contract Audit Requirements
-- **Comprehensive Audit**: Full security audit by leading firms (OpenZeppelin, Trail of Bits, or Certik)
+
-- **ZK Circuit Audit**: Specialized audit for zero-knowledge circuits and cryptographic proofs
+- **Comprehensive Audit**: Full security audit by leading firms (OpenZeppelin,
+  Trail of Bits, or Certik)
+- **ZK Circuit Audit**: Specialized audit for zero-knowledge circuits and
+  cryptographic proofs
 - **Timeline**: Weeks 10-11 (after core functionality is complete)
 - **Budget**: $50,000-75,000 for combined smart contract and ZK audit
-- **Scope**: Reentrancy, access control, overflow/underflow, oracle manipulation, cryptographic correctness
+- **Scope**: Reentrancy, access control, overflow/underflow, oracle
+  manipulation, cryptographic correctness
 
 #### Audit Deliverables
-- **Security Report**: Detailed findings with severity levels and remediation steps
+
+- **Security Report**: Detailed findings with severity levels and remediation
+  steps
 - **Gas Optimization**: Contract optimization recommendations
 - **Test Coverage**: Requirements for additional test scenarios
 - **Monitoring Recommendations**: On-chain monitoring and alerting setup
@@ -165,6 +237,7 @@ This document outlines a detailed implementation plan for extending the AITBC pl
 ### Model Versioning & Upgrade Mechanism
 
 #### Version Control System
+
 ```solidity
 // Enhanced ModelListing with versioning
 struct ModelVersion {
@@ -213,6 +286,7 @@ function upgradeModel(
 ```
 
 #### Database Extensions
+
 ```python
 class ModelVersion(SQLModel, table=True):
     id: str = Field(default_factory=lambda: uuid4().hex, primary_key=True)
@@ -231,25 +305,35 @@ class ModelVersion(SQLModel, table=True):
 ### Platform Economics & Revenue Model
 
 #### Fee Structure
+
 - **Listing Fee**: 0.1 AIT per model listing (covers IPFS/Arweave storage costs)
-- **Platform Sales Cut**: 2.5% of all sales (0.5% platform, 2% miner rewards pool)
+- **Platform Sales Cut**: 2.5% of all sales (0.5% platform, 2% miner rewards
-- **Premium Features**: Additional fees for FHE inference (5 AIT/setup), priority verification (1 AIT), featured listings (10 AIT/week)
+  pool)
-- **Subscription Tiers**: Creator premium subscriptions (50 AIT/month) for advanced analytics and marketing tools
+- **Premium Features**: Additional fees for FHE inference (5 AIT/setup),
+  priority verification (1 AIT), featured listings (10 AIT/week)
+- **Subscription Tiers**: Creator premium subscriptions (50 AIT/month) for
+  advanced analytics and marketing tools
 
 #### Revenue Sharing with Miners
-- **Inference Revenue Split**: 70% to miners, 20% to model creators, 10% platform
+
-- **Quality-Based Rewards**: Higher rewards for miners with better performance/reliability scores
+- **Inference Revenue Split**: 70% to miners, 20% to model creators, 10%
+  platform
+- **Quality-Based Rewards**: Higher rewards for miners with better
+  performance/reliability scores
 - **Staking Multipliers**: Miners staking AIT tokens get 2x reward multipliers
 - **Geographic Bonuses**: Extra rewards for serving underserved regions
 
 #### Economic Incentives
+
 - **Creator Rewards**: Royalties, platform referrals, quality bonuses
 - **Miner Rewards**: Inference payments, staking rewards, performance bonuses
-- **User Benefits**: Volume discounts, loyalty rewards, early access to new models
+- **User Benefits**: Volume discounts, loyalty rewards, early access to new
+  models
 
 ### Secure Preview Sandbox
 
 #### Sandbox Architecture
+
 ```python
 class ModelSandbox:
     """Secure environment for model previews and testing"""
@@ -315,6 +399,7 @@ class ModelSandbox:
 ```
 
 #### API Endpoints
+
 ```python
 @router.post("/model-marketplace/models/{model_id}/preview")
 async def preview_model(
@@ -331,6 +416,7 @@ async def preview_model(
 ### Large File Handling (>10GB Models)
 
 #### Chunked Upload System
+
 ```python
 class ChunkedUploadService:
     """Handle large model file uploads with resumable chunking"""
@@ -415,6 +501,7 @@ class ChunkedUploadService:
 ```
 
 #### Streaming Download
+
 ```python
 @router.get("/model-marketplace/models/{model_id}/download")
 async def stream_model_download(
@@ -460,6 +547,7 @@ async def stream_model_download(
 ### Official SDK & Developer Tools
 
 #### SDK Architecture
+
 ```python
 # Python SDK
 class AITBCModelMarketplace:
@@ -587,6 +675,7 @@ class AITBCSDK {
 ### Creator Reputation & Quality Scoring
 
 #### Reputation System
+
 ```python
 class ReputationEngine:
     """Calculate and maintain creator reputation scores"""
@@ -677,6 +766,7 @@ class ReputationEngine:
 ```
 
 #### Database Extensions
+
 ```python
 class CreatorReputation(SQLModel, table=True):
     creator_address: str = Field(primary_key=True)
@@ -694,12 +784,17 @@ class CreatorReputation(SQLModel, table=True):
 ### Regulatory Compliance & KYC/AML
 
 #### EU AI Act Compliance
-- **Risk Classification**: Automatic model risk assessment (unacceptable, high, medium, low risk)
+
-- **Transparency Requirements**: Mandatory disclosure of training data, model capabilities, and limitations
+- **Risk Classification**: Automatic model risk assessment (unacceptable, high,
-- **Data Governance**: GDPR-compliant data handling with right to explanation and erasure
+  medium, low risk)
+- **Transparency Requirements**: Mandatory disclosure of training data, model
+  capabilities, and limitations
+- **Data Governance**: GDPR-compliant data handling with right to explanation
+  and erasure
 - **Conformity Assessment**: Third-party auditing for high-risk AI systems
 
 #### KYC/AML Framework
+
 ```python
 class ComplianceService:
     """Handle KYC/AML and regulatory compliance"""
@@ -798,6 +893,7 @@ class ComplianceService:
 ```
 
 #### Regulatory Database Models
+
 ```python
 class KYCRecord(SQLModel, table=True):
     user_address: str = Field(primary_key=True)
@@ -823,6 +919,7 @@ class ComplianceLog(SQLModel, table=True):
 ### Performance Optimization & Efficient Lookups
 
 #### Optimized Smart Contract Lookups
+
 ```solidity
 // Replace O(n) tokenURI loop with efficient mapping
 contract AIModelMarketplace is AccessControl, ReentrancyGuard, ERC721 {
@@ -871,6 +968,7 @@ contract AIModelMarketplace is AccessControl, ReentrancyGuard, ERC721 {
 ```
 
 #### Off-Chain Indexing Service
+
 ```python
 class MarketplaceIndexer:
     """Maintain efficient off-chain indexes for fast lookups"""
@@ -939,6 +1037,7 @@ class MarketplaceIndexer:
 ### Dispute Resolution & Governance
 
 #### Dispute Resolution Framework
+
 ```solidity
 contract ModelDisputeResolution is AccessControl {
     enum DisputeStatus { Open, UnderReview, Resolved, Appealed }
@@ -1027,6 +1126,7 @@ contract ModelDisputeResolution is AccessControl {
 ```
 
 #### Usage-Based Licensing
+
 ```solidity
 contract UsageBasedLicensing {
     struct UsageLicense {
@@ -1084,6 +1184,7 @@ contract UsageBasedLicensing {
 ### Semantic Search & Recommendations
 
 #### AI-Powered Discovery Engine
+
 ```python
 class SemanticSearchEngine:
     """Semantic search and recommendation system"""
@@ -1207,6 +1308,7 @@ class SemanticSearchEngine:
 ### CDN Caching & Performance Infrastructure
 
 #### Global CDN Integration
+
 ```python
 class CDNManager:
     """Manage CDN caching for model files and metadata"""
@@ -1263,6 +1365,7 @@ class CDNManager:
 ```
 
 #### Ollama Auto-Quantization Pipeline
+
 ```python
 class OllamaOptimizationPipeline:
     """Automatic model quantization and optimization for Ollama"""
@@ -1361,6 +1464,7 @@ class OllamaOptimizationPipeline:
 ```
 
 #### 1.1 AIModelMarketplace Contract
+
 ```solidity
 // Location: packages/solidity/aitbc-token/contracts/AIModelMarketplace.sol
 contract AIModelMarketplace is AccessControl, ReentrancyGuard, ERC721 {
@@ -1554,9 +1658,9 @@ contract AIModelMarketplace is AccessControl, ReentrancyGuard, ERC721 {
     }
 }
 ```
-```
 
 #### 1.2 ModelVerification Contract
+
 ```solidity
 // Location: packages/solidity/aitbc-token/contracts/ModelVerification.sol
 contract ModelVerification is AccessControl {
@@ -1633,6 +1737,7 @@ contract ModelVerification is AccessControl {
 ```
 
 #### 1.3 RoyaltyDistributor Contract
+
 ```solidity
 // Location: packages/solidity/aitbc-token/contracts/RoyaltyDistributor.sol
 contract RoyaltyDistributor {
@@ -1657,6 +1762,7 @@ contract RoyaltyDistributor {
 ### Phase 2: Backend Integration (Week 3-4)
 
 #### 2.1 Database Models
+
 ```python
 # Location: apps/coordinator-api/src/app/domain/model_marketplace.py
 class AIModel(SQLModel, table=True):
@@ -1719,6 +1825,7 @@ class ModelReview(SQLModel, table=True):
 ```
 
 #### 2.2 Service Layer
+
 ```python
 # Location: apps/coordinator-api/src/app/services/model_marketplace.py
 class ModelMarketplaceService:
@@ -1974,6 +2081,7 @@ class ModelMarketplaceService:
 ```
 
 #### 2.3 API Endpoints
+
 ```python
 # Location: apps/coordinator-api/src/app/routers/model_marketplace.py
 router = APIRouter(tags=["model-marketplace"])
@@ -2055,6 +2163,7 @@ async def download_model(
 ### Phase 3: Frontend Integration (Week 5-6)
 
 #### 3.1 Model Marketplace Web Interface
+
 ```typescript
 // Location: apps/model-marketplace-web/src/components/ModelCard.tsx
 interface ModelCardProps {
@@ -2113,6 +2222,7 @@ export const ModelCard: React.FC<ModelCardProps> = ({ model, onPurchase, onPrevi
 ```
 
 #### 3.2 Model Upload Interface
+
 ```typescript
 // Location: apps/model-marketplace-web/src/components/ModelUpload.tsx
 export const ModelUpload: React.FC = () => {
@@ -2196,6 +2306,7 @@ export const ModelUpload: React.FC = () => {
 ### Phase 4: Integration Testing (Week 7)
 
 #### 4.1 Smart Contract Tests
+
 ```javascript
 // Location: packages/solidity/aitbc-token/test/ModelMarketplace.test.js
 describe("AIModelMarketplace", function () {
@@ -2209,7 +2320,10 @@ describe("AIModelMarketplace", function () {
     marketplace = await AIModelMarketplace.deploy(owner.address);
     modelRegistry = await ModelRegistry.deploy();
 
-    await marketplace.grantRole(await marketplace.MODEL_CREATOR_ROLE(), creator.address);
+    await marketplace.grantRole(
+      await marketplace.MODEL_CREATOR_ROLE(),
+      creator.address,
+    );
   });
 
   it("Should list a new model", async function () {
@@ -2218,13 +2332,13 @@ describe("AIModelMarketplace", function () {
     const price = ethers.parseEther("100");
     const royaltyBps = 250; // 2.5%
 
-    await expect(marketplace.connect(creator).listModel(
+    await expect(
-      modelHash,
+      marketplace
-      metadataHash,
+        .connect(creator)
-      price,
+        .listModel(modelHash, metadataHash, price, royaltyBps),
-      royaltyBps
+    )
-    )).to.emit(marketplace, "ModelListed")
+      .to.emit(marketplace, "ModelListed")
-     .withArgs(1, creator.address, price, royaltyBps);
+      .withArgs(1, creator.address, price, royaltyBps);
 
     const model = await marketplace.modelListings(1);
     expect(model.creator).to.equal(creator.address);
@@ -2234,16 +2348,15 @@ describe("AIModelMarketplace", function () {
 
   it("Should purchase model and distribute royalties", async function () {
     // First list a model
-    await marketplace.connect(creator).listModel(
+    await marketplace
-      "QmTest123",
+      .connect(creator)
-      "QmMetadata456",
+      .listModel("QmTest123", "QmMetadata456", ethers.parseEther("100"), 250);
-      ethers.parseEther("100"),
-      250
-    );
 
     // Mint tokens to buyer
     await aitoken.mint(buyer.address, ethers.parseEther("1000"));
-    await aitoken.connect(buyer).approve(marketplace.getAddress(), ethers.parseEther("100"));
+    await aitoken
+      .connect(buyer)
+      .approve(marketplace.getAddress(), ethers.parseEther("100"));
 
     // Purchase model
     await expect(marketplace.connect(buyer).purchaseModel(1))
@@ -2258,6 +2371,7 @@ describe("AIModelMarketplace", function () {
 ```
 
 #### 4.2 Integration Tests
+
 ```python
 # Location: tests/integration/test_model_marketplace.py
 @pytest.mark.asyncio
@@ -2324,6 +2438,7 @@ async def test_model_listing_workflow(coordinator_client, test_wallet):
 ### Phase 5: Deployment & Monitoring (Week 8)
 
 #### 5.1 Smart Contract Deployment
+
 ```bash
 # Location: packages/solidity/aitbc-token/scripts/deploy-model-marketplace.sh
 #!/bin/bash
@@ -2355,6 +2470,7 @@ echo "RoyaltyDistributor: $ROYALTY_DISTRIBUTOR_ADDRESS"
 ```
 
 #### 5.2 Monitoring & Metrics
+
 ```python
 # Location: apps/coordinator-api/src/app/metrics/model_marketplace.py
 from prometheus_client import Counter, Histogram, Gauge
@@ -2396,58 +2512,75 @@ active_models_gauge = Gauge(
 ### Technical Risks
 
 #### 1. IPFS Storage Reliability
+
 - **Risk**: IPFS pinning service failure, content availability
-- **Mitigation**: Multiple pinning providers, local caching, content verification
+- **Mitigation**: Multiple pinning providers, local caching, content
+  verification
 
 #### 2. Smart Contract Security
+
 - **Risk**: Reentrancy attacks, access control bypass
 - **Mitigation**: OpenZeppelin libraries, comprehensive testing, security audits
 
 #### 3. Model File Integrity
+
 - **Risk**: Model tampering, corrupted downloads
-- **Mitigation**: Hash verification, version control, integrity checks with ZK proofs
+- **Mitigation**: Hash verification, version control, integrity checks with ZK
+  proofs
 
 #### 4. ZK Proof Performance
+
 - **Risk**: Proof generation too slow for large models
 - **Mitigation**: Recursive proof techniques, model compression, proof caching
 
 #### 5. Privacy Mechanism Overhead
+
 - **Risk**: FHE operations too expensive for practical use
 - **Mitigation**: Model optimization, selective encryption, hybrid approaches
 
 ### Business Risks
 
 #### 1. Model Piracy
+
 - **Risk**: Unauthorized redistribution of purchased models
-- **Mitigation**: License tracking, watermarking, legal terms, privacy-preserving access controls
+- **Mitigation**: License tracking, watermarking, legal terms,
+  privacy-preserving access controls
 
 #### 2. Quality Control
+
 - **Risk**: Low-quality or malicious models
-- **Mitigation**: Review process, rating system, creator verification, automated model validation
+- **Mitigation**: Review process, rating system, creator verification, automated
+  model validation
 
 #### 3. Privacy vs Usability Trade-offs
+
 - **Risk**: Privacy features reduce model usability
 - **Mitigation**: Configurable privacy levels, hybrid approaches, user education
 
 ### Privacy-Specific Risks
 
 #### 1. Key Management Complexity
+
 - **Risk**: Secure distribution of encryption keys
-- **Mitigation**: Multi-party computation, threshold cryptography, hardware security modules
+- **Mitigation**: Multi-party computation, threshold cryptography, hardware
+  security modules
 
 #### 2. ZK Proof Verification Overhead
+
 - **Risk**: Verification too expensive for frequent operations
 - **Mitigation**: Batch verification, proof aggregation, optimized circuits
 
 ## Success Metrics
 
 ### Technical Metrics
+
 - **Model Listing Success Rate**: >95%
 - **Download Success Rate**: >98%
 - **Transaction Confirmation Time**: <5 minutes
 - **Smart Contract Gas Efficiency**: <200k gas per operation
 
 ### Business Metrics
+
 - **Models Listed**: 100+ in first quarter
 - **Active Creators**: 50+ in first quarter
 - **Model Purchases**: 500+ transactions in first quarter
@@ -2455,34 +2588,43 @@ active_models_gauge = Gauge(
 
 ## Timeline Summary
 
-| Week | Phase | Key Deliverables |
+| Week  | Phase                            | Key Deliverables                                                                                |
-|------|-------|------------------|
+| ----- | -------------------------------- | ----------------------------------------------------------------------------------------------- |
-| 1-2 | Smart Contract Development | AIModelMarketplace, ModelVerification, RoyaltyDistributor contracts with privacy features |
+| 1-2   | Smart Contract Development       | AIModelMarketplace, ModelVerification, RoyaltyDistributor contracts with privacy features       |
-| 3-4 | Backend Integration | Database models with verification fields, service layer with ZK/FHE integration, API endpoints |
+| 3-4   | Backend Integration              | Database models with verification fields, service layer with ZK/FHE integration, API endpoints  |
-| 5-6 | Frontend Integration | Model marketplace UI with privacy options, upload interface with verification, purchase flow |
+| 5-6   | Frontend Integration             | Model marketplace UI with privacy options, upload interface with verification, purchase flow    |
-| 7-8 | Privacy & Verification Testing | Smart contract tests, API integration tests, ZK proof validation, FHE testing, end-to-end tests |
+| 7-8   | Privacy & Verification Testing   | Smart contract tests, API integration tests, ZK proof validation, FHE testing, end-to-end tests |
-| 9-10 | Advanced Features & Optimization | Batch verification, proof aggregation, model compression, performance optimization |
+| 9-10  | Advanced Features & Optimization | Batch verification, proof aggregation, model compression, performance optimization              |
-| 11-12 | Deployment & Monitoring | Contract deployment with privacy features, monitoring setup, documentation, security audits |
+| 11-12 | Deployment & Monitoring          | Contract deployment with privacy features, monitoring setup, documentation, security audits     |
 
 ## Resource Requirements
 
 ### Development Team
+
 - **Smart Contract Developer**: 1 FTE (Weeks 1-2, 8, 12)
-- **Cryptography Engineer**: 1 FTE (Weeks 1-4, 7-10) - ZK proofs and privacy mechanisms
+- **Cryptography Engineer**: 1 FTE (Weeks 1-4, 7-10) - ZK proofs and privacy
-- **Backend Developer**: 1.5 FTE (Weeks 3-4, 7-8, 10-12) - Enhanced with privacy integration
+  mechanisms
-- **Frontend Developer**: 1 FTE (Weeks 5-6, 9-10) - Privacy options and verification UI
+- **Backend Developer**: 1.5 FTE (Weeks 3-4, 7-8, 10-12) - Enhanced with privacy
-- **DevOps Engineer**: 1 FTE (Weeks 8, 11-12) - Privacy infrastructure deployment
+  integration
-- **Security Researcher**: 0.5 FTE (Weeks 7-12) - Privacy and verification security analysis
+- **Frontend Developer**: 1 FTE (Weeks 5-6, 9-10) - Privacy options and
+  verification UI
+- **DevOps Engineer**: 1 FTE (Weeks 8, 11-12) - Privacy infrastructure
+  deployment
+- **Security Researcher**: 0.5 FTE (Weeks 7-12) - Privacy and verification
+  security analysis
 
 ### Infrastructure
+
 - **IPFS Cluster**: 3 nodes for redundancy
 - **Blockchain Node**: Dedicated node for contract interactions
 - **ZK Proving Service**: Cloud-based proving service for large circuits
 - **FHE Computation Nodes**: Specialized hardware for homomorphic operations
-- **Database Storage**: Additional 200GB for model metadata and verification data
+- **Database Storage**: Additional 200GB for model metadata and verification
+  data
 - **Monitoring**: Enhanced Prometheus/Grafana with privacy metrics
 
 ### Budget Estimate
+
 - **Development**: ~300 hours total (increased due to privacy complexity)
 - **Cryptography Research**: ~100 hours for ZK/FHE optimization
 - **Infrastructure**: $3,000/month additional (ZK proving, FHE nodes)
@@ -2492,6 +2634,12 @@ active_models_gauge = Gauge(
 
 ## Conclusion
 
-The on-chain model marketplace implementation leverages existing AITBC infrastructure while introducing sophisticated model trading, licensing, and royalty mechanisms. The phased approach ensures manageable development cycles with clear deliverables and risk mitigation strategies.
+The on-chain model marketplace implementation leverages existing AITBC
+infrastructure while introducing sophisticated model trading, licensing, and
+royalty mechanisms. The phased approach ensures manageable development cycles
+with clear deliverables and risk mitigation strategies.
 
-The implementation positions AITBC as a leader in decentralized AI model economies, providing creators with monetization opportunities and users with access to verified, high-quality models through a transparent blockchain-based marketplace.
+The implementation positions AITBC as a leader in decentralized AI model
+economies, providing creators with monetization opportunities and users with
+access to verified, high-quality models through a transparent blockchain-based
+marketplace.

docs/policies/BRANCH_PROTECTION.md

@@ -2,7 +2,8 @@
 
 ## Overview
 
-This document outlines the recommended branch protection settings for the AITBC repository to ensure code quality, security, and collaboration standards.
+This document outlines the recommended branch protection settings for the AITBC
+repository to ensure code quality, security, and collaboration standards.
 
 ## GitHub Branch Protection Settings
 
@@ -14,11 +15,13 @@ Navigate to: `Settings > Branches > Branch protection rules`
 
 **Branch name pattern**: `main`
 
-**Require status checks to pass before merging**
+##### Require status checks to pass before merging
+
 - ✅ Require branches to be up to date before merging
 - ✅ Require status checks to pass before merging
 
-**Required status checks**
+##### Required status checks
+
 - ✅ Lint (ruff)
 - ✅ Check .env.example drift
 - ✅ Test (pytest)
@@ -34,22 +37,28 @@ Navigate to: `Settings > Branches > Branch protection rules`
 - ✅ security-scanning / trivy
 - ✅ security-scanning / ossf-scorecard
 
-**Require pull request reviews before merging**
+##### Require pull request reviews before merging
+
 - ✅ Require approvals
   - **Required approving reviews**: 2
 - ✅ Dismiss stale PR approvals when new commits are pushed
 - ✅ Require review from CODEOWNERS
 - ✅ Require review from users with write access in the target repository
-- ✅ Limit the number of approvals required (2) - **Do not allow users with write access to approve their own pull requests**
+- ✅ Limit the number of approvals required (2)
+  - **Do not allow users with write access to approve their own pull
+    requests**
+
+##### Restrict pushes
 
-**Restrict pushes**
 - ✅ Limit pushes to users who have write access in the repository
 - ✅ Do not allow force pushes
 
-**Restrict deletions**
+##### Restrict deletions
+
 - ✅ Do not allow users with write access to delete matching branches
 
-**Require signed commits**
+##### Require signed commits
+
 - ✅ Require signed commits (optional, for enhanced security)
 
 ### Develop Branch Protection
@@ -57,6 +66,7 @@ Navigate to: `Settings > Branches > Branch protection rules`
 **Branch name pattern**: `develop`
 
 **Settings** (same as main, but with fewer required checks):
+
 - Require status checks to pass before merging
 - Required status checks: Lint, Test, Check .env.example drift
 - Require pull request reviews before merging (1 approval)
@@ -67,26 +77,39 @@ Navigate to: `Settings > Branches > Branch protection rules`
 
 ### Continuous Integration Checks
 
-| Status Check | Description | Workflow |
+- **`Lint (ruff)`**: Python code linting. Workflow:
-|-------------|-------------|----------|
+  `.github/workflows/ci.yml`
-| `Lint (ruff)` | Python code linting | `.github/workflows/ci.yml` |
+- **`Check .env.example drift`**: Configuration drift detection. Workflow:
-| `Check .env.example drift` | Configuration drift detection | `.github/workflows/ci.yml` |
+  `.github/workflows/ci.yml`
-| `Test (pytest)` | Python unit tests | `.github/workflows/ci.yml` |
+- **`Test (pytest)`**: Python unit tests. Workflow:
-| `contracts-ci / Lint` | Solidity linting | `.github/workflows/contracts-ci.yml` |
+  `.github/workflows/ci.yml`
-| `contracts-ci / Slither Analysis` | Solidity security analysis | `.github/workflows/contracts-ci.yml` |
+- **`contracts-ci / Lint`**: Solidity linting. Workflow:
-| `contracts-ci / Compile` | Smart contract compilation | `.github/workflows/contracts-ci.yml` |
+  `.github/workflows/contracts-ci.yml`
-| `contracts-ci / Test` | Smart contract tests | `.github/workflows/contracts-ci.yml` |
+- **`contracts-ci / Slither Analysis`**: Solidity security analysis.
-| `dotenv-check / dotenv-validation` | .env.example format validation | `.github/workflows/dotenv-check.yml` |
+  Workflow: `.github/workflows/contracts-ci.yml`
-| `dotenv-check / dotenv-security` | .env.example security check | `.github/workflows/dotenv-check.yml` |
+- **`contracts-ci / Compile`**: Smart contract compilation. Workflow:
-| `security-scanning / bandit` | Python security scanning | `.github/workflows/security-scanning.yml` |
+  `.github/workflows/contracts-ci.yml`
-| `security-scanning / codeql` | CodeQL analysis | `.github/workflows/security-scanning.yml` |
+- **`contracts-ci / Test`**: Smart contract tests. Workflow:
-| `security-scanning / safety` | Dependency vulnerability scan | `.github/workflows/security-scanning.yml` |
+  `.github/workflows/contracts-ci.yml`
-| `security-scanning / trivy` | Container security scan | `.github/workflows/security-scanning.yml` |
+- **`dotenv-check / dotenv-validation`**: `.env.example` format validation.
-| `security-scanning / ossf-scorecard` | OSSF Scorecard analysis | `.github/workflows/security-scanning.yml` |
+  Workflow: `.github/workflows/dotenv-check.yml`
+- **`dotenv-check / dotenv-security`**: `.env.example` security check.
+  Workflow: `.github/workflows/dotenv-check.yml`
+- **`security-scanning / bandit`**: Python security scanning. Workflow:
+  `.github/workflows/security-scanning.yml`
+- **`security-scanning / codeql`**: CodeQL analysis. Workflow:
+  `.github/workflows/security-scanning.yml`
+- **`security-scanning / safety`**: Dependency vulnerability scan. Workflow:
+  `.github/workflows/security-scanning.yml`
+- **`security-scanning / trivy`**: Container security scan. Workflow:
+  `.github/workflows/security-scanning.yml`
+- **`security-scanning / ossf-scorecard`**: OSSF Scorecard analysis.
+  Workflow: `.github/workflows/security-scanning.yml`
 
 ### Additional Checks for Feature Branches
 
 For feature branches, consider requiring:
+
 - `comprehensive-tests / unit-tests`
 - `comprehensive-tests / integration-tests`
 - `comprehensive-tests / api-tests`
@@ -94,7 +117,8 @@ For feature branches, consider requiring:
 
 ## CODEOWNERS Integration
 
-The branch protection should be configured to require review from CODEOWNERS. This ensures that:
+The branch protection should be configured to require review from CODEOWNERS.
+This ensures that:
 
 1. **Domain experts review relevant changes**
 2. **Security team reviews security-sensitive files**
@@ -208,7 +232,9 @@ jobs:
         run: python scripts/focused_dotenv_linter.py --check
       
       - name: Test (pytest)
-        run: poetry run pytest --cov=aitbc_cli --cov-report=term-missing --cov-report=xml
+        run: >-
+          poetry run pytest --cov=aitbc_cli --cov-report=term-missing
+          --cov-report=xml
 ```
 
 ## Security Best Practices
@@ -386,6 +412,9 @@ New team members should be trained on:
 
 ## Conclusion
 
-Proper branch protection configuration ensures code quality, security, and collaboration standards. By implementing these settings, the AITBC repository maintains high standards while enabling efficient development workflows.
+Proper branch protection configuration ensures code quality, security, and
+collaboration standards. By implementing these settings, the AITBC repository
+maintains high standards while enabling efficient development workflows.
 
-Regular review and updates to branch protection settings ensure they remain effective as the project evolves.
+Regular review and updates to branch protection settings ensure they remain
+effective as the project evolves.

docs/policies/CLI_TRANSLATION_SECURITY_POLICY.md

@@ -2,12 +2,16 @@
 
 ## 🔐 Security Overview
 
-This document outlines the comprehensive security policy for CLI translation functionality in the AITBC platform, ensuring that translation services never compromise security-sensitive operations.
+This document outlines the comprehensive security policy for CLI translation
+functionality in the AITBC platform, ensuring that translation services never
+compromise security-sensitive operations.
 
 ## ⚠️ Security Problem Statement
 
 ### Identified Risks
-1. **API Dependency**: Translation services rely on external APIs (OpenAI, Google, DeepL)
+
+1. **API Dependency**: Translation services rely on external APIs (OpenAI,
+   Google, DeepL)
 2. **Network Failures**: Translation unavailable during network outages
 3. **Data Privacy**: Sensitive command data sent to third-party services
 4. **Command Injection**: Risk of translated commands altering security context
@@ -15,6 +19,7 @@ This document outlines the comprehensive security policy for CLI translation fun
 6. **Audit Trail**: Loss of original command intent in translation
 
 ### Security-Sensitive Operations
+
 - **Agent Strategy Commands**: `aitbc agent strategy --aggressive`
 - **Wallet Operations**: `aitbc wallet send --to 0x... --amount 100`
 - **Deployment Commands**: `aitbc deploy --production`
@@ -26,48 +31,63 @@ This document outlines the comprehensive security policy for CLI translation fun
 ### Security Levels
 
 #### 🔴 CRITICAL (Translation Disabled)
-**Commands**: `agent`, `strategy`, `wallet`, `sign`, `deploy`, `genesis`, `transfer`, `send`, `approve`, `mint`, `burn`, `stake`
+
+**Commands**: `agent`, `strategy`, `wallet`, `sign`, `deploy`, `genesis`,
+`transfer`, `send`, `approve`, `mint`, `burn`, `stake`
 
 **Policy**:
+
 - ✅ Translation: **DISABLED**
 - ✅ External APIs: **BLOCKED**
 - ✅ User Consent: **REQUIRED**
 - ✅ Fallback: **Original text only**
 
-**Rationale**: These commands handle sensitive operations where translation could compromise security or financial transactions.
+**Rationale**: These commands handle sensitive operations where translation
+could compromise security or financial transactions.
 
 #### 🟠 HIGH (Local Translation Only)
-**Commands**: `config`, `node`, `chain`, `marketplace`, `swap`, `liquidity`, `governance`, `vote`, `proposal`
+
+**Commands**: `config`, `node`, `chain`, `marketplace`, `swap`, `liquidity`,
+`governance`, `vote`, `proposal`
 
 **Policy**:
+
 - ✅ Translation: **LOCAL ONLY**
 - ✅ External APIs: **BLOCKED**
 - ✅ User Consent: **REQUIRED**
 - ✅ Fallback: **Local dictionary**
 
-**Rationale**: Important operations that benefit from localization but don't require external services.
+**Rationale**: Important operations that benefit from localization but don't
+require external services.
 
 #### 🟡 MEDIUM (Fallback Mode)
-**Commands**: `balance`, `status`, `monitor`, `analytics`, `logs`, `history`, `simulate`, `test`
+
+**Commands**: `balance`, `status`, `monitor`, `analytics`, `logs`, `history`,
+`simulate`, `test`
 
 **Policy**:
+
 - ✅ Translation: **EXTERNAL WITH LOCAL FALLBACK**
 - ✅ External APIs: **ALLOWED**
 - ✅ User Consent: **NOT REQUIRED**
 - ✅ Fallback: **Local translation on failure**
 
-**Rationale**: Standard operations where translation enhances user experience but isn't critical.
+**Rationale**: Standard operations where translation enhances user experience
+but isn't critical.
 
 #### 🟢 LOW (Full Translation)
+
 **Commands**: `help`, `version`, `info`, `list`, `show`, `explain`
 
 **Policy**:
+
 - ✅ Translation: **FULL CAPABILITIES**
 - ✅ External APIs: **ALLOWED**
 - ✅ User Consent: **NOT REQUIRED**
 - ✅ Fallback: **External retry then local**
 
-**Rationale**: Informational commands where translation improves accessibility without security impact.
+**Rationale**: Informational commands where translation improves
+accessibility without security impact.
 
 ## 🔧 Implementation Details
 
@@ -107,15 +127,26 @@ HIGH_POLICY = {
 
 ### Local Translation System
 
-For security-sensitive operations, a local translation system provides basic localization:
+For security-sensitive operations, a local translation system provides basic
+localization:
 
 ```python
 LOCAL_TRANSLATIONS = {
     "help": {"es": "ayuda", "fr": "aide", "de": "hilfe", "zh": "帮助"},
     "error": {"es": "error", "fr": "erreur", "de": "fehler", "zh": "错误"},
     "success": {"es": "éxito", "fr": "succès", "de": "erfolg", "zh": "成功"},
-    "wallet": {"es": "cartera", "fr": "portefeuille", "de": "börse", "zh": "钱包"},
+    "wallet": {
-    "transaction": {"es": "transacción", "fr": "transaction", "de": "transaktion", "zh": "交易"}
+        "es": "cartera",
+        "fr": "portefeuille",
+        "de": "börse",
+        "zh": "钱包"
+    },
+    "transaction": {
+        "es": "transacción",
+        "fr": "transaction",
+        "de": "transaktion",
+        "zh": "交易"
+    }
 }
 ```
 
@@ -237,7 +268,10 @@ from aitbc_cli.security import get_translation_security_report
 
 report = get_translation_security_report()
 print(f"Total security checks: {report['security_summary']['total_checks']}")
-print(f"Critical operations: {report['security_summary']['by_security_level']['critical']}")
+print(
+    f"Critical operations: "
+    f"{report['security_summary']['by_security_level']['critical']}"
+)
 print(f"Recommendations: {report['recommendations']}")
 ```
 
@@ -333,7 +367,8 @@ def handle_security_incident(incident_type: str):
 
 ### Key Performance Indicators
 
-- **Translation Success Rate**: Percentage of successful translations by security level
+- **Translation Success Rate**: Percentage of successful translations by
+  security level
 - **Fallback Usage Rate**: How often local fallback is used
 - **API Response Time**: External API performance metrics
 - **Security Violations**: Attempts to bypass security policies
@@ -356,24 +391,32 @@ def get_security_metrics():
 
 ### Planned Security Features
 
-1. **Machine Learning Detection**: AI-powered detection of sensitive command patterns
+1. **Machine Learning Detection**: AI-powered detection of sensitive command
-2. **Dynamic Policy Adjustment**: Automatic security level adjustment based on context
+   patterns
+2. **Dynamic Policy Adjustment**: Automatic security level adjustment based on
+   context
 3. **Zero-Knowledge Translation**: Privacy-preserving translation protocols
 4. **Blockchain Auditing**: Immutable audit trail on blockchain
-5. **Multi-Factor Authentication**: Additional security for sensitive translations
+5. **Multi-Factor Authentication**: Additional security for sensitive
+   translations
 
 ### Research Areas
 
-1. **Federated Learning**: Local translation models without external dependencies
+1. **Federated Learning**: Local translation models without external
-2. **Quantum-Resistant Security**: Future-proofing against quantum computing threats
+   dependencies
+2. **Quantum-Resistant Security**: Future-proofing against quantum computing
+   threats
 3. **Behavioral Analysis**: User behavior patterns for anomaly detection
 4. **Cross-Platform Security**: Consistent security across all CLI platforms
 
 ---
 
-**Security Policy Status**: ✅ **IMPLEMENTED**  
+- **Security Policy Status**: ✅ **IMPLEMENTED**
-**Last Updated**: March 3, 2026  
+- **Last Updated**: March 3, 2026
-**Next Review**: March 17, 2026  
+- **Next Review**: March 17, 2026
-**Security Level**: 🔒 **HIGH** - Comprehensive protection for sensitive operations  
+- **Security Level**: 🔒 **HIGH** - Comprehensive protection for sensitive
+  operations
 
-This security policy ensures that CLI translation functionality never compromises security-sensitive operations while providing appropriate localization capabilities for non-critical commands.
+This security policy ensures that CLI translation functionality never
+compromises security-sensitive operations while providing appropriate
+localization capabilities for non-critical commands.

docs/policies/DOTENV_DISCIPLINE.md

@@ -2,7 +2,9 @@
 
 ## 🎯 Problem Solved
 
-Having a `.env.example` file is good practice, but without automated checking, it can drift from what the application actually uses. This creates silent configuration issues where:
+Having a `.env.example` file is good practice, but without automated
+checking, it can drift from what the application actually uses. This creates
+silent configuration issues where:
 
 - New environment variables are added to code but not documented
 - Old variables remain in `.env.example` but are no longer used
@@ -14,28 +16,35 @@ Having a `.env.example` file is good practice, but without automated checking, i
 ### **Focused Dotenv Linter**
 
 Created a sophisticated linter that:
+
 - **Scans all code** for actual environment variable usage
 - **Filters out script variables** and non-config variables
 - **Compares with `.env.example`** to find drift
-- **Auto-fixes missing variables** in `.env.example
+- **Auto-fixes missing variables** in `.env.example`
 - **Validates format** and security of `.env.example`
 - **Integrates with CI/CD** to prevent drift
 
+
 ### **Key Features**
 
 #### **Smart Variable Detection**
+
 - Scans Python files for `os.environ.get()`, `os.getenv()`, etc.
 - Scans config files for `${VAR}` and `$VAR` patterns
 - Scans shell scripts for `export VAR=` and `VAR=` patterns
 - Filters out script variables, system variables, and internal variables
 
+
 #### **Comprehensive Coverage**
+
 - **Python files**: `*.py` across the entire project
 - **Config files**: `pyproject.toml`, `*.yml`, `*.yaml`, `Dockerfile`, etc.
 - **Shell scripts**: `*.sh`, `*.bash`, `*.zsh`
 - **CI/CD files**: `.github/workflows/*.yml`
 
+
 #### **Intelligent Filtering**
+
 - Excludes common script variables (`PID`, `VERSION`, `DEBUG`, etc.)
 - Excludes system variables (`PATH`, `HOME`, `USER`, etc.)
 - Excludes external tool variables (`NODE_ENV`, `DOCKER_HOST`, etc.)
@@ -61,7 +70,7 @@ python scripts/focused_dotenv_linter.py --check
 
 ### **Output Example**
 
-```
+```text
 🔍 Focused Dotenv Linter for AITBC
 ==================================================
 📄 Found 111 variables in .env.example
@@ -140,28 +149,37 @@ Created `.github/workflows/dotenv-check.yml` with:
 ### **Workflow Triggers**
 
 The dotenv check runs on:
+
 - **Push** to any branch (when relevant files change)
 - **Pull Request** (when relevant files change)
 - **File patterns**: `.env.example`, `*.py`, `*.yml`, `*.toml`, `*.sh`
 
+
 ## 📊 Benefits Achieved
 
 ### ✅ **Prevents Silent Drift**
+
 - **Automated Detection**: Catches drift as soon as it's introduced
 - **CI/CD Integration**: Prevents merging with configuration issues
 - **Developer Feedback**: Clear reports on what's missing/unused
 
+
 ### ✅ **Maintains Documentation**
+
 - **Always Up-to-Date**: `.env.example` reflects actual usage
 - **Comprehensive Coverage**: All environment variables documented
 - **Clear Organization**: Logical grouping and naming
 
+
 ### ✅ **Improves Developer Experience**
+
 - **Easy Discovery**: Developers can see all required variables
 - **Auto-Fix**: One-command fix for missing variables
 - **Validation**: Format and security checks
 
+
 ### ✅ **Enhanced Security**
+
 - **No Secrets**: Ensures `.env.example` contains only placeholders
 - **Security Scanning**: Detects potential actual secrets
 - **Best Practices**: Enforces good naming conventions
@@ -210,7 +228,8 @@ r'([A-Z_][A-Z0-9_]*)='
 
 ```bash
 # Checks for actual secrets vs placeholders
-if grep -i "password=" .env.example | grep -v -E "(your-|placeholder|change-)"; then
+if grep -i "password=" .env.example \
+  | grep -v -E "(your-|placeholder|change-)"; then
   echo "❌ Potential actual secrets found!"
   exit 1
 fi
@@ -219,13 +238,16 @@ fi
 ## 📈 Statistics
 
 ### **Current State**
+
 - **Variables in .env.example**: 111
 - **Actual variables used**: 124
 - **Missing variables**: 13 (auto-fixed)
 - **Unused variables**: 0
 - **Coverage**: 89.5%
 
+
 ### **Historical Tracking**
+
 - **Before linter**: 14 variables, 357 missing
 - **After linter**: 111 variables, 13 missing
 - **Improvement**: 693% increase in coverage
@@ -233,12 +255,15 @@ fi
 ## 🔮 Future Enhancements
 
 ### **Planned Features**
+
 - **Environment-specific configs**: `.env.development`, `.env.production`
 - **Type validation**: Validate variable value formats
 - **Dependency tracking**: Track which variables are required together
 - **Documentation generation**: Auto-generate config documentation
 
+
 ### **Advanced Validation**
+
 - **URL validation**: Ensure RPC URLs are properly formatted
 - **File path validation**: Check if referenced paths exist
 - **Value ranges**: Validate numeric variables have reasonable ranges
@@ -277,7 +302,9 @@ The dotenv configuration discipline ensures:
 ✅ **Security**: Ensures no actual secrets in documentation
 ✅ **Maintainability**: Clean, organized, and up-to-date configuration
 
-This discipline prevents the common problem of configuration drift and ensures that `.env.example` always accurately reflects what the application actually needs.
+This discipline prevents the common problem of configuration drift and ensures
+that `.env.example` always accurately reflects what the application actually
+needs.
 
 ---
 

scripts/blockchain-communication-test.sh

@@ -7,11 +7,14 @@
 
 set -e
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
 # Configuration
 GENESIS_IP="10.1.223.40"
 FOLLOWER_IP="<aitbc1-ip>"  # Replace with actual IP
 PORT=8006
-CLI_PATH="/opt/aitbc/aitbc-cli"
+CLI_PATH="${CLI_PATH:-${REPO_ROOT}/aitbc-cli}"
 LOG_DIR="/var/log/aitbc"
 LOG_FILE="${LOG_DIR}/blockchain-communication-test.log"
 MONITOR_LOG="${LOG_DIR}/blockchain-monitor.log"

scripts/testing/test_workflow.sh

@@ -2,17 +2,22 @@
 # Test Updated Workflow Scripts
 echo "=== Testing Updated Workflow Scripts ==="
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+WORKFLOW_DIR="${REPO_ROOT}/scripts/workflow"
+CLI_PATH="${REPO_ROOT}/aitbc-cli"
+
 echo "1. Testing wallet creation script..."
-/opt/aitbc/scripts/workflow/04_create_wallet.sh
+"${WORKFLOW_DIR}/04_create_wallet.sh"
 
 echo ""
 echo "2. Testing final verification script..."
-export WALLET_ADDR=$(/opt/aitbc/aitbc-cli wallet balance aitbc-user 2>/dev/null | grep "Address:" | awk '{print $2}' || echo "")
+export WALLET_ADDR=$("$CLI_PATH" wallet balance aitbc-user 2>/dev/null | grep "Address:" | awk '{print $2}' || echo "")
-/opt/aitbc/scripts/workflow/06_final_verification.sh
+"${WORKFLOW_DIR}/06_final_verification.sh"
 
 echo ""
 echo "3. Testing transaction manager script..."
-/opt/aitbc/scripts/workflow/09_transaction_manager.sh
+"${WORKFLOW_DIR}/09_transaction_manager.sh"
 
 echo ""
 echo "✅ All script tests completed!"

scripts/training/master_training_launcher.sh

@@ -10,8 +10,7 @@ set -e
 
 # Training configuration
 TRAINING_PROGRAM="OpenClaw AITBC Mastery Training"
-CLI_PATH="/opt/aitbc/aitbc-cli"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-SCRIPT_DIR="/opt/aitbc/scripts/training"
 LOG_DIR="/var/log/aitbc"
 WALLET_NAME="openclaw-trainee"
 

scripts/training/openclaw_cross_node_comm.sh

@@ -7,11 +7,14 @@
 
 set -e
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
 # Configuration
 GENESIS_IP="10.1.223.40"
 FOLLOWER_IP="<aitbc1-ip>"  # To be replaced during live training
 PORT=8006
-CLI_PATH="/opt/aitbc/aitbc-cli"
+CLI_PATH="${CLI_PATH:-${REPO_ROOT}/aitbc-cli}"
 
 # Colors for output
 RED='\033[0;31m'

scripts/training/stage4_marketplace_economics.sh

@@ -10,7 +10,6 @@ set -e
 
 # Training configuration
 TRAINING_STAGE="Stage 4: Marketplace & Economic Intelligence"
-CLI_PATH="/opt/aitbc/aitbc-cli"
 LOG_FILE="/var/log/aitbc/training_stage4.log"
 WALLET_NAME="openclaw-trainee"
 WALLET_PASSWORD="trainee123"

scripts/training/stage5_expert_automation.sh

@@ -10,7 +10,6 @@ set -e
 
 # Training configuration
 TRAINING_STAGE="Stage 5: Expert Operations & Automation"
-CLI_PATH="/opt/aitbc/aitbc-cli"
 LOG_FILE="/var/log/aitbc/training_stage5.log"
 WALLET_NAME="openclaw-trainee"
 WALLET_PASSWORD="trainee123"
@@ -176,7 +175,7 @@ advanced_scripting() {
     print_status "Advanced Automation Scripting"
     
     print_status "Creating custom automation script..."
-    cat > /tmp/openclaw_automation.py << 'EOF'
+    cat > /tmp/openclaw_automation.py <<EOF
 #!/usr/bin/env python3
 """
 OpenClaw Advanced Automation Script
@@ -191,6 +190,7 @@ import logging
 # Setup logging
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
+CLI_PATH = "${CLI_PATH}"
 
 def run_command(cmd):
     """Execute AITBC CLI command and return result"""
@@ -207,13 +207,13 @@ def automated_job_submission():
     logger.info("Starting automated job submission...")
     
     # Submit inference job
-    success, output, error = run_command("/opt/aitbc/aitbc-cli ai submit --prompt 'Automated analysis'")
+    success, output, error = run_command(f"{CLI_PATH} ai submit --prompt 'Automated analysis'")
     
     if success:
         logger.info(f"Job submitted successfully: {output}")
         # Monitor job completion
         time.sleep(5)
-        success, output, error = run_command("/opt/aitbc/aitbc-cli ai list --status completed")
+        success, output, error = run_command(f"{CLI_PATH} ai list --status completed")
         logger.info(f"Job monitoring result: {output}")
     else:
         logger.error(f"Job submission failed: {error}")
@@ -223,14 +223,14 @@ def automated_marketplace_monitoring():
     logger.info("Starting marketplace monitoring...")
     
     # Check marketplace status
-    success, output, error = run_command("/opt/aitbc/aitbc-cli market list")
+    success, output, error = run_command(f"{CLI_PATH} market list")
     
     if success:
         logger.info(f"Marketplace status: {output}")
         
         # Simple trading logic - place buy order for low-priced items
         if "test-item" in output:
-            success, output, error = run_command("/opt/aitbc/aitbc-cli market buy --item test-item --price 25")
+            success, output, error = run_command(f"{CLI_PATH} market buy --item test-item --price 25")
             logger.info(f"Buy order placed: {output}")
     else:
         logger.error(f"Marketplace monitoring failed: {error}")

scripts/training/training_lib.sh

@@ -6,12 +6,15 @@
 # Version: 1.0
 # Last Updated: 2026-04-02
 
+TRAINING_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${TRAINING_LIB_DIR}/../.." && pwd)"
+
 # ============================================================================
 # CONFIGURATION
 # ============================================================================
 
 # Default configuration (can be overridden)
-export CLI_PATH="${CLI_PATH:-/opt/aitbc/aitbc-cli}"
+export CLI_PATH="${CLI_PATH:-${REPO_ROOT}/aitbc-cli}"
 export LOG_DIR="${LOG_DIR:-/var/log/aitbc}"
 export WALLET_NAME="${WALLET_NAME:-openclaw-trainee}"
 export WALLET_PASSWORD="${WALLET_PASSWORD:-trainee123}"

scripts/workflow/04_create_wallet.sh

@@ -4,33 +4,37 @@
 
 set -e  # Exit on any error
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+CLI_PATH="${REPO_ROOT}/aitbc-cli"
+
 echo "=== AITBC Wallet Creation (Enhanced CLI) ==="
 
 echo "1. Pre-creation verification..."
 echo "=== Current wallets on aitbc ==="
-/opt/aitbc/aitbc-cli wallet list
+"$CLI_PATH" wallet list
 
 echo "2. Creating new wallet on aitbc..."
-/opt/aitbc/aitbc-cli wallet create aitbc-user $(cat /var/lib/aitbc/keystore/.password)
+"$CLI_PATH" wallet create aitbc-user $(cat /var/lib/aitbc/keystore/.password)
 
 # Get wallet address using CLI
-WALLET_ADDR=$(/opt/aitbc/aitbc-cli wallet balance aitbc-user 2>/dev/null | grep "Address:" | awk '{print $2}' || echo "")
+WALLET_ADDR=$("$CLI_PATH" wallet balance aitbc-user 2>/dev/null | grep "Address:" | awk '{print $2}' || echo "")
 echo "New wallet address: $WALLET_ADDR"
 
 # Verify wallet was created successfully using CLI
 echo "3. Post-creation verification..."
 echo "=== Updated wallet list ==="
-/opt/aitbc/aitbc-cli wallet list | grep aitbc-user || echo "Wallet not found in list"
+"$CLI_PATH" wallet list | grep aitbc-user || echo "Wallet not found in list"
 
 echo "=== New wallet details ==="
-/opt/aitbc/aitbc-cli wallet balance aitbc-user
+"$CLI_PATH" wallet balance aitbc-user
 
 echo "=== All wallets summary ==="
-/opt/aitbc/aitbc-cli wallet list
+"$CLI_PATH" wallet list
 
 echo "4. Cross-node verification..."
 echo "=== Network status (local) ==="
-/opt/aitbc/aitbc-cli network status 2>/dev/null || echo "Network status not available"
+"$CLI_PATH" network status 2>/dev/null || echo "Network status not available"
 
 echo "✅ Wallet created successfully using enhanced CLI!"
 echo "Wallet name: aitbc-user"

scripts/workflow/06_final_verification.sh

@@ -4,6 +4,10 @@
 
 set -e  # Exit on any error
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+CLI_PATH="${REPO_ROOT}/aitbc-cli"
+
 echo "=== AITBC Multi-Node Blockchain Final Verification ==="
 
 # Get wallet address (source from wallet creation script)
@@ -34,18 +38,18 @@ echo "Height difference: $HEIGHT_DIFF blocks"
 # Check wallet balance using CLI
 echo "2. Checking aitbc wallet balance..."
 echo "=== aitbc wallet balance (local) ==="
-BALANCE=$(/opt/aitbc/aitbc-cli wallet balance aitbc-user 2>/dev/null | grep "Balance:" | awk '{print $2}' || echo "0")
+BALANCE=$("$CLI_PATH" wallet balance aitbc-user 2>/dev/null | grep "Balance:" | awk '{print $2}' || echo "0")
 echo $BALANCE AIT
 
 # Get blockchain information using CLI
 echo "3. Blockchain information..."
 echo "=== Chain Information ==="
-/opt/aitbc/aitbc-cli blockchain info
+"$CLI_PATH" blockchain info
 
 # Network health check using CLI
 echo "4. Network health check..."
 echo "=== Network Status (local) ==="
-/opt/aitbc/aitbc-cli network status 2>/dev/null || echo "Network status not available"
+"$CLI_PATH" network status 2>/dev/null || echo "Network status not available"
 
 # Service status
 echo "5. Service status..."

scripts/workflow/09_transaction_manager.sh

@@ -4,6 +4,10 @@
 
 echo "=== AITBC Transaction Manager ==="
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+CLI_PATH="${REPO_ROOT}/aitbc-cli"
+
 # Configuration
 GENESIS_WALLET="aitbc1genesis"
 TARGET_WALLET="aitbc-user"
@@ -21,7 +25,7 @@ fi
 # Get wallet addresses
 echo "2. Getting wallet addresses..."
 GENESIS_ADDR=$(cat /var/lib/aitbc/keystore/aitbc1genesis.json | jq -r '.address')
-TARGET_ADDR=$(/opt/aitbc/aitbc-cli wallet balance aitbc-user 2>/dev/null | grep "Address:" | awk '{print $2}' || echo "")
+TARGET_ADDR=$("$CLI_PATH" wallet balance aitbc-user 2>/dev/null | grep "Address:" | awk '{print $2}' || echo "")
 
 echo "Genesis address: $GENESIS_ADDR"
 echo "Target address: $TARGET_ADDR"
@@ -92,7 +96,7 @@ else
   # Try alternative method using CLI
   echo "7. Trying alternative CLI method..."
   PASSWORD=$(cat $PASSWORD_FILE)
-  /opt/aitbc/aitbc-cli wallet send $GENESIS_WALLET $TARGET_ADDR $AMOUNT $PASSWORD
+  "$CLI_PATH" wallet send $GENESIS_WALLET $TARGET_ADDR $AMOUNT $PASSWORD
 fi
 
 # Final verification

tests/integration/integration_test.sh

@@ -3,7 +3,9 @@
 
 echo "=== AITBC Integration Tests ==="
 
-CLI_CMD="/opt/aitbc/aitbc-cli"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+CLI_CMD="${REPO_ROOT}/aitbc-cli"
 
 # Test 1: Basic connectivity
 echo "1. Testing connectivity..."
@@ -12,24 +14,24 @@ ssh -i ~/.ssh/id_ed25519_aitbc -o StrictHostKeyChecking=no root@aitbc1 'curl -s
 
 # Test 2: Wallet operations
 echo "2. Testing wallet operations..."
-$CLI_CMD wallet list >/dev/null && echo "✅ Wallet list works" || echo "❌ Wallet list failed"
+"$CLI_CMD" wallet list >/dev/null && echo "✅ Wallet list works" || echo "❌ Wallet list failed"
 
 # Test 3: Transaction operations
 echo "3. Testing transactions..."
 # Create test wallet
-$CLI_CMD wallet create test-integration --password-file /var/lib/aitbc/keystore/.password >/dev/null && echo "✅ Wallet creation works" || echo "❌ Wallet creation failed"
+"$CLI_CMD" wallet create test-integration --password-file /var/lib/aitbc/keystore/.password >/dev/null && echo "✅ Wallet creation works" || echo "❌ Wallet creation failed"
 
 # Test 4: Blockchain operations
 echo "4. Testing blockchain operations..."
-$CLI_CMD blockchain info >/dev/null && echo "✅ Chain info works" || echo "❌ Chain info failed"
+"$CLI_CMD" blockchain info >/dev/null && echo "✅ Chain info works" || echo "❌ Chain info failed"
 
 # Test 5: Enterprise CLI operations
 echo "5. Testing enterprise CLI operations..."
-$CLI_CMD market list >/dev/null && echo "✅ Marketplace CLI works" || echo "❌ Marketplace CLI failed"
+"$CLI_CMD" market list >/dev/null && echo "✅ Marketplace CLI works" || echo "❌ Marketplace CLI failed"
 
 # Test 6: Mining operations
 echo "6. Testing mining operations..."
-$CLI_CMD mining status >/dev/null && echo "✅ Mining operations work" || echo "❌ Mining operations failed"
+"$CLI_CMD" mining status >/dev/null && echo "✅ Mining operations work" || echo "❌ Mining operations failed"
 
 # Test 7: AI services
 echo "7. Testing AI services..."

tests/production/test_error_handling.py

@@ -5,6 +5,10 @@ Test error handling improvements in AITBC services
 import pytest
 import subprocess
 import time
+from pathlib import Path
+
+
+CLI_BIN = Path(__file__).resolve().parents[2] / "aitbc-cli"
 
 
 class TestServiceErrorHandling:
@@ -126,7 +130,7 @@ class TestCLIComprehensiveTesting:
     def test_cli_help_command(self):
         """Test CLI help command works"""
         result = subprocess.run(
-            ["/opt/aitbc/aitbc-cli", "--help"],
+            [str(CLI_BIN), "--help"],
             capture_output=True,
             text=True
         )
@@ -136,7 +140,7 @@ class TestCLIComprehensiveTesting:
     def test_cli_system_command(self):
         """Test CLI system command works"""
         result = subprocess.run(
-            ["/opt/aitbc/aitbc-cli", "system", "status"],
+            [str(CLI_BIN), "system", "status"],
             capture_output=True,
             text=True
         )
@@ -146,7 +150,7 @@ class TestCLIComprehensiveTesting:
     def test_cli_chain_command(self):
         """Test CLI chain command works"""
         result = subprocess.run(
-            ["/opt/aitbc/aitbc-cli", "blockchain", "info"],
+            [str(CLI_BIN), "blockchain", "info"],
             capture_output=True,
             text=True
         )
@@ -156,7 +160,7 @@ class TestCLIComprehensiveTesting:
     def test_cli_network_command(self):
         """Test CLI network command works"""
         result = subprocess.run(
-            ["/opt/aitbc/aitbc-cli", "network", "status"],
+            [str(CLI_BIN), "network", "status"],
             capture_output=True,
             text=True
         )
@@ -166,7 +170,7 @@ class TestCLIComprehensiveTesting:
     def test_cli_wallet_command(self):
         """Test CLI wallet command works"""
         result = subprocess.run(
-            ["/opt/aitbc/aitbc-cli", "wallet", "--help"],
+            [str(CLI_BIN), "wallet", "--help"],
             capture_output=True,
             text=True
         )
@@ -176,7 +180,7 @@ class TestCLIComprehensiveTesting:
     def test_cli_marketplace_list_command(self):
         """Test CLI marketplace list command works"""
         result = subprocess.run(
-            ["/opt/aitbc/aitbc-cli", "market", "list"],
+            [str(CLI_BIN), "market", "list"],
             capture_output=True,
             text=True
         )