Hoox Trading System — Complete Setup & Operations Guide

CLI: @hoox-sh/hoox-cli 0.13.x (hoox / hx)
Last Updated: 2026-08-13
Classification: Internal Operations Manual
Audience: DevOps Engineers, Senior TypeScript Developers, System Administrators

---

Table of Contents

1. System Overview
2. Pre-Flight Requirements
3. Complete Environment Matrix
4. Development Setup
5. Production Setup
6. Infrastructure Provisioning
7. Worker Deployment Sequence
8. Dashboard Setup & Deployment
9. Secret Management Reference
10. Validation & Health Checks
11. Repair & Recovery Procedures
12. Operational Runbook
13. Complete File Inventory
14. Troubleshooting Matrix

---

1. System Overview

1.1 Architecture

Hoox is an edge-deployed cryptocurrency trading system built on Cloudflare® Workers. It consists of 11 compute surfaces (10 workers + dashboard):

1.2 Communication Flow

External Webhook → hoox → [Queue] → trade-worker → D1 (via d1-worker)
                        ↓
                  telegram-worker (notifications)
                        ↓
                  analytics-worker (metrics)

agent-worker (cron) → trade-worker / d1-worker / telegram-worker
email-worker → trade-worker
pyne-worker (cron /run) → trade-worker (mesh internal auth on live forward)

1.3 Infrastructure Components

---

2. Pre-Flight Requirements

2.1 Required Accounts

2.2 Required Tools

2.3 Required Cloudflare® Permissions

Your Cloudflare® API Token needs these permissions:

2.4 Required Repository Access

You need access to clone with submodules:

# Main repository
git clone --recursive https://github.com/hoox-sh/hoox.git

# Or via CLI
hoox clone my-hoox-app

---

3. Complete Environment Matrix

3.1 Secret Inventory

3.2 Environment Variables by File

.env.local (Project Root)

# === CLOUDFLARE ACCOUNT ===
CLOUDFLARE_API_TOKEN="cfut_..."
CLOUDFLARE_ACCOUNT_ID="debc6545e63bea36be059cbc82d80ec8"
CLOUDFLARE_SECRET_STORE_ID="48433bc559a943f09d9d6c622e188fd5"
SUBDOMAIN_PREFIX="hoox"

# === INTERNAL AUTH KEYS ===
D1_INTERNAL_KEY="<generate-secure-random-string>"
TRADE_INTERNAL_KEY="<generate-secure-random-string>"
AGENT_INTERNAL_KEY="<generate-secure-random-string>"

# === TELEGRAM ===
TELEGRAM_BOT_TOKEN="<your-bot-token>"

# === AI PROVIDERS (optional) ===
AGENT_OPENAI_KEY="sk-..."
AGENT_ANTHROPIC_KEY="sk-ant-..."
AGENT_GOOGLE_KEY="..."

# === EXCHANGE API KEYS (optional) ===
BINANCE_API_KEY="..."
BINANCE_API_SECRET="..."
MEXC_API_KEY="..."
MEXC_API_SECRET="..."
BYBIT_API_KEY="..."
BYBIT_API_SECRET="..."

# === DASHBOARD AUTH ===
DASHBOARD_USER="admin"
DASHBOARD_PASS="<secure-password>"
SESSION_SECRET="<32-character-secure-random-string>"

workers/dashboard/.env.local (Dashboard Local Dev)

DASHBOARD_USER=admin
DASHBOARD_PASS=admin

workers/dashboard/.dev.vars (Wrangler Dev Mode)

DASHBOARD_USER=admin
DASHBOARD_PASS=admin

wrangler.jsonc (Central Configuration)

{
  "global": {
    "cloudflare_api_token": "<USE_WRANGLER_SECRET_PUT>",
    "cloudflare_account_id": "debc6545e63bea36be059cbc82d80ec8",
    "cloudflare_secret_store_id": "48433bc559a943f09d9d6c622e188fd5",
    "subdomain_prefix": "hoox",
  },
  "workers": {
    "d1-worker": {
      "enabled": true,
      "path": "workers/d1-worker",
      "vars": { "database_name": "my-database" },
    },
    "telegram-worker": {
      "enabled": true,
      "path": "workers/telegram-worker",
      "vars": {},
      "secrets": ["TELEGRAM_BOT_TOKEN"],
    },
    "trade-worker": {
      "enabled": true,
      "path": "workers/trade-worker",
      "vars": {},
      "secrets": [
        "API_SERVICE_KEY",
        "BINANCE_API_KEY",
        "BINANCE_API_SECRET",
        "MEXC_API_KEY",
        "MEXC_API_SECRET",
        "BYBIT_API_KEY",
        "BYBIT_API_SECRET",
      ],
    },
    "web3-wallet-worker": {
      "enabled": true,
      "path": "workers/web3-wallet-worker",
      "vars": {},
      "secrets": ["WALLET_MNEMONIC_SECRET", "WALLET_PK_SECRET"],
    },
    "hoox": {
      "enabled": true,
      "path": "workers/hoox-worker",
      "vars": {},
      "secrets": ["WEBHOOK_API_KEY_BINDING"],
    },
    "agent-worker": {
      "enabled": true,
      "path": "workers/agent-worker",
      "vars": {},
      "secrets": ["AGENT_INTERNAL_KEY"],
    },
    "email-worker": {
      "enabled": true,
      "path": "workers/email-worker",
      "vars": { "USE_IMAP": "false" },
      "secrets": ["EMAIL_HOST", "EMAIL_USER", "EMAIL_PASS", "INTERNAL_KEY"],
    },
    "analytics-worker": {
      "enabled": true,
      "path": "workers/analytics-worker",
      "vars": {},
      "secrets": ["CLOUDFLARE_API_TOKEN"],
    },
  },
  "dev": {
    "runtime": "native", // "native" (wrangler) or "docker" (compose) — hoox dev start preference
  },
}

3.3 KV Configuration Keys

These keys must be set in CONFIG_KV namespace:

---

4. Development Setup

4.1 Step 1: Clone Repository

# Option A: Via CLI (Recommended)
hoox clone my-hoox-app
cd my-hoox-app

# Option B: Direct git clone
git clone --recursive https://github.com/hoox-sh/hoox.git my-hoox-app
cd my-hoox-app

# If submodules are missing
git submodule update --init --recursive

4.2 Step 2: Verify Submodules

# Check all worker directories exist
bun run check:worker-submodules

# Expected directories (submodules + dashboard):
# workers/hoox-worker
# workers/trade-worker
# workers/agent-worker
# workers/d1-worker
# workers/telegram-worker
# workers/web3-wallet-worker
# workers/email-worker
# workers/analytics-worker
# workers/report-worker
# workers/pyne-worker
# workers/dashboard

4.3 Step 3: Install Dependencies

# Install all workspace dependencies
bun install

# Verify installation
bun run lint        # ESLint check
bun run typecheck   # TypeScript check

4.4 Step 4: Configure Local Environment

# Copy environment template
cp .env.example .env.local

# Edit .env.local with your values
# At minimum, set:
# - CLOUDFLARE_API_TOKEN
# - CLOUDFLARE_ACCOUNT_ID
# - SUBDOMAIN_PREFIX

4.5 Step 5: Authenticate Wrangler

# Login to Cloudflare
wrangler login

# Verify authentication
wrangler whoami

4.6 Step 6: Create Infrastructure (Local)

For local development, some infrastructure is optional. You need:

Required:

• D1 database (for trade data)
• KV namespace (for config)

Optional for local dev:

• R2 buckets
• Queues
• Vectorize
• Analytics Engine

# Create D1 database
wrangler d1 create trade-data-db

# Create KV namespace
wrangler kv:namespace create CONFIG_KV
wrangler kv:namespace create SESSIONS_KV

# Note the IDs and update wrangler.jsonc files

4.7 Step 7: Apply Database Schema

# Apply trade worker schema to D1
wrangler d1 execute trade-data-db --file=workers/trade-worker/schema.sql

# Apply tracking schema
bun run migrate:tracking

4.8 Step 8: Start Development

# Start all workers (prompts for runtime: Native or Docker)
hoox dev start

# Or force a specific runtime
hoox dev start --runtime docker   # docker compose
hoox dev start --runtime native   # wrangler dev

# Docker Compose directly (with profiles)
docker compose --profile workers up        # workers only
docker compose --profile full up           # workers + dashboard
docker compose --profile dashboard up      # dashboard only

# Or start individual workers
hoox dev worker <name> [--runtime native|docker]
hoox dev dashboard                         # dashboard only

# TUI (interactive terminal UI)
./hoox-tui

4.9 Step 9: Dashboard Local Dev

# Start dashboard dev server
hoox dev dashboard

# Or manually
cd workers/dashboard && bun run dev

The dashboard runs at http://localhost:3000.

---

5. Production Setup

5.1 Phase 1: Account & Tooling

1. Create Cloudflare® account
2. Generate API Token with required permissions (see Section 2.3)
3. Install Bun ≥1.2 and @hoox-sh/hoox-cli (bun add -g @hoox-sh/hoox-cli)
4. Authenticate: wrangler login (or set CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID)

5.2 Phase 2: Repository Setup

# Preferred one-shot (from monorepo root — path is remembered for later hx)
git clone --recursive https://github.com/hoox-sh/hoox.git
cd hoox
bun install
hoox doctor                   # Remembered + Runtime root
hoox onboard                  # init + setup (auth, keys, D1, secrets, dashboard)

# Or manual clone / verify
bun run check:worker-submodules

5.3 Phase 3: Infrastructure Provisioning

hoox onboard / hoox setup and hoox infra cover D1/KV/R2/queues for typical installs. See Section 6 for raw wrangler equivalents.

5.4 Phase 4: Configuration

# Interactive config (writes wrangler.jsonc)
hoox init
# Or edit wrangler.jsonc / .env.local after onboard:
# - cloudflare_account_id, subdomain_prefix, enabled workers

5.5 Phase 5: Secret Deployment

# Push mesh/system secrets only (recommended after key rotation)
hoox secrets sync --system
# Alias: hoox secrets sync --required

# Or push all declared secrets from .dev.vars
# (reports partial sync: synced / skipped placeholders / failed)
hoox secrets sync

# Or set individually per worker:
hoox secrets set hoox WEBHOOK_API_KEY_BINDING
wrangler secret put WEBHOOK_API_KEY_BINDING --config workers/hoox-worker/wrangler.jsonc

5.6 Phase 6: Database Setup

# Preferred
hoox setup --skip-keys --skip-secrets --skip-dashboard
# or: hoox db apply (when using db command group)

# Manual
wrangler d1 execute trade-data-db --file=workers/trade-worker/schema.sql --remote
bun run migrate:tracking

5.7 Phase 7: KV Configuration

# Manifest-driven (when configured)
hoox deploy kv-config

# Or set required KV keys manually
wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d \
  "webhook:tradingview:ip_check_enabled" "false"

wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d \
  "trade:kill_switch" "false"

wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d \
  "trade:max_daily_drawdown_percent" "10"

5.8 Phase 8: Worker Deployment

hoox deploy all --auto
# Order: see Section 7 (includes pyne-worker)

5.9 Phase 9: Dashboard Deployment

# Preferred (CLI)
hoox deploy dashboard
# or: hoox dashboard deploy

# Manual OpenNext path
cd workers/dashboard
bun run opennext:build
bun run opennext:deploy

5.10 Phase 10: Verification

See Section 10 for validation procedures.

---

6. Infrastructure Provisioning

6.1 D1 Database

# Create database
wrangler d1 create trade-data-db

# Note the database_id from output
# Update in:
# - workers/trade-worker/wrangler.jsonc
# - workers/d1-worker/wrangler.jsonc

# Apply schema
wrangler d1 execute trade-data-db --file=workers/trade-worker/schema.sql --remote

Schema Tables:

• trade_signals — Incoming signal tracker
• trades — Executed trades log
• positions — Active & closed positions
• balances — Exchange balance snapshots
• system_logs — System observability logs

6.2 KV Namespaces

# Create CONFIG_KV (shared across all workers)
wrangler kv:namespace create CONFIG_KV
# ID: c5917667a21745e390ff969f32b1847d

# Create SESSIONS_KV (for hoox gateway)
wrangler kv:namespace create SESSIONS_KV
# ID: ff70a58b492e45d79880a7a8213c745c

# Update all wrangler.jsonc files with these IDs

6.3 R2 Buckets

# Create trade reports bucket
wrangler r2 bucket create trade-reports

# Create system logs bucket
wrangler r2 bucket create hoox-system-logs

# Create user uploads bucket
wrangler r2 bucket create user-uploads

6.4 Queue

# Create trade execution queue
wrangler queues create trade-execution

6.5 Vectorize Index

# Create RAG vector index
wrangler vectorize create my-rag-index --dimensions=768 --metric=cosine

6.6 Analytics Engine

# Create analytics dataset
# Via Cloudflare Dashboard: Workers & Pages > Analytics Engine
# Name: hoox-analytics

6.7 Durable Objects Migration

The hoox worker requires Durable Object migrations (v1 + v2):

// Already defined in workers/hoox-worker/wrangler.jsonc(.example)
"durable_objects": {
  "bindings": [
    {
      "name": "IDEMPOTENCY_STORE",
      "class_name": "IdempotencyStore"
    },
    {
      "name": "RATE_LIMITER",
      "class_name": "RateLimiterStore"
    }
  ]
},
"migrations": [
  {
    "tag": "v1",
    "new_sqlite_classes": ["IdempotencyStore"]
  },
  {
    "tag": "v2",
    "new_sqlite_classes": ["RateLimiterStore"]
  }
]

Applied automatically on wrangler deploy / hoox deploy worker hoox. New tags run once per account/script. RATE_LIMITER is required for atomic multi-isolate rate limits; without the binding, the gateway falls back to CONFIG_KV / in-memory.

---

7. Worker Deployment Sequence

7.1 Deployment Order

Order used by the CLI when deploying all enabled workers:

1.  analytics-worker    (observability fan-in; few dependencies)
2.  d1-worker           (SQL hub)
3.  telegram-worker     (notifications)
4.  web3-wallet-worker  (DeFi identity)
5.  email-worker        (email signal ingress)
6.  trade-worker        (execution — needs d1 / telegram bindings)
7.  pyne-worker         (Pine Script™ tooling; live forward → trade-worker)
8.  report-worker       (PDF / Browser Rendering)
9.  agent-worker        (AI risk — needs trade / d1 / telegram)
10. hoox                (gateway — last worker so bindings resolve)
11. dashboard           (OpenNext UI — after services are live)

Unknown workers (not in the list) are appended before dashboard.

7.2 Deployment Commands

# Preferred: deploy all enabled workers + dashboard (CLI applies order)
hoox deploy all
hoox deploy all --auto          # non-interactive

# Workers only (skip dashboard)
hoox deploy workers

# One isolate
hoox deploy worker trade-worker
hoox deploy worker pyne-worker
# pyne also has vendor+deploy helper:
hoox pyne deploy                # sync-vendor then wrangler deploy

7.3 Post-Deployment: Telegram Webhook

# Preferred CLI helper
hoox deploy telegram-webhook
# or with explicit token:
hoox deploy telegram-webhook --token <TELEGRAM_BOT_TOKEN>

# Manual fallback
curl -X POST "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://telegram-worker.<SUBDOMAIN_PREFIX>.workers.dev/webhook",
    "secret_token": "<TELEGRAM_SECRET_TOKEN>"
  }'

7.4 Post-Deployment: Update Internal URLs

# Update service URLs in dashboard wrangler.jsonc
hoox deploy update-internal-urls

---

8. Dashboard Setup & Deployment

8.1 Configuration Files

8.2 Wrangler Configuration

// workers/dashboard/wrangler.jsonc
{
  "name": "hoox-dashboard",
  "main": ".open-next/worker.js",
  "account_id": "debc6545e63bea36be059cbc82d80ec8",
  "compatibility_date": "2026-04-17",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS",
  },
  "kv_namespaces": [
    {
      "binding": "CONFIG_KV",
      "id": "c5917667a21745e390ff969f32b1847d",
    },
  ],
  "vars": {
    "D1_WORKER_URL": "https://d1-worker.hoox.workers.dev",
    "AGENT_SERVICE_URL": "https://agent-worker.hoox.workers.dev",
    "TRADE_SERVICE_URL": "https://trade-worker.hoox.workers.dev",
    "TELEGRAM_SERVICE_URL": "https://telegram-worker.hoox.workers.dev",
  },
}

8.3 Local Development

cd workers/dashboard

# Install dashboard dependencies (if not done at root)
bun install

# Set credentials
cp .env.local.example .env.local
# Edit: DASHBOARD_USER, DASHBOARD_PASS

# Start dev server
bun run dev
# Access: http://localhost:3000

8.4 Production Build & Deploy

cd workers/dashboard

# Install dependencies
bun install

# Build with OpenNext
bun run opennext:build
# Output: .open-next/worker.js and .open-next/assets

# Deploy to Cloudflare Workers
bun run opennext:deploy

# Or from root:
bun run pages:deploy

8.5 Dashboard Environment Variables

---

9. Secret Management Reference

9.1 Setting Secrets via CLI

# Set a secret for a specific worker
wrangler secret put <SECRET_NAME> --config workers/<worker>/wrangler.jsonc
# You will be prompted to enter the value (hidden input)

# Set one secret via hoox CLI (writes .dev.vars + puts to Cloudflare)
hoox secrets set <WORKER_NAME> <SECRET_NAME>

# Sync mesh/system secrets only (INTERNAL_KEY_BINDING, WEBHOOK_*, …)
hoox secrets sync --system
# Alias: hoox secrets sync --required

# Sync all declared secrets from .dev.vars
# Partial results report synced / skipped (placeholders) / failed
hoox secrets sync
hoox secrets sync trade-worker

9.2 Local Development Secrets

For local development with wrangler dev, create .dev.vars in each worker directory:

# workers/hoox-worker/.dev.vars
WEBHOOK_API_KEY_BINDING=dev-webhook-key
INTERNAL_KEY_BINDING=dev-internal-key

# workers/trade-worker/.dev.vars
INTERNAL_KEY_BINDING=dev-internal-key
MEXC_KEY_BINDING=dev-mexc-key
MEXC_SECRET_BINDING=dev-mexc-secret
# ... etc

9.3 Secret Security Best Practices

1. Never commit secrets — Use .gitignore for .env.local, .dev.vars, .keys/
2. Use wrangler secret put — Never pass secrets as CLI arguments
3. Rotate regularly — Exchange API keys every 90 days
4. Use least privilege — Create exchange API keys with minimal permissions
5. Enable IP restrictions — Restrict exchange API keys to Cloudflare IP ranges
6. Monitor usage — Review analytics-worker logs for unusual patterns

---

10. Validation & Health Checks

10.1 Automated Validation Commands

# Workspace / toolchain
hoox doctor                   # Remembered monorepo + runtime root
hoox check prerequisites      # bun, git, wrangler, CF auth
hoox check setup              # Config, infra, secrets, database

# Secrets inventory (names only)
hoox secrets list

# Worker health — single source of truth (GET /health per enabled worker)
hoox check health
hoox check health --json

# Specialist probes
hoox agent health
hoox pyne health              # pyne-worker GET /health

# Run tests
bun test
bun run tests:coverage

# Type checking
bun run typecheck
bun run build

# Lint
bun run lint

10.2 Manual Health Checks

Public liveness is GET /health on each isolate (unauthenticated). Prefer hoox check health over ad-hoc curls; the snippets below are for debugging.

10.2.1 Gateway Health

# Check hoox gateway
curl https://hoox.<SUBDOMAIN_PREFIX>.workers.dev/health

# Expected: {"status":"ok"} (or equivalent healthy JSON)

10.2.2 Trade Worker Health

# Check trade worker
curl https://trade-worker.<SUBDOMAIN_PREFIX>.workers.dev/health

# Protected signals endpoint (mesh / service key — not public)
curl https://trade-worker.<SUBDOMAIN_PREFIX>.workers.dev/api/signals \
  -H "X-Internal-Auth-Key: <INTERNAL_KEY_BINDING>"

10.2.3 Agent Worker Health

# Check agent health
curl https://agent-worker.<SUBDOMAIN_PREFIX>.workers.dev/health

# Or via CLI
hoox agent health

10.2.4 D1 Worker Health

curl https://d1-worker.<SUBDOMAIN_PREFIX>.workers.dev/health

# Authenticated SQL (mesh)
curl -X POST https://d1-worker.<SUBDOMAIN_PREFIX>.workers.dev/query \
  -H "Content-Type: application/json" \
  -H "X-Internal-Auth-Key: <INTERNAL_KEY_BINDING>" \
  --data '{"query":"SELECT 1"}'

10.2.5 Telegram Worker Health

curl https://telegram-worker.<SUBDOMAIN_PREFIX>.workers.dev/health

10.2.6 Analytics Worker Health

curl https://analytics-worker.<SUBDOMAIN_PREFIX>.workers.dev/health

10.2.7 PYNE Worker Health

# Tooling isolate — public /health; evaluate routes need X-API-Key
curl https://pyne-worker.<SUBDOMAIN_PREFIX>.workers.dev/health
hoox pyne health
# or: hoox pyne health --url https://pyne-worker.<SUBDOMAIN_PREFIX>.workers.dev

10.2.8 Dashboard Health

# Check dashboard (OpenNext worker URL depends on wrangler name)
curl https://hoox-dashboard.<SUBDOMAIN_PREFIX>.workers.dev/api/health

10.3 Database Validation

# List tables
wrangler d1 execute trade-data-db --command="SELECT name FROM sqlite_master WHERE type='table'" --remote

# Check trade_signals count
wrangler d1 execute trade-data-db --command="SELECT COUNT(*) FROM trade_signals" --remote

# Check recent logs
wrangler d1 execute trade-data-db --command="SELECT * FROM system_logs ORDER BY timestamp DESC LIMIT 10" --remote

10.4 KV Validation

# List KV keys
wrangler kv:key list --namespace-id=c5917667a21745e390ff969f32b1847d

# Check kill switch
wrangler kv:key get --namespace-id=c5917667a21745e390ff969f32b1847d "trade:kill_switch"

10.5 Complete System Validation Checklist

• All enabled workers return healthy from hoox check health (GET /health)
• D1 database has all required tables
• KV namespace has required configuration keys
• Secrets are set for all enabled workers (hoox secrets list / hoox check setup)
• Service bindings resolve correctly (no 502/503 errors)
• Queue is configured and consumer is registered
• Telegram webhook is set and responding (hoox deploy telegram-webhook)
• Dashboard accessible and authenticated
• Analytics Engine receiving data points
• If enabled: hoox pyne health OK; API_KEY set for production evaluate routes
• Cron triggers scheduled (agent-worker: 1–1440 min via triggers.crons, default 15 min; pyne-worker: * * * * * bar-close)

---

11. Repair & Recovery Procedures

11.1 Complete System Repair Checklist

# 1. Verify repository integrity
bun run check:worker-submodules
bun run lint:scripts

# 2. Verify dependencies
bun install

# 3. Verify TypeScript
bun run typecheck

# 4. Verify tests
bun test

# 5. Verify infrastructure exists
wrangler d1 list
wrangler kv:namespace list
wrangler r2 bucket list
wrangler queues list
wrangler vectorize list

# 6. Verify secrets
hoox secrets list

# 7. Verify worker health
hoox check health

# 8. Redeploy if needed
hoox deploy workers

11.2 Individual Worker Repair

# Redeploy a single worker
hoox deploy worker <worker-name>

# Check worker logs
hoox workers logs <worker-name>
# or: hoox logs worker <worker-name>

# Tail logs in real-time
wrangler tail --config workers/<worker-name>/wrangler.jsonc

11.3 Database Repair

# Reset database schema (WARNING: Destructive)
wrangler d1 execute trade-data-db --file=workers/trade-worker/schema.sql --remote

# Apply tracking schema
bun run migrate:tracking

# Check for missing tables
wrangler d1 execute trade-data-db --command="SELECT name FROM sqlite_master WHERE type='table'" --remote

11.4 Secret Repair

# If mesh keys are missing after rotation, re-upload system secrets only
hoox secrets sync --system

# Or re-upload all declared secrets from .dev.vars (partial sync reported)
hoox secrets sync

# Or set individual secrets
wrangler secret put <SECRET_NAME> --config workers/<worker>/wrangler.jsonc
hoox secrets set <WORKER_NAME> <SECRET_NAME>

11.5 KV Configuration Repair

# Reset critical KV keys
wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d "trade:kill_switch" "false"
wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d "webhook:tradingview:ip_check_enabled" "false"
wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d "trade:max_daily_drawdown_percent" "10"

11.6 Dashboard Repair

cd workers/dashboard

# Rebuild
bun run opennext:build

# Redeploy
bun run opennext:deploy

# Clear browser cache and cookies if auth issues

11.7 Complete Rebuild from Scratch

# 1. Backup any important data from D1/R2

# 2. Delete and recreate D1
wrangler d1 delete trade-data-db
wrangler d1 create trade-data-db

# 3. Delete and recreate KV (note: data loss)
# KV namespaces cannot be renamed, create new ones if needed

# 4. Redeploy all workers + dashboard (CLI order)
hoox deploy all --auto

# 5. Re-apply schema
wrangler d1 execute trade-data-db --file=workers/trade-worker/schema.sql --remote

# 6. Reconfigure KV
# Set all required keys (see Section 3.3) or: hoox deploy kv-config

# 7. Reconfigure Telegram webhook
hoox deploy telegram-webhook

# 8. Redeploy dashboard alone (if needed)
hoox deploy dashboard

---

12. Operational Runbook

12.1 Daily Operations

# Check system health
hoox check health

# Check recent trades
wrangler d1 execute trade-data-db --command="SELECT * FROM trades ORDER BY timestamp DESC LIMIT 5" --remote

# Check system logs
wrangler d1 execute trade-data-db --command="SELECT * FROM system_logs ORDER BY timestamp DESC LIMIT 20" --remote

12.2 Kill Switch Operations

# Emergency stop all trading
wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d "trade:kill_switch" "true"

# Resume trading
wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d "trade:kill_switch" "false"

12.3 Updating Workers

# Pull latest code
git pull --recurse-submodules

# Update dependencies
bun install

# Run checks
bun run lint
bun run typecheck
bun test

# Deploy updated workers
hoox deploy workers

# Verify deployment
hoox check health

12.4 Rotating Secrets

# Generate new internal/mesh keys (writes to .keys/ and .dev.vars)
hoox keys generate

# Push mesh/system secrets only to Cloudflare
hoox secrets sync --system

# Or rotate a single integration secret
hoox secrets set <WORKER_NAME> <SECRET_NAME>

# Verify functionality
bun test

12.5 Monitoring

12.6 Backup Procedures

# Export D1 database
wrangler d1 export trade-data-db --output=backup-$(date +%Y%m%d).sql --remote

# Export KV (manual script needed)
# R2 buckets can be synced with rclone

---

13. Complete File Inventory

13.1 Required Configuration Files

13.2 Worker Configuration Files

13.3 Dashboard Files

13.4 Package Files

13.5 Script Files

13.6 Documentation Files

---

14. Troubleshooting Matrix

---

Appendix A: Quick Reference Commands

# Setup
bun install
hoox onboard                  # One-shot full bootstrap (recommended)
hoox secrets sync --system    # Push mesh/system secrets only
hoox secrets sync             # Push all .dev.vars (partial reporting)

# Development
hoox dev start                # Start all workers (choose runtime)
hoox dashboard dev            # Dashboard only
hoox tui                      # Interactive TUI
hoox workers dev <name>       # Dev single worker
bun run dev                   # Dashboard dev

# Testing
bun test                      # Unit tests
bun run tests:coverage        # Coverage
bun run test:integration      # Integration tests

# Deployment
hoox deploy all               # Workers + dashboard (ordered)
hoox deploy workers           # Deploy enabled workers only
hoox deploy worker <name>     # Deploy one worker
hoox deploy dashboard         # Deploy dashboard
# OR: hoox dashboard deploy
hoox pyne deploy              # Vendor pynescript + deploy pyne-worker

# Operations
hoox doctor                   # Paths / remembered monorepo / TUI entry
hoox check health             # Worker health (GET /health; single source of truth)
hoox workers logs <name>      # View worker logs
hoox check setup              # Validate setup
hoox secrets list <worker>    # Check secrets
hoox secrets sync --system    # Mesh keys only
hoox secrets sync             # All .dev.vars (partial reporting)

# Database
wrangler d1 execute trade-data-db --file=workers/trade-worker/schema.sql --remote
bun run migrate:tracking

# KV
wrangler kv:key put --namespace-id=<ID> <key> <value>
wrangler kv:key list --namespace-id=<ID>

# Secrets
wrangler secret put <NAME> --config workers/<worker>/wrangler.jsonc
hoox secrets sync --system        # mesh keys only
hoox secrets sync                 # all from .dev.vars (partial reporting)

# Health Checks
curl https://<worker>.<prefix>.workers.dev/health

Appendix B: Directory Structure

hoox/
├── .opencode/                    # Project intelligence hub
├── .env.local                    # Local environment (gitignored)
├── .env.example                  # Environment template
├── wrangler.jsonc                 # Central worker config
├── package.json                  # Root workspace manifest
├── bunfig.toml                   # Bun config
├── tsconfig.json                 # TypeScript config
├── vitest.config.ts              # Vitest config
├── hoox-tui                      # TUI launcher (if exists)
│
├── packages/
│   ├── cli/                      # @hoox-sh/hoox-cli (hoox / hx)
│   │   ├── bin/hoox.js           # CLI entry
│   │   └── src/
│   │       ├── index.ts          # Command dispatcher
│   │       ├── commands/         # CLI commands
│   │       ├── services/         # setup, secrets, workspace, CF, …
│   │       ├── ui/               # Interactive menu + Linear Rail banner
│   │       └── utils/            # formatters, theme, help
│   ├── tui/                      # @hoox-sh/hoox-tui (OpenTUI)
│   └── shared/                   # Shared types/utilities
│       └── src/
│           ├── types.ts          # Core types
│           ├── router.ts         # Custom router
│           ├── middleware/       # Auth, rate-limit, logger
│           └── errors.ts         # Error factories
│
├── workers/
│   ├── hoox-worker/              # Gateway worker (published name: hoox)
│   ├── trade-worker/             # Trading execution
│   │   └── schema.sql            # D1 schema
│   ├── agent-worker/             # AI risk manager
│   ├── d1-worker/                # Database service
│   ├── telegram-worker/          # Telegram notifications
│   ├── web3-wallet-worker/       # DeFi operations
│   ├── email-worker/             # Email signal parsing
│   ├── analytics-worker/         # Analytics collection
│   ├── report-worker/            # PDF reports
│   ├── pyne-worker/              # Pine Script™ edge evaluate (Python)
│   └── dashboard/                # Next.js 16 dashboard
│       ├── next.config.ts
│       ├── wrangler.jsonc
│       ├── src/middleware.ts
│       └── src/app/              # Next.js app routes
│
├── scripts/
│   ├── migrate-tracking.sh       # D1 tracking migration
│   ├── check-worker-submodules.ts
│   └── purge-credentials.sh      # Emergency credential purge
│
└── docs/                         # Documentation
    ├── getting-started/
    ├── deployment/
    ├── development/
    ├── workers/
    └── architecture/

---

Document Version: 1.0.0
Last Updated: 2026-05-05
Maintainer: Hoox Development Team