```

chore: remove obsolete files and add Solidity build artifacts to .gitignore

- Add ignore patterns for Solidity build artifacts (typechain-types, artifacts, cache)
- Remove unused exchange mock API server (api/exchange_mock_api.py)
- Remove obsolete client-web README placeholder
- Remove deprecated marketplace-ui HTML implementation
```

docs/.github/workflows/deploy-docs.yml

@@ -1,115 +0,0 @@
-name: Deploy Documentation
-
-on:
-  push:
-    branches: [ main, develop ]
-    paths: [ 'docs/**' ]
-  pull_request:
-    branches: [ main ]
-    paths: [ 'docs/**' ]
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: "pages"
-  cancel-in-progress: false
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.11'
-
-      - name: Install dependencies
-        run: |
-          pip install -r docs/requirements.txt
-
-      - name: Generate OpenAPI specs
-        run: |
-          cd docs
-          python scripts/generate_openapi.py
-
-      - name: Build documentation
-        run: |
-          cd docs
-          mkdocs build --strict
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v2
-        with:
-          path: docs/site
-
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    if: github.ref == 'refs/heads/main'
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v2
-
-  # Deploy to staging for develop branch
-  deploy-staging:
-    runs-on: ubuntu-latest
-    needs: build
-    if: github.ref == 'refs/heads/develop'
-    steps:
-      - name: Deploy to Staging
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/site
-          destination_dir: staging
-          user_name: github-actions[bot]
-          user_email: github-actions[bot]@users.noreply.github.com
-
-  # Deploy to production S3
-  deploy-production:
-    runs-on: ubuntu-latest
-    needs: build
-    if: github.ref == 'refs/heads/main'
-    environment: production
-    steps:
-      - name: Configure AWS Credentials
-        uses: aws-actions/configure-aws-credentials@v2
-        with:
-          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
-          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-          aws-region: us-east-1
-
-      - name: Deploy to S3
-        run: |
-          aws s3 sync docs/site/ s3://docs.aitbc.io/ --delete
-          aws cloudfront create-invalidation --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} --paths "/*"
-
-  # Notify on deployment
-  notify:
-    runs-on: ubuntu-latest
-    needs: [deploy, deploy-production]
-    if: always()
-    steps:
-      - name: Notify Discord
-        uses: rjstone/discord-webhook-notify@v1
-        with:
-          severity: info
-          text: "Documentation deployment completed"
-          description: |
-            Build: ${{ needs.build.result }}
-            Deploy: ${{ needs.deploy.result }}
-            Production: ${{ needs.deploy-production.result }}
-          webhookUrl: ${{ secrets.DISCORD_WEBHOOK }}

docs/.pages

@@ -1,87 +0,0 @@
-# .pages configuration for awesome-pages plugin
-
-home: index.md
-format: standard
-ordering:
-  asc: title
-
-sections:
-  - title: Getting Started
-    icon: material/rocket-launch
-    children:
-      - getting-started/introduction.md
-      - getting-started/quickstart.md
-      - getting-started/installation.md
-      - getting-started/architecture.md
-  
-  - title: User Guide
-    icon: material/account-group
-    children:
-      - user-guide/overview.md
-      - user-guide/creating-jobs.md
-      - user-guide/marketplace.md
-      - user-guide/explorer.md
-      - user-guide/wallet-management.md
-  
-  - title: Developer Guide
-    icon: material/code-tags
-    children:
-      - developer-guide/overview.md
-      - developer-guide/setup.md
-      - developer-guide/api-authentication.md
-      - title: SDKs
-        icon: material/package-variant
-        children:
-          - developer-guide/sdks/python.md
-          - developer-guide/sdks/javascript.md
-      - developer-guide/examples.md
-      - developer-guide/contributing.md
-  
-  - title: API Reference
-    icon: material/api
-    children:
-      - title: Coordinator API
-        icon: material/server
-        children:
-          - api/coordinator/overview.md
-          - api/coordinator/authentication.md
-          - api/coordinator/endpoints.md
-          - api/coordinator/openapi.md
-      - title: Blockchain Node API
-        icon: material/link-variant
-        children:
-          - api/blockchain/overview.md
-          - api/blockchain/websocket.md
-          - api/blockchain/jsonrpc.md
-          - api/blockchain/openapi.md
-      - title: Wallet Daemon API
-        icon: material/wallet
-        children:
-          - api/wallet/overview.md
-          - api/wallet/endpoints.md
-          - api/wallet/openapi.md
-  
-  - title: Operations
-    icon: material/cog
-    children:
-      - operations/deployment.md
-      - operations/monitoring.md
-      - operations/security.md
-      - operations/backup-restore.md
-      - operations/troubleshooting.md
-  
-  - title: Tutorials
-    icon: material/school
-    children:
-      - tutorials/building-dapp.md
-      - tutorials/mining-setup.md
-      - tutorials/running-node.md
-      - tutorials/integration-examples.md
-  
-  - title: Resources
-    icon: material/information
-    children:
-      - resources/glossary.md
-      - resources/faq.md
-      - resources/support.md
-      - resources/changelog.md

docs/done.md

@@ -219,7 +219,7 @@ This document tracks components that have been successfully deployed and are ope
   - Documented common issues, troubleshooting, and performance metrics
 
 - ✅ **Documentation Updates**
-  - Updated `docs/localhost-testing-scenario.md` with CLI wrapper usage
+  - Updated `docs/developer/testing/localhost-testing-scenario.md` with CLI wrapper usage
   - Converted all examples to use localhost URLs (127.0.0.1) instead of production
   - Added host user paths and quick start commands
   - Documented complete testing workflow from setup to verification
@@ -268,3 +268,31 @@ This document tracks components that have been successfully deployed and are ope
 - ✅ **Comprehensive .gitignore**
   - Expanded from 39 to 145 lines with organized sections
   - Added project-specific rules for coordinator, explorer, GPU miner
+
+### Repository File Audit & Cleanup
+- ✅ **File Audit Document** (`docs/files.md`)
+  - Created comprehensive audit of all 849 repository files
+  - Categorized into Whitelist (60), Greylist (0), Placeholders (12), Removed (35)
+  - All greylist items resolved - no pending reviews
+
+- ✅ **Abandoned Folders Removed** (35 items total)
+  - `ecosystem*/` (4 folders), `enterprise-connectors/`, `research/`
+  - `apps/client-web/`, `apps/marketplace-ui/`, `apps/wallet-cli/`
+  - `apps/miner-node/`, `apps/miner-dashboard/`
+  - `packages/py/aitbc-core/`, `aitbc-p2p/`, `aitbc-scheduler/`
+  - `packages/js/ui-widgets/`
+  - `python-sdk/`, `windsurf/`, `configs/`, `docs/user-guide/`, `docs/bootstrap/`
+  - `api/`, `governance/`, `protocols/`
+  - 5 GPU miner variants, 3 extension variants
+
+- ✅ **Docs Folder Reorganization**
+  - Root now contains only: `done.md`, `files.md`, `roadmap.md`
+  - Created new subfolders: `_config/`, `reference/components/`, `reference/governance/`
+  - Created: `operator/deployment/`, `operator/migration/`
+  - Created: `developer/testing/`, `developer/integration/`
+  - Moved 25 files to appropriate subfolders
+  - Moved receipt spec: `protocols/receipts/spec.md` → `docs/reference/specs/receipt-spec.md`
+
+- ✅ **Roadmap Updates**
+  - Added Stage 19: Placeholder Content Development
+  - Added Stage 20: Technical Debt Remediation (blockchain-node, solidity-token, ZKReceiptVerifier)

docs/files.md

@@ -0,0 +1,317 @@
+# AITBC Repository File Audit
+
+This document categorizes all files and folders in the repository by their status:
+- **Whitelist (✅)**: Active, up-to-date, essential
+- **Greylist (⚠️)**: Uncertain status, may need review
+- **Blacklist (❌)**: Legacy, unused, outdated, candidates for removal
+
+Last updated: 2026-01-24
+
+---
+
+## Whitelist ✅ (Active & Essential)
+
+### Core Applications (`apps/`)
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `apps/coordinator-api/` | ✅ Active | Main API service, recently updated (Jan 2026) |
+| `apps/explorer-web/` | ✅ Active | Blockchain explorer, recently updated |
+| `apps/wallet-daemon/` | ✅ Active | Wallet service, deployed in production |
+| `apps/trade-exchange/` | ✅ Active | Bitcoin exchange, deployed |
+| `apps/zk-circuits/` | ✅ Active | ZK proof circuits, deployed |
+| `apps/marketplace-web/` | ✅ Active | Marketplace frontend, deployed |
+
+### Scripts (`scripts/`)
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `scripts/aitbc-cli.sh` | ✅ Active | Main CLI tool, heavily used |
+| `scripts/gpu/gpu_miner_host.py` | ✅ Active | Production GPU miner |
+| `scripts/gpu/gpu_miner_host_wrapper.sh` | ✅ Active | Systemd wrapper |
+| `scripts/deploy/` | ✅ Active | Deployment scripts |
+| `scripts/service/` | ✅ Active | Service management |
+| `scripts/dev_services.sh` | ✅ Active | Local development |
+
+### Infrastructure (`infra/`, `systemd/`)
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `infra/nginx/` | ✅ Active | Production nginx configs |
+| `systemd/aitbc-host-gpu-miner.service` | ✅ Active | Production service |
+| `systemd/coordinator-api.service` | ✅ Active | Production service |
+
+### Website (`website/`)
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `website/docs/` | ✅ Active | HTML documentation, recently refactored |
+| `website/docs/css/docs.css` | ✅ Active | Shared CSS (1232 lines) |
+| `website/docs/js/theme.js` | ✅ Active | Theme toggle |
+| `website/index.html` | ✅ Active | Main website |
+| `website/dashboards/` | ✅ Active | Admin/miner dashboards |
+
+### Documentation (`docs/`)
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `docs/done.md` | ✅ Active | Completion tracking |
+| `docs/roadmap.md` | ✅ Active | Development roadmap |
+| `docs/developer/testing/localhost-testing-scenario.md` | ✅ Active | Testing guide |
+| `docs/reference/components/miner_node.md` | ✅ Active | Miner documentation |
+| `docs/reference/components/coordinator_api.md` | ✅ Active | API documentation |
+| `docs/developer/integration/skills-framework.md` | ✅ Active | Skills documentation |
+
+### Cascade Skills (`.windsurf/`)
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `.windsurf/skills/blockchain-operations/` | ✅ Active | Node management skill |
+| `.windsurf/skills/deploy-production/` | ✅ Active | Deployment skill |
+| `.windsurf/workflows/` | ✅ Active | Workflow definitions |
+
+### CLI Tools (`cli/`)
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `cli/client.py` | ✅ Active | Client CLI |
+| `cli/miner.py` | ✅ Active | Miner CLI |
+| `cli/wallet.py` | ✅ Active | Wallet CLI |
+| `cli/test_ollama_gpu_provider.py` | ✅ Active | GPU testing |
+
+### Home Scripts (`home/`)
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `home/client/` | ✅ Active | Client test scripts |
+| `home/miner/` | ✅ Active | Miner test scripts |
+| `home/quick_job.py` | ✅ Active | Quick job submission |
+| `home/simple_job_flow.py` | ✅ Active | Job flow testing |
+
+### Plugins (`plugins/`)
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `plugins/ollama/` | ✅ Active | Ollama integration |
+
+### Root Files
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `README.md` | ✅ Active | Project readme |
+| `LICENSE` | ✅ Active | License file |
+| `.gitignore` | ✅ Active | Recently updated (145 lines) |
+| `pyproject.toml` | ✅ Active | Python project config |
+| `.editorconfig` | ✅ Active | Editor config |
+
+---
+
+## Greylist ⚠️ (Needs Review)
+
+### Applications - Uncertain Status
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `apps/blockchain-node/` | 📋 Planned | Has code, SQLModel issues - see roadmap Stage 20 |
+
+### Packages
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `packages/solidity/aitbc-token/` | 📋 Planned | Smart contracts, deployment planned - see roadmap Stage 20 |
+
+### Scripts
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `scripts/test/` | ✅ Keep | 7 test scripts, all current (Jan 2026) |
+
+### Documentation
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `docs/developer/` | ✅ Keep | 6 markdown files |
+| `docs/operator/` | ✅ Keep | 5 markdown files |
+| `docs/user/` | ✅ Keep | 1 markdown file |
+| `docs/tutorials/` | ✅ Keep | 3 markdown files |
+
+### Infrastructure
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `infra/k8s/` | ✅ Keep | 5 yaml files (backup, cert-manager, netpol, sealed-secrets) |
+
+### Extensions
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `extensions/aitbc-wallet-firefox/` | ✅ Keep | Firefox extension source (7 files) |
+| `extensions/aitbc-wallet-firefox-v1.0.5.xpi` | ✅ Keep | Built extension package |
+
+### Other
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `contracts/ZKReceiptVerifier.sol` | 📋 Planned | ZK verifier contract - see roadmap Stage 20 |
+| `docs/reference/specs/receipt-spec.md` | ✅ Keep | Canonical receipt schema (moved from protocols/) |
+
+---
+
+## Future Placeholders 📋 (Keep - Will Be Populated)
+
+These empty folders are intentional scaffolding for planned future work per the roadmap.
+
+| Path | Status | Roadmap Stage |
+|------|--------|---------------|
+| `docs/user/guides/` | 📋 Placeholder | Stage 5 - Documentation |
+| `docs/developer/tutorials/` | 📋 Placeholder | Stage 5 - Documentation |
+| `docs/reference/specs/` | 📋 Placeholder | Stage 5 - Documentation |
+| `infra/terraform/environments/staging/` | 📋 Placeholder | Stage 5 - Infrastructure |
+| `infra/terraform/environments/prod/` | 📋 Placeholder | Stage 5 - Infrastructure |
+| `infra/helm/values/dev/` | 📋 Placeholder | Stage 5 - Infrastructure |
+| `infra/helm/values/staging/` | 📋 Placeholder | Stage 5 - Infrastructure |
+| `infra/helm/values/prod/` | 📋 Placeholder | Stage 5 - Infrastructure |
+| `apps/coordinator-api/migrations/` | 📋 Placeholder | Alembic migrations |
+| `apps/pool-hub/src/app/routers/` | 📋 Placeholder | Stage 3 - Pool Hub |
+| `apps/pool-hub/src/app/registry/` | 📋 Placeholder | Stage 3 - Pool Hub |
+| `apps/pool-hub/src/app/scoring/` | 📋 Placeholder | Stage 3 - Pool Hub |
+
+---
+
+## Blacklist ❌ (Abandoned - Remove)
+
+### Abandoned Empty Folders (Created but never used)
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `apps/client-web/src/` | ❌ Remove | Created Sep 2025, never implemented |
+| `apps/client-web/public/` | ❌ Remove | Created Sep 2025, never implemented |
+| `apps/marketplace-ui/` | ❌ Remove | Superseded by `marketplace-web` |
+| `apps/wallet-cli/` | ❌ Remove | Superseded by `cli/wallet.py` |
+| `packages/py/aitbc-core/src/` | ❌ Remove | Created Sep 2025, never implemented |
+| `packages/py/aitbc-p2p/src/` | ❌ Remove | Created Sep 2025, never implemented |
+| `packages/py/aitbc-scheduler/src/` | ❌ Remove | Created Sep 2025, never implemented |
+| `packages/js/ui-widgets/src/` | ❌ Remove | Created Sep 2025, never implemented |
+| `protocols/api/` | ❌ Remove | Never implemented |
+| `protocols/payouts/` | ❌ Remove | Never implemented |
+| `data/fixtures/` | ❌ Remove | Never populated |
+| `data/samples/` | ❌ Remove | Never populated |
+| `tools/mkdiagram/` | ❌ Remove | Never implemented |
+| `examples/quickstart-client-python/` | ❌ Remove | Never implemented |
+| `examples/quickstart-client-js/node/` | ❌ Remove | Never implemented |
+| `examples/quickstart-client-js/browser/` | ❌ Remove | Never implemented |
+| `examples/receipts-sign-verify/python/` | ❌ Remove | Never implemented |
+| `examples/receipts-sign-verify/js/` | ❌ Remove | Never implemented |
+| `scripts/env/` | ❌ Remove | Never populated |
+| `windsurf/prompts/` | ❌ Remove | Superseded by `.windsurf/` |
+| `windsurf/tasks/` | ❌ Remove | Superseded by `.windsurf/` |
+
+### Duplicate/Redundant Folders
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `python-sdk/` | ❌ Duplicate | Duplicates `packages/py/aitbc-sdk/` |
+| `windsurf/` | ❌ Duplicate | Superseded by `.windsurf/` |
+| `configs/` | ❌ Duplicate | Empty subfolders, duplicates `infra/` and `systemd/` |
+| `docs/user-guide/` | ❌ Duplicate | Duplicates `docs/user/` |
+
+### Ecosystem Folders (Scaffolded but Unused)
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `ecosystem/` | ❌ Unused | Only has empty `academic/` subfolder |
+| `ecosystem-analytics/` | ❌ Unused | Scaffolded Dec 2025, never used |
+| `ecosystem-certification/` | ❌ Unused | Scaffolded Dec 2025, never used |
+| `ecosystem-extensions/` | ❌ Unused | Only has template folder |
+| `enterprise-connectors/` | ❌ Unused | Scaffolded Dec 2025, never used |
+
+### Research Folders (Scaffolded but Unused)
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `research/autonomous-agents/` | ❌ Unused | Scaffolded, no active work |
+| `research/consortium/` | ❌ Unused | Scaffolded, no active work |
+| `research/prototypes/` | ❌ Unused | Scaffolded, no active work |
+| `research/standards/` | ❌ Unused | Scaffolded, no active work |
+
+### Generated/Build Artifacts (Should be in .gitignore)
+
+| Path | Status | Notes |
+|------|--------|-------|
+| `packages/solidity/aitbc-token/typechain-types/` | ❌ Generated | Build artifact |
+| `apps/explorer-web/dist/` | ❌ Generated | Build artifact |
+| `logs/` | ❌ Generated | Runtime logs |
+
+---
+
+## Summary Statistics
+
+| Category | Count | Action |
+|----------|-------|--------|
+| **Whitelist ✅** | ~60 items | Keep and maintain |
+| **Greylist ⚠️** | 0 items | All resolved! |
+| **Placeholders 📋** | 12 folders | Fill per roadmap Stage 19 |
+| **Removed ❌** | 35 items | Cleaned up 2026-01-24 |
+
+### Completed Actions (2026-01-24)
+
+1. **Cleanup Done**:
+   - ✅ Removed 21 abandoned/duplicate folders
+   - ✅ Updated `.gitignore` with comprehensive rules
+   - ✅ Created this audit document
+
+2. **Additional Cleanup (2026-01-24)**:
+   - ✅ Removed `apps/miner-node/` (superseded by `scripts/gpu/`)
+   - ✅ Removed `apps/miner-dashboard/` (superseded by `website/dashboards/`)
+   - ✅ Removed `docs/bootstrap/` (empty)
+   - ✅ Removed 5 GPU miner variants (kept only `gpu_miner_host.py`)
+   - ✅ Removed 3 extension variants (kept only `aitbc-wallet-firefox/`)
+
+3. **Final Cleanup (2026-01-24)**:
+   - ✅ Removed `api/` folder (mock no longer needed - using live production)
+   - ✅ Removed `governance/` folder (too far in future)
+   - ✅ Removed `protocols/` folder (spec moved to docs/reference/specs/)
+   - ✅ Moved `protocols/receipts/spec.md` → `docs/reference/specs/receipt-spec.md`
+   - ✅ Added ZKReceiptVerifier and receipt spec to roadmap Stage 20
+
+4. **Placeholder Plan** (see `roadmap.md` Stage 19):
+   - Q1 2026: Documentation folders (`docs/user/guides/`, `docs/developer/tutorials/`, `docs/reference/specs/`)
+   - Q2 2026: Infrastructure (`infra/terraform/`, `infra/helm/`)
+   - Q2 2026: Pool Hub components
+
+---
+
+## Folder Structure Recommendation
+
+```
+aitbc/
+├── apps/                    # Core applications
+│   ├── coordinator-api/     # ✅ Keep
+│   ├── explorer-web/        # ✅ Keep
+│   ├── marketplace-web/     # ✅ Keep
+│   ├── wallet-daemon/       # ✅ Keep
+│   └── zk-circuits/         # ✅ Keep
+├── cli/                     # ✅ CLI tools
+├── docs/                    # ✅ Markdown documentation
+├── infra/                   # ✅ Infrastructure configs
+├── packages/                # ✅ Keep (aitbc-crypto, aitbc-sdk, aitbc-token)
+├── plugins/                 # ✅ Keep (ollama)
+├── scripts/                 # ✅ Keep - organized
+├── systemd/                 # ✅ Keep
+├── tests/                   # ✅ Keep (e2e, integration, unit, security, load)
+├── website/                 # ✅ Keep
+└── .windsurf/               # ✅ Keep
+```
+
+**Folders Removed (2026-01-24)**:
+- ✅ `ecosystem*/` (all 4 folders) - removed
+- ✅ `enterprise-connectors/` - removed
+- ✅ `research/` - removed
+- ✅ `python-sdk/` - removed (duplicate)
+- ✅ `windsurf/` - removed (duplicate of `.windsurf/`)
+- ✅ `configs/` - removed (duplicated `infra/`)
+- ✅ Empty `apps/` subfolders - removed (client-web, marketplace-ui, wallet-cli)
+- ✅ Empty `packages/` subfolders - removed (aitbc-core, aitbc-p2p, aitbc-scheduler, ui-widgets)
+- ✅ Empty `examples/` subfolders - removed
+- ✅ `tools/` - removed (empty)
+- ✅ `docs/user-guide/` - removed (duplicate)

docs/mkdocs.yml

@@ -1,204 +0,0 @@
-site_name: AITBC Documentation
-site_description: AI Trusted Blockchain Computing Platform Documentation
-site_author: AITBC Team
-site_url: https://docs.aitbc.io
-
-# Repository
-repo_name: aitbc/docs
-repo_url: https://github.com/aitbc/docs
-edit_uri: edit/main/docs/
-
-# Copyright
-copyright: Copyright © 2024 AITBC Team
-
-# Configuration
-theme:
-  name: material
-  language: en
-  features:
-    - announce.dismiss
-    - content.action.edit
-    - content.action.view
-    - content.code.annotate
-    - content.code.copy
-    - content.tabs.link
-    - content.tooltips
-    - header.autohide
-    - navigation.expand
-    - navigation.footer
-    - navigation.indexes
-    - navigation.instant
-    - navigation.instant.prefetch
-    - navigation.instant.progress
-    - navigation.instant.scroll
-    - navigation.prune
-    - navigation.sections
-    - navigation.tabs
-    - navigation.tabs.sticky
-    - navigation.top
-    - navigation.tracking
-    - search.highlight
-    - search.share
-    - search.suggest
-    - toc.follow
-    - toc.integrate
-  palette:
-    - scheme: default
-      primary: blue
-      accent: blue
-      toggle:
-        icon: material/brightness-7
-        name: Switch to dark mode
-    - scheme: slate
-      primary: blue
-      accent: blue
-      toggle:
-        icon: material/brightness-4
-        name: Switch to light mode
-  font:
-    text: Roboto
-    code: Roboto Mono
-  favicon: assets/favicon.png
-  logo: assets/logo.png
-
-# Plugins
-plugins:
-  - search:
-      separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
-  - minify:
-      minify_html: true
-  - git-revision-date-localized:
-      enable_creation_date: true
-      type: datetime
-      timezone: UTC
-  - awesome-pages
-  - glightbox
-  - mkdocs-video
-  - social:
-      cards_layout_options:
-        font_family: Roboto
-
-# Customization
-extra:
-  analytics:
-    provider: google
-    property: !ENV GOOGLE_ANALYTICS_KEY
-  social:
-    - icon: fontawesome/brands/github
-      link: https://github.com/aitbc
-    - icon: fontawesome/brands/twitter
-      link: https://twitter.com/aitbc
-    - icon: fontawesome/brands/discord
-      link: https://discord.gg/aitbc
-  version:
-    provider: mike
-    default: stable
-  generator: false
-
-# Extensions
-markdown_extensions:
-  - abbr
-  - admonition
-  - attr_list
-  - def_list
-  - footnotes
-  - md_in_html
-  - toc:
-      permalink: true
-  - pymdownx.arithmatex:
-      generic: true
-  - pymdownx.betterem:
-      smart_enable: all
-  - pymdownx.caret
-  - pymdownx.details
-  - pymdownx.emoji:
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-  - pymdownx.highlight:
-      anchor_linenums: true
-      line_spans: __span
-      pygments_lang_class: true
-  - pymdownx.inlinehilite
-  - pymdownx.keys
-  - pymdownx.magiclink:
-      repo_url_shorthand: true
-      user: aitbc
-      repo: docs
-  - pymdownx.mark
-  - pymdownx.smartsymbols
-  - pymdownx.superfences:
-      custom_fences:
-        - name: mermaid
-          class: mermaid
-          format: !!python/name:pymdownx.superfences.fence_code_format
-  - pymdownx.tabbed:
-      alternate_style: true
-  - pymdownx.tasklist:
-      custom_checkbox: true
-  - pymdownx.tilde
-
-# Navigation
-nav:
-  - Home: index.md
-  - Getting Started:
-    - Introduction: getting-started/introduction.md
-    - Quickstart: getting-started/quickstart.md
-    - Installation: getting-started/installation.md
-    - Architecture: getting-started/architecture.md
-  - User Guide:
-    - Overview: user-guide/overview.md
-    - Trade Exchange: trade_exchange.md
-    - Zero-Knowledge Applications: zk-applications.md
-    - Creating Jobs: user-guide/creating-jobs.md
-    - Marketplace: user-guide/marketplace.md
-    - Explorer: user-guide/explorer.md
-    - Wallet Management: user-guide/wallet-management.md
-  - Developer Guide:
-    - Overview: developer-guide/overview.md
-    - Setup: developer-guide/setup.md
-    - API Authentication: developer-guide/api-authentication.md
-    - SDKs:
-      - Python SDK: developer-guide/sdks/python.md
-      - JavaScript SDK: developer-guide/sdks/javascript.md
-    - Examples: developer-guide/examples.md
-    - Contributing: developer-guide/contributing.md
-  - API Reference:
-    - Coordinator API:
-      - Overview: api/coordinator/overview.md
-      - Authentication: api/coordinator/authentication.md
-      - Endpoints: api/coordinator/endpoints.md
-      - OpenAPI Spec: api/coordinator/openapi.md
-    - ZK Applications API:
-      - Overview: api/zk/overview.md
-      - Endpoints: api/zk/endpoints.md
-      - Circuits: api/zk/circuits.md
-      - OpenAPI Spec: api/zk/openapi.md
-    - Blockchain Node API:
-      - Overview: api/blockchain/overview.md
-      - WebSocket API: api/blockchain/websocket.md
-      - JSON-RPC API: api/blockchain/jsonrpc.md
-      - OpenAPI Spec: api/blockchain/openapi.md
-    - Wallet Daemon API:
-      - Overview: api/wallet/overview.md
-      - Endpoints: api/wallet/endpoints.md
-      - OpenAPI Spec: api/wallet/openapi.md
-  - Operations:
-    - Deployment: operations/deployment.md
-    - Monitoring: operations/monitoring.md
-    - Security: operations/security.md
-    - Backup & Restore: operations/backup-restore.md
-    - Troubleshooting: operations/troubleshooting.md
-  - Tutorials:
-    - Building a DApp: tutorials/building-dapp.md
-    - Mining Setup: tutorials/mining-setup.md
-    - Running a Node: tutorials/running-node.md
-    - Integration Examples: tutorials/integration-examples.md
-  - Resources:
-    - Glossary: resources/glossary.md
-    - FAQ: resources/faq.md
-    - Support: resources/support.md
-    - Changelog: resources/changelog.md
-
-# Page tree
-plugins:
-  - awesome-pages

docs/reference/done.md

@@ -1,205 +0,0 @@
-# Completed Bootstrap Tasks
-
-## Repository Initialization
-
-- Scaffolded core monorepo directories reflected in `docs/bootstrap/dirs.md`.
-- Added top-level config files: `.editorconfig`, `.gitignore`, `LICENSE`, and root `README.md`.
-- Created Windsurf workspace metadata under `windsurf/`.
-
-## Documentation
-
-- Authored `docs/roadmap.md` capturing staged development targets.
-- Added README placeholders for primary apps under `apps/` to outline purpose and setup notes.
-
-## Coordinator API
-
-- Implemented SQLModel-backed job persistence and service layer in `apps/coordinator-api/src/app/`.
-- Wired client, miner, and admin routers to coordinator services (job lifecycle, scheduling, stats).
-- Added initial pytest coverage under `apps/coordinator-api/tests/test_jobs.py`.
-- Added signed receipt generation, persistence (`Job.receipt`, `JobReceipt` history table), retrieval endpoints, telemetry metrics, and optional coordinator attestations.
-- Persisted historical receipts via `JobReceipt`; exposed `/v1/jobs/{job_id}/receipts` endpoint and integrated canonical serialization.
-- Documented receipt attestation configuration (`RECEIPT_ATTESTATION_KEY_HEX`) in `docs/run.md` and coordinator README.
-
-## Miner Node
-
-- Created coordinator client, control loop, and capability/backoff utilities in `apps/miner-node/src/aitbc_miner/`.
-- Implemented CLI/Python runners and execution pipeline with result reporting.
-- Added starter tests for runners in `apps/miner-node/tests/test_runners.py`.
-
-## Blockchain Node
-
-- Added websocket fan-out, disconnect cleanup, and load-test coverage in `apps/blockchain-node/tests/test_websocket.py`, ensuring gossip topics deliver reliably to multiple subscribers.
-
-## Directory Preparation
-
-- Established scaffolds for Python and JavaScript packages in `packages/py/` and `packages/js/`.
-- Seeded example project directories under `examples/` for quickstart clients and receipt verification.
-- Added `examples/receipts-sign-verify/fetch_and_verify.py` demonstrating coordinator receipt fetching + verification using Python SDK.
-
-## Python SDK
-
-- Created `packages/py/aitbc-sdk/` with coordinator receipt client and verification helpers consuming `aitbc_crypto` utilities.
-- Added pytest coverage under `packages/py/aitbc-sdk/tests/test_receipts.py` validating miner/coordinator signature checks and client behavior.
-
-## Wallet Daemon
-
-- Added `apps/wallet-daemon/src/app/receipts/service.py` providing `ReceiptVerifierService` that fetches and validates receipts via `aitbc_sdk`.
-- Created unit tests under `apps/wallet-daemon/tests/test_receipts.py` verifying service behavior.
-- Implemented wallet SDK receipt ingestion + attestation surfacing in `packages/py/aitbc-sdk/src/receipts.py`, including pagination client, signature verification, and failure diagnostics with full pytest coverage.
-- Hardened REST API by wiring dependency overrides in `apps/wallet-daemon/tests/test_wallet_api.py`, expanding workflow coverage (create/list/unlock/sign) and enforcing structured password policy errors consumed in CI.
-
-## Explorer Web
-
-- Initialized a Vite + TypeScript scaffold in `apps/explorer-web/` with `vite.config.ts`, `tsconfig.json`, and placeholder `src/main.ts` content.
-- Installed frontend dependencies locally to unblock editor tooling and TypeScript type resolution.
-- Implemented `overview` page stats rendering backed by mock block/transaction/receipt fetchers, including robust empty-state handling and TypeScript type fixes.
-
-## Pool Hub
-
-- Implemented FastAPI service scaffolding with Redis/PostgreSQL-backed repositories, match/health/metrics endpoints, and Prometheus instrumentation (`apps/pool-hub/src/poolhub/`).
-- Added Alembic migrations (`apps/pool-hub/migrations/`) and async integration tests covering repositories and endpoints (`apps/pool-hub/tests/`).
-
-## Solidity Token
-
-- Implemented attested minting logic in `packages/solidity/aitbc-token/contracts/AIToken.sol` using `AccessControl` role gates and ECDSA signature recovery.
-- Added Hardhat unit tests in `packages/solidity/aitbc-token/test/aitoken.test.ts` covering successful minting, replay prevention, and invalid attestor signatures.
-- Configured project TypeScript settings via `packages/solidity/aitbc-token/tsconfig.json` to align Hardhat, Node, and Mocha typings for the contract test suite.
-
-## JavaScript SDK
-
-- Delivered fetch-based client wrapper with TypeScript definitions and Vitest coverage under `packages/js/aitbc-sdk/`.
-
-## Blockchain Node Enhancements
-
-- Added comprehensive WebSocket tests for blocks and transactions streams including multi-subscriber and high-volume scenarios.
-- Extended PoA consensus with per-proposer block metrics and rotation tracking.
-- Added latest block interval gauge and RPC error spike alerting.
-- Enhanced observability with Grafana dashboards for blockchain node and coordinator overview.
-- Implemented marketplace endpoints in coordinator API with explorer and marketplace routers.
-- Added mock coordinator integration with enhanced telemetry capabilities.
-- Created comprehensive observability documentation and alerting rules.
-
-## Explorer Web Production Readiness
-
-- Implemented Playwright end-to-end tests for live mode functionality.
-- Enhanced responsive design with improved CSS layout system.
-- Added comprehensive error handling and fallback mechanisms for live API responses.
-- Integrated live coordinator endpoints with proper data reconciliation.
-
-## Marketplace Web Launch
-
-- Completed auth/session scaffolding for marketplace actions.
-- Implemented API abstraction layer with mock/live mode toggle.
-- Connected mock listings and bids to coordinator data sources.
-- Added feature flags for controlled live mode rollout.
-
-## Cross-Chain Settlement
-
-- Implemented cross-chain settlement hooks with external bridges.
-- Created BridgeAdapter interface for LayerZero integration.
-- Implemented BridgeManager for orchestration and retry logic.
-- Added settlement storage and API endpoints.
-- Created cross-chain settlement documentation.
-
-## Python SDK Transport Abstraction
-
-- Designed pluggable transport abstraction layer for multi-network support.
-- Implemented base Transport interface with HTTP/WebSocket transports.
-- Created MultiNetworkClient for managing multiple blockchain networks.
-- Updated AITBCClient to use transport abstraction with backward compatibility.
-- Added transport documentation and examples.
-
-## GPU Service Provider Configuration
-
-- Extended Miner model to include service configurations.
-- Created service configuration API endpoints in pool-hub.
-- Built HTML/JS UI for service provider configuration.
-- Added service pricing configuration and capability validation.
-- Implemented service selection for GPU providers.
-
-## GPU Service Expansion
-
-- Implemented dynamic service registry framework for 30+ GPU services.
-- Created service definitions for 6 categories: AI/ML, Media Processing, Scientific Computing, Data Analytics, Gaming, Development Tools.
-- Built comprehensive service registry API with validation and discovery.
-- Added hardware requirement checking and pricing models.
-- Updated roadmap with service expansion phase documentation.
-
-## Stage 7 - GPU Service Expansion & Privacy Features 
-
-### GPU Service Infrastructure
-- Create dynamic service registry with JSON schema validation
-- Implement service provider configuration UI with dynamic service selection
-- Create service definitions for AI/ML (LLM inference, image/video generation, speech recognition, computer vision, recommendation systems)
-- Create service definitions for Media Processing (video transcoding, streaming, 3D rendering, image/audio processing)
-- Create service definitions for Scientific Computing (molecular dynamics, weather modeling, financial modeling, physics simulation, bioinformatics)
-- Create service definitions for Data Analytics (big data processing, real-time analytics, graph analytics, time series analysis)
-- Create service definitions for Gaming & Entertainment (cloud gaming, asset baking, physics simulation, VR/AR rendering)
-- Create service definitions for Development Tools (GPU compilation, model training, data processing, simulation testing, code generation)
-- Implement service-specific validation and hardware requirement checking
-
-### Privacy & Cryptography Features
-- ✅ Research zk-proof-based receipt attestation and prototype a privacy-preserving settlement flow
-- ✅ Implement Groth16 ZK circuit for receipt hash preimage proofs
-- ✅ Create ZK proof generation service in coordinator API
-- ✅ Implement on-chain verification contract (ZKReceiptVerifier.sol)
-- ✅ Add confidential transaction support with opt-in ciphertext storage
-- ✅ Implement HSM-backed key management (Azure Key Vault, AWS KMS, Software)
-- ✅ Create hybrid encryption system (AES-256-GCM + X25519)
-- ✅ Implement role-based access control with time restrictions
-- ✅ Create tamper-evident audit logging with chain of hashes
-- ✅ Publish comprehensive threat modeling with STRIDE analysis
-- ✅ Update cross-chain settlement hooks for ZK proofs and privacy levels
-
-### Enterprise Integration Features
-- ✅ Deliver reference connectors for ERP/payment systems with Python SDK
-- ✅ Implement Stripe payment connector with full charge/refund/subscription support
-- ✅ Create enterprise-grade Python SDK with async support, dependency injection, metrics
-- ✅ Build ERP connector base classes with plugin architecture for protocols
-- ✅ Document comprehensive SLAs with uptime guarantees and support commitments
-- ✅ Stand up multi-tenant coordinator infrastructure with per-tenant isolation
-- ✅ Implement tenant management service with lifecycle operations
-- ✅ Create tenant context middleware for automatic tenant identification
-- ✅ Build resource quota enforcement with Redis-backed caching
-- ✅ Create usage tracking and billing metrics with tiered pricing
-- ✅ Launch ecosystem certification program with SDK conformance testing
-- ✅ Define Bronze/Silver/Gold certification tiers with clear requirements
-- ✅ Build language-agnostic test suite with OpenAPI contract validation
-- ✅ Implement security validation framework with dependency scanning
-- ✅ Design public registry API for partner/SDK discovery
-- ✅ Validate certification system with Stripe connector certification
-
-### Community & Governance Features
-- ✅ Establish open RFC process with clear stages and review criteria
-- ✅ Create governance website with documentation and navigation
-- ✅ Set up community call schedule with multiple call types
-- ✅ Design RFC template and GitHub PR template for submissions
-- ✅ Implement benevolent dictator model with sunset clause
-- ✅ Create hybrid governance structure (GitHub + Discord + Website)
-- ✅ Document participation guidelines and code of conduct
-- ✅ Establish transparency and accountability processes
-
-### Ecosystem Growth Initiatives
-- ✅ Create hackathon organization framework with quarterly themes and bounty board
-- ✅ Design grant program with hybrid approach (micro-grants + strategic grants)
-- ✅ Build marketplace extension SDK with cookiecutter templates
-- ✅ Create analytics tooling for ecosystem metrics and KPI tracking
-- ✅ Track ecosystem KPIs (active marketplaces, cross-chain volume) and feed them into quarterly strategy reviews
-- ✅ Establish judging criteria with ecosystem impact weighting
-- ✅ Create sponsor partnership framework with tiered benefits
-- ✅ Design retroactive grants for proven projects
-- ✅ Implement milestone-based disbursement for accountability
-
-### Stage 8 - Frontier R&D & Global Expansion
-- ✅ Launch research consortium framework with governance model and membership tiers
-- ✅ Develop hybrid PoA/PoS consensus research plan with 12-month implementation timeline
-- ✅ Create scaling research plan for sharding and rollups (100K+ TPS target)
-- ✅ Design ZK applications research plan for privacy-preserving AI
-- ✅ Create governance research plan with liquid democracy and AI assistance
-- ✅ Develop economic models research plan with sustainable tokenomics
-- ✅ Implement hybrid consensus prototype demonstrating dynamic mode switching
-- ✅ Create executive summary for consortium recruitment
-- ✅ Prototype sharding architecture with beacon chain coordination
-- ✅ Implement ZK-rollup prototype for transaction batching
-- ⏳ Set up consortium legal structure and operational infrastructure
-- ⏳ Recruit founding members from industry and academia

docs/reference/roadmap.md

@@ -1,458 +0,0 @@
-# AITBC Development Roadmap
-
-This roadmap aggregates high-priority tasks derived from the bootstrap specifications in `docs/bootstrap/` and tracks progress across the monorepo. Update this document as milestones evolve.
-
-## Stage 1 — Upcoming Focus Areas [COMPLETED: 2025-12-22]
-
-- **Blockchain Node Foundations**
-  - ✅ Bootstrap module layout in `apps/blockchain-node/src/`.
-  - ✅ Implement SQLModel schemas and RPC stubs aligned with historical/attested receipts.
-
-- **Explorer Web Enablement**
-  - ✅ Finish mock integration across all pages and polish styling + mock/live toggle.
-  - ✅ Begin wiring coordinator endpoints (e.g., `/v1/jobs/{job_id}/receipts`).
-
-- **Marketplace Web Scaffolding**
-  - ✅ Scaffold Vite/vanilla frontends consuming coordinator receipt history endpoints and SDK examples.
-
-- **Pool Hub Services**
-  - ✅ Initialize FastAPI project, scoring registry, and telemetry ingestion hooks leveraging coordinator/miner metrics.
-
-- **CI Enhancements**
-  - ✅ Add blockchain-node tests once available and frontend build/lint checks to `.github/workflows/python-tests.yml` or follow-on workflows.
-  - ✅ Provide systemd unit + installer scripts under `scripts/` for streamlined deployment.
-
-## Stage 2 — Core Services (MVP) [COMPLETED: 2025-12-22]
-
-- **Coordinator API**
-  - ✅ Scaffold FastAPI project (`apps/coordinator-api/src/app/`).
-  - ✅ Implement job submission, status, result endpoints.
-  - ✅ Add miner registration, heartbeat, poll, result routes.
-  - ✅ Wire SQLite persistence for jobs, miners, receipts (historical `JobReceipt` table).
-  - ✅ Provide `.env.example`, `pyproject.toml`, and run scripts.
-  - ✅ Deploy minimal version in container with nginx proxy
-
-- **Miner Node**
-  - ✅ Implement capability probe and control loop (register → heartbeat → fetch jobs).
-  - ✅ Build CLI and Python runners with sandboxed work dirs (result reporting stubbed to coordinator).
-
-- **Blockchain Node**
-  - ✅ Define SQLModel schema for blocks, transactions, accounts, receipts (`apps/blockchain-node/src/aitbc_chain/models.py`).
-  - ✅ Harden schema parity across runtime + storage:
-    - Alembic baseline + follow-on migrations in `apps/blockchain-node/migrations/` now track the SQLModel schema (blocks, transactions, receipts, accounts).
-    - Added `Relationship` + `ForeignKey` wiring in `apps/blockchain-node/src/aitbc_chain/models.py` for block ↔ transaction ↔ receipt joins.
-    - Introduced hex/enum validation hooks via Pydantic validators to ensure hash integrity and safe persistence.
-  - ✅ Implement PoA proposer loop with block assembly (`apps/blockchain-node/src/aitbc_chain/consensus/poa.py`).
-  - ✅ Expose REST RPC endpoints for tx submission, balances, receipts (`apps/blockchain-node/src/aitbc_chain/rpc/router.py`).
-  - ✅ Deliver WebSocket RPC + P2P gossip layer:
-    - ✅ Stand up WebSocket subscription endpoints (`apps/blockchain-node/src/aitbc_chain/rpc/websocket.py`) mirroring REST payloads.
-    - ✅ Implement pub/sub transport for block + transaction gossip backed by an in-memory broker (Starlette `Broadcast` or Redis) with configurable fan-out.
-    - ✅ Add integration tests and load-test harness ensuring gossip convergence and back-pressure handling.
-  - ✅ Ship devnet scripts (`apps/blockchain-node/scripts/`).
-  - ✅ Add observability hooks (JSON logging, Prometheus metrics) and integrate coordinator mock into devnet tooling.
-  - ✅ Expand observability dashboards + miner mock integration:
-    - Build Grafana dashboards for consensus health (block intervals, proposer rotation) and RPC latency (`apps/blockchain-node/observability/`).
-    - Expose miner mock telemetry (job throughput, error rates) via shared Prometheus registry and ingest into blockchain-node dashboards.
-    - Add alerting rules (Prometheus `Alertmanager`) for stalled proposers, queue saturation, and miner mock disconnects.
-    - Wire coordinator mock into devnet tooling to simulate real-world load and validate observability hooks.
-
-- **Receipt Schema**
-  - ✅ Finalize canonical JSON receipt format under `protocols/receipts/` (includes sample signed receipts).
-  - ✅ Implement signing/verification helpers in `packages/py/aitbc-crypto` (JS SDK pending).
-  - ✅ Translate `docs/bootstrap/aitbc_tech_plan.md` contract skeleton into Solidity project (`packages/solidity/aitbc-token/`).
-  - ✅ Add deployment/test scripts and document minting flow (`packages/solidity/aitbc-token/scripts/` and `docs/run.md`).
-
-- **Wallet Daemon**
-  - ✅ Implement encrypted keystore (Argon2id + XChaCha20-Poly1305) via `KeystoreService`.
-  - ✅ Provide REST and JSON-RPC endpoints for wallet management and signing (`api_rest.py`, `api_jsonrpc.py`).
-  - ✅ Add mock ledger adapter with SQLite backend powering event history (`ledger_mock/`).
-  - ✅ Integrate Python receipt verification helpers (`aitbc_sdk`) and expose API/service utilities validating miner + coordinator signatures.
-  - ✅ Harden REST API workflows (create/list/unlock/sign) with structured password policy enforcement and deterministic pytest coverage in `apps/wallet-daemon/tests/test_wallet_api.py`.
-  - ✅ Implement Wallet SDK receipt ingestion + attestation surfacing:
-    - Added `/v1/jobs/{job_id}/receipts` client helpers with cursor pagination, retry/backoff, and summary reporting (`packages/py/aitbc-sdk/src/receipts.py`).
-    - Reused crypto helpers to validate miner and coordinator signatures, capturing per-key failure reasons for downstream UX.
-    - Surfaced aggregated attestation status (`ReceiptStatus`) and failure diagnostics for SDK + UI consumers; JS helper parity still planned.
-
-## Stage 3 — Pool Hub & Marketplace [COMPLETED: 2025-12-22]
-
-- **Pool Hub**
-  - ✅ Implement miner registry, scoring engine, and `/v1/match` API with Redis/PostgreSQL backing stores.
-  - ✅ Add observability endpoints (`/v1/health`, `/v1/metrics`) plus Prometheus instrumentation and integration tests.
-
-- **Marketplace Web**
-  - ✅ Initialize Vite project with vanilla TypeScript (`apps/marketplace-web/`).
-  - ✅ Build offer list, bid form, and stats cards powered by mock data fixtures (`public/mock/`).
-  - ✅ Provide API abstraction toggling mock/live mode (`src/lib/api.ts`) and wire coordinator endpoints.
-  - ✅ Validate live mode against coordinator `/v1/marketplace/*` responses and add auth feature flags for rollout.
-  - ✅ Deploy to production at https://aitbc.bubuit.net/marketplace/
-
-- **Explorer Web**
-  - ✅ Initialize Vite + TypeScript project scaffold (`apps/explorer-web/`).
-  - ✅ Add routed pages for overview, blocks, transactions, addresses, receipts.
-  - ✅ Seed mock datasets (`public/mock/`) and fetch helpers powering overview + blocks tables.
-  - ✅ Extend mock integrations to transactions, addresses, and receipts pages.
-  - ✅ Implement styling system, mock/live data toggle, and coordinator API wiring scaffold.
-  - ✅ Render overview stats from mock block/transaction/receipt summaries with graceful empty-state fallbacks.
-  - ✅ Validate live mode + responsive polish:
-    - Hit live coordinator endpoints via nginx (`/api/explorer/blocks`, `/api/explorer/transactions`, `/api/explorer/addresses`, `/api/explorer/receipts`) via `getDataMode() === "live"` and reconcile payloads with UI models.
-    - Add fallbacks + error surfacing for partial/failed live responses (toast + console diagnostics).
-    - Audit responsive breakpoints (`public/css/layout.css`) and adjust grid/typography for tablet + mobile; add regression checks in Percy/Playwright snapshots.
-  - ✅ Deploy to production at https://aitbc.bubuit.net/explorer/ with genesis block display
-
-## Stage 4 — Observability & Production Polish
-
-- **Observability & Telemetry**
-  - ✅ Build Grafana dashboards for PoA consensus health (block intervals, proposer rotation cadence) leveraging `poa_last_block_interval_seconds`, `poa_proposer_rotations_total`, and per-proposer counters.
-  - ✅ Surface RPC latency histograms/summaries for critical endpoints (`rpc_get_head`, `rpc_send_tx`, `rpc_submit_receipt`) and add Grafana panels with SLO thresholds.
-  - ✅ Ingest miner mock telemetry (job throughput, failure rate) into the shared Prometheus registry and wire panels/alerts that correlate miner health with consensus metrics.
-
-- **Explorer Web (Live Mode)**
-  - ✅ Finalize live `getDataMode() === "live"` workflow: align API payload contracts, render loading/error states, and persist mock/live toggle preference.
-  - ✅ Expand responsive testing (tablet/mobile) and add automated visual regression snapshots prior to launch.
-  - ✅ Integrate Playwright smoke tests covering overview, blocks, and transactions pages in live mode.
-
-- **Marketplace Web (Launch Readiness)**
-  - ✅ Connect mock listings/bids to coordinator data sources and provide feature flags for live mode rollout.
-  - ✅ Implement auth/session scaffolding for marketplace actions and document API assumptions in `apps/marketplace-web/README.md`.
-  - ✅ Add Grafana panels monitoring marketplace API throughput and error rates once endpoints are live.
-
-- **Operational Hardening**
-  - ✅ Extend Alertmanager rules to cover RPC error spikes, proposer stalls, and miner disconnects using the new metrics.
-  - ✅ Document dashboard import + alert deployment steps in `docs/run.md` for operators.
-  - ✅ Prepare Stage 3 release checklist linking dashboards, alerts, and smoke tests prior to production cutover.
-  - ✅ Enable host GPU miner with coordinator proxy routing and systemd-backed coordinator service; add proxy health timer.
-
-## Stage 5 — Scaling & Release Readiness
-
-- **Infrastructure Scaling**
-  - ✅ Benchmark blockchain node throughput under sustained load; capture CPU/memory targets and suggest horizontal scaling thresholds.
-  - ✅ Build Terraform/Helm templates for dev/staging/prod environments, including Prometheus/Grafana bundles.
-  - ✅ Implement autoscaling policies for coordinator, miners, and marketplace services with synthetic traffic tests.
-
-- **Reliability & Compliance**
-  - ✅ Formalize backup/restore procedures for PostgreSQL, Redis, and ledger storage with scheduled jobs.
-  - ✅ Complete security hardening review (TLS termination, API auth, secrets management) and document mitigations in `docs/security.md`.
-  - ✅ Add chaos testing scripts (network partition, coordinator outage) and track mean-time-to-recovery metrics.
-
-- **Product Launch Checklist**
-  - ✅ Finalize public documentation (API references, onboarding guides) and publish to the docs portal.
-  - ✅ Coordinate beta release timeline, including user acceptance testing of explorer/marketplace live modes.
-  - ✅ Establish post-launch monitoring playbooks and on-call rotations.
-
-## Stage 6 — Ecosystem Expansion
-
-- **Cross-Chain & Interop**
-  - ✅ Prototype cross-chain settlement hooks leveraging external bridges; document integration patterns.
-  - ✅ Extend SDKs (Python/JS) with pluggable transport abstractions for multi-network support.
-  - 🔄 Evaluate third-party explorer/analytics integrations and publish partner onboarding guides.
-
-- **Marketplace Growth**
-  - 🔄 Launch incentive programs (staking, liquidity mining) and expose telemetry dashboards tracking campaign performance.
-  - 🔄 Implement governance module (proposal voting, parameter changes) and add API/UX flows to explorer/marketplace.
-  - 🔄 Provide SLA-backed coordinator/pool hubs with capacity planning and billing instrumentation.
-
-- **Developer Experience**
-  - ✅ Publish advanced tutorials (custom proposers, marketplace extensions) and maintain versioned API docs.
-  - 🔄 Integrate CI/CD pipelines with canary deployments and blue/green release automation.
-  - 🔄 Host quarterly architecture reviews capturing lessons learned and feeding into roadmap revisions.
-
-## Stage 7 — Innovation & Ecosystem Services
-
-- **GPU Service Expansion**
-  - ✅ Implement dynamic service registry framework for 30+ GPU-accelerated services
-  - ✅ Create service definitions for AI/ML (LLM inference, image/video generation, speech recognition, computer vision, recommendation systems)
-  - ✅ Create service definitions for Media Processing (video transcoding, streaming, 3D rendering, image/audio processing)
-  - ✅ Create service definitions for Scientific Computing (molecular dynamics, weather modeling, financial modeling, physics simulation, bioinformatics)
-  - ✅ Create service definitions for Data Analytics (big data processing, real-time analytics, graph analytics, time series analysis)
-  - ✅ Create service definitions for Gaming & Entertainment (cloud gaming, asset baking, physics simulation, VR/AR rendering)
-  - ✅ Create service definitions for Development Tools (GPU compilation, model training, data processing, simulation testing, code generation)
-  - ✅ Deploy service provider configuration UI with dynamic service selection
-  - ✅ Implement service-specific validation and hardware requirement checking
-
-- **Advanced Cryptography & Privacy**
-  - ✅ Research zk-proof-based receipt attestation and prototype a privacy-preserving settlement flow.
-  - ✅ Add confidential transaction support with opt-in ciphertext storage and HSM-backed key management.
-  - ✅ Publish threat modeling updates and share mitigations with ecosystem partners.
-
-- **Enterprise Integrations**
-  - ✅ Deliver reference connectors for ERP/payment systems and document SLA expectations.
-  - ✅ Stand up multi-tenant coordinator infrastructure with per-tenant isolation and billing metrics.
-  - ✅ Launch ecosystem certification program (SDK conformance, security best practices) with public registry.
-
-- **Community & Governance**
-  - ✅ Establish open RFC process, publish governance website, and schedule regular community calls.
-  - ✅ Sponsor hackathons/accelerators and provide grants for marketplace extensions and analytics tooling.
-  - ✅ Track ecosystem KPIs (active marketplaces, cross-chain volume) and feed them into quarterly strategy reviews.
-
-## Stage 8 — Frontier R&D & Global Expansion [COMPLETED: 2025-12-28]
-
-- **Protocol Evolution**
-  - ✅ Launch research consortium exploring next-gen consensus (hybrid PoA/PoS) and finalize whitepapers.
-  - 🔄 Prototype sharding or rollup architectures to scale throughput beyond current limits.
-  - 🔄 Standardize interoperability specs with industry bodies and submit proposals for adoption.
-
-- **Global Rollout**
-  - 🔄 Establish regional infrastructure hubs (multi-cloud) with localized compliance and data residency guarantees.
-  - 🔄 Partner with regulators/enterprises to pilot regulated marketplaces and publish compliance playbooks.
-  - 🔄 Expand localization (UI, documentation, support) covering top target markets.
-
-- **Long-Term Sustainability**
-  - 🔄 Create sustainability fund for ecosystem maintenance, bug bounties, and community stewardship.
-  - 🔄 Define succession planning for core teams, including training programs and contributor pathways.
-  - 🔄 Publish bi-annual roadmap retrospectives assessing KPI alignment and revising long-term goals.
-
-## Stage 9 — Moonshot Initiatives [COMPLETED: 2025-12-28]
-
-- **Decentralized Infrastructure**
-  - 🔄 Transition coordinator/miner roles toward community-governed validator sets with incentive alignment.
-  - 🔄 Explore decentralized storage/backbone options (IPFS/Filecoin) for ledger and marketplace artifacts.
-  - 🔄 Prototype fully trustless marketplace settlement leveraging zero-knowledge rollups.
-
-- **AI & Automation**
-  - 🔄 Integrate AI-driven monitoring/anomaly detection for proposer health, market liquidity, and fraud detection.
-  - 🔄 Automate incident response playbooks with ChatOps and policy engines.
-  - 🔄 Launch research into autonomous agent participation (AI agents bidding/offering in the marketplace) and governance implications.
-- **Global Standards Leadership**
-  - 🔄 Chair industry working groups defining receipt/marketplace interoperability standards.
-  - 🔄 Publish annual transparency reports and sustainability metrics for stakeholders.
-  - 🔄 Engage with academia and open-source foundations to steward long-term protocol evolution.
-
-### Stage 10 — Stewardship & Legacy Planning [COMPLETED: 2025-12-28]
-
-- **Open Governance Maturity**
-  - 🔄 Transition roadmap ownership to community-elected councils with transparent voting and treasury controls.
-  - 🔄 Codify constitutional documents (mission, values, conflict resolution) and publish public charters.
-  - 🔄 Implement on-chain governance modules for protocol upgrades and ecosystem-wide decisions.
-
-- **Educational & Outreach Programs**
-  - 🔄 Fund university partnerships, research chairs, and developer fellowships focused on decentralized marketplace tech.
-  - 🔄 Create certification tracks and mentorship programs for new validator/operators.
-  - 🔄 Launch annual global summit and publish proceedings to share best practices across partners.
-
-- **Long-Term Preservation**
-  - 🔄 Archive protocol specs, governance records, and cultural artifacts in decentralized storage with redundancy.
-  - 🔄 Establish legal/organizational frameworks to ensure continuity across jurisdictions.
-  - 🔄 Develop end-of-life/transition plans for legacy components, documenting deprecation strategies and migration tooling.
-
-
-## Shared Libraries & Examples
-
-## Stage 11 — Trade Exchange & Token Economy [COMPLETED: 2025-12-28]
-
-- **Bitcoin Wallet Integration**
-  - ✅ Implement Bitcoin payment gateway for AITBC token purchases
-  - ✅ Create payment request API with unique payment addresses
-  - ✅ Add QR code generation for mobile payments
-  - ✅ Implement real-time payment monitoring with blockchain API
-  - ✅ Configure exchange rate: 1 BTC = 100,000 AITBC
-
-- **User Management System**
-  - ✅ Implement wallet-based authentication with session management
-  - ✅ Create individual user accounts with unique wallets
-  - ✅ Add user profile pages with transaction history
-  - ✅ Implement secure session tokens with 24-hour expiry
-  - ✅ Add login/logout functionality across all pages
-
-- **Trade Exchange Platform**
-  - ✅ Build responsive trading interface with real-time price updates
-  - ✅ Integrate Bitcoin payment flow with QR code display
-  - ✅ Add payment status monitoring and confirmation handling
-  - ✅ Implement AITBC token minting upon payment confirmation
-  - ✅ Deploy to production at https://aitbc.bubuit.net/Exchange/
-
-- **API Infrastructure**
-  - ✅ Add user management endpoints (/api/users/*)
-  - ✅ Implement exchange payment endpoints (/api/exchange/*)
-  - ✅ Add session-based authentication for protected routes
-  - ✅ Create transaction history and balance tracking APIs
-  - ✅ Fix all import and syntax errors in coordinator API
-
-## Stage 13 — Explorer Live API & Reverse Proxy Fixes [COMPLETED: 2025-12-28]
-
-- **Explorer Live API**
-  - ✅ Enable coordinator explorer routes at `/v1/explorer/*`.
-  - ✅ Expose nginx explorer proxy at `/api/explorer/*` (maps to backend `/v1/explorer/*`).
-  - ✅ Fix response schema mismatches (e.g., receipts response uses `jobId`).
-
-- **Coordinator API Users/Login**
-  - ✅ Ensure `/v1/users/login` is registered and working.
-  - ✅ Fix missing SQLModel tables by initializing DB on startup (wallet/user tables created).
-
-- **nginx Reverse Proxy Hardening**
-  - ✅ Fix `/api/v1/*` routing to avoid double `/v1` prefix.
-  - ✅ Add compatibility proxy for Exchange: `/api/users/*` → backend `/v1/users/*`.
-
-## Stage 12 — Zero-Knowledge Proof Implementation [COMPLETED: 2025-12-28]
-
-- **Circom Compiler Setup**
-  - ✅ Install Circom compiler v2.2.3 on production server
-  - ✅ Configure Node.js environment for ZK circuit compilation
-  - ✅ Install circomlib and required dependencies
-
-- **ZK Circuit Development**
-  - ✅ Create receipt attestation circuit (receipt_simple.circom)
-  - ✅ Implement membership proof circuit template
-  - ✅ Implement bid range proof circuit template
-  - ✅ Compile circuits to R1CS, WASM, and symbolic files
-
-- **Trusted Setup Ceremony**
-  - ✅ Perform Powers of Tau setup ceremony (2^12)
-  - ✅ Generate proving keys (zkey) for Groth16
-  - ✅ Export verification keys for on-chain verification
-  - ✅ Complete phase 2 preparation with contributions
-
-- **ZK Applications API**
-  - ✅ Implement identity commitment endpoints
-  - ✅ Create stealth address generation service
-  - ✅ Add private receipt attestation API
-  - ✅ Implement group membership proof verification
-  - ✅ Add private bidding functionality
-  - ✅ Create computation proof verification
-  - ✅ Deploy to production at /api/zk/ endpoints
-
-- **Integration & Deployment**
-  - ✅ Integrate ZK proof service with coordinator API
-  - ✅ Configure circuit files in production environment
-  - ✅ Enable ZK proof generation in coordinator service
-  - ✅ Update documentation with ZK capabilities
-
-## Stage 14 — Explorer JavaScript Error Fixes [COMPLETED: 2025-12-30]
-
-- **JavaScript Error Resolution**
-  - ✅ Fixed "can't access property 'length', t is undefined" error on Explorer page load
-  - ✅ Updated fetchMock function in mockData.ts to return correct structure with 'items' property
-  - ✅ Added defensive null checks in all page init functions (overview, blocks, transactions, addresses, receipts)
-  - ✅ Fixed TypeScript errors for null checks and missing properties
-  - ✅ Deployed fixes to production server (/var/www/aitbc.bubuit.net/explorer/)
-  - ✅ Configured mock data serving from correct path (/explorer/mock/)
-
-## Stage 15 — Cascade Skills Framework [COMPLETED: 2025-01-19]
-
-- **Skills Infrastructure**
-  - ✅ Implement Cascade skills framework for complex workflow automation
-  - ✅ Create skills directory structure at `.windsurf/skills/`
-  - ✅ Define skill metadata format with YAML frontmatter
-  - ✅ Add progressive disclosure for intelligent skill invocation
-
-- **Deploy-Production Skill**
-  - ✅ Create comprehensive deployment workflow skill
-  - ✅ Implement pre-deployment validation script (disk, memory, services, SSL)
-  - ✅ Add environment template with all production variables
-  - ✅ Create rollback procedures with emergency steps
-  - ✅ Build health check script for post-deployment verification
-
-- **Blockchain-Operations Skill**
-  - ✅ Create node health monitoring with peer analysis and sync status
-  - ✅ Implement transaction tracer for debugging and gas optimization
-  - ✅ Build GPU mining optimization script for NVIDIA/AMD cards
-  - ✅ Add real-time sync monitor with visual progress bar
-  - ✅ Create network diagnostics tool with connectivity analysis
-
-- **Skills Integration**
-  - ✅ Enable automatic skill invocation based on context
-  - ✅ Add manual skill triggering with keyword detection
-  - ✅ Implement error handling and logging in all skills
-  - ✅ Create comprehensive documentation and usage examples
-
-## Stage 16 — Service Maintenance & Optimization [COMPLETED: 2026-01-21]
-
-- **Service Recovery**
-  - ✅ Diagnose and fix all failing AITBC container services
-  - ✅ Resolve duplicate service conflicts causing port binding errors
-  - ✅ Fix marketplace service implementation (missing server.py)
-  - ✅ Disable redundant services to prevent resource conflicts
-
-- **System Administration**
-  - ✅ Configure passwordless SSH access for automation
-  - ✅ Create dedicated SSH keys for secure service management
-  - ✅ Document service dependencies and port mappings
-  - ✅ Establish service monitoring procedures
-
-- **Service Status Verification**
-  - ✅ Verify all 7 core services running correctly
-  - ✅ Confirm proper nginx reverse proxy configuration
-  - ✅ Validate API endpoints accessibility
-  - ✅ Test service recovery procedures
-
-## Stage 17 — Ollama GPU Inference & CLI Tooling [COMPLETED: 2026-01-24]
-
-- **End-to-End Ollama Testing**
-  - ✅ Verify complete GPU inference workflow from job submission to receipt generation
-  - ✅ Test Ollama integration with multiple models (llama3.2, mistral, deepseek, etc.)
-  - ✅ Validate job lifecycle: QUEUED → RUNNING → COMPLETED
-  - ✅ Confirm receipt generation with accurate payment calculations
-  - ✅ Record transactions on blockchain with proper metadata
-
-- **Coordinator API Bug Fixes**
-  - ✅ Fix missing `_coerce_float()` helper function causing 500 errors
-  - ✅ Deploy fix to production incus container via SSH
-  - ✅ Verify result submission returns 200 OK with valid receipts
-  - ✅ Validate receipt payload structure and signature generation
-
-- **Miner Configuration & Optimization**
-  - ✅ Fix miner ID mismatch (host-gpu-miner → REDACTED_MINER_KEY)
-  - ✅ Enhance logging with explicit flush handlers for systemd journal
-  - ✅ Configure unbuffered Python logging environment variables
-  - ✅ Create systemd service unit with proper environment configuration
-
-- **CLI Tooling Development**
-  - ✅ Create unified bash CLI wrapper (`scripts/aitbc-cli.sh`)
-  - ✅ Implement commands: submit, status, browser, blocks, receipts, cancel
-  - ✅ Add admin commands: admin-miners, admin-jobs, admin-stats
-  - ✅ Support environment variable overrides for URL and API keys
-  - ✅ Make script executable and document usage patterns
-
-- **Blockchain-Operations Skill Enhancement**
-  - ✅ Add comprehensive Ollama testing scenarios to skill
-  - ✅ Create detailed test documentation (`ollama-test-scenario.md`)
-  - ✅ Document common issues and troubleshooting procedures
-  - ✅ Add performance metrics and expected results
-  - ✅ Include end-to-end automation script template
-
-- **Documentation Updates**
-  - ✅ Update localhost testing scenario with CLI wrapper usage
-  - ✅ Convert examples to use localhost URLs (127.0.0.1)
-  - ✅ Add host user paths and quick start commands
-  - ✅ Document complete workflow from setup to verification
-  - ✅ Update skill documentation with testing scenarios
-
-## Stage 18 — Repository Reorganization & CSS Consolidation [COMPLETED: 2026-01-24]
-
-- **Root Level Cleanup**
-  - ✅ Move 60+ loose files from root to proper directories
-  - ✅ Organize deployment scripts into `scripts/deploy/`
-  - ✅ Organize GPU miner files into `scripts/gpu/`
-  - ✅ Organize test/verify files into `scripts/test/`
-  - ✅ Organize service management scripts into `scripts/service/`
-  - ✅ Move systemd services to `systemd/`
-  - ✅ Move nginx configs to `infra/nginx/`
-  - ✅ Move dashboards to `website/dashboards/`
-
-- **Website/Docs Folder Structure**
-  - ✅ Establish `/website/docs/` as source for HTML documentation
-  - ✅ Create shared CSS file (`css/docs.css`) with 1232 lines
-  - ✅ Create theme toggle JavaScript (`js/theme.js`)
-  - ✅ Migrate all HTML files to use external CSS (45-66% size reduction)
-  - ✅ Clean `/docs/` folder to only contain mkdocs markdown files
-
-- **Documentation Styling Fixes**
-  - ✅ Fix dark theme background consistency across all docs pages
-  - ✅ Add dark theme support to `full-documentation.html`
-  - ✅ Fix Quick Start section cascade styling in docs-miners.html
-  - ✅ Fix SDK Examples cascade indentation in docs-clients.html
-  - ✅ Fix malformed `</code-block>` tags across all docs
-  - ✅ Update API endpoint example to use Python/FastAPI
-
-- **Path Reference Updates**
-  - ✅ Update systemd service file with new `scripts/gpu/gpu_miner_host.py` path
-  - ✅ Update skill documentation with new file locations
-  - ✅ Update localhost-testing-scenario.md with correct paths
-  - ✅ Update gpu_miner_host_wrapper.sh with new path
-
-- **Repository Maintenance**
-  - ✅ Expand .gitignore from 39 to 145 lines with organized sections
-  - ✅ Add project-specific ignore rules for coordinator, explorer, GPU miner
-  - ✅ Document final folder structure in done.md
-
-the canonical checklist during implementation. Mark completed tasks with ✅ and add dates or links to relevant PRs as development progresses.
-

docs/reference/specs/receipt-spec.md

@@ -0,0 +1,95 @@
+# AITBC Receipt Specification (Draft)
+
+## Overview
+
+This document defines the canonical schema and serialization rules for receipts generated by the AITBC network after miners complete compute jobs. Receipts serve as tamper-evident evidence tying compute usage to token minting events.
+
+## Receipt Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `version` | string | yes | Receipt schema version (e.g., `"1.0"`). |
+| `receipt_id` | string | yes | Unique identifier for this receipt. SHOULD be globally unique (UUID or hash). |
+| `job_id` | string | yes | Identifier of the coordinator job this receipt references. |
+| `provider` | string | yes | Miner address/account that executed the job. |
+| `client` | string | yes | Client address/account that requested the job. |
+| `units` | number | yes | Compute units earned by the miner (token minting basis). |
+| `unit_type` | string | yes | Unit denomination (e.g., `"gpu_seconds"`, `"token_ops"`). |
+| `price` | number | optional | Price paid by the client for the job (same unit as `units` if applicable). |
+| `model` | string | optional | Model or workload identifier (e.g., `"runwayml/stable-diffusion-v1-5"`). |
+| `prompt_hash` | string | optional | Hash of user prompt or workload input to preserve privacy. |
+| `started_at` | integer | yes | Unix timestamp (seconds) when the job started. |
+| `completed_at` | integer | yes | Unix timestamp when the job completed. |
+| `duration_ms` | integer | optional | Milliseconds elapsed during execution. |
+| `artifact_hash` | string | optional | SHA-256 hash of the result artifact(s). |
+| `coordinator_id` | string | optional | Coordinator identifier if multiple coordinators exist. |
+| `nonce` | string | optional | Unique nonce to prevent replay/double minting. |
+| `chain_id` | integer | optional | Target chain/network identifier. |
+| `metadata` | object | optional | Arbitrary key/value pairs for future extensions. |
+| `signature` | object | conditional | Signature object (see below). |
+
+### Signature Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `alg` | string | yes | Signature algorithm (e.g., `"Ed25519"`, `"secp256k1"`). |
+| `key_id` | string | yes | Identifier of signing key (e.g., `"miner-ed25519-2025-09"`). |
+| `sig` | string | yes | Base64url-encoded signature over the canonical receipt bytes. |
+
+Receipts SHOULD be signed by either the miner, coordinator attester, or both depending on trust model. Multiple signatures can be supported by storing them in `metadata.signatures` array.
+
+## Canonical Serialization
+
+1. Construct a JSON object containing all fields except `signature`.
+2. Remove any fields with null/undefined values.
+3. Sort keys lexicographically at each object level.
+4. Serialize using UTF-8 without whitespace (RFC 8785 style).
+5. Compute hash as `sha256(serialized_json)` for Ed25519 signing.
+6. Attach `signature` object containing algorithm, key ID, and base64url signature over the hash.
+
+## Validation Rules
+
+- `completed_at >= started_at`.
+- `units >= 0` and `price >= 0` when present.
+- `signature.alg` MUST be one of the network approved algorithms (initially `Ed25519`).
+- `chain_id` SHOULD match the target blockchain network when provided.
+- Reject receipts older than network-defined retention period.
+
+## Example Receipt (unsigned)
+
+```json
+{
+  "version": "1.0",
+  "receipt_id": "rcpt-20250926-000123",
+  "job_id": "job-abc123",
+  "provider": "ait1minerxyz...",
+  "client": "ait1clientabc...",
+  "units": 1.9,
+  "unit_type": "gpu_seconds",
+  "price": 4.2,
+  "model": "runwayml/stable-diffusion-v1-5",
+  "prompt_hash": "sha256:cf1f...",
+  "started_at": 1695720000,
+  "completed_at": 1695720002,
+  "artifact_hash": "sha256:deadbeef...",
+  "coordinator_id": "coord-eu-west-1",
+  "nonce": "b7f3d10b",
+  "chain_id": 12345
+}
+```
+
+Signed form includes:
+
+```json
+"signature": {
+  "alg": "Ed25519",
+  "key_id": "miner-ed25519-2025-09",
+  "sig": "Fql0..."
+}
+```
+
+## Future Extensions
+
+- Multi-signature receipts (miner + coordinator attestations).
+- ZK-proof metadata for privacy-preserving verification.
+- On-chain receipt anchors with Merkle proofs.

docs/requirements.txt

@@ -1,27 +0,0 @@
-# MkDocs Material Theme
-mkdocs-material==9.4.8
-mkdocs-material-extensions==1.3.1
-
-# MkDocs Core and Plugins
-mkdocs==1.5.3
-mkdocs-git-revision-date-localized-plugin==1.2.6
-mkdocs-awesome-pages-plugin==2.9.2
-mkdocs-minify-plugin==0.7.4
-mkdocs-glightbox==0.3.4
-mkdocs-video==1.5.0
-mkdocs-social-plugin==1.0.0
-mkdocs-macros-plugin==1.0.5
-
-# Python Extensions for Markdown
-pymdown-extensions==10.8.1
-markdown-include==0.8.0
-mkdocs-mermaid2-plugin==1.1.1
-
-# Additional dependencies
-requests==2.31.0
-aiohttp==3.9.1
-python-dotenv==1.0.0
-
-# Development dependencies
-mkdocs-redirects==1.2.1
-mkdocs-monorepo-plugin==1.0.2

docs/roadmap.md

@@ -1 +0,0 @@
-reference/roadmap.md

docs/roadmap.md

@@ -0,0 +1,600 @@
+# AITBC Development Roadmap
+
+This roadmap aggregates high-priority tasks derived from the bootstrap specifications in `docs/bootstrap/` and tracks progress across the monorepo. Update this document as milestones evolve.
+
+## Stage 1 — Upcoming Focus Areas [COMPLETED: 2025-12-22]
+
+- **Blockchain Node Foundations**
+  - ✅ Bootstrap module layout in `apps/blockchain-node/src/`.
+  - ✅ Implement SQLModel schemas and RPC stubs aligned with historical/attested receipts.
+
+- **Explorer Web Enablement**
+  - ✅ Finish mock integration across all pages and polish styling + mock/live toggle.
+  - ✅ Begin wiring coordinator endpoints (e.g., `/v1/jobs/{job_id}/receipts`).
+
+- **Marketplace Web Scaffolding**
+  - ✅ Scaffold Vite/vanilla frontends consuming coordinator receipt history endpoints and SDK examples.
+
+- **Pool Hub Services**
+  - ✅ Initialize FastAPI project, scoring registry, and telemetry ingestion hooks leveraging coordinator/miner metrics.
+
+- **CI Enhancements**
+  - ✅ Add blockchain-node tests once available and frontend build/lint checks to `.github/workflows/python-tests.yml` or follow-on workflows.
+  - ✅ Provide systemd unit + installer scripts under `scripts/` for streamlined deployment.
+
+## Stage 2 — Core Services (MVP) [COMPLETED: 2025-12-22]
+
+- **Coordinator API**
+  - ✅ Scaffold FastAPI project (`apps/coordinator-api/src/app/`).
+  - ✅ Implement job submission, status, result endpoints.
+  - ✅ Add miner registration, heartbeat, poll, result routes.
+  - ✅ Wire SQLite persistence for jobs, miners, receipts (historical `JobReceipt` table).
+  - ✅ Provide `.env.example`, `pyproject.toml`, and run scripts.
+  - ✅ Deploy minimal version in container with nginx proxy
+
+- **Miner Node**
+  - ✅ Implement capability probe and control loop (register → heartbeat → fetch jobs).
+  - ✅ Build CLI and Python runners with sandboxed work dirs (result reporting stubbed to coordinator).
+
+- **Blockchain Node**
+  - ✅ Define SQLModel schema for blocks, transactions, accounts, receipts (`apps/blockchain-node/src/aitbc_chain/models.py`).
+  - ✅ Harden schema parity across runtime + storage:
+    - Alembic baseline + follow-on migrations in `apps/blockchain-node/migrations/` now track the SQLModel schema (blocks, transactions, receipts, accounts).
+    - Added `Relationship` + `ForeignKey` wiring in `apps/blockchain-node/src/aitbc_chain/models.py` for block ↔ transaction ↔ receipt joins.
+    - Introduced hex/enum validation hooks via Pydantic validators to ensure hash integrity and safe persistence.
+  - ✅ Implement PoA proposer loop with block assembly (`apps/blockchain-node/src/aitbc_chain/consensus/poa.py`).
+  - ✅ Expose REST RPC endpoints for tx submission, balances, receipts (`apps/blockchain-node/src/aitbc_chain/rpc/router.py`).
+  - ✅ Deliver WebSocket RPC + P2P gossip layer:
+    - ✅ Stand up WebSocket subscription endpoints (`apps/blockchain-node/src/aitbc_chain/rpc/websocket.py`) mirroring REST payloads.
+    - ✅ Implement pub/sub transport for block + transaction gossip backed by an in-memory broker (Starlette `Broadcast` or Redis) with configurable fan-out.
+    - ✅ Add integration tests and load-test harness ensuring gossip convergence and back-pressure handling.
+  - ✅ Ship devnet scripts (`apps/blockchain-node/scripts/`).
+  - ✅ Add observability hooks (JSON logging, Prometheus metrics) and integrate coordinator mock into devnet tooling.
+  - ✅ Expand observability dashboards + miner mock integration:
+    - Build Grafana dashboards for consensus health (block intervals, proposer rotation) and RPC latency (`apps/blockchain-node/observability/`).
+    - Expose miner mock telemetry (job throughput, error rates) via shared Prometheus registry and ingest into blockchain-node dashboards.
+    - Add alerting rules (Prometheus `Alertmanager`) for stalled proposers, queue saturation, and miner mock disconnects.
+    - Wire coordinator mock into devnet tooling to simulate real-world load and validate observability hooks.
+
+- **Receipt Schema**
+  - ✅ Finalize canonical JSON receipt format under `protocols/receipts/` (includes sample signed receipts).
+  - ✅ Implement signing/verification helpers in `packages/py/aitbc-crypto` (JS SDK pending).
+  - ✅ Translate `docs/bootstrap/aitbc_tech_plan.md` contract skeleton into Solidity project (`packages/solidity/aitbc-token/`).
+  - ✅ Add deployment/test scripts and document minting flow (`packages/solidity/aitbc-token/scripts/` and `docs/run.md`).
+
+- **Wallet Daemon**
+  - ✅ Implement encrypted keystore (Argon2id + XChaCha20-Poly1305) via `KeystoreService`.
+  - ✅ Provide REST and JSON-RPC endpoints for wallet management and signing (`api_rest.py`, `api_jsonrpc.py`).
+  - ✅ Add mock ledger adapter with SQLite backend powering event history (`ledger_mock/`).
+  - ✅ Integrate Python receipt verification helpers (`aitbc_sdk`) and expose API/service utilities validating miner + coordinator signatures.
+  - ✅ Harden REST API workflows (create/list/unlock/sign) with structured password policy enforcement and deterministic pytest coverage in `apps/wallet-daemon/tests/test_wallet_api.py`.
+  - ✅ Implement Wallet SDK receipt ingestion + attestation surfacing:
+    - Added `/v1/jobs/{job_id}/receipts` client helpers with cursor pagination, retry/backoff, and summary reporting (`packages/py/aitbc-sdk/src/receipts.py`).
+    - Reused crypto helpers to validate miner and coordinator signatures, capturing per-key failure reasons for downstream UX.
+    - Surfaced aggregated attestation status (`ReceiptStatus`) and failure diagnostics for SDK + UI consumers; JS helper parity still planned.
+
+## Stage 3 — Pool Hub & Marketplace [COMPLETED: 2025-12-22]
+
+- **Pool Hub**
+  - ✅ Implement miner registry, scoring engine, and `/v1/match` API with Redis/PostgreSQL backing stores.
+  - ✅ Add observability endpoints (`/v1/health`, `/v1/metrics`) plus Prometheus instrumentation and integration tests.
+
+- **Marketplace Web**
+  - ✅ Initialize Vite project with vanilla TypeScript (`apps/marketplace-web/`).
+  - ✅ Build offer list, bid form, and stats cards powered by mock data fixtures (`public/mock/`).
+  - ✅ Provide API abstraction toggling mock/live mode (`src/lib/api.ts`) and wire coordinator endpoints.
+  - ✅ Validate live mode against coordinator `/v1/marketplace/*` responses and add auth feature flags for rollout.
+  - ✅ Deploy to production at https://aitbc.bubuit.net/marketplace/
+
+- **Explorer Web**
+  - ✅ Initialize Vite + TypeScript project scaffold (`apps/explorer-web/`).
+  - ✅ Add routed pages for overview, blocks, transactions, addresses, receipts.
+  - ✅ Seed mock datasets (`public/mock/`) and fetch helpers powering overview + blocks tables.
+  - ✅ Extend mock integrations to transactions, addresses, and receipts pages.
+  - ✅ Implement styling system, mock/live data toggle, and coordinator API wiring scaffold.
+  - ✅ Render overview stats from mock block/transaction/receipt summaries with graceful empty-state fallbacks.
+  - ✅ Validate live mode + responsive polish:
+    - Hit live coordinator endpoints via nginx (`/api/explorer/blocks`, `/api/explorer/transactions`, `/api/explorer/addresses`, `/api/explorer/receipts`) via `getDataMode() === "live"` and reconcile payloads with UI models.
+    - Add fallbacks + error surfacing for partial/failed live responses (toast + console diagnostics).
+    - Audit responsive breakpoints (`public/css/layout.css`) and adjust grid/typography for tablet + mobile; add regression checks in Percy/Playwright snapshots.
+  - ✅ Deploy to production at https://aitbc.bubuit.net/explorer/ with genesis block display
+
+## Stage 4 — Observability & Production Polish
+
+- **Observability & Telemetry**
+  - ✅ Build Grafana dashboards for PoA consensus health (block intervals, proposer rotation cadence) leveraging `poa_last_block_interval_seconds`, `poa_proposer_rotations_total`, and per-proposer counters.
+  - ✅ Surface RPC latency histograms/summaries for critical endpoints (`rpc_get_head`, `rpc_send_tx`, `rpc_submit_receipt`) and add Grafana panels with SLO thresholds.
+  - ✅ Ingest miner mock telemetry (job throughput, failure rate) into the shared Prometheus registry and wire panels/alerts that correlate miner health with consensus metrics.
+
+- **Explorer Web (Live Mode)**
+  - ✅ Finalize live `getDataMode() === "live"` workflow: align API payload contracts, render loading/error states, and persist mock/live toggle preference.
+  - ✅ Expand responsive testing (tablet/mobile) and add automated visual regression snapshots prior to launch.
+  - ✅ Integrate Playwright smoke tests covering overview, blocks, and transactions pages in live mode.
+
+- **Marketplace Web (Launch Readiness)**
+  - ✅ Connect mock listings/bids to coordinator data sources and provide feature flags for live mode rollout.
+  - ✅ Implement auth/session scaffolding for marketplace actions and document API assumptions in `apps/marketplace-web/README.md`.
+  - ✅ Add Grafana panels monitoring marketplace API throughput and error rates once endpoints are live.
+
+- **Operational Hardening**
+  - ✅ Extend Alertmanager rules to cover RPC error spikes, proposer stalls, and miner disconnects using the new metrics.
+  - ✅ Document dashboard import + alert deployment steps in `docs/run.md` for operators.
+  - ✅ Prepare Stage 3 release checklist linking dashboards, alerts, and smoke tests prior to production cutover.
+  - ✅ Enable host GPU miner with coordinator proxy routing and systemd-backed coordinator service; add proxy health timer.
+
+## Stage 5 — Scaling & Release Readiness
+
+- **Infrastructure Scaling**
+  - ✅ Benchmark blockchain node throughput under sustained load; capture CPU/memory targets and suggest horizontal scaling thresholds.
+  - ✅ Build Terraform/Helm templates for dev/staging/prod environments, including Prometheus/Grafana bundles.
+  - ✅ Implement autoscaling policies for coordinator, miners, and marketplace services with synthetic traffic tests.
+
+- **Reliability & Compliance**
+  - ✅ Formalize backup/restore procedures for PostgreSQL, Redis, and ledger storage with scheduled jobs.
+  - ✅ Complete security hardening review (TLS termination, API auth, secrets management) and document mitigations in `docs/security.md`.
+  - ✅ Add chaos testing scripts (network partition, coordinator outage) and track mean-time-to-recovery metrics.
+
+- **Product Launch Checklist**
+  - ✅ Finalize public documentation (API references, onboarding guides) and publish to the docs portal.
+  - ✅ Coordinate beta release timeline, including user acceptance testing of explorer/marketplace live modes.
+  - ✅ Establish post-launch monitoring playbooks and on-call rotations.
+
+## Stage 6 — Ecosystem Expansion
+
+- **Cross-Chain & Interop**
+  - ✅ Prototype cross-chain settlement hooks leveraging external bridges; document integration patterns.
+  - ✅ Extend SDKs (Python/JS) with pluggable transport abstractions for multi-network support.
+  - 🔄 Evaluate third-party explorer/analytics integrations and publish partner onboarding guides.
+
+- **Marketplace Growth**
+  - 🔄 Launch incentive programs (staking, liquidity mining) and expose telemetry dashboards tracking campaign performance.
+  - 🔄 Implement governance module (proposal voting, parameter changes) and add API/UX flows to explorer/marketplace.
+  - 🔄 Provide SLA-backed coordinator/pool hubs with capacity planning and billing instrumentation.
+
+- **Developer Experience**
+  - ✅ Publish advanced tutorials (custom proposers, marketplace extensions) and maintain versioned API docs.
+  - 🔄 Integrate CI/CD pipelines with canary deployments and blue/green release automation.
+  - 🔄 Host quarterly architecture reviews capturing lessons learned and feeding into roadmap revisions.
+
+## Stage 7 — Innovation & Ecosystem Services
+
+- **GPU Service Expansion**
+  - ✅ Implement dynamic service registry framework for 30+ GPU-accelerated services
+  - ✅ Create service definitions for AI/ML (LLM inference, image/video generation, speech recognition, computer vision, recommendation systems)
+  - ✅ Create service definitions for Media Processing (video transcoding, streaming, 3D rendering, image/audio processing)
+  - ✅ Create service definitions for Scientific Computing (molecular dynamics, weather modeling, financial modeling, physics simulation, bioinformatics)
+  - ✅ Create service definitions for Data Analytics (big data processing, real-time analytics, graph analytics, time series analysis)
+  - ✅ Create service definitions for Gaming & Entertainment (cloud gaming, asset baking, physics simulation, VR/AR rendering)
+  - ✅ Create service definitions for Development Tools (GPU compilation, model training, data processing, simulation testing, code generation)
+  - ✅ Deploy service provider configuration UI with dynamic service selection
+  - ✅ Implement service-specific validation and hardware requirement checking
+
+- **Advanced Cryptography & Privacy**
+  - ✅ Research zk-proof-based receipt attestation and prototype a privacy-preserving settlement flow.
+  - ✅ Add confidential transaction support with opt-in ciphertext storage and HSM-backed key management.
+  - ✅ Publish threat modeling updates and share mitigations with ecosystem partners.
+
+- **Enterprise Integrations**
+  - ✅ Deliver reference connectors for ERP/payment systems and document SLA expectations.
+  - ✅ Stand up multi-tenant coordinator infrastructure with per-tenant isolation and billing metrics.
+  - ✅ Launch ecosystem certification program (SDK conformance, security best practices) with public registry.
+
+- **Community & Governance**
+  - ✅ Establish open RFC process, publish governance website, and schedule regular community calls.
+  - ✅ Sponsor hackathons/accelerators and provide grants for marketplace extensions and analytics tooling.
+  - ✅ Track ecosystem KPIs (active marketplaces, cross-chain volume) and feed them into quarterly strategy reviews.
+
+## Stage 8 — Frontier R&D & Global Expansion [COMPLETED: 2025-12-28]
+
+- **Protocol Evolution**
+  - ✅ Launch research consortium exploring next-gen consensus (hybrid PoA/PoS) and finalize whitepapers.
+  - 🔄 Prototype sharding or rollup architectures to scale throughput beyond current limits.
+  - 🔄 Standardize interoperability specs with industry bodies and submit proposals for adoption.
+
+- **Global Rollout**
+  - 🔄 Establish regional infrastructure hubs (multi-cloud) with localized compliance and data residency guarantees.
+  - 🔄 Partner with regulators/enterprises to pilot regulated marketplaces and publish compliance playbooks.
+  - 🔄 Expand localization (UI, documentation, support) covering top target markets.
+
+- **Long-Term Sustainability**
+  - 🔄 Create sustainability fund for ecosystem maintenance, bug bounties, and community stewardship.
+  - 🔄 Define succession planning for core teams, including training programs and contributor pathways.
+  - 🔄 Publish bi-annual roadmap retrospectives assessing KPI alignment and revising long-term goals.
+
+## Stage 9 — Moonshot Initiatives [COMPLETED: 2025-12-28]
+
+- **Decentralized Infrastructure**
+  - 🔄 Transition coordinator/miner roles toward community-governed validator sets with incentive alignment.
+  - 🔄 Explore decentralized storage/backbone options (IPFS/Filecoin) for ledger and marketplace artifacts.
+  - 🔄 Prototype fully trustless marketplace settlement leveraging zero-knowledge rollups.
+
+- **AI & Automation**
+  - 🔄 Integrate AI-driven monitoring/anomaly detection for proposer health, market liquidity, and fraud detection.
+  - 🔄 Automate incident response playbooks with ChatOps and policy engines.
+  - 🔄 Launch research into autonomous agent participation (AI agents bidding/offering in the marketplace) and governance implications.
+- **Global Standards Leadership**
+  - 🔄 Chair industry working groups defining receipt/marketplace interoperability standards.
+  - 🔄 Publish annual transparency reports and sustainability metrics for stakeholders.
+  - 🔄 Engage with academia and open-source foundations to steward long-term protocol evolution.
+
+### Stage 10 — Stewardship & Legacy Planning [COMPLETED: 2025-12-28]
+
+- **Open Governance Maturity**
+  - 🔄 Transition roadmap ownership to community-elected councils with transparent voting and treasury controls.
+  - 🔄 Codify constitutional documents (mission, values, conflict resolution) and publish public charters.
+  - 🔄 Implement on-chain governance modules for protocol upgrades and ecosystem-wide decisions.
+
+- **Educational & Outreach Programs**
+  - 🔄 Fund university partnerships, research chairs, and developer fellowships focused on decentralized marketplace tech.
+  - 🔄 Create certification tracks and mentorship programs for new validator/operators.
+  - 🔄 Launch annual global summit and publish proceedings to share best practices across partners.
+
+- **Long-Term Preservation**
+  - 🔄 Archive protocol specs, governance records, and cultural artifacts in decentralized storage with redundancy.
+  - 🔄 Establish legal/organizational frameworks to ensure continuity across jurisdictions.
+  - 🔄 Develop end-of-life/transition plans for legacy components, documenting deprecation strategies and migration tooling.
+
+
+## Shared Libraries & Examples
+
+## Stage 11 — Trade Exchange & Token Economy [COMPLETED: 2025-12-28]
+
+- **Bitcoin Wallet Integration**
+  - ✅ Implement Bitcoin payment gateway for AITBC token purchases
+  - ✅ Create payment request API with unique payment addresses
+  - ✅ Add QR code generation for mobile payments
+  - ✅ Implement real-time payment monitoring with blockchain API
+  - ✅ Configure exchange rate: 1 BTC = 100,000 AITBC
+
+- **User Management System**
+  - ✅ Implement wallet-based authentication with session management
+  - ✅ Create individual user accounts with unique wallets
+  - ✅ Add user profile pages with transaction history
+  - ✅ Implement secure session tokens with 24-hour expiry
+  - ✅ Add login/logout functionality across all pages
+
+- **Trade Exchange Platform**
+  - ✅ Build responsive trading interface with real-time price updates
+  - ✅ Integrate Bitcoin payment flow with QR code display
+  - ✅ Add payment status monitoring and confirmation handling
+  - ✅ Implement AITBC token minting upon payment confirmation
+  - ✅ Deploy to production at https://aitbc.bubuit.net/Exchange/
+
+- **API Infrastructure**
+  - ✅ Add user management endpoints (/api/users/*)
+  - ✅ Implement exchange payment endpoints (/api/exchange/*)
+  - ✅ Add session-based authentication for protected routes
+  - ✅ Create transaction history and balance tracking APIs
+  - ✅ Fix all import and syntax errors in coordinator API
+
+## Stage 13 — Explorer Live API & Reverse Proxy Fixes [COMPLETED: 2025-12-28]
+
+- **Explorer Live API**
+  - ✅ Enable coordinator explorer routes at `/v1/explorer/*`.
+  - ✅ Expose nginx explorer proxy at `/api/explorer/*` (maps to backend `/v1/explorer/*`).
+  - ✅ Fix response schema mismatches (e.g., receipts response uses `jobId`).
+
+- **Coordinator API Users/Login**
+  - ✅ Ensure `/v1/users/login` is registered and working.
+  - ✅ Fix missing SQLModel tables by initializing DB on startup (wallet/user tables created).
+
+- **nginx Reverse Proxy Hardening**
+  - ✅ Fix `/api/v1/*` routing to avoid double `/v1` prefix.
+  - ✅ Add compatibility proxy for Exchange: `/api/users/*` → backend `/v1/users/*`.
+
+## Stage 12 — Zero-Knowledge Proof Implementation [COMPLETED: 2025-12-28]
+
+- **Circom Compiler Setup**
+  - ✅ Install Circom compiler v2.2.3 on production server
+  - ✅ Configure Node.js environment for ZK circuit compilation
+  - ✅ Install circomlib and required dependencies
+
+- **ZK Circuit Development**
+  - ✅ Create receipt attestation circuit (receipt_simple.circom)
+  - ✅ Implement membership proof circuit template
+  - ✅ Implement bid range proof circuit template
+  - ✅ Compile circuits to R1CS, WASM, and symbolic files
+
+- **Trusted Setup Ceremony**
+  - ✅ Perform Powers of Tau setup ceremony (2^12)
+  - ✅ Generate proving keys (zkey) for Groth16
+  - ✅ Export verification keys for on-chain verification
+  - ✅ Complete phase 2 preparation with contributions
+
+- **ZK Applications API**
+  - ✅ Implement identity commitment endpoints
+  - ✅ Create stealth address generation service
+  - ✅ Add private receipt attestation API
+  - ✅ Implement group membership proof verification
+  - ✅ Add private bidding functionality
+  - ✅ Create computation proof verification
+  - ✅ Deploy to production at /api/zk/ endpoints
+
+- **Integration & Deployment**
+  - ✅ Integrate ZK proof service with coordinator API
+  - ✅ Configure circuit files in production environment
+  - ✅ Enable ZK proof generation in coordinator service
+  - ✅ Update documentation with ZK capabilities
+
+## Stage 14 — Explorer JavaScript Error Fixes [COMPLETED: 2025-12-30]
+
+- **JavaScript Error Resolution**
+  - ✅ Fixed "can't access property 'length', t is undefined" error on Explorer page load
+  - ✅ Updated fetchMock function in mockData.ts to return correct structure with 'items' property
+  - ✅ Added defensive null checks in all page init functions (overview, blocks, transactions, addresses, receipts)
+  - ✅ Fixed TypeScript errors for null checks and missing properties
+  - ✅ Deployed fixes to production server (/var/www/aitbc.bubuit.net/explorer/)
+  - ✅ Configured mock data serving from correct path (/explorer/mock/)
+
+## Stage 15 — Cascade Skills Framework [COMPLETED: 2025-01-19]
+
+- **Skills Infrastructure**
+  - ✅ Implement Cascade skills framework for complex workflow automation
+  - ✅ Create skills directory structure at `.windsurf/skills/`
+  - ✅ Define skill metadata format with YAML frontmatter
+  - ✅ Add progressive disclosure for intelligent skill invocation
+
+- **Deploy-Production Skill**
+  - ✅ Create comprehensive deployment workflow skill
+  - ✅ Implement pre-deployment validation script (disk, memory, services, SSL)
+  - ✅ Add environment template with all production variables
+  - ✅ Create rollback procedures with emergency steps
+  - ✅ Build health check script for post-deployment verification
+
+- **Blockchain-Operations Skill**
+  - ✅ Create node health monitoring with peer analysis and sync status
+  - ✅ Implement transaction tracer for debugging and gas optimization
+  - ✅ Build GPU mining optimization script for NVIDIA/AMD cards
+  - ✅ Add real-time sync monitor with visual progress bar
+  - ✅ Create network diagnostics tool with connectivity analysis
+
+- **Skills Integration**
+  - ✅ Enable automatic skill invocation based on context
+  - ✅ Add manual skill triggering with keyword detection
+  - ✅ Implement error handling and logging in all skills
+  - ✅ Create comprehensive documentation and usage examples
+
+## Stage 16 — Service Maintenance & Optimization [COMPLETED: 2026-01-21]
+
+- **Service Recovery**
+  - ✅ Diagnose and fix all failing AITBC container services
+  - ✅ Resolve duplicate service conflicts causing port binding errors
+  - ✅ Fix marketplace service implementation (missing server.py)
+  - ✅ Disable redundant services to prevent resource conflicts
+
+- **System Administration**
+  - ✅ Configure passwordless SSH access for automation
+  - ✅ Create dedicated SSH keys for secure service management
+  - ✅ Document service dependencies and port mappings
+  - ✅ Establish service monitoring procedures
+
+- **Service Status Verification**
+  - ✅ Verify all 7 core services running correctly
+  - ✅ Confirm proper nginx reverse proxy configuration
+  - ✅ Validate API endpoints accessibility
+  - ✅ Test service recovery procedures
+
+## Stage 17 — Ollama GPU Inference & CLI Tooling [COMPLETED: 2026-01-24]
+
+- **End-to-End Ollama Testing**
+  - ✅ Verify complete GPU inference workflow from job submission to receipt generation
+  - ✅ Test Ollama integration with multiple models (llama3.2, mistral, deepseek, etc.)
+  - ✅ Validate job lifecycle: QUEUED → RUNNING → COMPLETED
+  - ✅ Confirm receipt generation with accurate payment calculations
+  - ✅ Record transactions on blockchain with proper metadata
+
+- **Coordinator API Bug Fixes**
+  - ✅ Fix missing `_coerce_float()` helper function causing 500 errors
+  - ✅ Deploy fix to production incus container via SSH
+  - ✅ Verify result submission returns 200 OK with valid receipts
+  - ✅ Validate receipt payload structure and signature generation
+
+- **Miner Configuration & Optimization**
+  - ✅ Fix miner ID mismatch (host-gpu-miner → REDACTED_MINER_KEY)
+  - ✅ Enhance logging with explicit flush handlers for systemd journal
+  - ✅ Configure unbuffered Python logging environment variables
+  - ✅ Create systemd service unit with proper environment configuration
+
+- **CLI Tooling Development**
+  - ✅ Create unified bash CLI wrapper (`scripts/aitbc-cli.sh`)
+  - ✅ Implement commands: submit, status, browser, blocks, receipts, cancel
+  - ✅ Add admin commands: admin-miners, admin-jobs, admin-stats
+  - ✅ Support environment variable overrides for URL and API keys
+  - ✅ Make script executable and document usage patterns
+
+- **Blockchain-Operations Skill Enhancement**
+  - ✅ Add comprehensive Ollama testing scenarios to skill
+  - ✅ Create detailed test documentation (`ollama-test-scenario.md`)
+  - ✅ Document common issues and troubleshooting procedures
+  - ✅ Add performance metrics and expected results
+  - ✅ Include end-to-end automation script template
+
+- **Documentation Updates**
+  - ✅ Update localhost testing scenario with CLI wrapper usage
+  - ✅ Convert examples to use localhost URLs (127.0.0.1)
+  - ✅ Add host user paths and quick start commands
+  - ✅ Document complete workflow from setup to verification
+  - ✅ Update skill documentation with testing scenarios
+
+## Stage 18 — Repository Reorganization & CSS Consolidation [COMPLETED: 2026-01-24]
+
+- **Root Level Cleanup**
+  - ✅ Move 60+ loose files from root to proper directories
+  - ✅ Organize deployment scripts into `scripts/deploy/`
+  - ✅ Organize GPU miner files into `scripts/gpu/`
+  - ✅ Organize test/verify files into `scripts/test/`
+  - ✅ Organize service management scripts into `scripts/service/`
+  - ✅ Move systemd services to `systemd/`
+  - ✅ Move nginx configs to `infra/nginx/`
+  - ✅ Move dashboards to `website/dashboards/`
+
+- **Website/Docs Folder Structure**
+  - ✅ Establish `/website/docs/` as source for HTML documentation
+  - ✅ Create shared CSS file (`css/docs.css`) with 1232 lines
+  - ✅ Create theme toggle JavaScript (`js/theme.js`)
+  - ✅ Migrate all HTML files to use external CSS (45-66% size reduction)
+  - ✅ Clean `/docs/` folder to only contain mkdocs markdown files
+
+- **Documentation Styling Fixes**
+  - ✅ Fix dark theme background consistency across all docs pages
+  - ✅ Add dark theme support to `full-documentation.html`
+  - ✅ Fix Quick Start section cascade styling in docs-miners.html
+  - ✅ Fix SDK Examples cascade indentation in docs-clients.html
+  - ✅ Fix malformed `</code-block>` tags across all docs
+  - ✅ Update API endpoint example to use Python/FastAPI
+
+- **Path Reference Updates**
+  - ✅ Update systemd service file with new `scripts/gpu/gpu_miner_host.py` path
+  - ✅ Update skill documentation with new file locations
+  - ✅ Update localhost-testing-scenario.md with correct paths
+  - ✅ Update gpu_miner_host_wrapper.sh with new path
+
+- **Repository Maintenance**
+  - ✅ Expand .gitignore from 39 to 145 lines with organized sections
+  - ✅ Add project-specific ignore rules for coordinator, explorer, GPU miner
+  - ✅ Document final folder structure in done.md
+  - ✅ Create `docs/files.md` file audit with whitelist/greylist/blacklist
+  - ✅ Remove 35 abandoned/duplicate folders and files
+  - ✅ Reorganize `docs/` folder - root contains only done.md, files.md, roadmap.md
+  - ✅ Move 25 doc files to appropriate subfolders (components, deployment, migration, etc.)
+
+## Stage 19 — Placeholder Content Development [PLANNED]
+
+Fill the intentional placeholder folders with actual content. Priority order based on user impact.
+
+### Phase 1: Documentation (High Priority)
+
+- **User Guides** (`docs/user/guides/`)
+  - [ ] Getting started guide for new users
+  - [ ] Wallet setup and management
+  - [ ] Job submission workflow
+  - [ ] Payment and receipt understanding
+  - [ ] Troubleshooting common issues
+
+- **Developer Tutorials** (`docs/developer/tutorials/`)
+  - [ ] Building a custom miner
+  - [ ] Integrating with Coordinator API
+  - [ ] Creating marketplace extensions
+  - [ ] Working with ZK proofs
+  - [ ] SDK usage examples (Python/JS)
+
+- **Reference Specs** (`docs/reference/specs/`)
+  - [ ] Receipt JSON schema specification
+  - [ ] API endpoint reference (OpenAPI)
+  - [ ] Protocol message formats
+  - [ ] Error codes and handling
+
+### Phase 2: Infrastructure (Medium Priority)
+
+- **Terraform Environments** (`infra/terraform/environments/`)
+  - [ ] `staging/` - Staging environment config
+  - [ ] `prod/` - Production environment config
+  - [ ] Variables and secrets management
+  - [ ] State backend configuration
+
+- **Helm Chart Values** (`infra/helm/values/`)
+  - [ ] `dev/` - Development values
+  - [ ] `staging/` - Staging values
+  - [ ] `prod/` - Production values
+  - [ ] Resource limits and scaling policies
+
+### Phase 3: Application Components (Lower Priority)
+
+- **Pool Hub Service** (`apps/pool-hub/src/app/`)
+  - [ ] `routers/` - API route handlers
+  - [ ] `registry/` - Miner registry implementation
+  - [ ] `scoring/` - Scoring engine logic
+
+- **Coordinator Migrations** (`apps/coordinator-api/migrations/`)
+  - [ ] Initial schema migration
+  - [ ] Index optimizations
+  - [ ] Data migration scripts
+
+### Placeholder Filling Schedule
+
+| Folder | Target Date | Owner | Status |
+|--------|-------------|-------|--------|
+| `docs/user/guides/` | Q1 2026 | Documentation | 🔄 Planned |
+| `docs/developer/tutorials/` | Q1 2026 | Documentation | 🔄 Planned |
+| `docs/reference/specs/` | Q1 2026 | Documentation | 🔄 Planned |
+| `infra/terraform/environments/` | Q2 2026 | DevOps | 🔄 Planned |
+| `infra/helm/values/` | Q2 2026 | DevOps | 🔄 Planned |
+| `apps/pool-hub/src/app/` | Q2 2026 | Backend | 🔄 Planned |
+| `apps/coordinator-api/migrations/` | As needed | Backend | 🔄 Planned |
+
+## Stage 20 — Technical Debt Remediation [PLANNED]
+
+Address known issues in existing components that are blocking production use.
+
+### Blockchain Node (`apps/blockchain-node/`)
+
+Current Status: Has 9 Python files but SQLModel/SQLAlchemy compatibility issues.
+
+- **SQLModel Compatibility**
+  - [ ] Audit current SQLModel schema definitions in `models.py`
+  - [ ] Fix relationship and foreign key wiring issues
+  - [ ] Resolve Alembic migration compatibility
+  - [ ] Add integration tests for database operations
+  - [ ] Document schema and migration procedures
+
+- **Production Readiness**
+  - [ ] Fix PoA consensus loop stability
+  - [ ] Harden RPC endpoints for production load
+  - [ ] Add proper error handling and logging
+  - [ ] Create deployment documentation
+
+### Solidity Token (`packages/solidity/aitbc-token/`)
+
+Current Status: Smart contracts exist but not deployed to mainnet.
+
+- **Contract Audit**
+  - [ ] Review AIToken.sol and AITokenRegistry.sol
+  - [ ] Run security analysis (Slither, Mythril)
+  - [ ] Fix any identified vulnerabilities
+  - [ ] Add comprehensive test coverage
+
+- **Deployment Preparation**
+  - [ ] Configure deployment scripts for testnet
+  - [ ] Deploy to testnet and verify
+  - [ ] Document deployment process
+  - [ ] Plan mainnet deployment timeline
+
+### ZK Receipt Verifier (`contracts/ZKReceiptVerifier.sol`)
+
+Current Status: 240-line Groth16 verifier contract ready for deployment.
+
+- **Integration with ZK Circuits**
+  - [ ] Verify compatibility with deployed `receipt_simple` circuit
+  - [ ] Test proof generation and verification flow
+  - [ ] Configure settlement contract integration
+  - [ ] Add authorized verifier management
+
+- **Deployment**
+  - [ ] Deploy to testnet with ZK circuits
+  - [ ] Integration test with Coordinator API
+  - [ ] Document on-chain verification flow
+
+### Receipt Specification (`docs/reference/specs/receipt-spec.md`)
+
+Current Status: Canonical receipt schema specification moved from `protocols/receipts/`.
+
+- **Specification Finalization**
+  - [x] Core schema defined (version 1.0)
+  - [x] Signature format specified (Ed25519)
+  - [x] Validation rules documented
+  - [ ] Add multi-signature receipt format
+  - [ ] Document ZK-proof metadata extension
+  - [ ] Add Merkle proof anchoring spec
+
+### Technical Debt Schedule
+
+| Component | Priority | Target | Status |
+|-----------|----------|--------|--------|
+| `apps/blockchain-node/` SQLModel fixes | Medium | Q2 2026 | 🔄 Planned |
+| `packages/solidity/aitbc-token/` audit | Low | Q3 2026 | 🔄 Planned |
+| `packages/solidity/aitbc-token/` testnet | Low | Q3 2026 | 🔄 Planned |
+| `contracts/ZKReceiptVerifier.sol` deploy | Low | Q3 2026 | 🔄 Planned |
+| `docs/reference/specs/receipt-spec.md` finalize | Low | Q2 2026 | 🔄 Planned |
+
+the canonical checklist during implementation. Mark completed tasks with ✅ and add dates or links to relevant PRs as development progresses.
+

docs/user-guide/creating-jobs.md

@@ -1,49 +0,0 @@
----
-title: Creating Jobs
-description: Learn how to create and submit AI jobs
----
-
-# Creating Jobs
-
-Jobs are the primary way to execute AI workloads on the AITBC platform.
-
-## Job Types
-
-- **AI Inference**: Run pre-trained models
-- **Model Training**: Train new models
-- **Data Processing**: Process datasets
-- **Custom**: Custom computations
-
-## Job Specification
-
-A job specification includes:
-- Model configuration
-- Input/output formats
-- Resource requirements
-- Pricing constraints
-
-## Example
-
-```yaml
-name: "image-classification"
-type: "ai-inference"
-model:
-  type: "python"
-  entrypoint: "model.py"
-```
-
-## Submitting Jobs
-
-Use the CLI or API to submit jobs:
-
-```bash
-aitbc job submit job.yaml
-```
-
-## Monitoring
-
-Track job progress through:
-- CLI commands
-- Web interface
-- API endpoints
-- WebSocket streams

docs/user-guide/explorer.md

@@ -1,49 +0,0 @@
----
-title: Explorer
-description: Using the AITBC blockchain explorer
----
-
-# Explorer
-
-The AITBC explorer allows you to browse and search the blockchain for transactions, jobs, and other activities.
-
-## Features
-
-### Transaction Search
-- Search by transaction hash
-- Filter by address
-- View transaction details
-
-### Job Tracking
-- Monitor job status
-- View job history
-- Analyze performance
-
-### Analytics
-- Network statistics
-- Volume metrics
-- Activity charts
-
-## Using the Explorer
-
-### Web Interface
-Visit [https://aitbc.bubuit.net/explorer/](https://aitbc.bubuit.net/explorer/)
-
-### API Access
-```bash
-# Get transaction
-curl https://aitbc.bubuit.net/api/v1/transactions/{tx_hash}
-
-# Get job details
-curl https://aitbc.bubuit.net/api/v1/jobs/{job_id}
-
-# Explorer data (blocks)
-curl https://aitbc.bubuit.net/api/explorer/blocks
-```
-
-## Advanced Features
-
-- Real-time updates
-- Custom dashboards
-- Data export
-- Alert notifications

docs/user-guide/marketplace.md

@@ -1,46 +0,0 @@
----
-title: Marketplace
-description: Using the AITBC marketplace
----
-
-# Marketplace
-
-The AITBC marketplace connects job creators with miners who can execute their AI workloads.
-
-## How It Works
-
-1. **Job Creation**: Users create jobs with specific requirements
-2. **Offer Matching**: The marketplace finds suitable miners
-3. **Execution**: Miners execute the jobs and submit results
-4. **Payment**: Automatic payment upon successful completion
-
-## Finding Services
-
-Browse available services:
-- By job type
-- By price range
-- By miner reputation
-- By resource requirements
-
-## Pricing
-
-Dynamic pricing based on:
-- Market demand
-- Resource availability
-- Miner reputation
-- Job complexity
-
-## Creating Offers
-
-As a miner, you can:
-- Set your prices
-- Specify job types
-- Define resource limits
-- Build reputation
-
-## Safety Features
-
-- Escrow payments
-- Dispute resolution
-- Reputation system
-- Cryptographic proofs

docs/user-guide/overview.md

@@ -1,27 +0,0 @@
----
-title: User Guide Overview
-description: Learn how to use AITBC as a user
----
-
-# User Guide Overview
-
-Welcome to the AITBC user guide! This section will help you understand how to interact with the AITBC platform.
-
-## What You'll Learn
-
-- Creating and submitting AI jobs
-- Using the marketplace
-- Managing your wallet
-- Monitoring your jobs
-- Understanding receipts and proofs
-
-## Getting Started
-
-If you're new to AITBC, start with the [Quickstart Guide](../getting-started/quickstart.md).
-
-## Navigation
-
-- [Creating Jobs](creating-jobs.md) - Learn to submit AI workloads
-- [Marketplace](marketplace.md) - Buy and sell AI services
-- [Explorer](explorer.md) - Browse the blockchain
-- [Wallet Management](wallet-management.md) - Manage your funds

docs/user-guide/wallet-management.md

@@ -1,65 +0,0 @@
----
-title: Wallet Management
-description: Managing your AITBC wallet
----
-
-# Wallet Management
-
-Your AITBC wallet allows you to store, send, and receive AITBC tokens and interact with the platform.
-
-## Creating a Wallet
-
-### New Wallet
-```bash
-aitbc wallet create
-```
-
-### Import Existing
-```bash
-aitbc wallet import <private_key>
-```
-
-## Wallet Operations
-
-### Check Balance
-```bash
-aitbc wallet balance
-```
-
-### Send Tokens
-```bash
-aitbc wallet send <address> <amount>
-```
-
-### Transaction History
-```bash
-aitbc wallet history
-```
-
-## Security
-
-- Never share your private key
-- Use a hardware wallet for large amounts
-- Enable two-factor authentication
-- Keep backups in secure locations
-
-## Staking
-
-Earn rewards by staking your tokens:
-```bash
-aitbc wallet stake <amount>
-```
-
-## Backup
-
-Always backup your wallet:
-```bash
-aitbc wallet backup --output wallet.backup
-```
-
-## Recovery
-
-Restore from backup:
-```bash
-aitbc wallet restore --input wallet.backup
-```