foxhunt/docs/plans/2026-02-22-documentation-cleanup-implementation.md

Documentation Cleanup Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Delete ~45 stale swarm artifact files, rewrite 7 outdated crate READMEs, fix 5 api_gateway/TLI docs, and add missing web-gateway/README.md.

Architecture: Worktree off main, two commits: one for deletion, one for rewrites. Parallel subagents for README writing since files are independent.

Tech Stack: Git, Markdown

---

Task 1: Create worktree and branch

Step 1: Create worktree off main

cd /home/jgrusewski/Work/foxhunt
git worktree add .claude/worktrees/docs-cleanup main -b docs/documentation-cleanup

Step 2: Verify worktree

cd .claude/worktrees/docs-cleanup && git branch --show-current

Expected: docs/documentation-cleanup

---

Task 2: Delete all stale swarm artifacts

Files: 45+ files across the workspace.

Step 1: Delete TLI stale docs

git rm tli/WIDGETS_README.md tli/README_EVENT_STREAMING.md tli/BENCHMARKS_STATUS.md tli/SECURITY_IMPLEMENTATION.md

Step 2: Delete api_gateway stale docs

git rm services/api_gateway/WAVE71_AGENT3_COMPLETE.md services/api_gateway/WAVE71_AGENT9_METRICS_REPORT.md

Step 3: Delete service-level agent reports

git rm services/AGENT_22_HEALTH_CHECK_TESTS_REPORT.md services/AGENT_22_TEST_PATTERNS.md \
  services/backtesting_service/tests/AGENT_8_REPORT.md \
  services/ml_training_service/AGENT_49_EXECUTION_GUIDE.md \
  services/ml_training_service/AGENT_49_FINAL_REPORT.md \
  services/ml_training_service/AGENT_W4_2_INTEGRATION_TESTS_COMPLETE.md \
  services/ml_training_service/AGENT_W4_4_STRESS_TESTS_COMPLETE.md \
  services/ml_training_service/IMPLEMENTATION_SUMMARY.md \
  services/ml_training_service/DELIVERY_VERIFICATION.md \
  services/ml_training_service/TUNING_INTEGRATION_CHECKLIST.md

Step 4: Delete test/e2e agent reports

git rm tests/e2e_helpers/AGENT_314_INFRASTRUCTURE_VALIDATION_REPORT.md \
  tests/e2e_helpers/AGENT_315_SERVICE_HEALTH_REPORT.txt \
  tests/e2e_helpers/AGENT_336_SERVICE_HEALTH_TEST_REPORT.md \
  tests/e2e_helpers/AGENT_339_JWT_AUTH_VALIDATION_REPORT.md \
  tests/e2e/integration/DELIVERABLES.md \
  data/tests/AGENT_14_REAL_DATA_INTEGRATION_REPORT.md

Step 5: Delete ML WAVE/AGENT artifacts

git rm ml/WAVE2_COMPLETION_REPORT.md ml/WAVE2_COMPILATION_ERRORS.md ml/WAVE2_FIX_CHECKLIST.md \
  ml/WAVE2_AGENT14_FINAL_REPORT.md ml/WAVE2_AGENT23_GIT_CHANGES_SUMMARY.md \
  ml/WAVE5_AGENT26_ZERO_PADDING_ELIMINATION.md ml/WAVE9_AGENT8_WIRING_COMPLETE.md \
  ml/AGENT_W3_20_ML_UNIT_TESTS.md ml/AGENT_W3_21_WAVE_D_INTEGRATION_TEST_REPORT.md \
  ml/AGENT_W9_13_TRAIN_MAMBA2_DBN_FIX.md ml/AGENT_W9_16_FEATURE_TEST_FIX_REPORT.md \
  ml/AGENT_W9_17_225_FEATURE_VALIDATION.md

Step 6: Delete other stale files

git rm adaptive-strategy/PHASE4_COMPLETION.md foxhunt-deploy/IMPLEMENTATION_SUMMARY.md

Step 7: Delete reports directory

git rm -r reports/

Step 8: Commit deletions

git commit -m "docs: delete stale swarm agent artifacts and reports

Remove 45+ AGENT_*, WAVE_*, and completion report files that were
one-time swarm deliverables with no living documentation value.
Remove reports/2025-11-16_17_hyperopt_analysis/ (55 files, code
changes already landed). Content preserved in git history.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"

---

Task 3: Rewrite root README.md

Files:

• Modify: README.md

Step 1: Rewrite with accurate project information

Replace entire contents. The README must include:

• Project name and one-line description
• Workspace crate table (41 members grouped by category)
• Build command: SQLX_OFFLINE=true cargo check --workspace
• Test command: SQLX_OFFLINE=true cargo test -p <crate> --lib
• ML models: DQN Rainbow, PPO, TFT, Mamba2
• Infrastructure: Gitea at git.fxhnt.ai (Tailscale-only)
• Key architecture: 8 microservices, web-gateway (Axum), web-dashboard (React 19)
• No inflated claims, no placeholder URLs, no references to non-existent scripts

---

Task 4: Rewrite ml/README.md

Files:

• Modify: ml/README.md

Step 1: Rewrite with correct model info

Must reflect:

• Models: DQN (Rainbow), PPO, TFT, Mamba2, Liquid Networks, TLOB, Flash Attention
• Training: Two paths per model — standalone trainer + UnifiedTrainable adapter
• Inference: InferenceAdapterBridge for ensemble coordination
• Candle v0.9.1 backend (GPU via CUDA, RTX 3050 Ti 4GB max batch 230)
• Hyperopt: ArgminOptimizer (PSO) with adapters for each model
• No placeholder docs.rs links
• ModelType enum: 14 variants

---

Task 5: Rewrite risk/README.md

Files:

• Modify: risk/README.md

Step 1: Rewrite with correct API surface

Must reflect:

• AtomicKillSwitch (not KillSwitch)
• VaR: Historical Simulation, Monte Carlo, Parametric, Expected Shortfall
• KellySizer, RiskEngine, StressTester, ComplianceValidator
• Circuit breaker, drawdown monitor, correlation monitor, position tracker
• Redis-coordinated kill switches
• Production vs development config presets

---

Task 6: Rewrite adaptive-strategy/README.md

Files:

• Modify: adaptive-strategy/README.md

Step 1: Rewrite with correct architecture

Must reflect:

• EnsembleConfig re-exported from ml crate (not local)
• Real model types: DQN, PPO, TFT, Mamba2 via InferenceAdapterBridge
• Modules: config, ensemble, execution (TWAP/VWAP/IS/POV/ArrivalPrice), microstructure, regime, risk
• AdaptiveStrategy as the top-level type
• PostgreSQL-backed hot-reload config (optional postgres feature)
• IB already integrated (not "pending")

---

Task 7: Rewrite data/README.md

Files:

• Modify: data/README.md

Step 1: Rewrite to describe actual crate purpose

Must reflect:

• Market data ingestion and broker integration
• Providers: Databento, Benzinga
• Broker integrations: IB TWS, ICMarkets FIX 4.4
• Features: DBN uploader, Parquet persistence, replay infrastructure, training pipeline
• Feature engineering: unified feature extraction for ML models
• Data validation and quality control
• Optional features: databento, benzinga, icmarkets, redis-cache, ib, mock

---

Task 8: Rewrite web-dashboard/README.md

Files:

• Modify: web-dashboard/README.md

Step 1: Rewrite with actual project details

Must reflect:

• React 19 + TypeScript + Vite 7 + Tailwind CSS 4
• TradingView charts (lightweight-charts 5.1.0) + Recharts
• State: Zustand + React Query (staleTime 10s, refetchInterval 15s)
• 6 dashboard pages: Trading, Risk, ML, Performance, Backtesting, Config
• Auth: Login page, ProtectedRoute guards, ErrorBoundary, 401 auto-logout
• Dev: npm run dev → localhost:5173, proxies to web-gateway at :3000

---

Task 9: Rewrite services/ml_training_service/README.md

Files:

• Modify: services/ml_training_service/README.md

Step 1: Rewrite with correct ports and remove Python

Must reflect:

• gRPC on env GRPC_PORT
• Prometheus metrics on 9094
• Rust-only service (remove Python client example)
• Features: minimal (default), gpu, debug, mock-data
• Connects to PostgreSQL via sqlx
• Model training orchestration and lifecycle management

---

Task 10: Fix api_gateway docs (3 files)

Files:

• Modify: services/api_gateway/ML_TRAINING_PROXY_INTEGRATION.md
• Modify: services/api_gateway/RATE_LIMITER_IMPLEMENTATION.md
• Modify: services/api_gateway/BENCHMARKS.md

Step 1: ML_TRAINING_PROXY_INTEGRATION.md

• Strip "Wave 70 Agent 10 Deliverables" framing
• Keep technical proxy content (gRPC forwarding, circuit breaker)
• Remove swarm artifact language throughout

Step 2: RATE_LIMITER_IMPLEMENTATION.md

• Strip "Wave 70 Agent 13" framing
• Note that web-gateway now handles rate limiting for HTTP traffic (3 tiers: auth 10/min, trading 200/min, compute 30/min)
• Keep api_gateway gRPC-level rate limiting docs if they describe different behavior

Step 3: BENCHMARKS.md

• Strip "Wave 71 Agent 4 Deliverable" framing
• Keep benchmark numbers with a note they need re-verification
• Remove swarm language

---

Task 11: Fix TLI docs (2 files)

Files:

• Modify: tli/TUNE_COMMAND_README.md
• Modify: tli/docs/USAGE.md

Step 1: TUNE_COMMAND_README.md

• Remove hardcoded /home/jgrusewski/Work/foxhunt/ paths
• Remove "Wave 152+ roadmap" language
• Keep tune CLI command documentation (it still exists)

Step 2: docs/USAGE.md

• Update service endpoints: all traffic goes through api_gateway at port 50050
• Remove cargo run --example basic_dashboard references (deleted)
• Remove ServiceEndpoints direct-connection pattern
• Keep CLI command documentation

---

Task 12: Create web-gateway/README.md

Files:

• Create: web-gateway/README.md

Step 1: Write README for the gateway

Must include:

• REST + WebSocket gateway for web dashboard
• Axum 0.7.9, listens on :3000 (env GATEWAY_LISTEN_ADDR)
• gRPC upstreams: trading (:50051), backtesting (:50052), ml_training (:50053)
• Route groups: public (auth), trading tier (200/min), compute tier (30/min)
• Auth: JWT middleware, 32-char minimum secret
• WebSocket: /api/ws, JWT via query param, topic subscriptions, ping/pong keepalive
• Rate limiting: 3 tiers per IP
• Security: CORS, 1MB body limit, security headers (HSTS, x-frame-options DENY, etc.)
• Health: GET /health, GET /ready

---

Task 13: Commit all README changes

Step 1: Stage and commit

git add README.md ml/README.md risk/README.md adaptive-strategy/README.md data/README.md \
  web-dashboard/README.md services/ml_training_service/README.md \
  services/api_gateway/ML_TRAINING_PROXY_INTEGRATION.md \
  services/api_gateway/RATE_LIMITER_IMPLEMENTATION.md \
  services/api_gateway/BENCHMARKS.md \
  tli/TUNE_COMMAND_README.md tli/docs/USAGE.md \
  web-gateway/README.md
git commit -m "docs: rewrite outdated READMEs and add web-gateway docs

Rewrite 7 crate READMEs to reflect current architecture: correct
model types, AtomicKillSwitch, real EnsembleConfig source, actual
data crate purpose, web-dashboard project details.

Fix 5 api_gateway/TLI docs: strip swarm agent framing, update
service endpoints, remove deleted dashboard references.

Add missing web-gateway/README.md documenting 24 REST endpoints,
WebSocket support, JWT auth, and rate limiting tiers.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"

---

Task 14: Push and merge

Step 1: Push branch to Gitea

git push origin docs/documentation-cleanup

Step 2: Merge to main (fast-forward if possible)

cd /home/jgrusewski/Work/foxhunt
git checkout main
git merge docs/documentation-cleanup
git push origin main

Step 3: Clean up worktree

git worktree remove .claude/worktrees/docs-cleanup
git branch -d docs/documentation-cleanup